wip: adding cap-01 spec and clearing mental hurdles

Author: CMCDragonkai

docs/reference/specifications/README.mdx

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# How-To Guides
+
+<DocCardList />

docs/reference/specifications/acceptance/TAP-01.mdx

@@ -0,0 +1,280 @@
+# CAP-01 - Capability Grammar
+
+<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>
+  </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).
+
+## 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).
+- 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).
+- 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).
+- 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.
+- Receipt-ready: CEPS capture a bind_snapshot in PoAR.
+
+## Verbs and Resources
+
+### Verb grammar
+
+Verbs are strings, recommended namespaced for clarity:
+
+- Format: namespace:verb or domain:action
+  - Examples:
+    - deploy:to_env
+    - access:open
+    - energy:curtail
+    - 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.
+
+### Resource addressing
+
+Resources are URIs or URI-like identifiers with scheme-specific rules:
+
+- `k8s://ns/prod`
+- `door:building-12:lock-3`
+- `meter:utility:site-42`
+- `api:https://api.vendor.com/path`
+- `vault:secret://org/team/service/key-id`
+
+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.
+
+Required fields:
+
+- id: opaque identifier (hash of canonicalized claim)
+- type: "grant"
+- issuer: DID of P
+- subject: DID of S
+- action: verb (string)
+- resource: resource URI
+- bind: Bind object (Section 5)
+- expiry: timestamp (notAfter)
+- prev: previous claim hash (sigchain link)
+- sig: signature by issuer's key
+
+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.
+- bind MUST be enforceable by CEPs and included in the PoAR bind_snapshot.
+- A Grant MAY be revoked (Section 8).
+
+Minimal JSON skeleton:
+
+```json
+{
+  "type": "grant",
+  "id": "hash(...)",
+  "issuer": "did:pk:P",
+  "subject": "did:pk:S",
+  "action": "deploy:to_env",
+  "resource": "k8s://ns/prod",
+  "bind": { ... },
+  "expiry": "2025-09-10T10:00:00Z",
+  "prev": "hash(prev)",
+  "sig": "..."
+}
+```
+
+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"}`)
+- 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)
+- 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.).
+
+```json
+"bind": {
+  "audience": ["did:pk:P"],
+  "purpose": "sha256:artifact-H",
+  "context": { "ns": "prod", "app": "web" },
+  "time_window": { "notBefore": "2025-09-10T09:00:00Z", "notAfter": "2025-09-10T10:00:00Z" },
+  "ttl": "120s"
+}
+```
+
+## Attenuation and Delegation
+
+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 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.
+
+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)
+
+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.
+
+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)
+- 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).
+- 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.
+
+Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
+```
+{
+  "type": "presentation",
+  "grant_ref": "hash(G)",
+  "holder": "did:pk:S",
+  "channelBinding": "base64url(exporter)",
+  "ctx": { "ns": "ci", "pod": "runner-xyz" },
+  "ttl": "120s",
+  "nonce": "uuid-...",
+  "pop_sig": "sig_by_S"
+}
+```
+
+## 8. Revocation and rotation
+
+### 8.1 Revocation
+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).
+
+### 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).
+
+## 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:
+   - 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).
+   - Deliver PoAR 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).
+- 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.
+
+## 11. Examples (JSON)
+
+Grant (P → S; deploy to prod for artifact H)
+```
+{
+  "type": "grant",
+  "id": "hash(G)",
+  "issuer": "did:pk:cmcdragonkai",
+  "subject": "did:pk:ci-runner-prod-01",
+  "action": "deploy:to_env",
+  "resource": "k8s://ns/prod",
+  "bind": {
+    "audience": ["did:pk:cmcdragonkai"],
+    "purpose": "sha256:artifact-H",
+    "context": { "ns": "prod", "app": "web" },
+    "time_window": { "notBefore": "2025-09-10T09:00:00Z", "notAfter": "2025-09-10T10:00:00Z" },
+    "ttl": "120s"
+  },
+  "expiry": "2025-09-10T10:00:00Z",
+  "prev": "hash(prev)",
+  "sig": "..."
+}
+```
+
+Presentation (S → CEP)
+
+```
+{
+  "type": "presentation",
+  "grant_ref": "hash(G)",
+  "holder": "did:pk:ci-runner-prod-01",
+  "channelBinding": "base64url(exporter)",
+  "ctx": { "ns": "prod", "pod": "runner-xyz" },
+  "ttl": "120s",
+  "nonce": "b1b2c3-...",
+  "pop_sig": "..."
+}
+```
+
+## Revision history
+
+- 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.