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 PHP Conventions 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).

FEPs (Fediverse Enhancement Proposals)

FEPs extend ActivityPub with additional features. Common FEP categories include: - Long-form text support. - Quote posts. - Activity intents. - Follower synchronization. - Actor metadata extensions.

For supported FEPs in this plugin: See FEDERATION.md for the authoritative list of implemented FEPs.

Implementation Notes

WordPress Plugin Specifics

This plugin implements: - Actor Types: User, Blog, Application - Transformers: Convert WordPress content to ActivityPub objects - Handlers: Process incoming activities

For implementation details, see: - PHP Conventions for code structure - Integration Guide for extending

Testing Federation

# Test actor endpoint
curl -H "Accept: application/activity+json" \
  https://site.com/@username

# Test WebFinger
curl https://site.com/.well-known/webfinger?resource=acct:[email protected]

# Test NodeInfo
curl https://site.com/.well-known/nodeinfo

Common Issues

Activities Not Received

• Check inbox URL is accessible
• Verify HTTP signature validation
• Ensure content-type headers correct
• Check for firewall/security blocks

Replies Not Federated

• Verify inbox forwarding enabled
• Check addressing includes relevant actors
• Ensure inReplyTo properly set

Follower Sync Issues

• Check Accept activities sent for Follow
• Verify followers collection updates
• Ensure shared inbox used when available

Resources

• ActivityPub Spec
• ActivityStreams Vocabulary
• Project FEDERATION.md
• FEPs Repository