132 lines
5.3 KiB
Markdown
132 lines
5.3 KiB
Markdown
# Decentralized Card & Capability Protocol (Draft)
|
||
|
||
## 1. Introduction
|
||
|
||
This document specifies a decentralized protocol for the creation, distribution, and validation of signed and encrypted **Cards**. Cards are the fundamental unit of communication in the system. They may be public or private, and may carry access control, distribution rules, and revocation semantics. The protocol also defines a system of **Capabilities** that allow interoperable feature negotiation without central coordination.
|
||
|
||
This protocol assumes three fundamental building blocks in addition to Cards:
|
||
|
||
- **Passports**: User-held identifiers derived from cryptographic seeds.
|
||
- **Nodes**: Rust-based servers that maintain membership, relay Cards, and enforce network policies.
|
||
- **Networks**: Collections of nodes and users defined by a shared Genesis Document.
|
||
|
||
This specification is written in the style of the [W3C ActivityPub Recommendation](https://www.w3.org/TR/activitypub/).
|
||
|
||
## 2. Terminology
|
||
|
||
- **Card**: A signed object representing a unit of content. Cards may be public or private, and may be encrypted.
|
||
- **Capability (cap)**: A content-addressed specification document that describes a feature, schema, or protocol behavior.
|
||
- **Capability ID (cap_id)**: The multibase-encoded hash of a capability spec. Immutable.
|
||
- **Requirements (`reqs`)**: Capabilities that a verifier MUST support in order to process the Card.
|
||
- **Provenance (`prov`)**: Capabilities the producer actually used when generating the Card. Defaults to `reqs` if omitted.
|
||
- **Bundle (rollup cap)**: A capability that implies a deterministic set of member capabilities.
|
||
- **Policy capsule**: An encrypted structure that defines the Card’s visibility, distribution, and keying material.
|
||
- **Visibility**: Who may decrypt the Card payload.
|
||
- **Distribution**: Where the Card may be transmitted.
|
||
- **Permanent public Card**: A Card with no encryption and no revocation path. Immutable.
|
||
- **Passport**: A user-held self-sovereign identifier derived from a mnemonic seed.
|
||
- **Node**: A server implementing this protocol and providing membership and relay functions.
|
||
- **Network**: A collection of nodes and users sharing a Genesis Document.
|
||
- **Genesis Document**: Immutable initial configuration defining a network.
|
||
|
||
## 3. Cards
|
||
|
||
### 3.1 Structure
|
||
[...] (unchanged content from before)
|
||
|
||
## 4. Capabilities
|
||
[...]
|
||
|
||
## 5. Visibility Modes
|
||
[...]
|
||
|
||
## 6. Distribution Modes
|
||
[...]
|
||
|
||
## 7. Revocation
|
||
[...]
|
||
|
||
## 8. Security Considerations
|
||
[...]
|
||
|
||
## 9. Extensibility
|
||
[...]
|
||
|
||
## 10. Conformance
|
||
[...]
|
||
|
||
## 11. Passports
|
||
|
||
### 11.1 Definition
|
||
A **Passport** is a user’s self-sovereign identifier. It consists of:
|
||
|
||
- A 24-word mnemonic seed (BIP-39 style).
|
||
- A derived Ed25519 keypair (public/private).
|
||
- A DID constructed from the public key.
|
||
|
||
The seed MUST remain private to the user’s device.
|
||
The private key is deterministically derived from the seed.
|
||
The public key is used to generate the DID and sign Cards.
|
||
|
||
### 11.2 Export and Recovery
|
||
- Users MAY export a **Passport file**: a locally encrypted container for the seed.
|
||
- Users MAY recover their Passport from the 24-word mnemonic if the file is lost.
|
||
- A password protects the Passport file, separate from the mnemonic.
|
||
- Importing from file requires the password; importing from mnemonic requires only the words.
|
||
|
||
### 11.3 Usage
|
||
- Cards are signed with the Passport’s Ed25519 private key.
|
||
- Verification uses the DID → public key mapping.
|
||
- Users MAY belong to multiple networks with the same Passport.
|
||
|
||
## 12. Nodes
|
||
|
||
### 12.1 Definition
|
||
A **Node** is a server implementing the protocol, typically written in Rust.
|
||
It provides:
|
||
|
||
- Membership management (accepting/revoking Passports).
|
||
- Card relay and storage.
|
||
- Capability advertisement.
|
||
- Optional Key Gate services for strong revocation.
|
||
|
||
### 12.2 Membership
|
||
- A user joins a Node by presenting a signed request with their Passport public DID.
|
||
- The Node MAY issue a Verifiable Credential (VC) attesting to membership.
|
||
- Users MAY leave a Node by revoking their VC locally.
|
||
- Nodes MAY gossip membership VCs to peers.
|
||
|
||
### 12.3 Federation
|
||
Nodes communicate using Cards.
|
||
Distribution policies determine which nodes are eligible to receive a Card.
|
||
Nodes MAY maintain trustsets to decide forwarding scopes.
|
||
|
||
## 13. Networks
|
||
|
||
### 13.1 Genesis Document
|
||
Each network begins with a **Genesis Document** that defines:
|
||
|
||
- `net_id`: Unique network identifier.
|
||
- `genesis_ts`: Timestamp of creation.
|
||
- `founders`: Initial node and user DIDs.
|
||
- `bootstrap_caps`: Minimal capability set required for participation.
|
||
- `initial_policies`: Distribution and trust defaults.
|
||
|
||
The Genesis Document is signed by the founders and distributed to all participants.
|
||
It MUST be immutable. Any update creates a **new network**.
|
||
|
||
### 13.2 Participation
|
||
- Users MAY join multiple networks.
|
||
- Nodes MAY serve one or more networks, but each Card is bound to a single `net_id`.
|
||
- Networks are sovereign: no privileged global operator exists.
|
||
|
||
### 13.3 Migration
|
||
- Cards and Passports MAY move between networks.
|
||
- Migration of state between networks requires new credentials or attestations.
|
||
- Cards created under one `net_id` remain bound to that `net_id` forever.
|
||
|
||
## Appendix A. Example Public Card
|
||
[...]
|
||
|
||
## Appendix B. Example Private Card (Direct)
|
||
[...]
|