# Sharenet Protocol Specification (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.  
- **Hubs**: Servers that maintain membership, relay Cards, and enforce network policies.  
- **Universes**: Collections of hubs and users defined by a shared Genesis Document.

## 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.  
- **Hub**: A server implementing this protocol and providing membership and relay functions.  
- **Universe**: A collection of hubs and users sharing a Genesis Document.  
- **Genesis Document**: Immutable initial configuration defining a universe.  

## 3. Cards

### 3.1 Structure

A Card is a CBOR map wrapped in a COSE_Sign1 envelope. Fields:

- `ver`: Protocol version.  
- `type`: MUST be `"card"`.  
- `univ`: Universe identifier.  
- `rid`: Unique Card identifier.  
- `ts`: Creation timestamp.  
- `reqs`: Array of capability IDs required to interpret the Card.  
- `prov`: Optional. Array of capabilities actually used. If absent, treated as identical to `reqs`.  
- `policy_hash`: Integrity hash of the policy capsule (encrypted for private Cards, plaintext for public Cards).
- `payload_hash`: Integrity hash of the payload.
- `payload`: The actual payload (ciphertext for private Cards, plaintext for public Cards).
- `policy`: The policy capsule (encrypted for private Cards, plaintext for public Cards).
- `dist_tag`: Optional opaque routing hint.  
- `sig`: Producer signature.  

### 3.2 Policy Capsule

The policy capsule is an encrypted CBOR map. Fields:

- `vis`: `"public" | "direct" | "hub" | "federation" | "group"`.
- `dist`: `"recipients" | "hub" | "federation" | "public"`.
- `keying`: HPKE encapsulations, MLS group material, or gate instructions for CEK recovery.  
- `flags`: e.g. `permanent_public`.  
- `exp`, `ttl`: Optional expiry or validity constraints.  
- `pad`: Optional padding to obscure audience size.  
- `roster_encrypted`: Optional, group roster encrypted under the group secret.  

### 3.3 Payload

- Private Cards: `payload` = AEAD(CEK, plaintext_card_body, AAD={univ, rid, policy_hash})
- Public Cards: `payload` = plaintext_card_body
- `payload_hash` = SHA-256(payload)

## 4. Capabilities

### 4.1 Capability ID

```
cap_id = multibase( sha256( canonical_cbor(spec_without_signatures) ) )
```

### 4.2 Capability Spec

A capability spec is a signed document:

- `schema`: MUST be `"cap-spec/v1"`.  
- `name`: Human-friendly name.  
- `semver`: Version.  
- `purpose`: Summary of semantics.  
- `behavior`: Protocol rules.  
- `interop`: `{requires, supersedes, conflicts}`.  
- `test_vectors`: Golden values for conformance.  
- `docs_uri`: Documentation.  
- `signatures`: Array of COSE signatures from authors/curators.  

### 4.3 Bundles

A bundle spec lists `members` (cap IDs). Bundles MUST expand deterministically into their atomic members before enforcement.

### 4.4 Negotiation

- Hubs advertise supported caps at `/.well-known/hub-caps`.  
- Cards include `reqs` for enforcement, `prov` for provenance.  
- Consumers MUST reject Cards if any `reqs` are unsupported.  

## 5. Visibility Modes

- **Public**: No encryption. MAY be flagged permanent.  
- **Direct**: Encrypted CEK to a single recipient (HPKE).  
- **Hub**: CEK encrypted to a hub’s group key or gate.  
- **Federation**: CEK encrypted to each trusted hub’s group key.  
- **Group**: CEK encrypted to an MLS group. Roster MAY remain private.  

## 6. Distribution Modes

- **recipients**: Honest hubs forward only to recipients.  
- **hub**: Not gossiped beyond hub.  
- **federation**: Forwarded only to federation.  
- **public**: Freely gossiped. Encryption still protects confidentiality.  

Distribution policies MAY be encrypted inside the policy capsule.

## 7. Revocation

- **Permanent public cards**: Irrevocable.  
- **Strong revoke (online gate)**: CEK fetched from gate; revocation = disable at gate. Instant, requires availability.  
- **Crypto-shred (offline)**: CEK wrapped under KEK. Revocation = delete KEK. Prevents new decryption, not past.  
- **Card Revocation List (CRL)**: Optional signed log of revoked card IDs. Honest clients suppress display.  

## 8. Security Considerations

- All hashes MUST be computed over canonical CBOR.  
- Policy capsule MUST bind `{univ, rid, payload_hash}` in AEAD AAD.  
- Bundles MUST be expanded before enforcement.  
- Unknown required caps MUST cause rejection.  
- Distribution enforcement relies on honest hubs; confidentiality relies on crypto.  
- Padding SHOULD be used to obscure audience sizes.  

## 9. Extensibility

- New caps define new features, schemas, and crypto suites.  
- Specs are content-addressed, so evolution produces new cap IDs.  
- Cards MAY carry adapters in `reqs` to allow downgrade/interop.  
- Deprecated caps SHOULD publish signed deprecation notices.  

## 10. Conformance

A conforming implementation MUST:  
- Validate COSE signatures and hashes.  
- Enforce all capabilities in `reqs`.  
- Expand bundles before enforcement.  
- Respect revocation policies.  
- Reject unsupported or malformed Cards.  

## 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 NOT belong to multiple universes with the same Passport.  

## 12. Hubs

### 12.1 Definition
A **Hub** 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 Hub by presenting a signed request with their Passport public DID.  
- The Hub MAY issue a Verifiable Credential (VC) attesting to membership.  
- Users MAY leave a Hub by revoking their VC locally.  
- Hubs MAY gossip membership VCs to peers.  

### 12.3 Federation
Hubs communicate using Cards.  
Distribution policies determine which hubs are eligible to receive a Card.  
Hubs MAY maintain federations to decide forwarding scopes.  

## 13. Universes

### 13.1 Genesis Document
Each universe begins with a **Genesis Document** that defines:

- `univ_id`: Unique universe identifier.  
- `genesis_ts`: Timestamp of creation.  
- `founders`: (Optional) Initial hub and user DIDs.  
- `bootstrap_caps`: Minimal capability set expected for participation. May be overcome by events.
- `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 universe**.

### 13.2 Participation
- Users MAY join multiple universes.  
- Hubs MAY serve one or more universe, but each Card is bound to a single `univ_id`.  
- Universes are sovereign: no privileged global operator exists.  

### 13.3 Migration
- Cards and Passports MAY NOT move between universes.
- Passports created under one `univ_id` remain bound to that `univ_id` forever.
- Cards created under one `univ_id` remain bound to that `univ_id` forever.

## 14. Security Model & Assumptions

The protocol operates under the following assumptions and goals:

- **Honest-but-curious hubs**: Hubs may relay Cards faithfully but attempt to learn additional metadata.  
- **Malicious peers**: Adversaries may forge, replay, strip capabilities, or attempt downgrade attacks.  
- **Passive observers**: Adversaries may monitor network traffic but lack access to private keys.  
- **Compromised devices**: If a user’s Passport seed is stolen, their identity is compromised until rotated.  
- **Goals**: Confidentiality of private Cards, authenticity of signatures, integrity of metadata (AAD), forward secrecy when possible, and user ability to revoke non-permanent Cards.  

## 15. Cryptographic Primitives & Parameters

Implementations MUST use the following algorithms unless explicitly negotiated by capabilities:

- **AEAD**: XChaCha20-Poly1305 with 256-bit keys.  
- **HPKE**: DHKEM(X25519, HKDF-SHA256) with AEAD-CHACHA20POLY1305.  
- **Signatures**: Ed25519 for Passports.  
- **Hashing**: SHA-256 for `content_hash`, `policy_ref`, and capability IDs.  
- **KDFs**: HKDF-SHA256 for deriving CEKs and KEKs.  
- **Randomness**: CEKs MUST be generated with a CSPRNG; nonces MUST NOT repeat.  
- **AAD binding**: `{univ, rid, content_hash, policy_ref}` MUST be included as Additional Authenticated Data in all AEAD operations.  

## 16. Key Management & Rotation

### 16.1 Hierarchy
- **Seed**: Root of identity, represented as a 24-word mnemonic.  
- **Ed25519 keypair**: Derived deterministically from the seed. Used for DIDs and signing.  
- **CEK (Content Encryption Key)**: Fresh symmetric key per Card.  
- **KEK (Key Encryption Key)**: Optional higher-level key wrapping CEKs, enabling revocation by deletion.  

### 16.2 Rotation
- Users MAY rotate Passport keys by generating a new keypair from the seed with a different derivation path.  
- DID key rotation certificates MAY be issued: signed by both old and new keys, linking continuity.  
- Hubs and verifiers MUST accept a chain of rotation certificates when validating historical Cards.  

### 16.3 Revocation
- Revocation of Cards MAY occur via deletion of KEKs (crypto-shred) or via refusal to release CEKs (online gate).  
- Membership credentials (VCs) MUST include status lists or revocation registries to support user exit from hubs.

## 17. Policy Capsule Wire Format

### 17.1 Encoding
- The policy capsule is encoded as **CBOR**, then wrapped in **COSE_Encrypt0**.  
- Key encapsulation MAY use **HPKE** (per recipient) or **MLS** (per group).  
- The capsule MUST be integrity-protected with AEAD; AAD MUST include `{univ, rid, payload_hash}`.  

### 17.2 Structure (plaintext before encryption)
```cbor
{
  "vis": "public" | "direct" | "hub" | "federation" | "group",
  "dist": "recipients" | "hub" | "federation" | "public",
  "keying": {
    "hpke": [ { "kid": <recipient_id>, "enc": <hpke_encap> }, ... ],
    "mls": { "group_id": bstr, "epoch": int, "welcome": bstr },
    "gate": { "uri": tstr, "aud": bstr, "ttl": int }
  },
  "flags": { "permanent_public": bool, ... },
  "exp": int,  ; expiry timestamp (optional)
  "pad": bstr, ; optional padding
  "roster_encrypted": bstr ; optional roster encrypted under group secret
}
```

### 17.3 Padding
- To obscure audience size, implementers SHOULD pad the capsule to fixed bucket sizes (e.g. 1kB, 2kB, 4kB).  
- `pad` MUST be random bytes ignored by consumers.  

### 17.4 Roster Secrecy
- Group rosters MUST NOT appear in plaintext.  
- If included, `roster_encrypted` MUST be encrypted under the group key.  

---

## 18. Revocation: Gate API, Crypto-Shred, and Status Lists

### 18.1 Gate API
An optional HTTP(S) service MAY act as a **key gate**.

Endpoints:
- `POST /cek` → returns CEK wrapped for the requester.  
- `POST /decrypt` → returns plaintext stream of Card body.  

Rules:
- Requests MUST carry an **audience binding** (`rid`, `univ`).  
- Gates MUST enforce **TTL** on issued tokens.  
- Rate limits and replay protection MUST be applied.  
- Revocation = gate refuses further issuance.

### 18.2 Crypto-Shred
- CEK is wrapped under a KEK stored at a hub or device.  
- Revocation = securely delete KEK.  
- Clients encountering missing KEK MUST treat the Card as revoked.  

### 18.3 Card Revocation Lists (CRL)
- A CRL is a signed CBOR array of revoked `rid`s with metadata:  
```cbor
{
  "univ": <univ_id>,
  "ts": <timestamp>,
  "revoked": [ <rid1>, <rid2>, ... ]
}
```
- CRLs MUST be signed by the issuer (user or hub).  
- Clients MUST hide revoked Cards even if cached.  
- Freshness MUST be enforced (CRL expiry or versioning).  

---

## 19. Distribution Rules & Relay Behavior

### 19.1 Enforcement by Honest Hubs
- **recipients**: forward only if hub is itself a recipient or directly connected to one.  
- **hub**: MUST NOT forward beyond local storage.  
- **federation**: MAY forward only to hubs in the local federation.  
- **public**: MAY forward freely.  

### 19.2 Logging
- Hubs SHOULD log distribution violations (attempts to forward beyond scope).  
- Logs MUST contain only hashes (`rid`, `content_hash`), not plaintext.  

### 19.3 Confidentiality Interaction
- Distribution rules are **policy**, not crypto.  
- Confidentiality is preserved by encryption regardless of distribution.  
- Even if a Card leaks beyond scope, non-recipients cannot decrypt.  

### 19.4 Error Signaling
- If a hub refuses to forward a Card due to distribution rules, it SHOULD return an error code:  
  - `err_dist_scope` = distribution violation  
  - `err_recipient_only` = not a recipient

## 20. Transport & Gossip Protocol

### 20.1 Discovery
- Hubs MAY be discovered via:
  - Static configuration files or bootstrap lists.
  - Distributed Hash Table (DHT) lookups.
  - Rendezvous services (non-privileged).

### 20.2 Message Relay
- Cards are propagated between peers using gossip-style replication.  
- Implementations SHOULD batch multiple Cards into a single message for efficiency.  
- Backoff strategies MUST be applied when peers are overloaded or unresponsive.

### 20.3 Deduplication and Replay Protection
- Every Card has a unique `rid`.  
- Hubs MUST maintain a deduplication cache to avoid re-processing the same Card.  
- Replay attacks MUST be prevented by rejecting Cards with duplicate `rid`s or stale timestamps.

### 20.4 Idempotency and Limits
- All Card handling MUST be idempotent: re-processing MUST NOT change system state.  
- Maximum Card size SHOULD be capped (e.g. 1 MB).  
- Hubs MAY reject or truncate oversized payloads.  

---

## 21. Identifiers, Timestamps, and Causality

### 21.1 RIDs
- `rid` is the globally unique identifier for a Card.  
- Recommended format: **UUIDv7** (time-ordered, random component).  
- Collisions are cryptographically improbable; hubs MUST treat duplicates as replay attempts.

### 21.2 Timestamps
- Each Card includes a creation timestamp (`ts`).  
- Verifiers SHOULD accept timestamps within a tolerance window (e.g. ±5 minutes) to handle clock skew.  
- Cards outside this window MAY be flagged or rejected.

### 21.3 Causality and Linking
- Cards MAY include causal references:  
  - `prev`: previous Card in a sequence.  
  - `thread`: identifier for a conversation thread.  
- Verifiers MAY use these references to reconstruct conversations or detect edits.  

---

## 22. Schema Packages & Module Loading

### 22.1 Package Format
- Schemas are distributed as **content-addressed packages** (hash = ID).  
- Packages MUST include:
  - Schema definition (e.g., JSON Schema or CDDL).  
  - Version metadata.  
  - Optional validation logic.  

### 22.2 Signatures and Trust
- Packages SHOULD be signed by their authors.  
- Hub admins MAY define local trust policies (e.g., trusted keyrings).  
- Unsigned or untrusted packages MAY be rejected.  

### 22.3 Module Execution
- Validation logic MAY be provided as **WebAssembly (WASM) modules**.  
- Hubs MUST sandbox modules with:
  - CPU, memory, and time limits.  
  - Deterministic APIs for schema validation and normalization.  

### 22.4 Installation
- Packages MAY be installed automatically from peers or manually by hub admins.  
- A CLI MAY be provided:  
```bash
syspm install <package_hash>
```
- Auto-installed packages MUST be verified by signature and hash.  
- Admin-installed packages override peer-provided ones.  

## 23. Capability Specs, Bundles, and Lifecycle

### 23.1 Capability Specs
- Capabilities are described in signed **spec documents**, encoded in CBOR.  
- Each spec MUST include:
  - `cap_id`: multibase-encoded SHA-256 hash of the spec.  
  - `version`: semantic version string.  
  - `description`: human-readable text.  
  - `deps`: optional list of dependent capabilities.  
- Specs SHOULD be signed by their authors to establish provenance.  

### 23.2 Bundles
- A bundle is a capability that expands into a fixed set of other capabilities.  
- Bundles MAY form a directed acyclic graph (DAG).  
- Expansion MUST be canonical (deterministic order by `cap_id`).  
- Consumers MUST fully expand bundles before validation.  

### 23.3 Deprecation
- A deprecated capability MUST include a **deprecation notice** object:
```cbor
{
  "deprecated": true,
  "replacement": [ <cap_id1>, <cap_id2> ],
  "reason": tstr
}
```
- Consumers SHOULD reject deprecated caps unless explicitly whitelisted.  
- Producers SHOULD migrate to replacements at earliest opportunity.  

---

## 24. Hub Roles & Federations

### 24.1 Hub Roles
Hubs MAY declare one or more roles:  
- **archive**: long-term storage of all Cards.  
- **relay**: ephemeral forwarder, minimal storage.  
- **light**: partial state, relies on peers for history.  

Roles MAY be declared in Hub metadata and MAY guide peer selection.  

### 24.2 Federations
- A federation is a locally defined list of hubs considered trustworthy by a given hub.  
- Federations MAY be defined by DID, fingerprint, or signed config.  
- Federations MUST be rotatable without changing the Genesis Document.  
- Distribution rules (e.g. “federation”) are enforced using federations.  

### 24.3 Rotation
- Federations SHOULD support rotation via signed update lists.  
- Hubs MAY advertise federation digests to peers.  
- Discrepancies MAY be logged for audit.  

---

## 25. Membership Credentials & Status

### 25.1 VC Schema
A membership Verifiable Credential (VC) MUST contain:  
```cbor
{
  "vc": {
    "sub": <user_did>,
    "iss": <hub_did>,
    "claim": "membership",
    "univ": <univ_id>,
    "ts": <issued_timestamp>,
    "exp": <expiry_timestamp>
  },
  "sig": <signature_by_hub>
}
```

### 25.2 Status Lists
- Hubs MAY maintain status lists indicating active, revoked, or suspended memberships.  
- Status lists MUST be signed and periodically refreshed.  
- Clients MUST check membership status before validating Cards.  

### 25.3 Verification
- To validate a Card:
  - Verify the Card signature against the user’s DID.  
  - Fetch the user’s membership VC for the target hub/universe.  
  - Check the VC’s signature, validity window, and status list entry.  
- Historical Cards MUST remain valid if the VC was active at the time of creation.

## 26. Universe Genesis, Publication, and Forks

### 26.1 Canonical Genesis
- The Genesis Document MUST be encoded in canonical CBOR.  
- The `univ_id` is computed as `SHA-256` of the canonical bytes.  
- Genesis MUST include:
  - `univ_id`, `genesis_ts`, founders (hub/user DIDs), bootstrap capabilities, and policies.  
- Genesis is immutable. Any change results in a new `univ_id` and thus a new universe.  

### 26.2 Multi-Signature Policy
- Genesis SHOULD be co-signed by multiple founders.  
- Minimum signature threshold MUST be specified (e.g., 2-of-3).  
- Verifiers MUST reject Genesis docs without sufficient signatures.  

### 26.3 Publication Channels
- Genesis MAY be published via:
  - Static files.  
  - Peer-to-peer distribution.  
  - Content-addressed storage (IPFS, Git, etc.).  

### 26.4 No-Tombstone Rule
- Once published, a Genesis Document MUST NOT be deleted.  
- Universes have permanence; dissolution only occurs if all peers stop participating.  

### 26.5 Fork Handling
- If conflicting successor Genesis docs appear, each creates a distinct new `univ_id`.  
- Participants MAY choose which fork to join.  
- Forks MUST NOT silently overwrite each other.  

---

## 27. Passport Storage & Recovery

### 27.1 Secure Storage Recommendations
- **iOS**: Secure Enclave + Keychain.  
- **Android**: Keystore with StrongBox if available.  
- **macOS**: Keychain, optionally hardware-backed.  
- **Windows**: DPAPI + TPM if present.  
- **Linux**: Kernel keyrings, Gnome Keyring, or hardware token (e.g., YubiKey).  
- **Raspberry Pi**: Encrypted filesystem or external hardware token.  

### 27.2 Export Format
- Passport file MUST be an **envelope**:  
```cbor
{
  "enc_seed": <seed_encrypted_under_kek>,
  "kdf": "HKDF-SHA256",
  "cipher": "XChaCha20-Poly1305",
  "salt": bstr,
  "nonce": bstr
}
```
- Protected with a KEK derived from a user-chosen password.  

### 27.3 Recovery from Mnemonic
- A 24-word BIP-39 mnemonic MAY recreate the seed if the file is lost.  
- No password required unless PBKDF2 passphrase extension is used.  
- Users SHOULD be instructed to back up the mnemonic offline in a safe place.  

### 27.4 Password Policies
- Passwords protecting Passport files SHOULD be high-entropy.  
- Minimum recommended length: 12 characters.  
- Implementations MAY enforce rate limiting to prevent brute-force attacks.  

### 27.5 Device-as-Gate
- Devices MAY serve as ephemeral gates: refusing to release CEKs unless locally approved.  
- Useful for preventing silent key misuse if the device is compromised.  

---

## 28. Privacy Considerations

### 28.1 Metadata Minimization
- Cleartext MUST be minimized: only `rid`, `cap_ids`, and distribution policies are visible.  
- Membership VCs SHOULD NOT be included unless necessary.  
- Recipient lists MUST remain encrypted when possible.  

### 28.2 Padding
- Implementations SHOULD pad policy capsules and encrypted payloads to fixed sizes.  
- Padding helps obscure audience size and plaintext length.  

### 28.3 Cover Traffic
- Hubs MAY generate synthetic Cards with random content to obscure traffic patterns.  
- Cover traffic MUST be clearly marked so peers can discard after validation.  

### 28.4 CEK Caching
- Recipients MAY cache CEKs for performance.  
- Caches MUST expire after a reasonable TTL (e.g., 24 hours).  
- Revoked CEKs MUST be purged immediately if a CRL or gate refusal is received.  

### 28.5 Oblivious HTTP for Gates
- Gates MAY use **Oblivious HTTP** to conceal requester identity.  
- This prevents correlation between user DID and requested Card IDs. 

## 29. Abuse & Resource Controls

### 29.1 Rate Limits
- Hubs MUST enforce per-peer request limits to prevent denial of service.  
- Suggested baseline: 100 requests/minute per peer, adjustable by implementation.  

### 29.2 Proof-of-Work or Postage
- Networks MAY require lightweight proof-of-work or postage tokens.  
- This mitigates spam and incentivizes responsible use of resources.  

### 29.3 Object Size Limits
- Maximum Card size SHOULD be capped (e.g., 1 MB).  
- Oversized Cards MAY be rejected with `err_size_exceeded`.  

### 29.4 Sandbox Budgets
- WASM modules used for schema validation MUST run in strict sandboxes.  
- Execution MUST be limited to:  
  - CPU time (e.g., 100ms).  
  - Memory (e.g., 16 MB).  
- Modules exceeding budgets MUST be terminated.  

### 29.5 Signature Verification Quotas
- Hubs SHOULD limit the number of signature verifications per peer per unit time.  
- Helps protect against CPU exhaustion attacks.  

### 29.6 Ban Lists
- Hubs MAY maintain local ban lists of misbehaving peers.  
- Ban lists SHOULD be rotatable and MAY be shared among trusted peers.  

---

## 30. Errors & Diagnostics

### 30.1 Error Codes
Implementations MUST support the following error codes for interoperability:

- `err_req_missing`: Required field missing.  
- `err_schema_unsupported`: Schema not recognized.  
- `err_cap_unknown`: Capability not recognized.  
- `err_revoked`: Card has been revoked.  
- `err_gate_denied`: Gate refused to provide CEK.  
- `err_dist_scope`: Distribution rule violation.  
- `err_recipient_only`: Hub not an intended recipient.  
- `err_size_exceeded`: Payload too large.  

### 30.2 Error Format
Errors MUST be encoded as CBOR objects:  
```cbor
{
  "err": <error_code>,
  "rid": <card_id>,
  "hint": tstr
}
```
- `hint` is an optional human-readable remediation suggestion.  

### 30.3 Logging
- Errors SHOULD be logged locally for diagnostics.  
- Logs MUST redact sensitive payload data.  

---

## 31. Conformance Profiles & Test Vectors

### 31.1 Profiles
- **Baseline Profile**: MUST implement  
  - Ed25519 signatures.  
  - XChaCha20-Poly1305 AEAD.  
  - Direct HPKE.  
  - Public and direct private Cards.  

- **Extended Profile**: MUST additionally implement  
  - MLS groups.  
  - Gate-based revocation.  
  - Cover traffic.  
  - Schema packages with WASM validation.  

### 31.2 Mandatory-to-Implement Capabilities
- `cap:sign/ed25519`  
- `cap:encrypt/xchacha20poly1305`  
- `cap:hpke/x25519-sha256`  

### 31.3 Test Vectors
The specification MUST include canonical CBOR + COSE test vectors for:  
- Public Card.  
- Direct HPKE-encrypted Card.  
- MLS group-encrypted Card.  
- Gate token retrieval.  
- CRL with revoked Cards.  

Implementations MUST validate against these vectors to ensure interoperability.

## 32. Content Addressing & Storage

### 32.1 Hash Algorithms
- Content hashes MUST use SHA-256 by default.  
- Alternative hash functions MAY be advertised via capability IDs.  
- The `content_hash` MUST uniquely identify the payload of a Card.  

### 32.2 URIs
- Content MAY be referenced via URIs:  
  - `ipfs://<cid>`  
  - `https://<host>/<path>`  
  - `s3://<bucket>/<object>`  
- Implementations MUST verify integrity by recomputing the hash.  

### 32.3 Chunking and Range Fetch
- Large payloads MAY be split into chunks.  
- Chunks MUST each carry their own `content_hash`.  
- Range fetch MUST allow partial retrieval and recombination.  

### 32.4 Retention and Garbage Collection
- Hubs MAY garbage-collect old payloads not recently requested.  
- Garbage collection policies MUST NOT break integrity: missing payloads must be detectable via hashes.  
- Permanent public Cards SHOULD be retained indefinitely.  

---

## 33. Observability & Audit

### 33.1 Minimal Logging
- Hubs SHOULD log only:  
  - `rid`  
  - `cap_ids`  
  - error codes  
- Payloads and policy capsules MUST NOT be logged in plaintext.  

### 33.2 Redaction Rules
- Logs MUST redact personally identifiable information (PII).  
- Only hashed identifiers may be retained for correlation.  

### 33.3 Migration Receipts
- When a Card is re-issued due to schema or protocol migration, hubs MAY attach a signed **migration receipt**:  
```cbor
{
  "old_rid": <rid>,
  "new_rid": <rid>,
  "ts": <timestamp>,
  "sig": <signature_by_hub>
}
```
- Receipts provide an auditable trail for backward compatibility.  

### 33.4 Telemetry
- Aggregate, privacy-preserving telemetry MAY be published (e.g., number of Cards relayed).  
- Telemetry MUST NOT expose user identifiers or Card contents.  

---

## 34. Human Aliases & I18N

### 34.1 Aliases for Capabilities
- Capabilities MAY have human-readable aliases.  
- Aliases are **non-authoritative** and for UI purposes only.  
- Each alias MUST map to a single `cap_id`, but a `cap_id` MAY have multiple aliases.  

### 34.2 Localization
- Aliases MAY be localized into different languages.  
- Localization data MUST be distributed separately from the canonical spec.  

### 34.3 Collision Handling
- If two aliases collide:  
  - Hub admins MAY configure preferred mappings.  
  - UIs SHOULD disambiguate by showing both alias and `cap_id`.  

### 34.4 Example
```cbor
{
  "alias": "en:signatures/ed25519",
  "cap_id": "zQm..."
}
```

## 35. Security Bulletins

### 35.1 Purpose
- Security bulletins provide a mechanism to urgently disable compromised capabilities, algorithms, or schema packages.  
- Bulletins are signed notices distributed across the universe.  

### 35.2 Structure
```cbor
{
  "bulletin": "disable",
  "cap_id": <capability_id>,
  "reason": tstr,
  "ts": <timestamp>,
  "sig": <signature_by_issuer>
}
```

### 35.3 Issuers
- Bulletins MAY be issued by capability authors, universe founders, or hub operators.  
- Clients MUST verify the issuer’s signature against a trusted keyring.  

### 35.4 Client Behavior
- Upon receiving a valid bulletin:
  - Clients MUST immediately reject any Card requiring the disabled capability.  
  - Historical Cards MAY remain valid unless otherwise specified.  
  - Warnings SHOULD be logged for operator review.  

### 35.5 Distribution
- Bulletins MAY be distributed via gossip, CRLs, or dedicated feeds.  
- Clients SHOULD retain bulletins for audit purposes.  

---

## 36. Evolution Without Epochs

### 36.1 Approach
- This protocol evolves without centralized epochs.  
- Capabilities (`cap_id`s) are the atomic unit of evolution.  
- Each new schema or feature is expressed as a new capability.  

### 36.2 Reqs Defaulting
- Cards MUST include a `reqs` field listing required capabilities.  
- If `prov` is omitted, verifiers MUST assume `prov = reqs`.  
- This ensures backward compatibility when producers omit `prov`.  

### 36.3 Prov Optionality
- The `prov` field MAY list capabilities actually used to generate the Card.  
- If present, `prov` MUST be a subset of `reqs`.  
- Consumers MAY use `prov` for debugging or migration tracking.  

### 36.4 Breaking Changes
- A breaking schema change MUST result in a new `cap_id`.  
- Producers MUST NOT reuse `cap_id`s for incompatible updates.  
- Consumers MUST reject Cards that require unknown or deprecated `cap_id`s.  

### 36.5 Adapters
- Hubs MAY provide **adapters** to transform Cards from older schema versions to newer ones.  
- Adapters MUST be deterministic and SHOULD be distributed as signed schema packages.  
- Consumers MUST record the use of adapters in audit logs.  

## Appendix A. Example Public Card

```json
{
  "ver": 1,
  "type": "card",
  "univ": "univ:prod:z9…",
  "rid": "0x12b…",
  "ts": 1738123456,
  "reqs": ["cap:card/v1@…"],
  "policy_hash": "sha256:…",
  "payload_hash": "sha256:…",
  "payload": { "msg": "hello world" },
  "policy": {
    "vis": "public",
    "dist": "public",
    "flags": { "permanent_public": true }
  }
}
```

## Appendix B. Example Private Card (Direct)

```json
{
  "ver": 1,
  "type": "card",
  "univ": "univ:prod:z9…",
  "rid": "0x44a…",
  "ts": 1738126789,
  "reqs": ["cap:card/v2@…","cap:hpke-x25519-xc20p@…"],
  "policy_hash": "sha256:7f…",
  "payload_hash": "sha256:aa…",
  "payload": "<ciphertext>",
  "policy": "<encrypted_policy_capsule>"
}
```

---

**Status of this Document**  
This is a working draft. It is subject to change as the protocol evolves. Implementers SHOULD anticipate breaking changes and support migration strategies.

# Object Taxonomy & Wire Types (Draft Addendum)

This addendum enumerates object types beyond **Cards** that a compliant implementation SHOULD/MUST support. It groups them by plane (data, control, governance/ops) and specifies wire shapes, minimal required fields, and security properties. Language follows the style of W3C specs used in the main document.

---

## 1. Conventions

- All objects are encoded as **CBOR**.  
- Signed objects use **COSE_Sign1** (envelope outside the CBOR map).  
- Encrypted objects use **COSE_Encrypt0**; HPKE/MLS may be used to deliver content keys.  
- Hashes MUST be over **canonical CBOR**.  
- `rid` identifies a Card; non-Card objects have their own identifiers as noted.  
- Capability IDs (`cap_id`) are multibase-encoded SHA-256 of the canonical spec bytes.

---

## 2. Data-Plane Objects

### 2.1 Media / Blob Chunks
**Purpose:** Large attachments referenced from Cards.

**Integrity:** `content_hash` (SHA-256) over the chunk bytes.  
**Encryption:** OPTIONAL; if used, reference ciphertext hash.

**Shape (meta, unsigned or signed)**:
```cbor
{
  "schema": "blob-meta/v1",
  "content_uri": tstr,
  "content_hash": bstr,  ; sha256 digest
  "size": uint,
  "mime": tstr
}
```

### 2.2 Search / Index Hints (Optional)
**Purpose:** Precomputed, normalized views to aid indexing/search.

**Security:** MUST be **signed** by the producer.

```cbor
{
  "schema": "index-hint/v1",
  "rid": bstr,
  "view": { * tstr => any }  ; normalized fields per schema module
}
```

---

## 3. Control-Plane Objects

### 3.1 Schema Packages
**Purpose:** Define fields & validation for schema-specific payloads.

**Security:** MUST be **signed** by author/curators.  
**Fetch:** Content-addressed by `schema_id` (hash of canonical package bytes).

```cbor
{
  "schema": "schema-package/v1",
  "schema_id": tstr,           ; cap:schema:<family>/<major>@<hash>
  "defs": { ... },             ; CDDL/JSON Schema/CUE
  "module": {                  ; OPTIONAL WASM validator/normalizer
    "type": "wasm",
    "hash": bstr,
    "size": uint
  },
  "test_vectors": [ bstr, ... ],
  "docs_uri": tstr
}
```

### 3.2 Schema Descriptors
**Purpose:** Operator-friendly pointer to install a module out-of-band.

**Security:** MUST be **signed**. Hub validates artifact hash before load.

```cbor
{
  "schema": "schema-desc/v1",
  "schema_id": tstr,
  "module": {
    "id": tstr,
    "version": tstr,
    "artifact_hash": bstr,
    "size": uint,
    "signatures": [ bstr, ... ]
  }
}
```

### 3.3 Capability Specs & Bundles
**Purpose:** Advertise features/algorithms/behaviors. Bundles roll up sets.

**Security:** MUST be **signed**.  
**Bundle rule:** MUST expand deterministically to atomic caps before enforcement.

```cbor
{
  "schema": "cap-spec/v1",
  "cap_id": tstr,
  "version": tstr,
  "purpose": tstr,
  "behavior": { * tstr => any },
  "interop": {
    "requires": [ tstr, ... ],
    "supersedes": [ tstr, ... ],
    "conflicts": [ tstr, ... ]
  }
}
```

**Bundle spec:**
```cbor
{
  "schema": "cap-bundle/v1",
  "cap_id": tstr,
  "members": [ tstr, ... ]  ; ordered, canonical
}
```

### 3.4 Hub Capability Manifests
**Purpose:** What a hub supports (caps, roles).

**Security:** SHOULD be **signed** and available at `/.well-known/hub-caps`.

```cbor
{
  "schema": "hub-caps/v1",
  "univ": tstr,
  "caps_supported": [ tstr, ... ],
  "roles": [ "relay", "archive", "light" ]
}
```

### 3.5 Membership Credentials (VC)
**Purpose:** “Alice @ Hub B” assertion for a given universe.

**Security:** MUST be **signed** by the issuing hub.

```cbor
{
  "schema": "membership-vc/v1",
  "vc": {
    "sub": tstr,   ; user DID
    "iss": tstr,   ; hub DID
    "univ": tstr,
    "claim": "membership",
    "ts": uint,
    "exp": uint
  }
}
```

### 3.6 Membership Status Lists
**Purpose:** Revocation/suspension state for membership VCs.

**Security:** MUST be **signed** and time-bounded.

```cbor
{
  "schema": "vc-status/v1",
  "univ": tstr,
  "ts": uint,
  "entries": [ { "did": tstr, "status": "active" | "revoked" | "suspended", "exp": uint } ]
}
```

### 3.7 Key Rotation Certificates
**Purpose:** Link old→new public key for a DID.

**Security:** MUST be **countersigned** by both old and new keys.

```cbor
{
  "schema": "key-rotate/v1",
  "did": tstr,
  "prev": bstr,  ; old public key
  "next": bstr   ; new public key
}
```

### 3.8 Group/MLS Control
**Purpose:** Group add/remove, epoch updates.

**Security:** MLS-native + optional outer signature if wrapped for uniform transport.

```cbor
{
  "schema": "mls-control/v1",
  "group_id": bstr,
  "epoch": uint,
  "msg": bstr   ; MLS-encoded frame
}
```

### 3.9 Gate Tokens / Requests (Optional)
**Purpose:** Short-lived authorization to retrieve CEKs or stream decrypts.

**Security:** MUST be **signed**, bound to `{rid, univ}`, have short TTL.

```cbor
{
  "schema": "gate-token/v1",
  "rid": bstr,
  "univ": tstr,
  "aud": bstr,
  "exp": uint
}
```

### 3.10 Federation Updates
**Purpose:** Rotate which hubs are considered trusted for forwarding.

**Security:** MUST be **signed** by local operator key.

```cbor
{
  "schema": "federation/v1",
  "version": uint,
  "entries": [ { "hub": tstr, "op": "add" | "remove" } ]
}
```

### 3.11 DID Resolution Hints (Optional)
**Purpose:** Cache pointers to DID docs/keys when using non-self-certifying DIDs.

**Security:** SHOULD be **signed**; TOFU acceptable per policy.

```cbor
{
  "schema": "did-hint/v1",
  "did": tstr,
  "endpoints": [ tstr, ... ]
}
```

---

## 4. Governance & Ops-Plane Objects

### 4.1 Capability Deprecation Notices
**Purpose:** Announce deprecation and recommended replacements.

**Security:** MUST be **signed**.

```cbor
{
  "schema": "cap-deprecate/v1",
  "cap_id": tstr,
  "replacement": [ tstr, ... ],
  "reason": tstr
}
```

### 4.2 Security Bulletins
**Purpose:** Urgently disable compromised capabilities or modules.

**Security:** MUST be **signed** by a trusted issuer.

```cbor
{
  "schema": "sec-bulletin/v1",
  "action": "disable",
  "cap_id": tstr,
  "reason": tstr,
  "ts": uint
}
```

### 4.3 Card Revocation Lists (CRL)
**Purpose:** Hide/invalidate Cards after intentional revocation.

**Security:** MUST be **signed**; freshness enforced.

```cbor
{
  "schema": "crl/v1",
  "univ": tstr,
  "ts": uint,
  "revoked": [ bstr, ... ]  ; list of rid
}
```

### 4.4 Migration Receipts
**Purpose:** Show lineage when a Card is re-issued under new schema/keys.

**Security:** MUST be **signed** by the re-issuer.

```cbor
{
  "schema": "migrate-receipt/v1",
  "old_rid": bstr,
  "new_rid": bstr,
  "ts": uint
}
```

### 4.5 Error Objects
**Purpose:** Interoperable failure signaling across peers.

**Security:** MAY be unsigned; MAY be signed for audit chains.

```cbor
{
  "schema": "error/v1",
  "err": "err_schema_unsupported" | "err_req_missing" | "err_dist_scope" | "err_gate_denied" | "err_revoked" | "err_size_exceeded",
  "rid": bstr,
  "hint": tstr
}
```

### 4.6 Observability / Audit Events
**Purpose:** Privacy-preserving telemetry and diagnostics.

**Security:** MUST NOT include plaintext payloads or PII.

```cbor
{
  "schema": "audit-event/v1",
  "ts": uint,
  "event": tstr,
  "rid": bstr,
  "caps": [ tstr, ... ],
  "code": tstr
}
```

---

## 5. Transport Considerations

- All control-plane and governance objects MAY be gossiped like Cards or fetched on demand by ID (content-addressed).  
- Hubs SHOULD cache verified specs/packages and bulletins.  
- Deduplicate by `(schema, primary id field)` to avoid reprocessing.  
- Objects MUST be small (typically <64KB), except blob metadata.

---

## 6. Security & Validation Rules (Normative)

- **Signature verification:** Required for all objects that change validation or trust (schema packages, caps, VCs, status lists, deprecations, bulletins, federations).  
- **Determinism:** Validators/normalizers MUST be pure and deterministic; no network/file I/O.  
- **Sandboxing:** Any executable validation logic MUST run in a WASM sandbox under strict CPU/mem/time budgets.  
- **Hash binding:** Where objects reference Cards or payloads, they MUST use `rid` or `content_hash` and verify before acting.  
- **Policy precedence:** Security Bulletins override Deprecation Notices; both override local caches.  
- **Fail closed:** If a required control object is missing or unverifiable, verifiers MUST reject dependent Cards.

---

## 7. IANA-Like Registries (Non-Normative)

This ecosystem is intentionally **registry-free**. Names are content-addressed and self-describing. Communities MAY publish curated alias lists for human UX; implementations MUST NOT rely on aliases for security decisions.