continuist 9586a9d948 Upload files to "/"

2025-09-30 15:59:52 -04:00

4.1 KiB

Raw Blame History

Primer: Decentralized Card & Capability Protocol

This primer introduces the main ideas of the Decentralized Card & Capability Protocol in a simplified, narrative form with examples and diagrams. It complements the full specification.

1. What is a Card?

A Card is a small digital envelope that carries a piece of content (a message, credential, or document). Every Card is:

Signed → you know who made it
Optional encrypted → you can restrict who can read it
Policy-bound → it carries rules for visibility, distribution, and revocation

Think of a Card as a "post" that can be public or private, and can move around the network.

2. Capabilities

Capabilities (caps) describe features in the system. Each cap has a unique ID (a hash of its definition).

Examples:

cap:card/v1 → basic card format
cap:hpke-x25519-xc20p → encryption using HPKE
cap:vc-staple → attach verifiable credentials

Cards declare:

Requirements (reqs) → features a reader MUST support
Provenance (prov) → features the sender’s software actually used (optional)

Bundles (Rollups)

Sometimes a set of caps is used together often. These can be rolled into a bundle cap. Expanding the bundle reveals all the atomic caps inside.

3. Anatomy of a Card

+-------------------------------+
| Signed Envelope (COSE_Sign1)  |
|-------------------------------|
| ver, type, net, rid, ts       |
| reqs, prov                    |
| policy_ref (hash)             |
| content_uri + content_hash    |
+-------------------------------+

Envelope: signed by the creator
Policy capsule: encrypted blob describing visibility & distribution
Content: ciphertext payload (or plaintext for public cards)

4. Visibility Modes

Public: anyone can read
Direct: private to one user
Node: private to members of a node
Trustset: private to nodes your node trusts
Group: private to a specific group of users

Recipient lists are hidden inside the encrypted policy capsule. Outsiders can’t even see who the recipients are.

5. Distribution Modes

Distribution is about where the Card is allowed to go (not who can read it):

to_recipients_only → only to recipients
this_node_only → never leaves a node
trusted_nodes → shared with trusted peers
public → gossip freely

Distribution rules can also be encrypted so outsiders can’t guess your intent.

6. Revocation

Cards that are not permanent can be invalidated later:

Strong revoke (online gate)
- Card points to a key gate.
- Gate can refuse further key requests → instant revoke.
Crypto-shred (offline)
- Keys are wrapped under a KEK.
- Delete the KEK → new readers can’t decrypt.

⚠️ If someone already decrypted before revocation, they still have the plaintext.

7. Example Flows

Public Post

Alice publishes a permanent public Card:

No encryption
Flags permanent_public=true
Anyone can read forever

Private Message

Alice sends Bob a direct Card:

Policy capsule contains an HPKE entry for Bob’s key
Bob decrypts → gets the content
Outsiders can’t see Bob is the recipient

Group Message

Carol posts to her study group:

Policy capsule carries MLS group state
Only members can open it
Outsiders can’t see who’s in the group

8. Why This Matters

Privacy: Audience lists are hidden
Control: Users can revoke their Cards (unless marked permanent public)
Flexibility: Supports nodes, trust sets, and groups without central control
Interoperability: Capabilities make it possible to evolve without breaking old Cards

9. Next Steps

Developers should first implement public cards + direct cards
Then add node/trustset/group encryption
Finally add revocation strategies and bundle caps

This primer is non-normative. For authoritative details, see the full specification.

4.1 KiB Raw Blame History Unescape Escape