feat: Enhance ActivityPub compliance with Move activity handling and featured collection support; add integration tests for actor document and migration scenarios

Author: aluitink

README.md

@@ -6,13 +6,104 @@ A modular .NET library for building ActivityPub-enabled applications.
 
 Broca provides a complete, standards-compliant implementation of the ActivityPub protocol for .NET developers. It offers both client and server capabilities with a clean API that makes federation simple.
 
-**Key Features:**
-- ✅ Full ActivityPub client and server implementation
-- ✅ HTTP Signatures for authenticated federation
+## Features
+
+### Core ActivityPub Protocol
+
+**Client-to-Server (C2S)**
+- ✅ Post activities to outbox (Create, Like, Follow, Announce, Undo)
+- ✅ Server-assigned activity IDs with proper URL structure
+- ✅ Follow/Unfollow relationship management
+- ✅ HTTP Signature authentication for outbox operations
+- ✅ API key-based client authentication
+
+**Server-to-Server (S2S) Federation**
+- ✅ Cross-server activity delivery with HTTP Signatures
+- ✅ Background delivery queue with retry logic
+- ✅ Follow/Accept/Reject workflow (auto-accept and manual approval modes)
+- ✅ Undo operations (Follow, Like, Announce)
+- ✅ Delete activities with Tombstone support
+- ✅ Update Person for profile changes
+- ✅ Move activity for account migration with `alsoKnownAs` validation
+- ✅ Date validation (reject stale or future-dated requests)
+- ✅ Actor caching and refresh
+
+**Shared Inbox**
+- ✅ Efficient batch delivery to multiple local users
+- ✅ To, Cc, and Bcc addressing support
+- ✅ Public addressing (`https://www.w3.org/ns/activitystreams#Public`)
+- ✅ Followers collection addressing
+- ✅ Smart routing (mixed local/remote recipient handling)
+
+### Collections & Discovery
+
+- ✅ Followers and Following collections
+- ✅ Custom collections (manual curation and query-based)
+- ✅ Ordered collection pagination
 - ✅ WebFinger support for @user@domain discovery
-- ✅ Background activity delivery with retry logic
-- ✅ Modular persistence (in-memory, file-based, or custom)
-- ✅ Production-ready with Docker and Let's Encrypt support
+- ✅ NodeInfo 2.0 and 2.1 (server metadata and statistics)
+
+### Media & Attachments
+
+- ✅ Blob storage for media files
+- ✅ Media endpoint (`/users/:username/media/:blobId`)
+- ✅ Attachments in Create activities
+- ✅ Content-Type preservation and validation
+
+### Security & Authentication
+
+- ✅ HTTP Signatures (draft-cavage-http-signatures-12)
+- ✅ Public key infrastructure with cryptographic key generation
+- ✅ Request date validation (prevents replay attacks)
+- ✅ Outbox authentication (users can only post as themselves)
+- ✅ Signature verification for incoming federation
+
+### Content Type Handling
+
+- ✅ `application/activity+json`
+- ✅ `application/ld+json`
+- ✅ Profile parameter support (`application/ld+json; profile="..."`)
+- ✅ Mastodon compatibility
+
+### Administration
+
+- ✅ Back-channel user management via ActivityPub protocol
+- ✅ System actor for server-level operations
+- ✅ Create/Update/Delete users through admin endpoints
+- ✅ Automatic key pair generation for new actors
+
+### Persistence & Storage
+
+- ✅ Modular storage abstractions (`IActorRepository`, `IActivityRepository`, `IBlobStorageService`)
+- ✅ In-memory implementation (development/testing)
+- ✅ File-based implementation (production-ready)
+- ✅ Easy integration with custom storage backends
+
+### Developer Experience
+
+- ✅ Comprehensive integration test suite (88+ tests)
+- ✅ Multi-server federation testing infrastructure
+- ✅ Activity builder API for constructing valid ActivityStreams objects
+- ✅ Blazor component library for building federated UIs
+- ✅ Docker and Let's Encrypt support for production deployment
+
+## Standards Compliance
+
+Broca implements the core [ActivityPub W3C Recommendation](https://www.w3.org/TR/activitypub/) with extensions for real-world interoperability:
+
+- ✅ **ActivityPub** - Client-to-Server and Server-to-Server protocols
+- ✅ **ActivityStreams 2.0** - Core vocabulary and extended types
+- ✅ **HTTP Signatures** - Request authentication (draft-cavage-http-signatures-12)
+- ✅ **WebFinger** (RFC 7033) - User discovery via @username@domain
+- ✅ **NodeInfo 2.0/2.1** - Server metadata and statistics
+
+**Interoperability Target:** Mastodon (primary), with support for Threads, Pixelfed, and Pleroma.
+
+**Known Limitations:**
+- `featured` collection not yet exposed on actor documents (pinned posts)
+- Follow/Following collections for locked accounts publicly visible (privacy enhancement pending)
+
+All critical and high-priority federation features are complete. See [docs/s2s-compliance-todo.md](docs/s2s-compliance-todo.md) for detailed compliance tracking.
 
 ## Library Components
 
@@ -309,6 +400,29 @@ builder.Services.AddSingleton<IIdentityProvider, CustomIdentityProvider>();
 - Docker (for containerized deployment)
 - A domain name with HTTPS for production federation
 
+## Testing & Quality Assurance
+
+Broca includes a comprehensive test suite to ensure reliability and standards compliance:
+
+**Integration Tests** (88+ tests across 10 test suites)
+- `ServerToServerTests` - Cross-server federation scenarios (22 tests)
+- `SharedInboxTests` - Efficient multi-user delivery (11 tests)
+- `ClientToServerTests` - Outbox posting and activity creation (7 tests)
+- `CustomCollectionsTests` - Manual and query-based collections (15 tests)
+- `AdminOperationsTests` - Back-channel user management (8 tests)
+- `ClientAuthenticationTests` - API key and HTTP Signature auth (5 tests)
+- `ContentTypeHandlingTests` - Mastodon compatibility (7 tests)
+- `BlobStorageTests` - Media upload and retrieval (4 tests)
+- `NodeInfoStatisticsTests` - Server metadata endpoints (5 tests)
+- `OutboxAuthenticationTests` - Security validation (3 tests)
+
+**Unit Tests**
+- Repository implementations (actors, activities, delivery queue)
+- Blob storage service functionality
+- Component rendering logic
+
+All tests use real HTTP clients and in-memory servers to validate end-to-end behavior, not mocked implementations. This ensures that Broca works correctly with actual ActivityPub clients and servers in the fediverse.
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and guidelines.

docs/s2s-compliance-todo.md

@@ -8,21 +8,21 @@ Last reviewed: 2026-02-28. Mastodon is the primary target for interop, with seco
 
 **Critical items:** 0 remaining (all resolved)  
 **High priority items:** 0 remaining (all resolved)  
-**Medium priority items:** 5 remaining  
+**Medium priority items:** 3 remaining  
 **Low priority items:** 2 remaining
 
 
 ## 🟡 Medium — Missing Features / Spec Gaps
 
-### M1 · `Move` activity not handled (account migration)
+### ✅ M1 · `Move` activity handled (COMPLETED)
 
 **File:** `InboxProcessor.cs`
 
-`Move` is used by Mastodon for account portability. Currently falls to `_ => true` (accepted but not processed).
+`Move` is used by Mastodon for account portability. When a user migrates to a new account, followers are automatically migrated.
 
-**Fix:** Handle `Move` by updating the follower's following list: replace the old actor IRI with the new one (if the new actor's `alsoKnownAs` references the old one, to prevent spoofing).
+**Implementation:** Handles `Move` by updating the follower's following list: replaces the old actor IRI with the new one if the new actor's `alsoKnownAs` references the old one (prevents spoofing).
 
-**Priority:** Medium - required for full Mastodon compatibility, but low usage.
+**Status:** ✅ Implemented and tested with security validation.
 
 ---
 
@@ -38,15 +38,15 @@ Mastodon expects a `featured` property on the actor document pointing to an `Ord
 
 ---
 
-### M3 · Actor document missing `alsoKnownAs` field
+### ✅ M3 · `alsoKnownAs` field supported (COMPLETED)
 
-**File:** `ActorController.cs` → `Get`
+**File:** `ActorController.cs`
 
-Required for `Move`-based account migration. Actors need to be able to declare aliases.
+Required for `Move`-based account migration. Actors can declare aliases via the `alsoKnownAs` property.
 
-**Fix:** Support an `alsoKnownAs` property in the actor's stored extension data and expose it in the actor document response.
+**Implementation:** Supported via actor's ExtensionData dictionary. Set as a JSON array of actor URI strings.
 
-**Priority:** Medium - required for M1 (Move activity) to be fully functional.
+**Status:** ✅ No code changes required - ExtensionData already serializes arbitrary fields in actor documents.
 
 ---
 
@@ -80,9 +80,9 @@ The outer `Split(',')` then inner `Split('=', 2)` approach is correct for most c
 
 | Order | Item | Effort | Notes |
 |-------|------|--------|-------|
-| 1 | M2 — `featured` collection on actor | Small | Quick win — collection infrastructure exists |
-| 2 | M3 — `alsoKnownAs` | Small | Required for M1 |
-| 3 | M1 — `Move` activity | Medium | Depends on M3 |
+| 1 | ~~M1 — `Move` activity~~ | ~~Medium~~ | ✅ **Completed** |
+| 2 | ~~M3 — `alsoKnownAs`~~ | ~~Small~~ | ✅ **Completed** (no code changes needed) |
+| 3 | M2 — `featured` collection on actor | Small | Quick win — collection infrastructure exists |
 | 4 | M4 — Followers list auth for locked accounts | Small | Privacy fix |
 | 5 | M5 — NodeInfo real stats | Medium | Requires repo changes |
 | 6 | L2 — Content-type testing | Small | Verification only |

src/Broca.ActivityPub.Server/Controllers/ActorController.cs

@@ -93,7 +93,18 @@ public async Task<IActionResult> Get(string username)
                         $"{baseUrl}/users/{username}/collections",
                         _jsonOptions);
 
-                    // Add individual collection links with broca: prefix
+                    // Special case: "featured" is a de facto standard across the fediverse (Mastodon, Pleroma, etc.)
+                    // for pinned posts. Expose it at root level for interoperability.
+                    // This is a one-off exception - all other collections use broca: prefix.
+                    var featuredCollection = publicCollections.FirstOrDefault(c => c.Id == "featured");
+                    if (featuredCollection != null)
+                    {
+                        actor.ExtensionData["featured"] = JsonSerializer.SerializeToElement(
+                            $"{baseUrl}/users/{username}/collections/featured",
+                            _jsonOptions);
+                    }
+                    
+                    // Add individual collection links with broca: prefix (for Broca-specific extensions)
                     foreach (var collection in publicCollections)
                     {
                         actor.ExtensionData[$"broca:{collection.Id}"] = JsonSerializer.SerializeToElement(

src/Broca.ActivityPub.Server/Services/InboxProcessor.cs

@@ -19,6 +19,7 @@ public class InboxProcessor : IInboxHandler
     private readonly AdminOperationsHandler _adminOperationsHandler;
     private readonly AttachmentProcessingService _attachmentProcessingService;
     private readonly ActivityDeliveryService _deliveryService;
+    private readonly IActivityPubClient _activityPubClient;
     private readonly ActivityPubServerOptions _options;
     private readonly ILogger<InboxProcessor> _logger;
 
@@ -30,6 +31,7 @@ public InboxProcessor(
         AdminOperationsHandler adminOperationsHandler,
         AttachmentProcessingService attachmentProcessingService,
         ActivityDeliveryService deliveryService,
+        IActivityPubClient activityPubClient,
         IOptions<ActivityPubServerOptions> options,
         ILogger<InboxProcessor> logger)
     {
@@ -40,6 +42,7 @@ public InboxProcessor(
         _adminOperationsHandler = adminOperationsHandler;
         _attachmentProcessingService = attachmentProcessingService;
         _deliveryService = deliveryService;
+        _activityPubClient = activityPubClient;
         _options = options.Value;
         _logger = logger;
     }
@@ -102,6 +105,7 @@ public async Task<bool> HandleActivityAsync(string username, IObjectOrLink activ
                 "Add" => await HandleAddAsync(username, activity as IObject, cancellationToken),
                 "Remove" => await HandleRemoveAsync(username, activity as IObject, cancellationToken),
                 "Update" => await HandleIncomingUpdateAsync(username, activity as IObject, cancellationToken),
+                "Move" => await HandleMoveAsync(username, activity as IObject, cancellationToken),
                 _ => true // Unknown types are accepted but not processed
             };
 
@@ -357,6 +361,111 @@ private Task<bool> HandleAnnounceAsync(string username, IObject? activity, Cance
         return Task.FromResult(true);
     }
 
+    private async Task<bool> HandleMoveAsync(string username, IObject? activity, CancellationToken cancellationToken)
+    {
+        if (activity is not Activity moveActivity || moveActivity.Object == null || moveActivity.Target == null)
+        {
+            _logger.LogWarning("Move activity missing required properties");
+            return false;
+        }
+
+        // Extract old actor ID (from object - the actor being moved from)
+        var oldActorRef = moveActivity.Object.FirstOrDefault();
+        var oldActorId = oldActorRef switch
+        {
+            ILink link => link.Href?.ToString(),
+            IObject obj => obj.Id,
+            _ => null
+        };
+
+        if (string.IsNullOrEmpty(oldActorId))
+        {
+            _logger.LogWarning("Move  activity has invalid object reference");
+            return false;
+        }
+
+        // Extract new actor ID (from target - the actor being moved to)
+        var newActorRef = moveActivity.Target.FirstOrDefault();
+        var newActorId = newActorRef switch
+        {
+            ILink link => link.Href?.ToString(),
+            IObject obj => obj.Id,
+            _ => null
+        };
+
+        if (string.IsNullOrEmpty(newActorId))
+        {
+            _logger.LogWarning("Move activity has invalid target reference");
+            return false;
+        }
+
+        _logger.LogInformation("Processing Move activity: {OldActorId} -> {NewActorId} for user {Username}", 
+            oldActorId, newActorId, username);
+
+        // Check if this user follows the old actor
+        var following = await _actorRepository.GetFollowingAsync(username, cancellationToken);
+        if (!following.Contains(oldActorId))
+        {
+            _logger.LogDebug("User {Username} does not follow {OldActorId}, skipping Move", username, oldActorId);
+            return true; // Not an error, just not relevant to this user
+        }
+
+        // Fetch the new actor to verify alsoKnownAs
+        try
+        {
+            var newActor = await _activityPubClient.GetAsync<Actor>(new Uri(newActorId), useCache: false, cancellationToken);
+            
+            if (newActor == null)
+            {
+                _logger.LogWarning("Could not fetch new actor {NewActorId} for Move verification", newActorId);
+                return false;
+            }
+
+            // Security check: verify alsoKnownAs contains the old actor ID
+            var alsoKnownAs = new List<string>();
+            if (newActor.ExtensionData?.TryGetValue("alsoKnownAs", out var alsoKnownAsElement) == true)
+            {
+                try
+                {
+                    if (alsoKnownAsElement.ValueKind == JsonValueKind.Array)
+                    {
+                        alsoKnownAs = JsonSerializer.Deserialize<List<string>>(alsoKnownAsElement.GetRawText()) ?? new List<string>();
+                    }
+                }
+                catch (JsonException ex)
+                {
+                    _logger.LogWarning(ex, "Failed to parse alsoKnownAs for {NewActorId}", newActorId);
+                }
+            }
+
+            if (!alsoKnownAs.Contains(oldActorId))
+            {
+                _logger.LogWarning("Security check failed: {NewActorId} does not list {OldActorId} in alsoKnownAs. Rejecting Move.",
+                    newActorId, oldActorId);
+                return false;
+            }
+
+            // Valid migration - update following list
+            await _actorRepository.RemoveFollowingAsync(username, oldActorId, cancellationToken);
+            await _actorRepository.AddFollowingAsync(username, newActorId, cancellationToken);
+            
+            _logger.LogInformation("Successfully migrated follow for {Username}: {OldActorId} -> {NewActorId}",
+                username, oldActorId, newActorId);
+
+            return true;
+        }
+        catch (HttpRequestException ex)
+        {
+            _logger.LogError(ex, "Network error fetching new actor {NewActorId} for Move verification", newActorId);
+            return false;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error processing Move activity for {Username}", username);
+            return false;
+        }
+    }
+
     private async Task<bool> HandleAddAsync(string username, IObject? activity, CancellationToken cancellationToken)
     {
         if (activity is not Activity addActivity || addActivity.Object == null || addActivity.Target == null)