Sharenet_Docs/decentralized_cards_primer.md

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:

1. Strong revoke (online gate)

   • Card points to a key gate.
   • Gate can refuse further key requests → instant revoke.

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