Federation

ActivityPub Federation Protocol

This skill provides understanding of the ActivityPub protocol specification and how federation works.

For supported features and compatibility: See FEDERATION.md for the complete list of implemented FEPs, supported standards, and federation compatibility details.

For implementation details: See AGENTS.md for transformers, handlers, and PHP code patterns.

Core Concepts

Three Building Blocks

1. Actors - Users/accounts in the system

   • Each actor has a unique URI
   • Required: inbox, outbox
   • Optional: followers, following, liked

2. Activities - Actions taken by actors

   • Create, Update, Delete, Follow, Like, Announce, Undo
   • Wrap objects to describe how they're shared

3. Objects - Content being acted upon

   • Notes, Articles, Images, Videos, etc.
   • Can be embedded or referenced by URI

Actor Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/@alice",
  "inbox": "https://example.com/@alice/inbox",
  "outbox": "https://example.com/@alice/outbox",
  "followers": "https://example.com/@alice/followers",
  "following": "https://example.com/@alice/following",
  "preferredUsername": "alice",
  "name": "Alice Example",
  "summary": "Bio text here"
}

Collections

Standard Collections

Inbox - Receives incoming activities

• De-duplicate by activity ID
• Filter based on permissions
• Process activities for side effects

Outbox - Publishes actor's activities

• Public record of what actor has posted
• Filtered based on viewer permissions
• Used for profile activity displays

Followers - Actors following this actor

• Updated when Follow activities are Accepted
• Used for delivery targeting

Following - Actors this actor follows

• Tracks subscriptions
• Used for timeline building

Public Addressing

Special collection: https://www.w3.org/ns/activitystreams#Public

• Makes content publicly accessible
• Do not deliver to this URI - it's a marker, not a real inbox
• Used in to, cc, bto, bcc fields for visibility

Activity Types

Create

Wraps newly published content:

{
  "type": "Create",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Note",
    "content": "Hello, Fediverse!"
  }
}

Follow

Initiates subscription:

{
  "type": "Follow",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob"
}

• Recipient should respond with Accept or Reject
• Only add to followers upon Accept

Like

Indicates appreciation:

{
  "type": "Like",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Announce

Reshares/boosts content:

{
  "type": "Announce",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Update

Modifies existing content:

• Supplied properties replace existing
• null values remove fields
• Must include original object ID

Delete

Removes content:

• May replace with Tombstone for referential integrity
• Should cascade to related activities

Undo

Reverses previous activities:

{
  "type": "Undo",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Follow",
    "id": "https://example.com/@alice/follow/123"
  }
}

Server-to-Server Federation

Activity Delivery Process

1. Resolve Recipients

   • Check to, bto, cc, bcc, audience fields
   • Dereference collections to find individual actors
   • De-duplicate recipient list
   • Exclude activity's own actor

2. Discover Inboxes

   • Fetch actor profiles
   • Extract inbox property
   • Use sharedInbox if available for efficiency

3. Deliver via HTTP POST

   • Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"
   • Include HTTP Signatures for authentication
   • Handle delivery failures gracefully

Inbox Forwarding

Ghost Replies Problem: When Alice replies to Bob's post that Carol follows, Carol might not see the reply if she doesn't follow Alice.

Solution: Inbox forwarding

• When receiving activity addressing a local collection
• If activity references local objects
• Forward to collection members
• Ensures conversation participants see replies

Shared Inbox Optimization

For public posts with many recipients on same server:

• Use sharedInbox endpoint instead of individual inboxes
• Reduces number of HTTP requests
• Server distributes internally

Addressing and Visibility

To/CC Fields

• to - Primary recipients (public in UI)
• cc - Secondary recipients (copied/mentioned)
• bto - Blind primary (hidden in delivery)
• bcc - Blind secondary (hidden in delivery)

Important: Remove bto and bcc before delivery to preserve privacy

Visibility Patterns

Public Post:

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/@alice/followers"]
}

Followers-Only:

{
  "to": ["https://example.com/@alice/followers"]
}

Direct Message:

{
  "to": ["https://other.example/@bob"],
  "cc": []
}

Content Verification

Security Considerations

1. Verify Origins

   • Don't trust claimed sources without verification
   • Check HTTP Signatures
   • Validate actor owns referenced objects

2. Prevent Spoofing

   • Mallory could claim Alice posted something
   • Always verify before processing side effects

3. Rate Limiting

   • Limit recursive dereferencing
   • Protect against denial-of-service
   • Implement spam filtering

4. Content Sanitization

   • Clean HTML before browser rendering
   • Validate media types
   • Check for malicious payloads

Protocol Extensions

Supported Standards

See FEDERATION.md for the complete list of implemented standards and FEPs, including:

• WebFinger - Actor discovery.
• HTTP Signatures - Request authentication.
• NodeInfo - Server metadata.
• Various FEPs (Fediverse Enhancement Proposals).