devteam/sharenet_passport_creator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sharenet_passport_creator/sharenet_spec.md

40 KiB
Raw Blame History

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 self-describing universe identifier.

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 self-describing universe identifier.
  • Universe Identifier (univ_id): A human-readable DID that encodes both a human-readable name and unique identifier in the format u:<name>:<uuidv7>.

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 Universe Identifier (univ_id)

Each universe is identified by a human-readable DID that encodes both a human-readable name and a unique identifier.

Format:

u:<name>:<uuidv7>

Components:

  • u: - Prefix identifying this as a universe identifier
  • <name> - UTF-8 encoded universe name (any length)
  • <uuidv7> - UUIDv7 identifier (RFC 4122 format)

Constraints:

  • The name MUST be a valid UTF-8 string
  • Special characters in the name SHOULD be URL-encoded if they conflict with the format
  • The UUIDv7 MUST be generated according to RFC 4122
  • The entire string MUST be treated as case-sensitive

Example:

u:Test Universe:018f1234-5678-90ab-cdef-123456789abc

The univ_id is used directly for passport creation and universe identification. No separate Genesis Document is required.

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)

{
  "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 rids with metadata:
{
  "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 rids 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:
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:
{
  "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 universe identifier.
  • 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:

{
  "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 Creation and Identification

26.1 Universe Identifier Generation

  • A universe is created by generating a human-readable DID
  • The format MUST be: u:<name>:<uuidv7>
  • The name MUST be a valid UTF-8 string (any length)
  • The UUIDv7 MUST be generated according to RFC 4122
  • Special characters in the name SHOULD be URL-encoded

26.2 Name Extraction

  • Given any valid univ_id, the human-readable name MUST be extractable
  • Implementations MUST parse the format to retrieve the name for display
  • The name is permanently embedded and cannot be changed
  • URL-encoded characters MUST be decoded when extracting the name

26.3 Uniqueness and Independence

  • Each univ_id is globally unique due to the UUIDv7 component
  • There is no concept of "forks" since each universe is independent
  • Participants MAY join any universe by its univ_id

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:
{
  "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:

{
  "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:
{
  "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

{
  "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

{
  "bulletin": "disable",
  "cap_id": <capability_id>,
  "reason": tstr,
  "ts": <timestamp>,
  "sig": <signature_by_issuer>
}

35.3 Issuers

  • Bulletins MAY be issued by capability authors 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_ids) 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_ids for incompatible updates.
  • Consumers MUST reject Cards that require unknown or deprecated cap_ids.

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

{
  "ver": 1,
  "type": "card",
  "univ": "u:Production Universe:018f1234-5678-90ab-cdef-123456789abc",
  "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)

{
  "ver": 1,
  "type": "card",
  "univ": "u:Production Universe:018f1234-5678-90ab-cdef-123456789abc",
  "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):

{
  "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.

{
  "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).

{
  "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.

{
  "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.

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

Bundle spec:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.