Entity System Security Architecture: Capabilities, Identity, and Trust in Content-Addressed Typed Data

1. Introduction

Security in distributed systems is usually bolted on. Identity, authorization, audit, revocation, and confidentiality each get their own subsystem, their own data model, their own deployment story. The integration between them — expressed in TLS configurations, IAM policies, session cookies, audit logs, certificate revocation lists, and out-of-band key exchanges — accumulates as accidental complexity.

The entity system is built differently. The same six primitives that define the system (see The Entity System) also carry every security mechanism. Capability tokens are entities. Peer identities are entities. Delegation chains are content-addressed. Revocation uses the tree’s mutable binding layer. Encryption wraps entities and preserves their identity. There is no separate “security layer” because there is no separate substance: typed content-addressed data is the substrate for data and for security alike.

This paper is the dedicated treatment of how that security model works end-to-end. The Entity Core Protocol covers the security mechanisms in protocol context — wire format, message structure, capability-token layout, the connection handshake. This paper goes deeper: how the mechanisms compose, how they are deployed, what they imply about peer roles and trust boundaries, and where they sit in the broader landscape of capability-based and access-control systems.

1.1. What Lives Where

Security in the entity system lives at the IXP capability triangle (see The Entity System) — one of the five named structural triangles formed by the six primitives. The triangle’s three pairs each carry part of the substrate:

• IX (Identity × Execution): the capability-as-content-addressed-entity. A capability token is an entity, its identity is its content hash, and verification across implementations converges by hash equality.
• XP (Execution × Peer): cross-peer dispatch carrying capabilities. Every EXECUTE between peers carries its own capability token; authorization is per-message, not per-session.
• IP (Identity × Peer): content-addressed peer identity. A peer’s ID is a hash of its public key. Same key, same ID, everywhere, always.

Two of these pairs are phase-transition pairs in the sense developed in The Entity System: IX (capability convergence verification) and IP (peer-ID derivation) do not activate at partial Identity levels. A system at I1 (assigned identity, not content-derived) cannot host the entity system’s capability model regardless of how richly its grant structure is specified. This is the structural reason content-derived identity is a precondition for the security model, not a complement to it. Without Full I, the IXP triangle has at most one pair active (XP), and the capability mechanism degrades to a session-bound authorization model.

Security mechanisms outside the IXP triangle ground in other structural locations:

• Authorization at the dispatch boundary uses the TX pair (handler dispatch via tree-walk) and the EX pair (typed handler operations). The four-dimensional grant covers exactly these: handler (TX), operation (EX), resource (TP for peer-namespaced paths), and peer (XP).
• Audit uses the ITM emit triangle (see The Entity System). Content storage is append-only along the IM axis (Store is monotone over content); the binding layer at TM carries revocation as ordinary binding changes. The IM/TM split is what lets audit and revocation compose without conflict: they live on different axes of the same primitive.
• Confidentiality lives at the EI pair: encrypted entities are typed and content-addressed exactly like any other entity. Authorization (IXP) and confidentiality (EI) are independent dimensions; either can apply without the other, and together they give defense in depth.

The capability model is the only authorization mechanism in the entity system. There is no parallel ACL system, no role table, no session cookie. Roles are expressed as capability-issuing patterns; groups are membership records that produce capabilities; clusters are mutual-trust patterns that share generation pools. The same mechanism handles every authorization question because the substrate provides only one.

1.2. What This Paper Covers

The paper is organized around five questions:

1. Who is acting? The identity model: content-addressed peer IDs, algorithm agility, identity entities as mini-trees, the connection handshake, peer roles.
2. What may they do? The capability architecture: four-dimensional grants, attenuation by construction, delegation chains, two-level verification, handler authority.
3. What happens when they should no longer act? Revocation: tree-based unbinding, generation pools, TTL, and the tiered implementation that scales from minimal deployments to large clusters.
4. What may they understand? Encryption: entity-level encryption with self, peer, and group modes. Scoped to stateless single-shot use — interactive session encryption is separate work and is not covered here — and specified but not yet exercised in deployment.
5. How is this used in practice? Deployment patterns: peer-role configurations, delegation patterns, cluster and group patterns, information disclosure control, incident response.

A comparative analysis section positions the entity system against existing capability systems (Macaroons, UCAN, Biscuit, Zanzibar) and against the security philosophies of high-primitive systems (Holochain’s “trust the code”, Plan 9’s “trust the steward”). The analysis grounds in the landscape developed in Convergent Evolution: of the systems analyzed there, the entity system is the only one that activates the full IXP triangle simultaneously.

1.3. What This Paper Does Not Cover

The six primitives and their build-up sequence are in The Entity System. Wire format, message layout, and the bootstrap handler manifest are in The Entity Core Protocol. Computational architecture and self-description are in The Entity Church Architecture. The full landscape analysis with cross-system scoring is in Convergent Evolution. OS-level deployment patterns and security tiers belong to DEOS; application-level security guidance belongs to Application Architecture. We assume familiarity with the primitives and pair-relationship framework from The Entity System; specific pair and triangle names (IXP, EIT, ITM, TMX, TXP) are used without re-introducing them.

2. Identity

Authorization rests on identity, but in this system “identity” is not one thing. It is a small stack of structurally distinct mechanisms composed under a discipline. At the bottom sits a cryptographic peer ID — the per-keypair identity that lets a peer sign and be recognised. Above that sits an optional identity layer that maintains a peer graph of attestations over time, supports recovery from key loss or compromise, and exposes a stable handle to contacts even as the underlying keys rotate. This section describes both: the peer-keypair foundation, the four-extension identity stack on top, the standard setup users should default to, and the recovery model that makes the whole thing survivable.

2.1. Peer IDs and the Peer Keypair Entity

The lowest layer of identity is per-keypair. Each peer has an Ed25519 keypair; the peer’s identifier is derived deterministically from the public key:

$$\text{PeerID} = \text{Base58}(\text{key\_type} \mathbin\| \text{hash\_type} \mathbin\| \text{SHA256}(\text{public\_key}))$$

Three single-byte format codes pin the cryptographic choices:

• key_type: which signature algorithm the public key uses (currently Ed25519, code 0x00).
• hash_type: which hash algorithm derives the ID from the key (currently SHA-256, code 0x00).
• A separate format code on every content hash pins the content-addressing algorithm (also 0x00 for ECFv1-SHA-256 today).

The three namespaces are independent: a deployment can adopt a new content-hash algorithm without changing peer IDs, a new peer-ID hash without changing keys, and a new signature scheme without changing existing hashes. Algorithm agility is built into the format, not bolted onto a separate negotiation layer.

The resulting peer ID is 46 characters of Base58. Collision analysis under generous assumptions ($10^9$ peers, $10^{12}$ connection events per peer per year) yields a per-event collision probability around $10^{-38}$, which is structurally adequate: a collision would not produce a security failure but would produce a routing confusion that any two affected peers could detect by comparing keys.

The peer’s keypair is itself an entity — the peer keypair entity at system/peer — holding the public key, key-type, and a self-signature. Every peer has one; it is the substrate every other identity mechanism builds on. An earlier revision named this entity system/identity; it was renamed to system/peer to avoid colliding with the identity-extension layer above.

A peer keypair is not yet a user identity. A single-user, single-device deployment can use the peer keypair as their identity (and we describe this as the core-only configuration below). For anything beyond that — multi-device, recovery from key loss, stable handles that survive key rotation — the identity extension layers on top.

2.2. Three Structurally Distinct Validation Classes

Before we describe the identity layer, the security architecture rests on an invariant that constrains its shape: there are three parallel classes of signed entity in the system, and they share no validator.

1. Core capability tokens — chain-walked by the core protocol’s verify_capability_chain, which checks the parent-reference chain, signature at each link, attenuation on every grant dimension, and freshness. Capabilities are how peers authorise specific actions.
2. system/attestation entities — signed claims that one peer makes about another, with kind-discriminated semantics. Validated by EXTENSION-ATTESTATION helpers plus consumer-specific predicates. Attestations are how peers certify state without thereby authorising operations.
3. system/quorum entities — K-of-N signer sets, validated by EXTENSION-QUORUM’s verify_k_of_n_signatures. Quorums are how a collective decision is expressed as a single verifiable entity.

These are three distinct entity types validated by three distinct functions and dispatched along three distinct paths. No code path treats a capability token, an attestation, and a quorum entity as interchangeable signed objects. This is a security invariant, not a stylistic choice. The natural implementation mistake — reusing the capability-chain walker for “anything multi-signed” — would collapse the security model: a multi-sig capability could be confused with a quorum decision; a controller certificate could be confused with a delegated authorisation. The architecture forbids this and the conformance tests check that implementations honour the separation.

The identity layer above composes these three classes into deployment-ready identity machinery; the separation gates the composition rather than constraining it.

2.3. The Identity Stack

Four extensions, in two layers, comprise the identity machinery:

The two substrate extensions are kind-agnostic by design: their primitives are reusable by any future consumer (group, transaction, governance, verifiable credentials, reputation, provenance, audit). The two composition extensions encode identity-specific and role-specific semantics on top.

Three of the four are specified and implemented; the role extension is the one still settling, and we mark where the paper leans on it. We name no version numbers: extension versions move independently of this paper, and a reader who needs the current revision of any of them should read the extension specification rather than trust a number printed here.

Implementations may opt out of the identity layer entirely (the core-only configuration described below); when an implementation installs IDENTITY it MUST also implement ATTESTATION and QUORUM, because IDENTITY’s mechanics actively compose them (registering an identity-resolved resolver against QUORUM at install time, wrapping ATTESTATION’s create/supersede/revoke ops with identity-specific properties and path conventions, dispatching side effects on attestation arrival via a process_attestation sync hook).

2.4. The Cert-Chain Framework

Identity, as the extension models it, is a peer graph rooted at a quorum. A K-of-N quorum sits at the structural root; certs are directed edges; functions (controller, agent, identifier, app-defined) are graph positions established by certs rather than properties stored on peers.

The model has four characteristic features:

Quorum-rooted. Every cert chain terminates at a top-level cert whose attesting field references the quorum’s identifier. The quorum is the trust anchor; verifiers walking any cert chain back to the quorum can validate the chain end-to-end against the K-of-N requirement.

Four standard functions. A cert’s properties.function field names a structural position:

• controller — authority to delegate within the identity (sign agent certs, write internal-management entities, issue local-peer capabilities to the controller’s keypair).
• agent — authority to act on behalf of the identity from a specific device. One agent per device daemon, typically; agent certs are signed by the controller (in the three-key default) or by the identifier (in the four-key advanced shape).
• identifier (four-key only) — the cert function contacts cache as the identity’s handle. Distinct from controller so that controllers can rotate without contacts re-validating.
• app-defined — consumers can register additional function values for domain-specific authority (audit-log signer, service account, custodial agent, etc.).

Chain depth bounded but flexible. Sub-controller chains allow a controller to issue a subordinate controller cert; the chain MUST terminate at a top-level controller (attesting = quorum_id). Default maximum chain depth is 32 per the substrate’s walk_attesting_chain parameter; identity sub-controller chains are typically shallow (2–3 levels).

Functions emerge from graph position, not from peer-side state. A peer is a controller because a cert with function="controller" chains it back to a quorum; revoking that cert (via supersedes, retirement, or revocation) removes the function. The peer’s keypair is unchanged; what changes is its position in the identity graph. This makes role transitions a graph operation, not a state migration.

The four identity-context attestation kinds (registered under the substrate’s kind-ownership table, namespace-prefixed with identity-) carry the lifecycle:

• "identity-cert" — active certification of a peer for a function.
• "identity-rotation-handoff" — graceful key roll; dual-signed by old and new key.
• "identity-rotation-recovery" — compromise-recovery; K-of-N signed by the quorum.
• "identity-retirement" — explicit cert retirement; K-of-N signed.

The substrate’s universal "revocation" kind applies on top of these, with identity’s own authority rules over who may revoke what (per identity_is_authorized_revoker).

2.5. Configuration Progression

The identity extension is opt-in, and not every deployment needs the full machinery. Configurations form a progression from cryptographically minimal (per-keypair only) through the recommended default (three-key with recovery) to advanced shapes:

Core-only

The identity extension is not installed. Each peer’s identity IS its keypair; the peer ID derived from the public key is the identity handle. Single-device, single-key, no recovery, no rotation. Loss of the key is loss of the identity; cross-peer recognition is by raw peer ID. Valid for closed networks, dev environments, IoT devices not intended to survive replacement.

1-of-1 quorum

The identity extension is installed but the quorum has one constituent with threshold 1. The cert-chain machinery operates correctly — agent certs sign other entities, rotation events compose — but no recovery is possible (loss of the single quorum constituent is catastrophic). Useful when a deployment wants the architectural shape (rotation, agent abstraction, controller-mediated grants) but accepts no recovery property.

Three-key default (recommended)

The canonical setup. Three peer functions:

• Quorum constituents. N peers, K-of-N threshold (typically K = 2, N = 3 or 5). Constituent keys held in cold custody: paper backup, hardware token, secondary device, or trusted holder. Used rarely — only for recovery, quorum updates, and minting new top-level controller certs.
• Controller. Hot, encrypted at rest. Signs internal-management entities: peer-config writes, role-assignment records, agent certs. In the three-key default the controller’s key IS the identifier — contacts cache the controller’s public key as the identity’s handle.
• Agents. One per device daemon, hot, on each running device. Sign cross-peer capability tokens (core-standard, per The Entity Core Protocol). The controller authorises each agent via an agent cert.

This configuration delivers the three properties most users actually want: recovery (K-of-N quorum can recover from controller compromise), multi-device (each device runs its own agent with its own keypair, all under the same controller), and stable cross-peer recognition (contacts cache the controller’s key; the identity survives device additions and replacements).

The setup ceremony is documented in §6 of EXTENSION-IDENTITY and is exposed via the system/identity:configure handler. In outline:

1. Choose N quorum constituents and the threshold K. Distribute the constituent keys across diverse custody (geographic, custodial, hardware-class) so that an attacker cannot reach K of them simultaneously without an extraordinary effort.
2. Mint the initial quorum entity (system/quorum:create) and seed it with the N constituent public keys plus the threshold.
3. K of the constituents sign the controller cert (kind = identity-cert, function = controller, attesting = quorum). The cert lives at system/identity/public/cert/{cert_hash_hex} and is published as part of the contact-facing sync surface.
4. The controller mints agent certs for each device (kind = identity-cert, function = agent, attesting = controller’s key). Initially each agent cert lives in mode = internal (privacy default); contacts who need to recognise the agent receive published versions (mode = public or mode = relationships/{contact_id}) per the deployment’s contact policy.
5. Each agent runs system/identity:configure to bind its local peer-config to the trusted quorum, validate the live controller cert chain, and mint the local-peer-to-controller capability that lets subsequent operations dispatch under the controller’s authority.

After this ceremony the identity is operational. Day-to-day work runs through the agents under controller-derived authority. The quorum constituents return to cold custody until rotation, recovery, or membership change.

Four-key advanced

The three-key default conflates the controller (signs internal management) and the identifier (contacts cache as the handle). Some deployments want these separated — controllers should rotate frequently for hygiene, but contacts should not re-validate every rotation. The four-key advanced shape adds an identifier peer:

• The controller rotates frequently; this is invisible to contacts.
• The identifier rotates rarely (only on compromise of the identifier itself). Contacts cache the identifier’s key as the handle.
• Agent certs are signed by the identifier (not the controller), since contacts cache the identifier’s key as the recognition anchor.

Most deployments do not need this. We document it as opt-in; the three-key default carries the load-bearing properties.

Other supported variants

The following composition shapes are normative configurations that compose from the same primitives:

• Multi-binding. A single host machine MAY operate as multiple agents (one per identity it serves) — personal and service-account on the same laptop, for example. Each agent has its own peer-config in its own peer namespace; peer-configs MUST NOT share state across identities.
• Concurrent multi-controller. Multiple controllers live concurrently under the same quorum (desktop + phone deployments where each device holds its own controller). Each agent holds one local-peer-to-controller capability per live controller.
• Sub-controller chains. A controller cert can be issued by another controller (rather than directly by the quorum), enabling delegated management hierarchies. The chain MUST terminate at a top-level controller whose attesting = quorum_id.
• App-defined functions. Custom function values (e.g., function="audit-log-signer", function="service-account") follow the standard cert lifecycle uniformly.
• Parent-managed. Controller keys held initially by a parental peer; the subject acquires their own keys over time via quorum-update ceremonies that add the subject’s peers to the quorum and eventually remove the parental ones. Used for child-account or device-onboarding scenarios.

The progression composes: a deployment can adopt the three-key default and later add sub-controllers, transition from parent-managed to self-custody, or expand to four-key when contact-stability requirements emerge. Each transition is itself a sequence of standard cert lifecycle events.

2.6. The Recovery Cluster

The quorum at the root of an identity is the recovery mechanism. We describe it as a recovery cluster to emphasise its operational character: it is not a routine signing surface but a small set of cold-stored keys whose collective authority can re-establish the identity if a controller is lost or compromised.

Custodial diversity. The N constituent keys should be held across diverse failure modes:

• Geographic diversity. Constituents in physically separated locations so a single fire, theft, or seizure does not reach K of them.
• Custodial diversity. A mix of self-held (paper backup in a safe, hardware token on a keychain, secondary device in a different location) and trust-held (lawyer, family member, employer). The trust assumption is that at most N − K of them collude or are coerced simultaneously.
• Hardware diversity. Some constituents on hardware tokens (YubiKey-class devices), some on software wallets, some on paper. A single supply-chain compromise does not reach all custody.

The threshold K controls the survivability/safety trade-off: low K (1-of-3) tolerates more loss but accepts lower attacker work; high K (3-of-5) tolerates one or two losses but requires more attackers to collude. The recommended default for personal identities is K = 2, N = 3 or K = 3, N = 5; institutional identities often use higher thresholds.

Recovery flow. When a controller is compromised or its key is lost, recovery proceeds as follows:

1. The user assembles K constituent signatures (K-of-N) on an identity-rotation-recovery attestation. This is a coordinated event: the constituents need to be reachable, but the K-of-N signature gathering can be asynchronous (via the proposals subtree convention in §8 of EXTENSION-IDENTITY).
2. The recovery attestation references the prior controller cert (in properties.target_cert) and asserts a new controller cert (in the same supersedes chain) issued to a fresh controller keypair.
3. Contacts processing the recovery attestation validate the K-of-N signatures against their cached quorum-publish attestation for the identity — the prior signer set that the contact already trusts. If the K-of-N signatures verify against that cached state, the contact accepts the new controller and updates its handle cache to the new key.
4. Contacts that never received a quorum-publish for this identity MUST reject the recovery (fail-closed). Deployments opting out of quorum-publish publication accept that compromise-recovery falls back to out-of-band re-establishment: the user sends contacts a fresh signed introduction, and contacts trust-on-first-use the new identity.

The fail-closed property is load-bearing for the security model. Without it, an attacker holding arbitrary signatures could synthesise a “recovery” event and convince contacts to update their address books. The cached quorum-publish is the contact’s trust anchor; recoveries that cannot validate against it are not honoured.

Quorum compromise. If more than N − K of the quorum’s constituent keys are compromised simultaneously, the attacker can sign any quorum-authorised attestation and the identity is fully compromised. The architecture mitigates this through K, N, and custodial diversity, but cannot eliminate it. Quorum compromise is the worst-case failure mode of any K-of-N system; the parameters are deployment choices reflecting the deployment’s threat model.

2.7. Rotation Mechanics

Three kinds of rotation appear in the cert lifecycle, each with distinct signing requirements and use cases:

• identity-rotation-handoff (graceful, dual-signed). Routine key roll: the old key signs and the new key signs the same attestation, demonstrating that the rotation is consensual. Used for hygiene rotation, scheduled key replacement, and planned device replacement. The dual signature is the security property — an attacker holding only the old key cannot complete the handoff alone; an attacker holding only the new key cannot either.
• identity-rotation-recovery (compromise, K-of-N quorum signed). Described above. Used when the old key is unavailable (lost, compromised, or destroyed). The quorum is the only signing path that does not require possession of the old key.
• identity-retirement (explicit termination, K-of-N quorum signed). Marks a cert as terminally retired (no successor); the chain dead-ends. Used when an identity is decommissioned (former employee, retired service account) or when a delegated sub-controller is removed without replacement.

Identity-rotation-handoff and identity-rotation-recovery preserve the identity (the handle the contacts cache); they replace the key behind the handle. The contact-side caching layer (§5.1 in EXTENSION-IDENTITY) tracks the supersedes chain and updates the handle cache to the current live key as rotations arrive. Identity-retirement terminates the chain; subsequent attestations attempting to reference the retired cert do not chain-validate.

2.8. Public-Facing Identity

What contacts see depends on which subtree of an identity is exposed to sync. The identity extension defines a small set of audience tiers:

• system/identity/internal/... — internal management state. NOT synced to contacts. Includes peer-config, internal-mode agent certs (privacy default), sub-controller certs that are deployment-internal.
• system/identity/public/... — the public face of the identity. Synced to all contacts. Contains the top-level controller cert (in the three-key default) or identifier cert (in the four-key advanced), plus agent certs in mode = public.
• system/identity/relationships/{contact_id}/... — per-relationship publication. Synced only to the named contact. Used for agent certs the identity has minted specifically for one contact (mode = per-relationship).
• system/quorum/{trusts_quorum}/... — the quorum’s published state, including quorum-publish events that contacts cache as the recovery trust anchor. Synced to all contacts as part of the identity’s dual-subtree sync surface.

Dual-subtree sync. Contacts receive both system/identity/public/... AND system/quorum/{trusts_quorum}/... as a unit. The quorum state is necessary for recovery validation; the public certs are necessary for connection authentication. Either alone is insufficient.

Operational-key confinement (MUST). Controller signatures NEVER appear under system/identity/public/.... This is a structural invariant: implementations MUST reject attestations under public paths carrying signatures from any currently-live controller of the trusted quorum. The invariant prevents an attacker who has compromised a controller from publishing controller-signed attestations to public paths and tricking contacts into trusting them. Controllers sign internal-management entities only; the K-of-N quorum signs everything that crosses to the public surface.

Privacy opt-out. Deployments may decline to publish quorum-publish. The trade-off is recovery ergonomics: contacts cannot validate identity-rotation-recovery events without a cached quorum-publish, so compromise-recovery degrades to out-of-band re-establishment. The architecture honours both choices: high-privacy deployments accept the out-of-band recovery flow; high-availability deployments publish quorum-publish so recovery is automatic.

2.9. Connection Establishment

The three-message connection handshake (see The Entity Core Protocol) is structured as three EXECUTE round-trips:

1. HELLO. Initiator presents its peer keypair entity, protocol version, and supported algorithm sets. Responder presents the same. The intersection of algorithm sets becomes the negotiated set for this connection.
2. AUTHENTICATE. A nonce-based proof of possession: each peer signs a challenge produced by the other. The signature is verifiable against the public key referenced in the peer keypair entity. Mutual authentication completes here.
3. Initial capability grant. The responder issues the initiator a starting capability covering what the initiator may immediately do — typically read access to the responder’s handler manifest plus the ability to request additional capabilities.

For peers running the identity extension, the HELLO carries the peer’s agent cert (and the cert chain back to the quorum) alongside the peer keypair entity. The responder validates the agent cert chain against the trusted quorum’s cached quorum-publish and (if accepted) issues the initial grant under authority derived from the identity context. For core-only peers, the HELLO carries only the peer keypair entity and the responder authenticates against the raw peer ID.

The handshake uses the same EXECUTE dispatch as everything else; there is no special connection protocol. Pre-authentication, only the connection handler at system/protocol/connect is reachable; post-authentication, the initial grant determines reachability.

2.10. Peer Roles in Deployment

In deployment, peers occupy a small number of structural roles, each with a characteristic capability and tree configuration. These are patterns the system supports rather than enumerated types; deployments compose them as needed.

• Long-lived peers. Stable identity (durable controller-cert chain in a three-key or four-key setup), persistent tree, full capability model. The typical user-facing peer.
• Service peers. Handler-focused. Limited tree (just the handler manifest, configuration, and operational state), grant-scoped to the operations they implement. Identity-wise, often a service-account identity with its own quorum.
• Relay peers. Route messages between peers without reading content. Capabilities cover routing operations (forwarding, queueing); encrypted content remains opaque to them. May run as a core-only peer if no identity-layer features are required.
• Light peers. Minimal tree, request-only, no handler hosting. Mobile clients, IoT devices, ephemeral session participants. Typically agents of a heavier identity (the user’s main identity) rather than identities of their own.
• Cluster peers. A set of peers with mutual full trust within an infrastructure boundary, sharing generation pools. Note: cluster in this sense refers to the planned system/cluster runtime-coordination layer (HA, replication, leader election), distinct from group, which is the identity-level concept for multi-user collective identities (per EXTENSION-GROUP). Cluster peers are an infrastructure pattern; group identities are an identity-extension consumer.

Each role is a configuration of identity, capability, tree, and (when applicable) encryption. The roles do not need separate spec support: they emerge from how the primitives are deployed.

2.11. Key Hierarchy

Three classes of keys appear at distinct lifetimes:

• Identity keys. Long-lived. Ed25519 keypairs whose public key derives the peer ID. Quorum constituent keys, controller keys, identifier keys (four-key only), and agent keys all sit here. Rotated under controller authority (handoff) or quorum authority (recovery) through the identity extension.
• Encryption subkeys. Long-lived but separately rotatable. X25519 keypairs derived from, or attested by, identity keys. Used for key agreement when establishing per-entity encryption keys. Separating signing and encryption follows standard cryptographic practice: an identity-key compromise does not immediately decrypt past traffic if the encryption subkey is rotated independently.
• Ephemeral keys. Short-lived. Per-entity or per-session symmetric keys, derived from key agreement, discarded after use. Forward secrecy lives here: a compromise of long-lived keys does not retroactively decrypt past sessions, because the ephemeral keys are no longer available.

The key hierarchy is enforced through the extension layer (identity for the long-lived part, the encryption extension for the ephemeral part). The substrate is agnostic: any peer that signs entities, derives content hashes, and verifies signatures has the cryptographic primitives the substrate requires.

3. Capability Architecture

The capability system is the core authorization mechanism. Every EXECUTE carries its own capability token; verification is per-message and stateless. We describe the structure of a capability, how attenuation is enforced, how delegation chains are verified, and how the two-level dispatch check works.

3.1. Four-Dimensional Grants

A capability token is an entity:

system/capability := {
  granter:        bytes,        # peer ID hash of the issuing peer
  grantee:        bytes,        # peer ID hash of the receiving peer
  parent:         hash?,        # content hash of parent capability (null for root)
  grants:         [grant_entry], # what this capability authorizes
  caveats:        map?,         # delegation constraints (depth, TTL, no-delegate)
  not_before:     timestamp,
  expires_at:     timestamp,
  signature:      bytes         # signature by granter over the rest
}

grant_entry := {
  handlers:       scope,        # which handlers (path patterns)
  resources:      scope,        # which data paths (path patterns)
  operations:     scope,        # which operations
  peers:          scope         # which remote peers
}

scope := {
  include:        [pattern],
  exclude:        [pattern]?
}

The grant entry has one field per per-grant-entry primitive that varies per grant: handler (Mechanism), resource (Object), operation (Verb), peer (Context spatial axis). These four are derived in Dimensional Completeness from analysis of the attribute structure of distributed-system authorization requests. A request to a peer for an operation on a resource via a handler has exactly these four per-grant-entry scopes; four additional per-token primitives (subject, authority, attenuation, and context-temporal) live at the capability-token level above the grant entries, and a separate revocation mechanism operates outside the token via system/capability/revocation.

All four dimensions in a single grant are conjunctive: a request matches the grant only if every one of (handler, resource, operation, peer) falls within its respective scope. Two grants in the same token are alternative: a request is authorized if it matches any of the token’s grant entries. This gives capability tokens compositional structure: a single token can authorize different things on different paths to different peers, without forcing a one-grant-per-target inflation.

The scope structure (include plus optional exclude) supports the same patterns across all four dimensions: exact matches, prefix patterns, wildcards. Pattern matching is uniform: the same matching algorithm applies to a handler scope as to a resource scope as to a peer scope. This uniformity is what makes the four-dimensional grant tractable: a verifier has one matching primitive, applied four times per check, rather than four different match logics.

3.2. Attenuation by Construction

A child capability must be a subset of its parent on every one of the four grant dimensions. Verification enforces this:

• For each grant entry in the child, there exists a grant entry in the parent such that every dimension of the child’s entry is a subset of the corresponding dimension of the parent’s.
• Subset is structural: every pattern in the child’s include must be covered by the parent’s include and not excluded; the child’s exclude can be larger than the parent’s.
• Caveats can only narrow: a child can shorten the not-before / expires-at window, lower the max-delegation-depth, or add a no-delegation caveat, but cannot expand any of these.

The verification is mechanical. Given a child and its parent, walking the four-dimensional containment check is bounded by the number of patterns in the scopes (typically small) and produces a single accept/reject. There is no semantic interpretation: subset is set containment, not policy interpretation.

The cryptographic enforcement is the parent-reference chain. The child capability includes parent: hash(parent_capability), and the parent’s content includes its own parent reference, and so on to a root capability. Any attempt to amplify — to insert a more-permissive intermediate, or to swap in a different parent — changes the content hash of the modified link, which breaks the chain because subsequent links reference the original hash. The chain cannot be modified without invalidating it. Amplification requires forging the signature of an intermediate granter; the entity model provides no other path.

3.3. Delegation Chains

A capability’s authority traces to a root capability through a chain of intermediate delegations. The root is a capability whose granter is a peer with structural authority over the resources being granted — typically the peer that owns the relevant tree subtree.

A delegation chain is content-addressed end-to-end. Every capability in the chain references its parent by hash; every reference is verifiable; the chain as a whole is verifiable by walking it and checking signatures, attenuation, and freshness at each step. The chain is also transferable: an EXECUTE envelope can carry the full chain in its included map, and the receiving peer can verify the chain without consulting any other peer. This is what self-authentication means for entity-system capabilities: a token plus its chain is, by itself, sufficient to prove authority.

Chains have a maximum depth (recommended default 64, configurable per deployment). Verification walks the chain link by link, so its cost is linear in depth — each link is a signature check. An attacker who could present an unbounded chain could therefore force unbounded verification work, so a conformant peer MUST enforce a finite maximum depth and reject an over-depth chain cleanly, with a chain_depth_exceeded (400) response, while continuing to serve other requests. The status is deliberately a structural error, not an authorization denial: a too-deep chain is something the caller corrects, not a statement that the caller lacks the capability. The bound’s value is a deployment choice, not a protocol constant — the requirement is that some finite bound is enforced; beyond capping verification cost, the bound forces deployments to design their delegation patterns rather than letting chains grow without limit.

A subtle point about chain verification: the chain proves what was granted at issue time, not what remains valid now. To verify a capability currently authorizes a request, the verifier must additionally check:

• Every link’s signature is valid.
• Every child is properly attenuated against its parent.
• Caveats are satisfied (delegation depth, TTL, no-delegation).
• The current time is within the token’s [not_before, expires_at] window.
• The root capability is still bound in the granter’s tree.

The last point is the link to revocation, covered next.

3.4. The Three Slots: Subject, Authority, Attenuation

A capability chain names three structurally distinct identities, and conflating them is the recurring source of cross-peer authorization bugs. They are independent slots:

• Subject — the grantee at the chain’s tip: the peer that authors the EXECUTE. Verification checks that the requester is this grantee (grantee == EXECUTE author).
• Authority — the chain root: the peer with structural authority over the resources, the source from which permission flows.
• Attenuation — the in-chain granters between root and tip, the installer among them: each link may only narrow what it received, never widen it.

In the single-peer case the three collapse onto one identity — a capability a peer issues to itself has the same peer as subject, authority, and sole attenuator — which is why the distinction is invisible locally and easy to miss. Cross-peer dispatch pulls them apart: the resource owner, the requester, and the attenuators become three different peers, and a check that silently treats any two as one is exactly the class of bug the spec kept hitting.

The protocol spec reached this decomposition empirically. Its §5.2 records the three slots as a clarifying note written after a run of cross-peer capability bugs, each one a place where two slots had been conflated — a chain root mistaken for an in-chain granter, a grantee mistaken for the author. The structural methodology of Dimensional Completeness arrives at the same three by irreducibility testing of the authorization attribute space. Both routes converge.

3.5. Two-Level Verification

A capability check happens at two levels in the dispatch path:

• Level 1 (dispatch). Before the handler runs, the dispatch layer checks the capability token against the four grant dimensions: does any grant entry in the token cover this handler, this operation, this resource, this peer? If not, the request is rejected before the handler sees it.
• Level 2 (handler). Inside the handler, before reading specific paths or performing specific operations, the handler re-checks the capability against the actual paths it will touch. The handler has its own grant (issued when it was registered); the effective authority is the intersection of the caller’s capability and the handler’s own grant.

The two levels are defense in depth. Level 1 catches broad violations cheaply (a peer with a read-only grant attempting a write is rejected at dispatch). Level 2 catches specific violations that the dispatch layer cannot anticipate (the handler may compute the specific path from the request and check it; the dispatch layer only sees the request’s declared scope).

Level 2 also handles the handler-on-behalf-of-caller pattern. When a handler issues sub-requests to other handlers (or to other peers), it can do so on its own authority (using the handler’s own grant) or on the caller’s behalf (passing the caller’s capability through). The two-grant intersection ensures that handlers cannot escalate: a handler issued a narrow grant cannot grant its callers broader access than its own, even if a caller’s capability would have allowed it.

3.6. Handler Authority

A handler’s grant is itself a capability token, issued when the handler is registered and stored at a known path under the handler manifest. The grant defines what the handler is permitted to do — which sub-handlers it may call, which paths it may write, which peers it may contact. Handler registration is an EXECUTE to the system handler at system/handler, and the registering peer’s capability must cover the registration scope: this prevents arbitrary peers from registering handlers with arbitrary grants.

The result is that handler authority is itself capability-scoped. A handler that promises to operate only within a subtree is structurally limited to that subtree by its own grant; if it attempts to act outside, its own capability check fails. The discipline forces handlers to declare their authority surface up front, and the system enforces the declaration.

4. Revocation

A capability that cannot be revoked is, in practice, a capability that lasts forever. TTL bounds are a partial answer; explicit revocation is the complete one. The entity system handles revocation as a tree operation: revoking a capability is unbinding it.

4.1. The Mechanism

A root capability is stored at a known path in the granter’s tree, typically:

system/capability/active/{root_hash}

The system/capability/active/ subtree is the set of currently-active root capabilities the granter has issued. To revoke a capability, the granter unbinds it:

EXECUTE put system/capability/active/{root_hash}  →  (binding deleted)

Verification then includes a tree-lookup step: at the end of chain walking, the verifier checks whether the root capability is still bound under system/capability/active/. If the binding is present, the chain is live. If absent, the entire chain rooted there is revoked — and because the chain is content-addressed and ordered, every descendant capability also becomes invalid.

This mechanism eliminates the blacklist problem. A blacklist grows monotonically: every revoked credential remains on the list, and verifiers must check the list on every authorization. The tree-based mechanism uses the same lookup that capability verification already requires (a tree get), with no auxiliary structure that grows over time. Revoked capabilities leave no trace in the active set; their content remains in the content store (audit is preserved by the IM axis of emit), but the tree no longer binds them (revocation is the TM axis).

4.2. The IM / TM Split

The two-axis structure of emit (see The Entity System) is what makes audit and revocation compose. Every emit is a Store event (the IM axis: a new content hash enters the immutable content store) and a Bind event (the TM axis: a path’s binding is updated).

• Audit lives on the IM axis. The content store is append-only: every capability ever issued, every entity ever stored, remains addressable by its content hash. A revoked capability is still inspectable; the binding has been removed, but the content endures. Audit logs are queries over the content store, not over the active bindings.
• Revocation lives on the TM axis. The binding at system/capability/active/{root_hash} is mutable; unbinding it is a TM event. The TM axis is where state changes meaningfully over time; the IM axis preserves history.

Because the two axes are independently observable, an audit consumer can subscribe to IM events (recording every capability issuance) without conflicting with a revocation consumer that subscribes to TM events. The split is structural, not implementational: it follows from how emit is defined as a primitive (see The Entity System).

4.3. Generation Pools

Individual revocation handles individual capabilities. Some deployment scenarios need broader revocation: an employee leaves the company; a relay peer is compromised; a key is rotated. Revoking each affected capability one at a time is slow and error-prone. The generation pool mechanism provides O(1) scoped mass revocation.

A capability can be issued under a pool: a named subtree like system/capability/pool/external_sharing/. The pool itself has a generation counter, stored at system/capability/pool/external_sharing/generation. Capabilities issued under the pool carry a pool_generation field with the value of the counter at issue time.

Verification adds one step: the verifier reads the pool’s current generation and compares it to the capability’s pool_generation. If they match, the capability is current; if they don’t, the capability is revoked. Incrementing the pool’s generation revokes every capability issued under that pool, instantly and in O(1) work: one tree write, with no need to enumerate the affected capabilities.

Pools are independent: revoking the external_sharing pool does not affect the internal pool or the audit pool. Deployments use pools to partition revocation domains: one pool per role, one per cluster, one per project, with revocation of each domain scoped to its pool. The cost of mass revocation becomes constant in the number of affected capabilities, rather than linear.

4.4. TTL as Baseline

Every capability carries not_before and expires_at fields. TTL is the baseline revocation mechanism: a capability with a short TTL is revoked when it expires, with no action required from anyone. Short TTLs (minutes to hours) force frequent refresh and bound the damage window of any single token. Long TTLs (days to weeks) reduce refresh overhead at the cost of slower natural revocation.

TTL handles offline peers without coordination: a peer that cannot reach the granter cannot refresh, and stale capabilities simply expire. The combination of TTL plus explicit revocation gives deployments two knobs: short TTL plus rare explicit revocation, or long TTL plus aggressive explicit revocation, depending on which cost they prefer to pay.

4.5. Tiered Implementation

Real deployments need different levels of revocation infrastructure. The capability specification supports a tiered model:

• Tier 0: TTL only. Capabilities expire; no explicit revocation. Suitable for short-lived sessions and simple deployments.
• Tier 1: + delegation chains with attenuation and caveats (depth, TTL, no-delegation). Still no explicit revocation, but delegation is structured.
• Tier 2: + explicit revocation via the tree-based mechanism. Individual capabilities can be revoked.
• Tier 3: + generation pools, push/pull propagation between peers. Scoped mass revocation, online-optimistic propagation.
• Tier 4: + relationship derivation. Capabilities derived from group membership, role assignment, or other patterns. The most expressive tier; required for large deployments with rich access patterns.

Unknown caveats are rejected (fail-closed). A peer that does not implement a higher tier cannot accidentally accept a capability that relies on a caveat it does not understand: the verifier rejects what it does not know how to check.

4.6. Trade-Offs

The tree-based mechanism is not free. Three trade-offs are worth naming:

• Online vs offline. Verification requires a tree-lookup against the granter’s current state. Offline verifiers must either trust a recent snapshot (with the staleness window as the revocation lag) or refuse to verify until they reconnect. TTL bounds the staleness exposure.
• Selective vs mass. Tier-2 individual revocation is selective but linear in revocations; Tier-3 pool revocation is mass but coarse-grained (the pool is the unit). Deployments compose both.
• Immediate vs eventual. Tree-unbinding is immediate locally: the granter sees the revocation as soon as the emit commits. Propagation to other peers is eventual: they see it when they next consult the granter’s tree (push notifications via subscriptions accelerate this). A revoked capability presented to a peer that has not yet seen the revocation will be accepted; the staleness window is the propagation lag. Deployments that need provably-immediate revocation must combine pool revocation with subscription-based push.

The mechanism handles most production revocation scenarios at low cost; the residual cases (immediate-globally, fully-offline) are handled by extension-level patterns rather than by the substrate.

5. Encryption

Encryption on this substrate is deliberately narrow, and the scope line is the first thing to understand about it. What is specified is stateless, single-shot encryption: an entity is encrypted once, for storage or for one recipient, and the ciphertext stands on its own. Stateful interactive encryption — sessions, streaming, chat, the ratcheting constructions of Signal, Noise, and MLS — is a structurally distinct problem and is a separate piece of work, sharing this substrate rather than extending it. Anything below is about the single-shot half. The other half is real, and it is not here.

The narrowness is deliberate rather than a gap: the design under-promises so that an implementation builds to the threat model actually met, and we follow that discipline rather than smoothing it. What the substrate has not had is use. The mechanisms have conformance vectors, not deployments; nothing here has been exercised against a real adversary, over real time, at real scale. Treat this section as a description of a design that fits the substrate, not as a report from production.

Encryption is independent of authorization. The capability system answers who may act; encryption answers who may understand. Both can apply to the same entity, either can apply without the other, and together they give defense in depth.

5.1. Entity-Level Encryption

An encrypted entity is an entity of type system/encrypted whose data field carries a typed ciphertext. The inner entity ({type, data}) is encrypted as a whole; the type information lives inside the ciphertext, not in the outer envelope. To a peer without decryption capability, the inner type is opaque; to a peer with it, decryption produces the inner entity directly, with its native type and content hash recoverable.

The encrypted entity has its own content hash, derived from its ciphertext bytes. This means the encrypted form is itself addressable, transferable, and integrity-checkable without decryption: a relay peer can route or replicate an encrypted entity without ever seeing its plaintext. The same encrypted entity is the form on the wire, on disk, and in memory — no re-encryption at boundaries, no separate transport-encryption layer.

The decrypted inner entity carries its own (separate) content hash: the hash it had before encryption, derived from its own bytes. So an entity has two identities — the encrypted form’s hash and the plaintext form’s hash — and the two are independent. References can be made to either, depending on which view of the entity is intended.

5.2. Three Modes

Three encryption modes are distinguished by recipient pattern:

Peer mode (single-shot, to one recipient). A specific recipient peer. Hybrid encryption: the inner entity is encrypted under a fresh symmetric key, and the symmetric key is wrapped under the recipient’s encryption subkey via key agreement (X25519). Structurally this is a sealed box — the same shape as crypto_box or age, with sender authentication added. The sender’s ephemeral key is discarded after encryption, so a sender cannot decrypt their own past sends.

It does not provide forward secrecy, and the distinction is worth stating precisely because the mechanism invites the opposite reading. Discarding the sender’s ephemeral key is not forward secrecy against compromise of the recipient. The recipient’s decryption key is long-lived by construction, and the wire carries the sender’s ephemeral public key alongside the ciphertext; anyone who later obtains the recipient’s private half and has kept that pair can recover the shared secret and decrypt. The threat model peer mode actually addresses is passive observation of the relay and storage path — an intermediary that carries the bytes without reading them — not later compromise of the endpoint that received them. Interactive forward secrecy of the kind a ratchet provides belongs to the session work named above, and is not available here.

Self mode (storage). Encryption for one’s own future access. The symmetric key is derived from a long-lived local secret; the same key encrypts and decrypts the entity across sessions. No forward secrecy: a key compromise reveals all past and future self-encrypted entities. The trade-off is intentional: archival storage requires that the holder be able to decrypt old data without preserving ephemeral keys.

Group mode (shared, static). A set of recipients sharing access. A random symmetric key encrypts the entity; the key is wrapped separately for each group member (using peer-mode wrapping). Group membership is then a key-distribution question: adding a member means wrapping the key for them; removing one means re-keying and re-wrapping. Two limits are structural rather than incidental. Re-keying protects future entities only — a removed member keeps the old key and can still decrypt anything they could read before, so removal is not retroactive. And the member set is not hidden: each wrapped key names its recipient, so anyone holding the entity can see who the group is. The cost is linear in group size, and the mode is built for small, stable groups; membership that churns wants the tree-based key agreement of MLS, which is the session work’s territory, not this one’s.

The three modes share the entity-level encrypted-wrapper structure; they differ in how the symmetric encryption key is established. The substrate is neutral: any keying mechanism that produces an authenticated ciphertext fits.

5.3. Recoverability Is the Axis, Not Secrecy

There is a real tension between forward secrecy — communication should stop being decryptable — and durable storage, where data must stay recoverable for as long as its holder needs it. The three modes do not resolve that tension; they sit on one side of it. All three are built so that a holder of the right long-lived key can decrypt later, because all three exist to move or keep data rather than to hold a conversation. What they distinguish is who retains that ability and for how long: self mode for one holder indefinitely, peer mode for one recipient, group mode for a fixed set until the key is rotated forward.

Naming this plainly matters more than claiming the tension away. A design that keeps data recoverable is the right design for storage and transfer, and the wrong one for a conversation that should become unreadable. Resolving the other side needs ratcheting state between two live parties, which is the session work, and it is a different extension for that reason. A deployment chooses a mode per entity rather than per protocol — but every choice on offer here is a choice about recoverability, not about secrecy over time.

5.4. Authorization vs. Confidentiality

Capabilities and encryption are independent dimensions of access. The clearest case is a relay peer:

• The relay holds a capability authorizing it to route messages between named peers. It can read the message envelopes, see source and destination, and forward the message.
• The relay does not hold the decryption key for the messages’ contents. The encrypted inner entity is opaque to it.

This is defense in depth: a relay compromise leaks routing metadata (who is talking to whom) but not message content. A capability compromise allows unauthorized actions but does not reveal encrypted content the attacker lacks keys for. The two compromise classes are independent; an attacker needs both to fully read encrypted communication.

The substrate does not couple the two. A peer can route encrypted entities it cannot read; a peer can decrypt entities it is not authorized to act on. This separation is what lets the capability layer and the encryption layer evolve independently — and what lets deployments mix and match (e.g., authenticated-but-unencrypted internal traffic plus encrypted-for-recipient external traffic) without compounding mechanism.

5.5. What Is Not Yet Settled

The encrypted-wrapper shape, the three-mode framing, the algorithm registries, and the authorization-confidentiality split are settled: algorithms are selected by a versioned byte under a documented registry rather than hardcoded, which is the same discipline the protocol applies to hashes and keys, and a floor suite is mandatory so that two peers always share one. What remains open is genuinely open, and most of it is about what the encrypted form reveals rather than whether it can be read:

• Metadata. Recipient-hiding and size-hiding are identified as work and are not specified. Today an encrypted entity discloses who it is for and roughly how large it is, and group membership is visible on its face. For some deployments that is the more important leak than the plaintext.
• Post-quantum key agreement. A hybrid slot is reserved so the discipline holds and a first implementation has a target, but the construction is not yet realized.
• Distributed key custody. Splitting a backup key across several holders is designed and not built, which leaves key loss a sharper operational risk than the cryptography suggests.
• The session half. Everything interactive — ratcheting, streaming, chat, dynamic groups — sits in the sibling work described at the top of this section. It is the larger unknown of the two, and no part of it is available yet.

Above all of it sits the plainest limitation: none of this has met a real adversary. The mechanisms are specified and checked against conformance vectors, which establishes that implementations agree with each other, not that the design survives contact with use. Cryptographic constructions earn their reputations by being deployed, attacked, and revised. This one has not started.

We describe the structure rather than the choices because the structure is the load-bearing claim: entity-level encryption with three modes, authorization-confidentiality separation, and same-bytes-everywhere. The choices will settle through implementation; the structure already fits the substrate.

6. Deployment Patterns

The substrate provides mechanism. Deployments compose mechanism into patterns. This section describes the patterns that recur across deployment scenarios, organized by the question they answer.

6.1. Identity Presentation

A peer’s identity in deployment is rarely just its peer ID. The standard presentation is a mini-tree envelope:

• The peer keypair entity at the root (system/peer).
• The public key it hashes, in the envelope’s included map.
• When the identity extension is installed: the relevant agent cert plus the cert chain back to the trusted quorum (per EXTENSION-IDENTITY’s peer graph). When it is not: nothing further at the identity layer; recognition is by raw peer ID.
• A starting capability the peer is bringing into the connection.
• Optional metadata: display name, organization, contact path.

The envelope is what the peer sends in HELLO. The counterparty verifies the peer keypair entity’s hash, checks the public key matches, validates the cert chain (if present) against its cached quorum-publish for the identity, and accepts the capability if it traces to a root the counterparty trusts.

Human-readable aliases are entities. A directory service is a peer that holds entries of the form alias/{name} → identity_hash, signed by an authority the consumers trust. Aliases are not part of the substrate; they are an application pattern built on the substrate’s primitives.

6.2. Delegation

A capability holder can delegate by issuing a child capability to another peer. The child must be a strict subset of the parent on all four dimensions. Common patterns:

• Sharing for collaboration. The owner of a subtree delegates read access to a collaborator, scoped to the subtree and with a finite TTL. The collaborator’s capability includes the owner’s as its parent and adds caveats (e.g., no_delegation to prevent further re-sharing).
• Time-boxed access. A short-TTL delegation that auto-expires; useful for temporary consultants, audits, or one-off tasks. The token’s expires_at field carries the explicit window.
• Capability request flow. The connecting peer sends an EXECUTE to a capability-issuing handler with a request for the scope it needs. The handler evaluates the request against the connecting peer’s identity, the existing trust relationships, and the deployment’s authorization policy, and issues the capability if the policy allows. The request flow is itself an EXECUTE; there is no separate channel.
• Re-delegation chains. Alice delegates to Bob; Bob, holding a delegate-able capability, further delegates to Charlie. Each link must attenuate; the chain depth is bounded by the max_delegation_depth caveat. Verifiers walk the full chain.

The patterns share the same mechanism (capability issuance with attenuation) and differ only in the policy that drives them.

6.3. Role-Based Configurations

Different peer roles need different default capability shapes. Concrete patterns:

• IoT sensor. Minimal grant: write access to a specific subtree (the device’s reporting path) and no other handler invocation rights. Identity is a long-lived peer key; capability is renewed periodically (short TTL, ~hours).
• Storage node. Read and write to sync paths shared with replication peers; no execute rights on application handlers. Replicates encrypted content without decrypting it.
• Relay peer. Routing rights only: dispatch operations on system/relay/*, capability-scoped visibility into which peers it may serve. No content-decryption capability.
• Service peer. Handler-focused: implements specific handlers, has a grant that lets it read its configuration subtree and the operational state it needs, and is authorized to invoke a defined set of upstream operations.
• Admin. Broad grant within a cluster boundary, with full audit logging (audit lives on the IM axis; admin actions are entities like any other). Often gated through a quorum of admin peers rather than a single admin peer.

Each is a configuration of capability, encryption, and tree shape. None requires special protocol support; each is composition of substrate features.

6.4. Cluster and Group Patterns

Cluster and group are different concepts in this architecture; the security model treats them differently.

A group is an identity-level concept (per EXTENSION-GROUP). A group is itself an identity — it has its own quorum, its own controller, its own agents, all built from the identity-stack primitives described above. What distinguishes a group from a single-user identity is that its quorum constituents are drawn from members or admins rather than from personal backup keys, and the group’s lifecycle (form, dissolve, merge, split, add/remove member, add/remove subgroup) is exposed through the group handler at system/group. Security-wise, every property of an individual identity — recovery via K-of-N, controller rotation without disturbing contacts, fail-closed validation against cached quorum-publish — applies to a group identity unchanged. Members may act as themselves (their own identity stack) or on behalf of the group (via an acting-on-behalf-of attestation that the group has issued); the two surfaces are distinct.

A cluster is an infrastructure-level concept (the planned system/cluster extension). A cluster coordinates peers at the runtime layer — high-availability, replication, leader election, generation-pool sharing within a trust boundary. Cluster peers typically share a generation pool, and revoking the pool revokes all cluster-internal access in a single tree write. The cluster extension is not yet specified at the same level of detail as identity or group; we treat it as a deployment pattern here rather than as a normative mechanism.

The two compose: a group’s members may run their daily work through a cluster (the user’s laptop, phone, and personal server forming a cluster of agents under the user’s individual identity, all of which are members of the group). The group’s identity manages the recognition surface; the cluster manages the operational shared state.

Trust boundaries are explicit at both levels: a cluster’s pool revocation does not affect another cluster’s pool; a group’s controller revocation does not affect another group’s controller; external delegations from a cluster’s peers do not implicitly cascade through the cluster pool; an agent’s authority within a group is scoped by the group’s role assignments, not by membership alone.

6.5. Information Disclosure

Authorization controls what a peer may do; it also controls what a peer may see. The two are connected through the tree.

• Handler manifest exposure. What a connecting peer can learn about available handlers depends on its initial capability. A minimal initial grant exposes only the connection handler and a request-capability handler; deeper grants expose more of the manifest. The minimum initial grant is by design: a peer with an unknown intent should see only enough to ask for what it needs.
• Capability-scoped views. Reads against the tree are scoped to what the requester’s capability allows. A peer that holds read rights on data/projects/alpha/* cannot enumerate data/projects/beta/* — not because the latter is hidden by convention, but because the read attempt fails the resource-scope check.
• Metadata leaks. Even with content encrypted, routing metadata (source, destination, timing) is visible to relays. Deployments concerned about metadata exposure use mix-network patterns or onion routing on top of the substrate; the substrate does not provide metadata privacy by itself.

6.6. Incident Response

When something goes wrong, the substrate provides several response patterns:

• Key compromise. Rotate the affected key through the IDENTITY extension’s rotation ceremony — identity-rotation-handoff (dual-signed) for graceful roll, identity-rotation-recovery (K-of-N quorum signed) when the old key is unavailable. The cert chain advances; predecessor attestations remain in the content store for audit, but the binding moves to the successor cert. If the compromised key was used to sign capability tokens, the relevant generation pool is incremented.
• Unauthorized access. Revoke the specific capability via tree unbind, increment the relevant pool, audit the trail via the content store (every action is an emit; every emit is content-addressed; the audit is cryptographic).
• Relay compromise. The encrypted content remains safe. Revoke the relay’s routing grant; rotate any cluster pools the relay had access to; reconfigure routing to other relays. The relay’s content store is forensically preserved; what it routed but could not decrypt is not at risk.
• Cluster compromise. Severity depends on whether internal-trust assumptions broke. The cluster pool is incremented (revokes all cluster-internal access); peer attestations are reviewed; the cluster is rebuilt from the surviving attestation graph if a recovery quorum is available.

Incident response in the entity system uses the same mechanisms as normal operation: tree writes, capability issuance and revocation, attestation updates. There is no separate “break-glass” interface, because break-glass is a generation-pool increment with the right authority.

7. Comparison and Analysis

This section places the entity system’s security model in context: against existing capability systems, against the security philosophies of high-primitive systems, and against the broader landscape analyzed in Convergent Evolution.

7.1. Comparison to Existing Capability Systems

We compare against four systems that represent different stable points in the capability-system design space.

Macaroons (Birgisson et al. 2014) use a contextual-caveat model: a Macaroon is a bearer token plus a chain of caveats, each restricting the bearer’s authority. Caveats are opaque to the protocol — their interpretation lives in the service that issues them. Strengths: flexible attenuation, no central authority for caveat interpretation. Gaps: no four-dimensional grant structure (caveats are general but unstructured), per-service granularity (no handler dimension across services), no peer dimension, no integrated content addressing.

UCAN (Zelenka et al. 2022) is a JWT-based capability format for decentralized contexts: a UCAN has a subject (DID), an ability (operation), a resource (URI), and a proof chain back to a root issuance. UCANs are signed and chainable. Strengths: decentralized issuance, structured delegation, DID-based identity. Gaps: no handler dimension (the resource URI encodes both routing and content), no peer dimension (URIs are location-independent), no content-addressed identity for the tokens themselves (UCANs are referenced by JWT identifier, not content hash).

Biscuit (Couprie et al. 2021) combines Macaroons-style attenuation with a Datalog policy layer: each token can carry a small Datalog program that participates in authorization decisions. Strengths: rich expressiveness for policy, structured attenuation. Gaps: the policy layer is per-token and per-service, not integrated with a substrate; no handler or peer dimensions in the base model; no content addressing.

Zanzibar (Pang et al. 2019) is Google’s centralized authorization system based on relation tuples. Authorization is computed by traversing a relation graph: a subject has a relation to an object via a path through groups, roles, and explicit grants. Strengths: enormous scale, strong consistency guarantees, sophisticated relation algebra. Gaps: centralized (a Zanzibar deployment has authoritative servers); not capability-based (no transferable tokens); no peer dimension (single-domain assumption); no content addressing.

The entity system’s distinctive structural contributions are Handler and Peer as first-class grant dimensions, and content-addressed identity for the tokens themselves. The handler dimension lets a capability carry mechanism scoping (“you may invoke this handler”) separate from operation scoping (“you may perform this action”), which existing systems collapse into a single resource-or-service axis. The peer dimension lets a capability carry topology scoping (“you may act on this peer’s tree”), which existing systems treat as a property of the deployment topology rather than as part of the authorization. Content-addressed identity lets the tokens themselves be entities — inspectable, composable, verifiable by hash equality.

7.2. Security Philosophy: What Do You Trust?

Different systems answer the question “what is the unit of trust?” differently. The answers are not feature-level differences; they are philosophical commitments about how security is supposed to work.

“Trust the code.” Holochain’s model: every peer runs identical validation code (the DNA), and security comes from code identity. If you and I run the same DNA, we follow the same rules, and the rules are themselves the guarantee. Capabilities in Holochain are per-function, non-delegatable, secret-based: they exist within a DNA’s runtime, not across DNA boundaries. The DNA wall structurally prevents capability migration; capability tokens cannot escape the DNA context that issued them. The model is internally coherent but architecturally incompatible with delegable capability-based authorization: a delegable capability would need to be meaningful across DNAs, which requires content addressing of the capability tokens, which Holochain does not have.

“Trust the steward.” Plan 9 and Inferno’s model: a single trusted operator administers the namespace, and authority flows from the operator’s configuration. Capabilities are not the primary mechanism; access control lives in the file-server’s per-mount permissions. The model works for the deployment context Plan 9 was designed for (research labs and small organizations) and breaks down at scales where no single steward can be globally trusted. The mechanism class is distinct from Holochain’s: Holochain’s wall is architectural (DNA-determinism), Plan 9’s is organizational (centralized stewardship).

“Trust the identity.” The entity system’s model: capability tokens prove what you are authorized to do, regardless of what code you run, by tracing a cryptographic chain to a root capability issued by a peer that owns the relevant resources. Verification is local, per-message, and content-addressed. Identity is content-derived, capability tokens are content-addressed, and the chain is verifiable by anyone with the public keys of the granters. The model rests on the IXP capability triangle, which requires Full I (content-derived identity); a system at I1 cannot host it.

These are not “better” or “worse” relative to each other. They are different architectural commitments about where security lives. Trust-the-code (Holochain) gives strong determinism at the cost of capability migration. Trust-the-steward (Plan 9) gives simple administration at the cost of decentralization. Trust-the-identity (the entity system) gives decentralized capability-based authorization at the cost of requiring Full I and a tree-walk-based revocation mechanism.

7.3. The IXP Triangle as Structurally Privileged Surface

Of the systems analyzed in Convergent Evolution, the entity system is the only one that activates all three pairs of the IXP triangle simultaneously at full strength. The structural reason is the conjunction of three requirements:

• IX active requires capability tokens to be content-addressed entities, so that convergence verification (same hash = same capability) is a structural fact.
• XP active requires cross-peer dispatch to carry capabilities as part of the message, so that authorization is per-message and not session-bound.
• IP active requires peer identity to be content-derived, so that the chain’s references to granter peer IDs are themselves verifiable hashes.

Adjacent systems each have part of the triangle and are missing a critical pair:

• Holochain has IX (DNA-bound capabilities are content-addressed within the DNA) and XP (zome calls carry capabilities), but its IP is degraded: peer IDs do not escape DNA context, so the cross-DNA capability-meaning that the triangle requires cannot exist.
• Urbit has XP (scry and poke dispatch cross-peer) and IP (self-addressed peer IDs), but lacks I in the entity-system sense: no content-addressed entities, so IX cannot activate. Capabilities, if added, would have to be rebuilt on path-rooted identity rather than content-rooted.
• AT Protocol has IP (DIDs) and partial structure for cross-peer trust, but lacks X (no protocol-level dispatch), so the XP pair is latent: handler authority lives in PDS implementations, not in the protocol’s authorization model.
• Bitcoin has IP (content-addressed addresses) and an economic XP analog, but lacks general-purpose X, so its capability model is bounded to economic operations.

The pair-coverage view makes the gap precise. “Capability-based security” is not a single thing; it is the activation of a specific pair-bundle (IX + XP + IP). Systems that have one or two of the pairs implement portions of capability-based security; systems that have all three implement it in full. The entity system’s distinction is not a feature; it is the unique landscape position where the triangle activates simultaneously.

7.4. Security Properties from Content Addressing

Content addressing provides several security properties as structural consequences, not as added features:

• Tamper evidence. Any modification to an entity changes its content hash, which breaks every reference to the original. There is no way to silently modify a content-addressed entity; modification is structurally visible.
• Verifiable delegation. A capability chain is a sequence of content-addressed entities, each referencing its parent by hash. The chain cannot be modified (insert, delete, swap intermediates) without breaking hash references; the verifier reconstructs the chain from the references and checks every link.
• Self-authenticating messages. A signed content-addressed entity is verifiable by anyone with the granter’s public key. The verifier needs no live connection to the granter, no shared session state, no out-of-band coordination. The token is its own proof.
• Cryptographic audit. The content store is append-only along the IM axis. Past actions are reconstructable from their content-addressed records; nothing is silently deleted; revocation is a binding change, not a content deletion.

These properties are not bolted on. They are what content addressing is: identity derived from bytes, with no separate identity-assignment authority. The security model inherits them by being built on the same substrate.

7.5. Algorithm Agility

Three independent format-code namespaces support cryptographic evolution:

• The content-hash format code (0x00 for ECFv1-SHA-256) selects the hash algorithm used in content addressing.
• The peer-ID hash format code selects the hash algorithm used in deriving peer IDs from public keys.
• The peer-ID key format code selects the signature algorithm.

A new algorithm can be introduced in any one of these namespaces without changing the others. Connection negotiation determines the per-connection set: each peer presents its supported algorithms in HELLO; the intersection is the active set. New algorithms enter through extension agreement (new format-code allocations); old algorithms phase out through deprecation in the connection-negotiation policy.

The agility is not unbounded. The hash function used for content addressing is a category-(b) structural instantiation (see The Entity System): changing it changes every content-addressed identity, which is a massive coordination event. Adding a new hash algorithm alongside the existing one is straightforward; replacing the existing one is not. The same holds for the peer-ID hash. Signature algorithms are easier to evolve because signatures are per-message and not retroactively re-keyed.

7.6. Limitations

Several limitations are worth naming explicitly.

• No formal security proofs. The argument that attenuation is enforced, that delegation chains are unforgeable, and that the tree-based revocation mechanism is sound rests on the cryptographic properties of the underlying primitives (Ed25519, SHA-256) plus the structural properties of content addressing. We have not constructed formal proofs in a proof system; this is an open direction.
• Clock skew affects TTL-based revocation. TTL bounds rely on synchronized clocks across peers. Clock skew beyond the TTL window can produce premature acceptance or premature rejection. Deployments tighten this with NTP or with overlap windows in their TTL policies.
• Offline peers cannot receive revocation updates. A peer that cannot reach the granter cannot observe a new revocation. Until reconnection, the peer’s stale view may accept revoked capabilities. TTL bounds the exposure window; the substrate does not eliminate it.
• Selective intermediate revocation requires Tier 2+. The substrate provides root-capability revocation cheaply; revoking a specific intermediate in a chain (without revoking the root) requires per-token tracking, which is Tier 2 work. Deployments that need fine-grained intermediate revocation accept the per-token cost.
• Encryption is specified but untried, and half of it is not specified at all. As the encryption section sets out, what exists covers stateless single-shot use; interactive session encryption is separate, later work. Within what exists, metadata protection (recipient-hiding, size-hiding) and distributed key custody are open, and none of it has deployment experience. Peer mode in particular does not provide forward secrecy against compromise of the recipient’s key, and should not be read as end-to-end encryption in the sense a messaging application means it.
• The role extension is still settling. EXTENSION-ROLE is specified but has not yet been through a cross-implementation green round. The role-based authority patterns described in this paper depend on its root-cap shape, and that shape may change before it stabilizes.
• No production-scale deployment data. The capability mechanism is implemented across three implementations (Go, Python, Rust) and has been exercised in conformance tests, but no large production deployment has been observed long enough to surface scaling or operational issues at scale.
• Generated under prompt-and-review. This paper, like the rest of the corpus, the supporting implementations, and the architectural specifications, is LLM-generated under direction from the author. The author provides prompts, evaluates outputs, redirects, and approves — text, code, and design refinements are generated rather than directly authored. The methodology this enables is described in The Entity Core Protocol.

8. Related Work

8.1. Capability Systems

The object-capability model originates with Dennis and Van Horn (Dennis and Van Horn 1966); modern treatments include KeyKOS (Hardy 1985), EROS (Shapiro et al. 1999), and seL4 (Klein et al. 2009) at the OS level. The entity system’s tokens-as-content-addressed-entities is a different specialization: tokens are transferable across the wire and across peer boundaries, while object capabilities (in the KeyKOS lineage) are bound to a particular kernel’s object table. Hardware capabilities are explored in CHERI (Watson et al. 2015), with ARM Morello (Arm Ltd. 2022) as a production prototype; CHERI capabilities are per-pointer bounds enforced in hardware, structurally distinct from semantic dispatch-level capabilities but using compatible techniques (tag bits, capability caches, bounds checking).

Decentralized capability tokens have a recent literature. Macaroons (Birgisson et al. 2014) established the contextual-caveat pattern. UCAN (Zelenka et al. 2022) adapted JWT for decentralized capability delegation with DID-based identity. Biscuit (Couprie et al. 2021) added a Datalog policy layer. ZCAP-LD (Sporny and Longley 2022) is a JSON-LD format for chained authorization. The entity system’s contribution to this lineage is the four-dimensional grant (handler, operation, resource, peer) and the content-addressed token, both of which are absent from the existing decentralized-capability literature.

8.2. Authorization Models

The role-based access control literature (RBAC (Sandhu et al. 1996)), attribute-based (ABAC (Hu et al. 2014)), and relationship-based (ReBAC (Fong 2011)) frameworks describe authorization policy at the application level. The entity system’s four grant dimensions map to ABAC attribute classes with finer granularity: Action attributes split into Handler and Operation, Environment attributes split into Peer and Time. The entity system implements something close to ReBAC at the substrate level: capability delegation chains are the relationship graph, and capability-derivation patterns (group membership, role assignment) are relationship-derived authority.

Zanzibar (Pang et al. 2019) represents the high-scale centralized branch of relation-based authorization: a single authoritative system maintains the relation graph and answers authorization queries. The entity system represents the decentralized branch: relations are content-addressed capability chains, and verification is local.

8.3. Decentralized Identity

The W3C Decentralized Identifiers (DID) specification (W3C 2022a) and Verifiable Credentials (W3C 2022b) provide a framework for content-or-key-derived identity in distributed contexts. AT Protocol’s identity model (Kleppmann et al. 2024) uses DIDs in a federated setting. The entity system’s peer-ID format is structurally similar (content-derived from a public key) but more minimal: a 46-character Base58 string rather than a URI. The identity entity layer above peer IDs — self-describing records with controller-cert chains and quorum attestations — is closer in spirit to W3C’s “DID Document” pattern.

8.4. Encryption Protocols

Modern messaging encryption is dominated by Signal Protocol (Perrin and Marlinspike 2016) and its successor Messaging Layer Security (MLS (Barnes et al. 2023)) for group messaging. The Noise framework (Perrin 2018) provides composable encrypted-transport patterns. The entity system’s encryption is structurally simpler than these, and the comparison is only fair once the scopes are lined up: what exists here is same-bytes-everywhere single-shot encryption in three modes, with no separate transport-encryption layer, and the simplicity comes from the substrate — encrypted entities are entities, and the same wrapper works on wire and in storage. Signal and MLS solve the problem this deliberately does not: ratcheting state between live parties, which buys forward and future secrecy and dynamic group membership. That is the sibling session work, not a weaker version of it delivered here, and until that work lands the honest comparison is between a sealed box and a session protocol rather than between two session protocols.

8.5. Tagged and Capability Hardware

The Burroughs B5000 (1961) introduced tagged memory with hardware-enforced type checks. KeyKOS (Hardy 1985) and EROS (Shapiro et al. 1999) are software predecessors of modern capability OSes. seL4 (Klein et al. 2009) is formally verified and provides strong isolation guarantees. CHERI (Watson et al. 2015) brings capability hardware to general-purpose computing; ARM Morello and University of Cambridge research prototypes demonstrate the approach. The entity system’s capability model operates at a higher semantic level (per-dispatch authorization rather than per-pointer bounds), but the hardware techniques (capability caches, tag bits, bounds checking) are directly applicable for hardware acceleration; The Entity Machine Boundary sketches how an entity-native processor would integrate capability verification into the dispatch pipeline.

8.6. Content-Addressed Security

Git (Torvalds 2005) provides signed commits over a content-addressed object store. IPFS (Benet 2014) uses content identifiers (CIDs) for distributed content addressing. Nix store paths (Dolstra et al. 2004) are content-addressed build outputs. None of these systems integrates content addressing with capability-based authorization at the protocol level; they provide content addressing as a storage / distribution primitive and leave authorization to other layers.

8.7. Limitations of Coverage

This related-work survey is selective. Deeper engagement with the formal capability literature (Drossopoulou and Noble’s reasoning frameworks, the type-systems treatment of capabilities), the MLS draft and its predecessors, the CHERI security model in detail, and the wider decentralized-identity ecosystem would strengthen the comparison. The selections here aim at the structurally closest systems; a fuller survey would expand the comparison without changing the structural argument.

9. Conclusion

The entity system’s security architecture is built from the same six primitives that define the system. Capabilities are entities; identities are entities; revocation is a binding change; encryption wraps entities and preserves their identity. There is no separate security substance because the substrate is the security substrate.

The architecture is structurally distinctive in several ways:

• Four-dimensional grants (handler, operation, resource, peer) cover the per-grant scope axis with uniform pattern matching. They sit inside an eight-primitive authorization structure (the four per-grant scopes plus four per-token primitives: subject, authority, attenuation, and context-temporal, with revocation as a separate lifecycle mechanism). The decomposition is derived in Dimensional Completeness from analysis of the attribute structure of distributed-system requests; the four per-grant axes are a principled subset, not an arbitrary count.
• Attenuation by construction: child capabilities are provably subsets of parents on all four dimensions. Cryptographic chain references prevent amplification without forging an intermediate granter’s signature.
• Tree-based revocation: revoking a capability is unbinding it from the active set. No blacklist accumulation; the IM/TM split keeps audit and revocation on independent emit axes. Generation pools give O(1) scoped mass revocation.
• Self-describing identities: peer IDs are content-derived; peer keypair entities and (when the identity extension is installed) cert chains compose into mini-trees that travel with the peer; algorithm agility is built into three independent format-code namespaces.
• Entity-level encryption: the same encrypted entity on wire, disk, and in memory, with three modes (self, peer, group) covering storage, single-recipient transfer, and shared archives. Authorization and confidentiality are independent dimensions. Interactive session encryption is separate work and is not part of this.

Structurally, security in the entity system lives at the IXP capability triangle (see The Entity System). The triangle’s three pairs (IX, XP, IP) carry the substrate of capability-based security: content-addressed tokens (IX), cross-peer dispatch carrying tokens (XP), content-addressed peer identity (IP). Two of these are phase-transition pairs that require Full I to activate: capability-based security in the entity-system sense is impossible without content-derived identity, regardless of how richly a grant structure is specified. Of the systems analyzed in Convergent Evolution, the entity system is the only one that activates the full triangle simultaneously.

Three open invitations to refute the closure claims sit alongside the model. An authorization need that requires a fifth grant dimension — a request attribute that is not subject, handler, operation, resource, peer, time, or delegation, and that is not expressible through the existing four-dimensional grant plus the token-level fields — would mean the dimensionality is wrong. A revocation scenario that tree-based revocation plus generation pools plus TTL does not cover at acceptable cost would expose a trade-off envelope the mechanism cannot reach; the trade-offs (online vs offline, selective vs mass, immediate vs eventual) are real, and a scenario outside the envelope would be informative. An attenuation attack that amplifies without forging an intermediate granter’s signature would invalidate the cryptographic construction. None has been identified.

Open questions remain. Formal security proofs of attenuation and chain unforgeability are an obvious next step; the discrete, finite structures of the capability model are well-suited to a proof system like Coq or Lean. Production-scale deployment data is the other major gap: the model has been validated in implementations and conformance tests but not in long-running production environments. The encryption work needs implementation experience on the half that exists and a specification for the interactive half that does not. The role extension’s shape needs cross-implementation green-round confirmation. Each of these is in motion; none is a blocker for the substrate-level claims this paper makes.

The security model has been under reduction throughout the protocol’s evolution. The wire format has not changed; the four-dimensional grant has not changed; the tree-based revocation mechanism has not changed. What has changed is the type system around them — new caveat types, new attestation formats, new role-derivation patterns. The pattern matches the broader system’s pattern (see The Entity System; The Entity Core Protocol): the protocol shrinks, the type system grows. Security is no exception.