# 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).