federation

Three Building Blocks

1. Actors - Users/accounts in the system

- Each actor has a unique URI

- Required: inbox, outbox

- Optional: followers, following, liked

1. Activities - Actions taken by actors

- Create, Update, Delete, Follow, Like, Announce, Undo

- Wrap objects to describe how they're shared

1. Objects - Content being acted upon

- Notes, Articles, Images, Videos, etc.

- Can be embedded or referenced by URI

Actor Structure

```json

{

"@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"

}

```

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

Create

Wraps newly published content:

```json

{

"type": "Create",

"actor": "https://example.com/@alice",

"object": {

"type": "Note",

"content": "Hello, Fediverse!"

}

}

```

Follow

Initiates subscription:

```json

{

"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:

```json

{

"type": "Like",

"actor": "https://example.com/@alice",

"object": "https://other.example/@bob/post/123"

}

```

Announce

Reshares/boosts content:

```json

{

"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:

```json

{

"type": "Undo",

"actor": "https://example.com/@alice",

"object": {

"type": "Follow",

"id": "https://example.com/@alice/follow/123"

}

}

```

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

1. Discover Inboxes

- Fetch actor profiles

- Extract inbox property

- Use sharedInbox if available for efficiency

1. 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

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:

```json

{

"to": ["https://www.w3.org/ns/activitystreams#Public"],

"cc": ["https://example.com/@alice/followers"]

}

```

Followers-Only:

```json

{

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

}

```

Direct Message:

```json

{

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

"cc": []

}

```

Security Considerations

1. Verify Origins

- Don't trust claimed sources without verification

- Check HTTP Signatures

- Validate actor owns referenced objects

1. Prevent Spoofing

- Mallory could claim Alice posted something

- Always verify before processing side effects

1. Rate Limiting

- Limit recursive dereferencing

- Protect against denial-of-service

- Implement spam filtering

1. Content Sanitization

- Clean HTML before browser rendering

- Validate media types

- Check for malicious payloads

Supported Standards

See [FEDERATION.md](../../../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](../../../FEDERATION.md) for the authoritative list of implemented FEPs.

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](../code-style/SKILL.md) for code structure
• [Integration Guide](../integrations/SKILL.md) for extending

Testing Federation

```bash

# Test actor endpoint

curl -H "Accept: application/activity+json" \

https://site.com/@username

# Test WebFinger

curl https://site.com/.well-known/webfinger?resource=acct:user@site.com

# Test NodeInfo

curl https://site.com/.well-known/nodeinfo

```

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

• [ActivityPub Spec](https://www.w3.org/TR/activitypub/)
• [ActivityStreams Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
• [Project FEDERATION.md](../../../FEDERATION.md)
• [FEPs Repository](https://codeberg.org/fediverse/fep)