Approval Token

This token represents an approval of another user’s content. When you approve someone’s action (e.g., a POST), it signals trust and enables federated fan-out to your followers.

The approval token must NOT contain a content (c) or attachments (a) field. The token must contain a subject (sub) field referencing the action being approved. For other constraints see the Action Tokens.

Content-Addressing

This token is content-addressed using SHA-256:

  • The entire JWT token (header + payload + signature) is hashed
  • Action ID format: a1~{base64_hash}
  • Changing any field invalidates the action_id
  • See Content-Addressing & Merkle Trees for details

Immutability: Once created, an APRV token cannot be modified without changing its action ID.

Purpose

APRV tokens serve several important purposes in the federated network:

  1. Trust Signal: Indicates that you endorse the referenced content
  2. Federated Fan-Out: When you approve a POST, it gets broadcast to your followers along with the approved content
  3. Content Discovery: Helps content spread across the network through trusted connections
  4. Status Update: Updates the original action’s status to ‘Active’ (A) on the original author’s instance

Required Fields

Field Required Description
iss Yes Your identity (the approver)
aud Yes The issuer of the approved action (content creator)
sub Yes The action_id being approved (a1~...)
t Yes “APRV”
c Forbidden Content field is not allowed
a Forbidden Attachments field is not allowed

Subject Reference

The sub (subject) field references the action being approved:

  • Contains the target action’s action_id (a1~...)
  • Target action must exist and be verifiable
  • Creates a non-hierarchical reference

Why Subject Instead of Parent:

  • APRV doesn’t create a visible hierarchy (unlike comments)
  • It references the action without threading
  • The semantic is “this action is about that action”

Broadcast Behavior

APRV tokens have broadcast=true behavior, meaning:

  • When you create an APRV, it’s sent to all your followers
  • The approved action (e.g., the POST) is bundled with the APRV delivery
  • Recipients receive both the APRV and the related action in a single delivery

This is how content spreads across the federated network through trust relationships.

Federation Flow

Creating an Approval

User approves remote content
         │
         ▼
┌─────────────────────────────┐
│ Create APRV token           │
│ - aud = content creator     │
│ - sub = content action_id   │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ schedule_delivery()         │
│ - Check subject broadcast   │
│ - Schedule broadcast fanout │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ schedule_broadcast_delivery │
│ - Get all followers         │
│ - Include original author   │
│ - Bundle approved action    │
└───────────┬─────────────────┘
            │
            ▼
    Delivered to all followers
    with approved POST bundled

Receiving an Approval

When you receive an APRV for your content:

APRV arrives at /inbox
         │
         ▼
┌─────────────────────────────┐
│ ActionVerifierTask          │
│ - Verify JWT signature      │
│ - Check permissions         │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ on_receive hook             │
│ - Find subject action       │
│ - Update status to 'A'      │
└───────────┬─────────────────┘
            │
            ▼
    Your content is now approved

Auto-Approval

The system can automatically create APRV tokens for content from trusted connections. See Auto-Approval for details.

Auto-approval conditions:

  1. Action type must be approvable (POST, MSG, REPOST)
  2. Action is addressed to you (audience = your id_tag)
  3. Sender is different from you
  4. federation.auto_approve setting is enabled
  5. Sender is connected (bidirectional connection established)

When an APRV is delivered, the approved action is included:

{
  "token": "eyJhbGciOi...APRV_TOKEN",
  "related": ["eyJhbGciOi...APPROVED_POST_TOKEN"]
}

Recipients receive both tokens in a single request. The related action is processed after the APRV, with permission checks skipped (pre-approved by the APRV issuer’s trust).

Example

User @alice.cloudillo.net approves a post from @bob.cloudillo.net:

Field Value
iss alice.cloudillo.net
aud bob.cloudillo.net
iat 2024-04-13T00:01:10.000Z
k 20240301
t APRV
sub a1~NAado5PS4j5+abYtRpBELU0e5OQ+zGf/tuuWvUwQ6PA=

Flow:

  1. Alice approves Bob’s post
  2. APRV is sent to Bob (notification)
  3. APRV + Bob’s POST are broadcast to Alice’s followers
  4. Bob’s post status is updated to ‘A’ (Active/Approved)

See Also