136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# 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](./decentralized_cards_spec.md).
|