Update spec nomenclature
This commit is contained in:
parent
92f4319dbc
commit
7b60e8e8ea
1 changed files with 120 additions and 120 deletions
240
sharenet_spec.md
240
sharenet_spec.md
|
|
@ -7,8 +7,8 @@ This document specifies a decentralized protocol for the creation, distribution,
|
|||
This protocol assumes three fundamental building blocks in addition to Cards:
|
||||
|
||||
- **Passports**: User-held identifiers derived from cryptographic seeds.
|
||||
- **Nodes**: Servers that maintain membership, relay Cards, and enforce network policies.
|
||||
- **Networks**: Collections of nodes and users defined by a shared Genesis Document.
|
||||
- **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
|
||||
|
||||
|
|
@ -23,9 +23,9 @@ This protocol assumes three fundamental building blocks in addition to Cards:
|
|||
- **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.
|
||||
- **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
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ A Card is a CBOR map wrapped in a COSE_Sign1 envelope. Fields:
|
|||
|
||||
- `ver`: Protocol version.
|
||||
- `type`: MUST be `"card"`.
|
||||
- `net`: Network identifier.
|
||||
- `univ`: Universe identifier.
|
||||
- `rid`: Unique Card identifier.
|
||||
- `ts`: Creation timestamp.
|
||||
- `reqs`: Array of capability IDs required to interpret the Card.
|
||||
|
|
@ -51,8 +51,8 @@ A Card is a CBOR map wrapped in a COSE_Sign1 envelope. Fields:
|
|||
|
||||
The policy capsule is an encrypted CBOR map. Fields:
|
||||
|
||||
- `vis`: `"public" | "direct" | "node" | "trustset" | "group"`.
|
||||
- `dist`: `"to_recipients_only" | "this_node_only" | "trusted_nodes" | "public"`.
|
||||
- `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.
|
||||
|
|
@ -61,7 +61,7 @@ The policy capsule is an encrypted CBOR map. Fields:
|
|||
|
||||
### 3.3 Payload
|
||||
|
||||
- Private Cards: `payload` = AEAD(CEK, plaintext_card_body, AAD={net, rid, policy_hash})
|
||||
- Private Cards: `payload` = AEAD(CEK, plaintext_card_body, AAD={univ, rid, policy_hash})
|
||||
- Public Cards: `payload` = plaintext_card_body
|
||||
- `payload_hash` = SHA-256(payload)
|
||||
|
||||
|
|
@ -93,7 +93,7 @@ A bundle spec lists `members` (cap IDs). Bundles MUST expand deterministically i
|
|||
|
||||
### 4.4 Negotiation
|
||||
|
||||
- Nodes advertise supported caps at `/.well-known/node-caps`.
|
||||
- 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.
|
||||
|
||||
|
|
@ -101,15 +101,15 @@ A bundle spec lists `members` (cap IDs). Bundles MUST expand deterministically i
|
|||
|
||||
- **Public**: No encryption. MAY be flagged permanent.
|
||||
- **Direct**: Encrypted CEK to a single recipient (HPKE).
|
||||
- **Node**: CEK encrypted to a node’s group key or gate.
|
||||
- **Trustset**: CEK encrypted to each trusted node’s group key.
|
||||
- **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
|
||||
|
||||
- **to_recipients_only**: Honest nodes forward only to recipients.
|
||||
- **this_node_only**: Not gossiped beyond node.
|
||||
- **trusted_nodes**: Forwarded only to trustset.
|
||||
- **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.
|
||||
|
|
@ -124,10 +124,10 @@ Distribution policies MAY be encrypted inside the policy capsule.
|
|||
## 8. Security Considerations
|
||||
|
||||
- All hashes MUST be computed over canonical CBOR.
|
||||
- Policy capsule MUST bind `{net, rid, payload_hash}` in AEAD AAD.
|
||||
- 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 nodes; confidentiality relies on crypto.
|
||||
- Distribution enforcement relies on honest hubs; confidentiality relies on crypto.
|
||||
- Padding SHOULD be used to obscure audience sizes.
|
||||
|
||||
## 9. Extensibility
|
||||
|
|
@ -168,12 +168,12 @@ The public key is used to generate the DID and sign Cards.
|
|||
### 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.
|
||||
- Users MAY NOT belong to multiple universes with the same Passport.
|
||||
|
||||
## 12. Nodes
|
||||
## 12. Hubs
|
||||
|
||||
### 12.1 Definition
|
||||
A **Node** is a server implementing the protocol, typically written in Rust.
|
||||
A **Hub** is a server implementing the protocol, typically written in Rust.
|
||||
It provides:
|
||||
|
||||
- Membership management (accepting/revoking Passports).
|
||||
|
|
@ -182,45 +182,45 @@ It provides:
|
|||
- 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.
|
||||
- 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
|
||||
Nodes communicate using Cards.
|
||||
Distribution policies determine which nodes are eligible to receive a Card.
|
||||
Nodes MAY maintain trustsets to decide forwarding scopes.
|
||||
Hubs communicate using Cards.
|
||||
Distribution policies determine which hubs are eligible to receive a Card.
|
||||
Hubs MAY maintain federations to decide forwarding scopes.
|
||||
|
||||
## 13. Networks
|
||||
## 13. Universes
|
||||
|
||||
### 13.1 Genesis Document
|
||||
Each network begins with a **Genesis Document** that defines:
|
||||
Each universe begins with a **Genesis Document** that defines:
|
||||
|
||||
- `net_id`: Unique network identifier.
|
||||
- `univ_id`: Unique universe identifier.
|
||||
- `genesis_ts`: Timestamp of creation.
|
||||
- `founders`: Initial node and user DIDs.
|
||||
- `bootstrap_caps`: Minimal capability set required for participation.
|
||||
- `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 network**.
|
||||
It MUST be immutable. Any update creates a **new universe**.
|
||||
|
||||
### 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.
|
||||
- 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 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.
|
||||
- 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 nodes**: Nodes may relay Cards faithfully but attempt to learn additional metadata.
|
||||
- **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.
|
||||
|
|
@ -236,7 +236,7 @@ Implementations MUST use the following algorithms unless explicitly negotiated b
|
|||
- **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**: `{net, rid, content_hash, policy_ref}` MUST be included as Additional Authenticated Data in all AEAD operations.
|
||||
- **AAD binding**: `{univ, rid, content_hash, policy_ref}` MUST be included as Additional Authenticated Data in all AEAD operations.
|
||||
|
||||
## 16. Key Management & Rotation
|
||||
|
||||
|
|
@ -249,24 +249,24 @@ Implementations MUST use the following algorithms unless explicitly negotiated b
|
|||
### 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.
|
||||
- Nodes and verifiers MUST accept a chain of rotation certificates when validating historical Cards.
|
||||
- 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 nodes.
|
||||
- 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 `{net, rid, payload_hash}`.
|
||||
- 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" | "node" | "trustset" | "group",
|
||||
"dist": "to_recipients_only" | "this_node_only" | "trusted_nodes" | "public",
|
||||
"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 },
|
||||
|
|
@ -299,13 +299,13 @@ Endpoints:
|
|||
- `POST /decrypt` → returns plaintext stream of Card body.
|
||||
|
||||
Rules:
|
||||
- Requests MUST carry an **audience binding** (`rid`, `net`).
|
||||
- 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 node or device.
|
||||
- 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.
|
||||
|
||||
|
|
@ -313,12 +313,12 @@ Rules:
|
|||
- A CRL is a signed CBOR array of revoked `rid`s with metadata:
|
||||
```cbor
|
||||
{
|
||||
"net": <net_id>,
|
||||
"univ": <univ_id>,
|
||||
"ts": <timestamp>,
|
||||
"revoked": [ <rid1>, <rid2>, ... ]
|
||||
}
|
||||
```
|
||||
- CRLs MUST be signed by the issuer (user or node).
|
||||
- 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).
|
||||
|
||||
|
|
@ -326,14 +326,14 @@ Rules:
|
|||
|
||||
## 19. Distribution Rules & Relay Behavior
|
||||
|
||||
### 19.1 Enforcement by Honest Nodes
|
||||
- **to_recipients_only**: forward only if node is itself a recipient or directly connected to one.
|
||||
- **this_node_only**: MUST NOT forward beyond local storage.
|
||||
- **trusted_nodes**: MAY forward only to nodes in the local trustset.
|
||||
### 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
|
||||
- Nodes SHOULD log distribution violations (attempts to forward beyond scope).
|
||||
- Hubs SHOULD log distribution violations (attempts to forward beyond scope).
|
||||
- Logs MUST contain only hashes (`rid`, `content_hash`), not plaintext.
|
||||
|
||||
### 19.3 Confidentiality Interaction
|
||||
|
|
@ -342,14 +342,14 @@ Rules:
|
|||
- Even if a Card leaks beyond scope, non-recipients cannot decrypt.
|
||||
|
||||
### 19.4 Error Signaling
|
||||
- If a node refuses to forward a Card due to distribution rules, it SHOULD return an error code:
|
||||
- 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
|
||||
- Nodes MAY be discovered via:
|
||||
- Hubs MAY be discovered via:
|
||||
- Static configuration files or bootstrap lists.
|
||||
- Distributed Hash Table (DHT) lookups.
|
||||
- Rendezvous services (non-privileged).
|
||||
|
|
@ -361,13 +361,13 @@ Rules:
|
|||
|
||||
### 20.3 Deduplication and Replay Protection
|
||||
- Every Card has a unique `rid`.
|
||||
- Nodes MUST maintain a deduplication cache to avoid re-processing the same Card.
|
||||
- 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).
|
||||
- Nodes MAY reject or truncate oversized payloads.
|
||||
- Hubs MAY reject or truncate oversized payloads.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -376,7 +376,7 @@ Rules:
|
|||
### 21.1 RIDs
|
||||
- `rid` is the globally unique identifier for a Card.
|
||||
- Recommended format: **UUIDv7** (time-ordered, random component).
|
||||
- Collisions are cryptographically improbable; nodes MUST treat duplicates as replay attempts.
|
||||
- Collisions are cryptographically improbable; hubs MUST treat duplicates as replay attempts.
|
||||
|
||||
### 21.2 Timestamps
|
||||
- Each Card includes a creation timestamp (`ts`).
|
||||
|
|
@ -402,17 +402,17 @@ Rules:
|
|||
|
||||
### 22.2 Signatures and Trust
|
||||
- Packages SHOULD be signed by their authors.
|
||||
- Node admins MAY define local trust policies (e.g., trusted keyrings).
|
||||
- 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**.
|
||||
- Nodes MUST sandbox modules with:
|
||||
- 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 node admins.
|
||||
- Packages MAY be installed automatically from peers or manually by hub admins.
|
||||
- A CLI MAY be provided:
|
||||
```bash
|
||||
syspm install <package_hash>
|
||||
|
|
@ -451,25 +451,25 @@ syspm install <package_hash>
|
|||
|
||||
---
|
||||
|
||||
## 24. Node Roles & Trustsets
|
||||
## 24. Hub Roles & Federations
|
||||
|
||||
### 24.1 Node Roles
|
||||
Nodes MAY declare one or more roles:
|
||||
### 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 Node metadata and MAY guide peer selection.
|
||||
Roles MAY be declared in Hub metadata and MAY guide peer selection.
|
||||
|
||||
### 24.2 Trustsets
|
||||
- A trustset is a locally defined list of nodes considered trustworthy by a given node.
|
||||
- Trustsets MAY be defined by DID, fingerprint, or signed config.
|
||||
- Trustsets MUST be rotatable without changing the Genesis Document.
|
||||
- Distribution rules (e.g. “trusted_nodes”) are enforced using trustsets.
|
||||
### 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
|
||||
- Trustsets SHOULD support rotation via signed update lists.
|
||||
- Nodes MAY advertise trustset digests to peers.
|
||||
- Federations SHOULD support rotation via signed update lists.
|
||||
- Hubs MAY advertise federation digests to peers.
|
||||
- Discrepancies MAY be logged for audit.
|
||||
|
||||
---
|
||||
|
|
@ -482,36 +482,36 @@ A membership Verifiable Credential (VC) MUST contain:
|
|||
{
|
||||
"vc": {
|
||||
"sub": <user_did>,
|
||||
"iss": <node_did>,
|
||||
"iss": <hub_did>,
|
||||
"claim": "membership",
|
||||
"net": <net_id>,
|
||||
"univ": <univ_id>,
|
||||
"ts": <issued_timestamp>,
|
||||
"exp": <expiry_timestamp>
|
||||
},
|
||||
"sig": <signature_by_node>
|
||||
"sig": <signature_by_hub>
|
||||
}
|
||||
```
|
||||
|
||||
### 25.2 Status Lists
|
||||
- Nodes MAY maintain status lists indicating active, revoked, or suspended memberships.
|
||||
- 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 node/network.
|
||||
- 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. Network Genesis, Publication, and Forks
|
||||
## 26. Universe Genesis, Publication, and Forks
|
||||
|
||||
### 26.1 Canonical Genesis
|
||||
- The Genesis Document MUST be encoded in canonical CBOR.
|
||||
- The `net_id` is computed as `SHA-256` of the canonical bytes.
|
||||
- The `univ_id` is computed as `SHA-256` of the canonical bytes.
|
||||
- Genesis MUST include:
|
||||
- `net_id`, `genesis_ts`, founders (node/user DIDs), bootstrap capabilities, and policies.
|
||||
- Genesis is immutable. Any change results in a new `net_id` and thus a new network.
|
||||
- `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.
|
||||
|
|
@ -526,10 +526,10 @@ A membership Verifiable Credential (VC) MUST contain:
|
|||
|
||||
### 26.4 No-Tombstone Rule
|
||||
- Once published, a Genesis Document MUST NOT be deleted.
|
||||
- Networks have permanence; dissolution only occurs if all peers stop participating.
|
||||
- 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 `net_id`.
|
||||
- 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.
|
||||
|
||||
|
|
@ -586,7 +586,7 @@ A membership Verifiable Credential (VC) MUST contain:
|
|||
- Padding helps obscure audience size and plaintext length.
|
||||
|
||||
### 28.3 Cover Traffic
|
||||
- Nodes MAY generate synthetic Cards with random content to obscure traffic patterns.
|
||||
- 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
|
||||
|
|
@ -601,7 +601,7 @@ A membership Verifiable Credential (VC) MUST contain:
|
|||
## 29. Abuse & Resource Controls
|
||||
|
||||
### 29.1 Rate Limits
|
||||
- Nodes MUST enforce per-peer request limits to prevent denial of service.
|
||||
- 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
|
||||
|
|
@ -620,11 +620,11 @@ A membership Verifiable Credential (VC) MUST contain:
|
|||
- Modules exceeding budgets MUST be terminated.
|
||||
|
||||
### 29.5 Signature Verification Quotas
|
||||
- Nodes SHOULD limit the number of signature verifications per peer per unit time.
|
||||
- Hubs SHOULD limit the number of signature verifications per peer per unit time.
|
||||
- Helps protect against CPU exhaustion attacks.
|
||||
|
||||
### 29.6 Ban Lists
|
||||
- Nodes MAY maintain local ban lists of misbehaving peers.
|
||||
- Hubs MAY maintain local ban lists of misbehaving peers.
|
||||
- Ban lists SHOULD be rotatable and MAY be shared among trusted peers.
|
||||
|
||||
---
|
||||
|
|
@ -640,7 +640,7 @@ Implementations MUST support the following error codes for interoperability:
|
|||
- `err_revoked`: Card has been revoked.
|
||||
- `err_gate_denied`: Gate refused to provide CEK.
|
||||
- `err_dist_scope`: Distribution rule violation.
|
||||
- `err_recipient_only`: Node not an intended recipient.
|
||||
- `err_recipient_only`: Hub not an intended recipient.
|
||||
- `err_size_exceeded`: Payload too large.
|
||||
|
||||
### 30.2 Error Format
|
||||
|
|
@ -710,7 +710,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
- Range fetch MUST allow partial retrieval and recombination.
|
||||
|
||||
### 32.4 Retention and Garbage Collection
|
||||
- Nodes MAY garbage-collect old payloads not recently requested.
|
||||
- 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.
|
||||
|
||||
|
|
@ -719,7 +719,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
## 33. Observability & Audit
|
||||
|
||||
### 33.1 Minimal Logging
|
||||
- Nodes SHOULD log only:
|
||||
- Hubs SHOULD log only:
|
||||
- `rid`
|
||||
- `cap_ids`
|
||||
- error codes
|
||||
|
|
@ -730,13 +730,13 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
- Only hashed identifiers may be retained for correlation.
|
||||
|
||||
### 33.3 Migration Receipts
|
||||
- When a Card is re-issued due to schema or protocol migration, nodes MAY attach a signed **migration receipt**:
|
||||
- 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_node>
|
||||
"sig": <signature_by_hub>
|
||||
}
|
||||
```
|
||||
- Receipts provide an auditable trail for backward compatibility.
|
||||
|
|
@ -760,7 +760,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
|
||||
### 34.3 Collision Handling
|
||||
- If two aliases collide:
|
||||
- Node admins MAY configure preferred mappings.
|
||||
- Hub admins MAY configure preferred mappings.
|
||||
- UIs SHOULD disambiguate by showing both alias and `cap_id`.
|
||||
|
||||
### 34.4 Example
|
||||
|
|
@ -775,7 +775,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
|
||||
### 35.1 Purpose
|
||||
- Security bulletins provide a mechanism to urgently disable compromised capabilities, algorithms, or schema packages.
|
||||
- Bulletins are signed notices distributed across the network.
|
||||
- Bulletins are signed notices distributed across the universe.
|
||||
|
||||
### 35.2 Structure
|
||||
```cbor
|
||||
|
|
@ -789,7 +789,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
```
|
||||
|
||||
### 35.3 Issuers
|
||||
- Bulletins MAY be issued by capability authors, network founders, or node operators.
|
||||
- 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
|
||||
|
|
@ -827,7 +827,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
- Consumers MUST reject Cards that require unknown or deprecated `cap_id`s.
|
||||
|
||||
### 36.5 Adapters
|
||||
- Nodes MAY provide **adapters** to transform Cards from older schema versions to newer ones.
|
||||
- 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.
|
||||
|
||||
|
|
@ -837,7 +837,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
{
|
||||
"ver": 1,
|
||||
"type": "card",
|
||||
"net": "net:prod:z9…",
|
||||
"univ": "univ:prod:z9…",
|
||||
"rid": "0x12b…",
|
||||
"ts": 1738123456,
|
||||
"reqs": ["cap:card/v1@…"],
|
||||
|
|
@ -858,7 +858,7 @@ Implementations MUST validate against these vectors to ensure interoperability.
|
|||
{
|
||||
"ver": 1,
|
||||
"type": "card",
|
||||
"net": "net:prod:z9…",
|
||||
"univ": "univ:prod:z9…",
|
||||
"rid": "0x44a…",
|
||||
"ts": 1738126789,
|
||||
"reqs": ["cap:card/v2@…","cap:hpke-x25519-xc20p@…"],
|
||||
|
|
@ -951,7 +951,7 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
### 3.2 Schema Descriptors
|
||||
**Purpose:** Operator-friendly pointer to install a module out-of-band.
|
||||
|
||||
**Security:** MUST be **signed**. Node validates artifact hash before load.
|
||||
**Security:** MUST be **signed**. Hub validates artifact hash before load.
|
||||
|
||||
```cbor
|
||||
{
|
||||
|
|
@ -997,32 +997,32 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
}
|
||||
```
|
||||
|
||||
### 3.4 Node Capability Manifests
|
||||
**Purpose:** What a node supports (caps, roles).
|
||||
### 3.4 Hub Capability Manifests
|
||||
**Purpose:** What a hub supports (caps, roles).
|
||||
|
||||
**Security:** SHOULD be **signed** and available at `/.well-known/node-caps`.
|
||||
**Security:** SHOULD be **signed** and available at `/.well-known/hub-caps`.
|
||||
|
||||
```cbor
|
||||
{
|
||||
"schema": "node-caps/v1",
|
||||
"net": tstr,
|
||||
"schema": "hub-caps/v1",
|
||||
"univ": tstr,
|
||||
"caps_supported": [ tstr, ... ],
|
||||
"roles": [ "relay", "archive", "light" ]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Membership Credentials (VC)
|
||||
**Purpose:** “Alice @ Node B” assertion for a given network.
|
||||
**Purpose:** “Alice @ Hub B” assertion for a given universe.
|
||||
|
||||
**Security:** MUST be **signed** by the issuing node.
|
||||
**Security:** MUST be **signed** by the issuing hub.
|
||||
|
||||
```cbor
|
||||
{
|
||||
"schema": "membership-vc/v1",
|
||||
"vc": {
|
||||
"sub": tstr, ; user DID
|
||||
"iss": tstr, ; node DID
|
||||
"net": tstr,
|
||||
"iss": tstr, ; hub DID
|
||||
"univ": tstr,
|
||||
"claim": "membership",
|
||||
"ts": uint,
|
||||
"exp": uint
|
||||
|
|
@ -1038,7 +1038,7 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
```cbor
|
||||
{
|
||||
"schema": "vc-status/v1",
|
||||
"net": tstr,
|
||||
"univ": tstr,
|
||||
"ts": uint,
|
||||
"entries": [ { "did": tstr, "status": "active" | "revoked" | "suspended", "exp": uint } ]
|
||||
}
|
||||
|
|
@ -1075,28 +1075,28 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
### 3.9 Gate Tokens / Requests (Optional)
|
||||
**Purpose:** Short-lived authorization to retrieve CEKs or stream decrypts.
|
||||
|
||||
**Security:** MUST be **signed**, bound to `{rid, net}`, have short TTL.
|
||||
**Security:** MUST be **signed**, bound to `{rid, univ}`, have short TTL.
|
||||
|
||||
```cbor
|
||||
{
|
||||
"schema": "gate-token/v1",
|
||||
"rid": bstr,
|
||||
"net": tstr,
|
||||
"univ": tstr,
|
||||
"aud": bstr,
|
||||
"exp": uint
|
||||
}
|
||||
```
|
||||
|
||||
### 3.10 Trustset Updates
|
||||
**Purpose:** Rotate which nodes are considered trusted for forwarding.
|
||||
### 3.10 Federation Updates
|
||||
**Purpose:** Rotate which hubs are considered trusted for forwarding.
|
||||
|
||||
**Security:** MUST be **signed** by local operator key.
|
||||
|
||||
```cbor
|
||||
{
|
||||
"schema": "trustset/v1",
|
||||
"schema": "federation/v1",
|
||||
"version": uint,
|
||||
"entries": [ { "node": tstr, "op": "add" | "remove" } ]
|
||||
"entries": [ { "hub": tstr, "op": "add" | "remove" } ]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -1154,7 +1154,7 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
```cbor
|
||||
{
|
||||
"schema": "crl/v1",
|
||||
"net": tstr,
|
||||
"univ": tstr,
|
||||
"ts": uint,
|
||||
"revoked": [ bstr, ... ] ; list of rid
|
||||
}
|
||||
|
|
@ -1209,7 +1209,7 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
## 5. Transport Considerations
|
||||
|
||||
- All control-plane and governance objects MAY be gossiped like Cards or fetched on demand by ID (content-addressed).
|
||||
- Nodes SHOULD cache verified specs/packages and bulletins.
|
||||
- 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.
|
||||
|
||||
|
|
@ -1217,7 +1217,7 @@ This addendum enumerates object types beyond **Cards** that a compliant implemen
|
|||
|
||||
## 6. Security & Validation Rules (Normative)
|
||||
|
||||
- **Signature verification:** Required for all objects that change validation or trust (schema packages, caps, VCs, status lists, deprecations, bulletins, trustsets).
|
||||
- **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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue