Subscription Token

This token represents a subscription to a subscribable action, such as a conversation (CONV). Subscriptions control who receives messages and updates from group activities.

The subscription token must contain both a subject (sub) field referencing the subscribable action and an audience (aud) field specifying the owner of that action. 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, a SUBS token cannot be modified without changing its action ID.

Purpose

SUBS tokens serve several important purposes:

  1. Membership Management: Track who is part of a conversation or group
  2. Message Delivery: Determine who receives messages sent to the group
  3. Role Assignment: Assign permissions (observer, member, moderator, admin)
  4. Participation Control: Enable joining, leaving, and role changes

Required Fields

Field Required Description
iss Yes The subscriber’s identity
aud Yes The owner of the subject action (e.g., CONV creator)
sub Yes The action_id being subscribed to (a1~...)
t Yes “SUBS”, “SUBS:UPD”, or “SUBS:DEL”
c Optional Subscription metadata (role, invitedBy, message)

Subtypes

Subtype Description
SUBS Create a new subscription (join)
SUBS:UPD Update subscription (change role)
SUBS:DEL Delete subscription (leave)

Content Structure

The optional content (c) field contains subscription metadata:

{
  "role": "member",
  "invitedBy": "alice.cloudillo.net",
  "message": "Joining the team discussion"
}
Property Type Required Description
role string No Participant role: “observer”, “member”, “moderator”, “admin”
invitedBy string No Identity of the user who invited this subscriber
message string No Optional message when joining

Database Key

The database key for a subscription token is {type}:{sub}:{iss}

Purpose: This key ensures that a user can only have one active subscription to a specific action. The key components are:

  • {type}: “SUBS” (base type)
  • {sub}: Subject ID (what they’re subscribing to)
  • {iss}: Issuer identity (who is subscribing)

Example:

  • Alice subscribes to a CONV → Stored with key SUBS:a1~conv123:alice.example.com
  • Alice updates her subscription → New SUBS:UPD with same key pattern
  • Only ONE active subscription per user per subject

Auto-Accept Logic

When a SUBS token is received, the system determines whether to accept it automatically:

Subscription received
         │
         ▼
┌─────────────────────────────┐
│ Check auto-accept conditions│
└───────────┬─────────────────┘
            │
    ┌───────┴───────┬───────────────┬───────────────┐
    ▼               ▼               ▼               ▼
Subject has    INVT exists     Issuer is      Otherwise
'O' flag?      for user?       subject creator?
    │               │               │               │
    ▼               ▼               ▼               ▼
 Accept          Accept          Accept          Reject
 (Open)         (Invited)       (Creator)      (status='R')

Auto-accept conditions (any one is sufficient):

  1. Subject action has the ‘O’ flag (open - anyone can join)
  2. An INVT token exists for this user + subject combination
  3. The subscriber is the creator of the subject action

If none of these conditions are met, the subscription is rejected (status=‘R’).

Participant Roles

Subscriptions can specify different access levels:

Role Can Read Can Write Can Invite Can Moderate Can Admin
observer Yes No No No No
member Yes Yes No No No
moderator Yes Yes Yes Yes No
admin Yes Yes Yes Yes Yes

Default role: member (if not specified)

Federation Flow

Subscribing to a Conversation

User creates SUBS token
         │
         ▼
┌─────────────────────────────┐
│ Local processing            │
│ - Validate subject exists   │
│ - Check for INVT or 'O'     │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ schedule_delivery()         │
│ - Send to subject owner     │
└───────────┬─────────────────┘
            │
            ▼
    Owner receives SUBS
         │
         ▼
┌─────────────────────────────┐
│ on_receive hook             │
│ - Check auto-accept logic   │
│ - Accept or reject          │
│ - Update subscription list  │
└─────────────────────────────┘

Receiving Messages After Subscription

Once subscribed, messages sent to the conversation are delivered via fan-out:

Message sent to CONV
         │
         ▼
┌─────────────────────────────┐
│ schedule_subscriber_fanout()│
│ - Walk parent chain to CONV │
│ - Get all SUBS for CONV     │
│ - Deliver to each subscriber│
└─────────────────────────────┘

Leaving a Conversation

User creates SUBS:DEL token
         │
         ▼
┌─────────────────────────────┐
│ Delivered to subject owner  │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ on_receive hook             │
│ - Mark SUBS as deleted      │
│ - Remove from subscriber    │
│   list                      │
└─────────────────────────────┘
            │
            ▼
    User no longer receives
    messages from conversation

Example

User @bob.cloudillo.net subscribes to a conversation owned by @alice.cloudillo.net:

Field Value
iss bob.cloudillo.net
aud alice.cloudillo.net
iat 2024-04-13T00:01:10.000Z
k 20240301
t SUBS
sub a1~NAado5PS4j5+abYtRpBELU0e5OQ+zGf/tuuWvUwQ6PA=
c {“role”: “member”, “invitedBy”: “alice.cloudillo.net”}

Status Values

Status Description
A (Active) Subscription is active, user receives messages
R (Rejected) Subscription was rejected (no invitation, not open)
D (Deleted) User left or was removed from the group

See Also