Federation Architecture

Instance A                          Instance B
  |                                   |
  |--- GET /api/me ------------------>| (Fetch Bob's profile)
  |<-- 200 OK {profile} --------------|
  |                                   |
  |--- Create FLLW action token ---   |
  |                                   |
  |--- POST /api/inbox -------------->| (Send follow action)
  |    {token: "eyJhbGc..."}         |
  |                                   |--- Verify signature
  |                                   |--- Check permissions
  |                                   |--- Store action
  |<-- 202 Accepted ------------------|

Algorithm: Distribute Action

Input: action_token, action_type
Output: Result<()>

1. Determine recipients based on action_type:
   a. "POST" → All followers of the user
   b. "CMNT" / "REACT" → Owner of parent post
   c. "CONN" / "FLLW" → Target from action audience (aud claim)
   d. "MSG" → All conversation participants
   e. Other → No recipients (skip)

2. For each recipient instance:
   a. Construct URL: https://cl-o.{recipient_id_tag}/api/inbox
   b. POST action token as JSON: {"token": "..."}
   c. Continue on error (best-effort delivery)

3. Return success

HTTP Endpoint: POST /api/inbox

Handler Algorithm:
1. Extract action token from JSON payload
2. No authentication required (token is self-authenticating)
3. Create ActionVerifierTask with token
4. Schedule task in task scheduler (for async processing)
5. Return HTTP 202 (Accepted) immediately
   - Verification and processing happen asynchronously
   - Prevents network timeouts on slow verification

On POST /api/inbox result:

1. Success (Ok):
   - Mark action as delivered in metadata
   - Update delivery status in history

2. Temporary Error (network timeout, 5xx, connection refused):
   - Schedule retry with exponential backoff
   - Maximum 3-5 retry attempts

3. Permanent Error (4xx status, validation error):
   - Log error with context
   - Mark as undeliverable
   - Continue (don't block other deliveries)

{
  "iss": "alice.example.com",      // Requesting instance
  "aud": "bob.example.com",         // Target instance
  "sub": "alice.example.com",       // User identity
  "exp": 1738400000,                // Short-lived (5-60 min)
  "iat": 1738396800,
  "action": "read_file",            // Requested operation
  "resource": "f1~abc123...",       // Resource identifier
  "k": "20250205"                   // Signing key ID
}

Algorithm: Create ProxyToken

Input: requester id_tag, target_instance, action, resource
Output: JWT token string

1. Retrieve latest signing key:
   - Query latest key_id for tenant
   - Load private key from AuthAdapter

2. Build JWT claims:
   - iss: Requester's id_tag
   - aud: Target instance domain
   - sub: Requester's id_tag
   - exp: Current time + 30 minutes
   - iat: Current time
   - action: Requested operation
   - resource: Resource identifier
   - k: Key ID used for signing

3. Sign JWT using ES384 algorithm:
   - Use private key
   - Standard JWT encoding

4. Return base64-encoded JWT

Algorithm: Validate ProxyToken

Input: JWT token string
Output: Result<ProxyTokenClaims>

1. Decode JWT without signature verification (read claims)
2. Extract issuer and key_id from unverified claims
3. Fetch issuer's profile from remote instance
4. Look up public key by key_id in profile
5. Verify JWT signature using issuer's public key (ES384)
6. Check expiration timestamp:
   - If exp < current_time: Return TokenExpired error
7. Check audience claim:
   - If aud != this_instance.base_id_tag: Return InvalidAudience error
8. Return verified claims

Validation ensures:
- Token signed by claimed issuer
- Token not expired
- Token intended for this instance

Algorithm: Sync Attachments

Input: attachment_ids from remote action
Output: Result<()>

For each attachment_id:
1. Check if already exists locally
   - If exists: Skip to next (already synced)

2. Construct remote URL:
   https://cl-o.{issuer_id_tag}/api/file/{attachment_id}

3. Download file from remote instance

4. Verify content integrity:
   - Compute SHA256 hash of downloaded data
   - Compare hash with attachment_id
   - If mismatch: Return FileIntegrityCheckFailed error

5. Store file data in blob adapter

6. Extract and store metadata:
   - Read X-File-Metadata header (if present)
   - Parse as JSON
   - Store in metadata adapter

7. Continue to next attachment

This ensures:
- Content-addressed files (hash = ID)
- No duplicate downloads
- Cryptographic integrity verification

User views post with image attachment
  ↓
Check if image exists locally
  ↓
If not, fetch from remote instance
  ↓
Verify content hash
  ↓
Store locally
  ↓
Serve to user

Algorithm: Sync Profile with Caching

Input: id_tag (remote user identifier)
Output: Result<Profile>

1. Check local cache for profile:
   - If cached AND cache_age < 24 hours: Return cached profile
   - If cache_age >= 24 hours: Continue to step 2

2. Fetch profile from remote instance:
   - GET https://cl-o.{id_tag}/api/me

3. Update local cache:
   - Store profile with current timestamp

4. Return profile

Benefits:
- Reduces network requests (24h TTL)
- Improves performance for repeated access
- Staleness acceptable for user profiles

Need to display Alice's profile
  ↓
Check cache (last updated < 24h?)
  ↓
If fresh: use cache
If stale: fetch from Alice's instance
  ↓
Update cache
  ↓
Display profile

Algorithm: Follow User

Input: follower_id_tag, target_id_tag
Output: Result<()>

1. Create FLLW action token:
   - issuer: follower's id_tag
   - subject: target's id_tag
   - action type: "FLLW"
   - Sign with follower's private key (ES384)

2. Store action locally:
   - Record in metadata adapter
   - Marks that follower follows target

3. Send to target instance:
   - POST https://cl-o.{target_id_tag}/api/inbox
   - Include signed action token

4. Return success

Alice sends CONN to Bob
  ↓
Bob receives, stores CONN
  ↓
Bob sends CONN to Alice
  ↓
Alice receives, detects mutual CONN
  ↓
Connection established (both sides)

Algorithm: Unfollow User

Input: follower_id_tag, target_id_tag
Output: Result<()>

1. Create FLLW action token with removed=true:
   - issuer: follower's id_tag
   - subject: target's id_tag
   - action type: "FLLW"
   - removed: true (indicates unfollow)
   - Sign with follower's private key (ES384)

2. Store action locally:
   - New FLLW action with removed=true
   - Supersedes previous FLLW action
   - Marks unfollow event

3. Send to target instance:
   - POST https://cl-o.{target_id_tag}/api/inbox
   - Include signed action token

4. Return success

The removed=true flag indicates this action cancels the previous follow.

Algorithm: Should Accept Action

Input: action_type, issuer, local_user
Output: bool (accept or reject)

Decision logic by action_type:

1. "POST" → Only from followed or connected users
   - Check relationship between issuer and local_user
   - Accept if: relationship.following OR relationship.connected
   - Reject if: stranger with no relationship

2. "CMNT" / "REACT" → Always accept
   - Verification phase checks ownership of target content
   - Accept all, let verification handle validation

3. "CONN" / "FLLW" → Always accept
   - Relationship requests always received
   - User can block after receiving

4. Other action types → Reject

Algorithm: Block Instance

Input: blocked_instance domain
Output: Result<()>

1. Add instance domain to user's blocklist
2. Store in metadata adapter
3. All future actions from this instance are rejected
4. Return success

User can later unblock by removing from blocklist.