wip: clearing mental hurdles

Author: CMCDragonkai

docs/reference/specifications/cap/CAP-01.mdx

@@ -3,49 +3,72 @@
 <details>
   <summary>Metadata</summary>
   <dl>
-    <dt>Status:</dt><dd>Draft</dd>
-    <dt>Edition:</dt><dd>2025-09-02</dd>
-    <dt>Extends:</dt><dd>-</dd>
-    <dt>Updates:</dt><dd>-</dd>
-    <dt>Obsoletes:</dt><dd>-</dd>
-    <dt>Depends on:</dt><dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
+    <dt>Status:</dt>
+    <dd>Draft</dd>
+    <dt>Edition:</dt>
+    <dd>2025-09-02</dd>
+    <dt>Extends:</dt>
+    <dd>-</dd>
+    <dt>Updates:</dt>
+    <dd>-</dd>
+    <dt>Obsoletes:</dt>
+    <dd>-</dd>
+    <dt>Depends on:</dt>
+    <dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
   </dl>
 </details>
 
 ## Abstract
 
-CAP-01 defines the portable, verifiable capability model used by Polykey to express delegated authority. It specifies the structure and semantics of Grants (capability tokens) and Presentations (ephemeral proofs of capability), including verbs, resource addressing, binding constraints, attenuation, and revocation. CAP-01 ensures capabilities are composable, attenuable (never broadened), and safely enforceable at CEPs (Capability Enforcement Points), producing settlement-grade receipts (RSC-01).
+CAP-01 defines the portable, verifiable capability model used by Polykey to
+express delegated authority. It specifies the structure and semantics of Grants
+(capability tokens) and Presentations (ephemeral proofs of capability),
+including verbs, resource addressing, binding constraints, attenuation, and
+revocation. CAP-01 ensures capabilities are composable, attenuable (never
+broadened), and safely enforceable at CEPs (Capability Enforcement Points),
+producing settlement-grade receipts (RSC-01).
 
 ## Terminology
 
 - Principal (P): Originator of authority; issues a Grant to a Subject.
 - Subject (S): Holder that exercises the capability by creating a Presentation.
 - Resource (R): Target of the action; may host a native CEP (CEP(R)).
-- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and enforces capabilities (writes the Access PoAR).
+- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and
+  enforces capabilities (writes the Access PoAR).
 - Grant (G): A signed, portable capability issued by P to S.
-- Presentation (Π): An ephemeral, proof-of-possession token created by S that references a Grant with context and channel binding. Not stored on-chain.
-- Bind: Binding constraints inside a Grant that restrict its use (audience, purpose, time, context, etc.).
-- Attenuation: Narrowing a capability when delegating; derived Grants must be a subset of their parent capability.
-- Verification (Σ): The verification handshake at the enforcing CEP. `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
-- Lease: The upstream authority relationship to a non-native SoA; referenced via leaseRef in PoAR (RSC-01).
+- Presentation (Π): An ephemeral, proof-of-possession token created by S that
+  references a Grant with context and channel binding. Not stored on-chain.
+- Bind: Binding constraints inside a Grant that restrict its use (audience,
+  purpose, time, context, etc.).
+- Attenuation: Narrowing a capability when delegating; derived Grants must be a
+  subset of their parent capability.
+- Verification (Σ): The verification handshake at the enforcing CEP.
+  `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
+- Lease: The upstream authority relationship to a non-native SoA; referenced via
+  leaseRef in PoAR (RSC-01).
 - PoAR: Proof-of-Action receipt written by the enforcing CEP (RSC-01).
 
 ## Overview and Goals
 
 CAP-01 provides:
 
-- A minimal, expressive grammar for capabilities (verbs over resources with constraints).
-- A binding system (Bind) to tie capability use to audience, purpose, context, and time.
-- A safe delegation model: capabilities can be attenuated and re-delegated without ever broadening power.
-- A secure, ephemeral Presentation that is resistant to theft and replay (PoP + channel binding).
+- A minimal, expressive grammar for capabilities (verbs over resources with
+  constraints).
+- A binding system (Bind) to tie capability use to audience, purpose, context,
+  and time.
+- A safe delegation model: capabilities can be attenuated and re-delegated
+  without ever broadening power.
+- A secure, ephemeral Presentation that is resistant to theft and replay (PoP +
+  channel binding).
 - Clear interoperability with CEP enforcement and receipt minting (RSC-01).
 
 Design goals:
 
 - Portable: Grants and Presentations are verifiable across boundaries.
 - Minimal: Core fields are few and clearly defined; extensions via vocabularies.
 - Attenuable: Derived Grants must shrink authority; verifiable at enforcement.
-- Secure by default: Holder-of-key + channel binding; short TTLs for Presentations.
+- Secure by default: Holder-of-key + channel binding; short TTLs for
+  Presentations.
 - Receipt-ready: CEPS capture a bind_snapshot in PoAR.
 
 ## Verbs and Resources
@@ -62,7 +85,8 @@ Verbs are strings, recommended namespaced for clarity:
     - secret:read, secret:derive
     - data:export, model:infer
 
-Verb semantics must be documented in a public or private registry (with versioned definitions). TAP profiles may whitelist verb sets per domain.
+Verb semantics must be documented in a public or private registry (with
+versioned definitions). TAP profiles may whitelist verb sets per domain.
 
 ### Resource addressing
 
@@ -78,7 +102,8 @@ TAP profiles may restrict acceptable schemes per domain and verb.
 
 ## Grant Structure and Rules
 
-A Grant is a signed claim on P's sigchain that authorizes S to perform actions (verbs) on resources, subject to Bind constraints.
+A Grant is a signed claim on P's sigchain that authorizes S to perform actions
+(verbs) on resources, subject to Bind constraints.
 
 Required fields:
 
@@ -97,7 +122,8 @@ Normative rules:
 
 - Grants MUST be written on the issuer's (P's) sigchain.
 - expiry MUST be present and enforced; Presentations beyond expiry are invalid.
-- action/resource MUST be specific; wildcards SHOULD be avoided unless constrained by Bind.
+- action/resource MUST be specific; wildcards SHOULD be avoided unless
+  constrained by Bind.
 - bind MUST be enforceable by CEPs and included in the PoAR bind_snapshot.
 - A Grant MAY be revoked (Section 8).
 
@@ -118,19 +144,25 @@ Minimal JSON skeleton:
 }
 ```
 
-Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and include a bind_snapshot in PoAR.
+Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and
+include a bind_snapshot in PoAR.
 
 Recommended fields:
 
 - audience: list of DIDs of acceptable enforcers (e.g., ["did:pk:P","did:pk:R"])
-- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H, “door-visit-123”)
-- context: structured k/v describing runtime context (e.g., `{"pod":"runner-xyz","ns":"ci"}`)
+- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H,
+  “door-visit-123”)
+- context: structured k/v describing runtime context (e.g.,
+  `{"pod":"runner-xyz","ns":"ci"}`)
 - time_window: `{ notBefore, notAfter }` narrower than Grant expiry
 - ttl: maximum Presentation TTL (e.g., "120s")
-- maxUses: optional counter for total uses (enforced by CEP capable of maintaining state)
+- maxUses: optional counter for total uses (enforced by CEP capable of
+  maintaining state)
 - geofence / net: optional constraints (e.g., CIDR, region, location)
 
-Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl, etc.).
+Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower
+or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl,
+etc.).
 
 ```json
 "bind": {
@@ -144,43 +176,57 @@ Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower
 
 ## Attenuation and Delegation
 
-A capability MAY be delegated by S to S2 by issuing a derived Grant on the delegator's sigchain, provided:
+A capability MAY be delegated by S to S2 by issuing a derived Grant on the
+delegator's sigchain, provided:
 
 - The derived Grant's action/resource are identical or narrower (subset).
-- The derived Grant's bind is a subset of the parent Grant's bind on all dimensions.
+- The derived Grant's bind is a subset of the parent Grant's bind on all
+  dimensions.
 - The chain of custody (P → S → S2) is provable via sigchains.
-- No broadening: delegation MUST NOT increase the set of allowed enforcers, time, scope, or resource coverage.
+- No broadening: delegation MUST NOT increase the set of allowed enforcers,
+  time, scope, or resource coverage.
 
 Normative subset checks (examples):
 
 - `time_window.child` ⊆ `time_window.parent`
 - `audience.child` ⊆ `audience.parent`
 - `ttl.child` ≤ `ttl.parent`
 - `resource.child` narrower (e.g., specific door vs building-wide)
-- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter descriptor)
+- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter
+  descriptor)
 
-CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may include a chain; otherwise, single-hop P→S is verified).
+CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may
+include a chain; otherwise, single-hop P→S is verified).
 
 ## Presentation
 
-A Presentation is an ephemeral proof by S that it holds a Grant and is using it now, in this context, on this channel. Presentations are NOT written to sigchains.
+A Presentation is an ephemeral proof by S that it holds a Grant and is using it
+now, in this context, on this channel. Presentations are NOT written to
+sigchains.
 
 Required fields:
+
 - grant_ref: hash of Grant (or terminal of a chain)
 - holder: DID of S
 - pop_sig: signature by S’s private key over the presentation payload
-- channelBinding: exporter-derived key for the live TLS/mTLS session (or equivalent)
+- channelBinding: exporter-derived key for the live TLS/mTLS session (or
+  equivalent)
 - ctx: runtime context (subset of bind.context)
 - ttl: small (e.g., 120s)
 - nonce: unique value to prevent replay
 
 Normative rules:
-- Presentations MUST be bound to holder’s key (PoP) and to the transport/session (channelBinding).
+
+- Presentations MUST be bound to holder’s key (PoP) and to the transport/session
+  (channelBinding).
 - Presentation ttl MUST be enforced by CEPs.
-- Presentations MUST include binding to Grant_ref and context; CEPs MUST check bind subset.
-- CEPs MUST reject Presentations beyond Grant expiry or outside bind.time_window.
+- Presentations MUST include binding to Grant_ref and context; CEPs MUST check
+  bind subset.
+- CEPs MUST reject Presentations beyond Grant expiry or outside
+  bind.time_window.
 
 Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
+
 ```
 {
   "type": "presentation",
@@ -197,42 +243,56 @@ Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
 ## 8. Revocation and rotation
 
 ### 8.1 Revocation
-A Grant MAY be revoked by its issuer with a signed revocation claim on P’s sigchain:
+
+A Grant MAY be revoked by its issuer with a signed revocation claim on P’s
+sigchain:
+
 - type: "revoke", target: grant_id/hash(G), reason(optional), time, sig
 - CEPs MUST check for revocation before enforcing.
-- ViewReceipts SHOULD include knowledge of revocation state at time of action (via bind_snapshot + revocation check in PoAR).
+- ViewReceipts SHOULD include knowledge of revocation state at time of action
+  (via bind_snapshot + revocation check in PoAR).
 
 ### 8.2 Rotation
-For secret-bound flows (PS-BA/SS-BA), upstream leases and secrets MUST be rotated per TAP policy. PoAR includes leaseRef (freshness proof). Rotation receipts may be recorded per SIGCHAIN-01 (optional).
+
+For secret-bound flows (PS-BA/SS-BA), upstream leases and secrets MUST be
+rotated per TAP policy. PoAR includes leaseRef (freshness proof). Rotation
+receipts may be recorded per SIGCHAIN-01 (optional).
 
 ## 9. CEP enforcement (normative algorithm)
 
 Given a Presentation p from S and an asserted Grant G:
-1) Verify issuer signature of G (P’s sigchain), subject DID, action/resource.
-2) Check expiry and revocation of G.
-3) Verify Presentation:
+
+1. Verify issuer signature of G (P’s sigchain), subject DID, action/resource.
+2. Check expiry and revocation of G.
+3. Verify Presentation:
    - pop_sig by holder S
    - channelBinding matches live session (mTLS/DPoP)
    - ttl within bind.ttl and current time within bind.time_window
    - ctx consistent and bind subset satisfied
-4) If Grant is a derived chain: verify attenuation (child bind/resource/action ⊆ parent).
-5) If enforcement passes, enforce per placement/mode and write PoAR:
-   - Include bind_snapshot (canonical copy of bind at enforcement), cepRef, exposureMode, time_source, requestDigest (if mediate).
+4. If Grant is a derived chain: verify attenuation (child bind/resource/action ⊆
+   parent).
+5. If enforcement passes, enforce per placement/mode and write PoAR:
+   - Include bind_snapshot (canonical copy of bind at enforcement), cepRef,
+     exposureMode, time_source, requestDigest (if mediate).
    - Deliver PoAR to S.
-6) If any check fails, mint DenyReceipt with reason_code and deliver to S.
+6. If any check fails, mint DenyReceipt with reason_code and deliver to S.
 
 ## 10. Security considerations
 
 - Holder-of-key (PoP) + channel binding prevent token theft and replay.
-- Presentations MUST be short-lived; CEPs SHOULD reject stale nonces (optional stateful defense).
+- Presentations MUST be short-lived; CEPs SHOULD reject stale nonces (optional
+  stateful defense).
 - Bind MUST be enforced; failure to snapshot bind in PoAR weakens auditability.
 - Delegation MUST be attenuating; TAP SHOULD disallow broadening by policy.
-- Reveal is dangerous; exposureMode="reveal" MUST follow strict TAP guardrails (tiny ttl/scope, dual-control, immediate revoke/rotate).
-- Privacy: Do not include raw PII in Grants/Presentations; use DIDs and contextual claims; ViewReceipts handle selective disclosure.
+- Reveal is dangerous; exposureMode="reveal" MUST follow strict TAP guardrails
+  (tiny ttl/scope, dual-control, immediate revoke/rotate).
+- Privacy: Do not include raw PII in Grants/Presentations; use DIDs and
+  contextual claims; ViewReceipts handle selective disclosure.
 
 ## 11. Examples (JSON)
 
 Grant (P → S; deploy to prod for artifact H)
+
 ```
 {
   "type": "grant",
@@ -271,10 +331,14 @@ Presentation (S → CEP)
 
 ## Revision history
 
-- 2025-09-02: Initial draft edition (holder-of-key + channel binding; Bind subset rules; attenuation; revocation; CEP enforcement algorithm; examples).
+- 2025-09-02: Initial draft edition (holder-of-key + channel binding; Bind
+  subset rules; attenuation; revocation; CEP enforcement algorithm; examples).
 
 Notes:
 
-- Registries (verbs, resource schemes) MAY be maintained as content-addressed vocabularies; TAP profiles SHOULD reference accepted vocab ids.
-- RSC-01 specifies how bind_snapshot, cepRef, exposureMode, leaseRef, and requestDigest appear in PoAR.
-- SIGCHAIN-01 and STORAGE-01 specify durability/archival; PRIVACY-01 covers ViewReceipts/redactions/crypto-erasure.
+- Registries (verbs, resource schemes) MAY be maintained as content-addressed
+  vocabularies; TAP profiles SHOULD reference accepted vocab ids.
+- RSC-01 specifies how bind_snapshot, cepRef, exposureMode, leaseRef, and
+  requestDigest appear in PoAR.
+- SIGCHAIN-01 and STORAGE-01 specify durability/archival; PRIVACY-01 covers
+  ViewReceipts/redactions/crypto-erasure.