@kya-os/mcp 1.16.2 → 1.18.0

package/CONFORMANCE.md

@@ -52,7 +52,7 @@ Implementation MUST:
 - Generate cryptographically secure random 32-byte private seed
 - Derive 32-byte public key from seed
 - Derive `did:key` DID from public key using multicodec prefix `0xed01` and base58btc encoding
-- Key ID format: `<did>#keys-1`
+- Key ID format: `<did>#<multibase>`, the W3C did:key verification method ID (SPEC.md §4.3)
 
 #### L1.2 — SHA-256 Hashing
 
@@ -125,7 +125,7 @@ Implementation MUST validate:
 #### L2.5 — Nonce Replay Prevention
 
 Implementation MUST:
-- Store (nonce, agentDid) tuples for at least `sessionTtlMinutes + 1 minute`
+- Store (nonce, agentDid) tuples at least until the nonce's timestamp leaves the acceptance window (`ts + skew`, SPEC §5.5)
 - Reject any request with a previously-seen nonce for the same agentDid
 - Support cleanup of expired nonces
 
@@ -139,10 +139,10 @@ Proof metadata MUST include:
 - `did`: Signer's DID
 - `kid`: Key ID used for signing
 - `ts`: Unix epoch seconds
-- `nonce`: Session nonce
+- `nonce`: Fresh random nonce per proof
 - `audience`: Session audience
 - `sessionId`: Session identifier
-- `requestHash`: SHA-256 of canonicalized request (`sha256:<hex>`)
+- `requestHash`: SHA-256 of the canonicalized request (`sha256:<hex>`), over the covered request of SPEC §7.3 or, as 1.x implementations emit it, the legacy `{method: <tool name>, params: <arguments>}` shape; a verifier accepts either for the same call
 
 `responseHash` (SHA-256 of the canonicalized response, `sha256:<hex>`) MUST be
 present on proofs that carry a response body — success proofs and
@@ -161,8 +161,14 @@ intact while swapping the `authorizationUrl`, and only the recompute detects it.
 
 `_meta` is the MCP per-request metadata channel and is shared with reserved
 reverse-DNS keys. A conformant verifier MUST:
-- Read the KYA-OS proof from `org.kya-os/proof` and, for backward compatibility,
-  from the legacy bare `proof` key.
+- Read the detached response proof from `org.kya-os/response-proof`. Through
+  1.x, also accept the prior keys `org.kya-os/proof` and bare `proof` (SPEC
+  §7.6), in that order: the first key present wins. Servers write `org.kya-os/response-proof` and, unless configured with
+  `emitLegacyProofKey: false`, mirror it under bare `proof`; nothing writes
+  `org.kya-os/proof`.
+- Treat the holder-of-key request proof, under `org.kya-os/request-proof`
+  (SPEC-ENTITY-CARD §8.1), as a separate profile: never read one in place of
+  the other.
 - Process **only** the KYA-OS proof key; ignore every other `_meta` key (never
   hash it, never trust it).
 - **Never reject** a response merely because `_meta` also carries non-KYA-OS

package/README.md

@@ -217,6 +217,8 @@ This starts all example servers and opens [MCP Inspector](https://github.com/mod
 
 Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway pattern), [verify-proof](./examples/verify-proof/) (standalone verification), [statuslist](./examples/statuslist/) (revocation lifecycle), [cheqd-dlr](./examples/cheqd-dlr/) (operator DID linkage + DLR publishing).
 
+To run one example on its own, use its `npm run example:*` script, for example `npm run example:server`. The scripts and `scripts/demo.sh` run the examples from `src/` through `tsconfig.examples.json`, so they need no build step. The scripts also need nothing beyond the root `npm install`; `demo.sh` additionally installs each example's own dependencies.
+
 ## Try it against the live server
 
 [![Live deployment probe](https://github.com/decentralized-identity/kya-os-mcp/actions/workflows/live-probe.yml/badge.svg)](https://github.com/decentralized-identity/kya-os-mcp/actions/workflows/live-probe.yml)
@@ -252,7 +254,7 @@ The server is operated by a maintainer on pinned releases; this repo does not de
 | **Revocation** | StatusList2021 bitstring with cascading revocation |
 | **Replay prevention** | Nonce-based handshake with timestamp skew validation |
 | **Verifiable auditability** | Typed producer events, authoritative atomic recorder, signed chain receipts, RFC 9162 checkpoints, independent observation, encrypted evidence references, replay bundles, and offline CLI |
-| **Extensible** | Bring your own KMS, HSM, nonce cache (Redis, DynamoDB, KV), or DID method |
+| **Extensible** | Bring your own KMS, HSM, atomic nonce provider, or DID method |
 
 ### Multi-instance deployments
 
@@ -263,25 +265,77 @@ implementation for **every** runtime-state seam — the nonce cache
 `PendingFlowStore`, `SessionStore`) — so replay protection, grants, pending OAuth
 flows, and sessions are shared across instances and survive restarts.
 
+Delegation grants must retain their original signed evidence: `credentialJwt` for VC-JWTs, or `delegationCredential` for object VCs.
+`wrapWithDelegation` revalidates that evidence with the same verifier as a directly presented credential on every reuse, including chain resolution, audience, scope, expiry, and configured status/revocation checks.
+Store providers must preserve these fields and return only active grants; cache availability alone does not authorize a request.
+Grant expiry is bounded by the earliest credential or constraint expiry in the verified chain.
+
+**Upgrade compatibility:** legacy grants without signed evidence intentionally return `needs_authorization`; re-present a valid delegation or complete the normal consent flow to replace them.
+Do not reconstruct unsigned credentials from cached metadata.
+Under `holderBinding: 'enforce'`, did:key session retries also require a fresh holder proof.
+`off` and `warn` retain their documented session behavior, and non-did:key binding remains deferred; neither provides an enforced proof-of-possession guarantee for those requests.
+Status and chain providers now receive reads on grant reuse as they do on direct calls, and an unavailable required provider prevents reuse.
+This does not strengthen a provider's own status-cache freshness policy.
+
+VC-JWT envelope `exp` and `nbf` are checked on every verification, including signature-cache hits and grant reuse.
+Omitted claims remain supported.
+A present claim must be a finite NumericDate.
+An expired envelope denies authorization even when the embedded VC is otherwise current, and verified envelope expiry can shorten the cached grant's lifetime.
+`nbf` allows `JWT_NBF_LEEWAY_SECONDS` (30 seconds) of clock skew; `exp` allows none.
+
+**Delegation issuers:** each re-delegation must be signed by its parent's subject.
+The `issuerDid` inside a credential is only a claim, so the chain walk also checks who signed it.
+Set `delegation.trustedRootIssuers` to the DIDs allowed to issue root delegations, the Responsible Party for the whole chain.
+With it set, a chain whose root is signed by any other DID is rejected, including when a stored grant is reused.
+Without it, any issuer is accepted, including an agent signing a delegation for itself, and the middleware logs a warning at startup.
+A root whose claimed `issuerDid` differs from its signer is still accepted, and logged.
+
+**Nonce providers:** give your `NonceCacheProvider` an atomic `consume(nonce, ttlSeconds, agentDid?)`.
+It must record an unseen `(agentDid, nonce)`, return literal `true` only to the call that recorded it, and reject on storage failure.
+Implement the claim in the shared backend with a conditional insert and expiry, not with a local mutex around remote reads and writes.
+Eventually consistent KV alone cannot provide it.
+The bundled memory provider implements `consume`, but it protects only one cache instance and loses its state on restart.
+`consume` is optional: a provider without it keeps working by falling back to `has` then `add`, which cannot stop concurrent duplicates of one signed request, and a warning is logged once.
+Set `requireAtomicNonce: true` on the middleware, `ProofVerifier`, `SessionManager` or `consumeFromNonceCacheProvider` to refuse that fallback; each then throws at construction for a provider without `consume`.
+Any result other than literal `true`, or a storage failure, denies admission.
+`withKyaOs` takes the same `nonceCache` and `requireAtomicNonce` options (and `responseProofProfile`) and passes them to the middleware.
+
+Providers must honor the requested retention duration.
+The verifiers retain nonces through the final accepted second, including future timestamps and clock skew, while preserving a longer configured TTL.
+The detached verifier also covers later increases up to its supported `setTimestampSkew` maximum.
+Custom card `consumeNonceIfFresh` callbacks must honor the new third `minTtlSec` argument; the bundled card cache and provider adapter do so.
+Instances sharing a replay namespace must agree on the longest proof-acceptance policy and retain state accordingly.
+Retire old non-atomic writers before claiming atomic protection.
+Preserve or extend existing records through the full remaining acceptance window; merely keeping their old, shorter TTLs is insufficient.
+If the backend cannot extend them safely, pause affected admission and wait out that window before cutover.
+Do not clear records while their proofs may still be accepted.
+
 ---
 
 ## Integrations
 
-KYA-OS reaches the outside world two ways: shipped **modules** for specific
-systems and standards, and typed **adapter seams** with in-memory defaults you
-swap out. Adding one is "drop a folder under `src/integrations/`" or "implement
-this interface" — contributions welcome.
-
-### Modules
+KYA-OS integrates through typed **seams** — the adapter pattern is the whole
+model. Every external dependency is a port with an in-memory or reference
+default; bind your own backend, or drop in a shipped adapter. Adding one is
+"implement this interface" (or, for a self-contained system, "drop a folder
+under `src/integrations/`") — contributions welcome.
 
-| Module | Adds | Docs |
+| Seam (port) | Reference / default | Bring your own |
 | --- | --- | --- |
-| **cheqd** (on-chain) | `did:cheqd` resolution, StatusList2021 revocation, DID-Linked Resources + registrar | [src/integrations/cheqd](./src/integrations/cheqd/README.md) |
-| **OAuth / OIDC** | PKCE + protected-resource metadata; generic-OIDC reference adapter | [`@kya-os/mcp/authz`](./src/authz/) · [example](./examples/authz-inspector/) |
-| **Verifiable audit** | RFC 9162 ledger; local or Checkpoint recorders, on-chain anchoring | [AUDITABILITY.md](./AUDITABILITY.md) |
+| DID resolution — `DIDResolver` | `did:key`, `did:web` | `did:cheqd`, custom methods |
+| Revocation — `StatusListResolver` | not configured | cheqd StatusList2021 |
+| Authorization — `AuthorizationServerAdapter` | `GenericOidcAdapter` (OIDC + PKCE) | Auth0, Okta, your IdP ([example](./examples/authz-inspector/)) |
+| State — `GrantStore`, `SessionStore`, `NonceCacheProvider`, `PendingFlowStore` | in-memory | Redis, DynamoDB, Durable Objects, DB; atomic consumption for replay and pending state ([multi-instance](#multi-instance-deployments)) |
+| Audit delivery — `AuditRecorder`, `AuditAnchorProvider` | local recorder | Checkpoint, on-chain anchoring ([AUDITABILITY.md](./AUDITABILITY.md)) |
+| Crypto — `CryptoProvider` | Node, WebCrypto | your KMS / HSM |
+| Policy — `PolicyEngine` | built-in default | custom engine |
+
+### cheqd: a fully-worked on-chain integration
 
-Enabling a module is a small config change. cheqd, for example, is a resolver
-you register under `didResolvers`:
+cheqd is the reference for what filling the seams looks like end to end — one
+package binds three at once: DID resolution (`did:cheqd`), revocation (on-chain
+StatusList2021), and audit anchoring (DID-Linked Resources). Enabling the
+resolver is a small config change:
 
 ```typescript
 import { cheqdResolver } from '@kya-os/mcp/cheqd';
@@ -299,19 +353,6 @@ DID-Linked Resource helpers, live testnet E2E) lives in
 [src/integrations/cheqd/README.md](./src/integrations/cheqd/README.md); see
 [examples/cheqd-dlr](./examples/cheqd-dlr/) for a complete operator flow.
 
-### Adapter seams (bring your own)
-
-Every external dependency is a typed interface with an in-memory default, so you
-can swap in your own backend without touching the middleware.
-
-| Seam | Default | Swap in |
-| --- | --- | --- |
-| DID resolution — `DIDResolver` | `did:key`, `did:web` | `did:cheqd`, custom |
-| Revocation — `StatusListResolver` | none | cheqd StatusList2021 |
-| State — `GrantStore`, `SessionStore`, `NonceCacheProvider`, `PendingFlowStore` | in-memory | Redis, DynamoDB, KV, Durable Objects, DB ([multi-instance](#multi-instance-deployments)) |
-| Crypto — `CryptoProvider` | Node, WebCrypto | your KMS / HSM |
-| Policy — `PolicyEngine` | default | custom |
-
 ## Links
 
 - [Spec](./SPEC.md) | [Card Profile](./SPEC-ENTITY-CARD.md) | [Changelog](./CHANGELOG.md) | [DIF TAAWG](https://identity.foundation/working-groups/trusted-agents.html) | [npm](https://www.npmjs.com/package/@kya-os/mcp)

package/SPEC.md

@@ -4,7 +4,7 @@
 
 Version: 1.0.0
 Status: Stable
-Editors: KYA-OS Working Group
+Editors: Dylan Hobbs ([@H0BB5](https://github.com/H0BB5)), KYA-OS Working Group
 Repository: https://github.com/decentralized-identity/kya-os-mcp
 
 ---
@@ -194,7 +194,18 @@ Base58btc:        6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
 DID:              did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
 ```
 
-The verification method ID is `<did>#keys-1`.
+The verification method ID is `<did>#<multibase>`: the fragment repeats the
+`z`-prefixed multibase value, as the W3C did:key method defines it. For the
+example above:
+
+```
+did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
+```
+
+This fragment identifies the Ed25519 verification method; `#keys-1` does not.
+A `did:key` document may also carry an X25519 `keyAgreement` method derived
+from the same key; its fragment is the X25519 key's own multibase value
+(`#z6LS…`).
 
 ### 4.4 did:web Resolution
 
@@ -384,8 +395,8 @@ The server MUST validate the handshake request:
 
 2. **Nonce Uniqueness**: The (nonce, agentDid) pair MUST NOT have been seen before
    - Reject with "Nonce already used (replay attack prevention)"
-   - Nonces MUST be cached for at least `sessionTtlMinutes + 1 minute`
-   - When `agentDid` is omitted, the dedupe key is `nonce` alone. Servers MUST use a shorter cache TTL for anonymous nonces (recommended: 60 seconds, vs. the default 120 seconds for authenticated handshakes)
+   - Nonces MUST be retained for at least the acceptance window of rule 1, as §5.5 specifies; retention is not tied to the session TTL
+   - When `agentDid` is omitted, the dedupe key is `nonce` alone. Servers MAY keep a shorter minimum retention for anonymous nonces than for authenticated ones (for example 60 and 120 seconds), never below what §5.5 requires
 
 3. **Audience Match**: `request.audience` MUST match the server's DID or expected domain
    - Prevents credential forwarding attacks
@@ -421,9 +432,11 @@ The nonce cache implementation MUST:
 - Store (nonce, agentDid, expiry) tuples
 - Support TTL-based automatic expiry
 - Be atomic to prevent race conditions in concurrent environments
-- For distributed deployments: use Redis, DynamoDB, or Cloudflare KV (not in-memory)
+- For distributed deployments: use a shared store with an atomic conditional insert and expiry, such as Redis `SET NX PX`, a DynamoDB conditional write or a Durable Object transaction (not in-memory). Eventually consistent stores such as Cloudflare Workers KV cannot provide the atomic check-and-set on their own.
 
-Nonce lifetime MUST exceed the session TTL. Servers MUST NOT drop nonces before the lifetime expires, to prevent replay attacks via early eviction.
+**Retention.** A verifier MUST retain each admitted nonce at least until the timestamp it was admitted with leaves the acceptance window on the verifier's clock: until `ts + skew`, plus a margin of at least one second for second-granularity timestamps. `ts` is the handshake `timestamp` or the proof's `ts`, and `skew` is the largest timestamp skew the verifier may apply while the nonce is retained; a verifier that can widen its skew at runtime (§10.1) retains for the widest. Servers MUST NOT evict a nonce before its retention ends, to prevent replay via early eviction. Verifiers MAY retain longer, and a verifier whose clock can be stepped backwards SHOULD add the largest expected step to the margin.
+
+Retention is bounded by the acceptance window, not by the session TTL. A nonce presented after its window is rejected on its timestamp (§5.2 rule 1, §11.3) before the cache is consulted, so keeping it longer adds memory and denial-of-service exposure and no replay protection. The bound holds because every nonce-checked path checks a timestamp window in the same verification: the handshake (§5.2), the detached proof and the holder-binding request proof (`ts` within skew, signed with the nonce, §7.4), and the Entity Card proof (`created`/`expires`, SPEC-ENTITY-CARD §8). The handshake request is unsigned, so a replayed handshake gives its sender nothing that a fresh handshake would not; its nonce check deduplicates and follows the same window. A path that checked a nonce without a timestamp window would have to retain the nonce for as long as the message it protects stays valid.
 
 ---
 
@@ -493,7 +506,7 @@ Delegations are issued as W3C Verifiable Credentials:
   "proof": {
     "type": "Ed25519Signature2020",
     "created": "2024-03-01T12:00:00Z",
-    "verificationMethod": "did:key:z6MkIssuer...#keys-1",
+    "verificationMethod": "did:key:z6MkIssuer...#z6MkIssuer...",
     "proofPurpose": "assertionMethod",
     "proofValue": "<base64url-encoded-signature>"
   }
@@ -591,6 +604,12 @@ Delegations form a directed acyclic graph (DAG):
 - Scope constraints MUST be equal to or narrower than parent's constraints
 - Every chain MUST terminate at a Responsible Party. The Responsible Party's DID is the `issuerDid` of the root `DelegationCredential` and is the entity ultimately accountable for actions taken under any descendant delegation. In personal use the Responsible Party equals the Principal; in organizational use the Responsible Party is the parent organization while the Principal is the immediate human delegator (see §2).
 
+**Chain length (non-normative).** The §6.2 profile does not limit how many times authority may be
+re-delegated. Separately, a verifier may cap how many credentials it will verify for one request, as
+a local resource limit: each credential costs a signature check and possibly a DID resolution. The
+reference implementation exposes this as `maxChainLength`, unset by default. Such a cap is the
+verifier's policy, not a protocol rule, and a chain it refuses is not thereby invalid elsewhere.
+
 ### 6.4.1 Designation Invariant
 
 A `DelegationCredential` may authorize multiple resources, either via a list
@@ -779,6 +798,11 @@ profile issues and verifies, this profile is what the Entity Card path issues an
 implementation encountering one never needs to accept the other in its place. The JSON Schema is
 published at `schemas/card-delegation-credential.json`.
 
+**Telling the profiles apart (non-normative).** Neither profile carries a separate profile
+identifier; the first `@context` entry selects the rule set. `https://www.w3.org/2018/credentials/v1`
+marks a §6.2 credential, and `https://www.w3.org/ns/credentials/v2`, with the ZCAP-LD context,
+marks a credential of this profile.
+
 **Credential shape.** One `DelegationCredential` per delegation **hop**; a chain runs `root → … → leaf`. A
 `DelegationCredential` is a VC 2.0 whose `credentialSubject` IS an attenuated ZCAP-LD capability:
 
@@ -819,18 +843,26 @@ chain:
 
 - **action subset** - child `allowedAction ⊆ parent`;
 - **monotone caveats** - no parent caveat may be silently dropped; for a shared caveat type, child
-  `MaxAmount ≤ parent` (same currency; compared as fixed-point decimals scaled to 6 places) and
+  `MaxAmount ≤ parent` (same currency; compared as exact decimals, never rounded or truncated) and
   child `ValidUntil ≤ parent`; an unknown caveat type MUST be replicated **verbatim**;
 - **top-level `validUntil` narrowing** - child `validUntil ≤ parent`;
 - **continuity** - the parent's delegate (`invoker`) MUST equal the child's `issuer` (you may only
   re-delegate what was delegated to YOUR key), and child `parentCapability` MUST reference the
   parent capability `id`;
 - **constant `invocationTarget`** along the chain;
-- **depth** MUST NOT exceed **10** hops (`MAX_DELEGATION_DEPTH`);
 - **root** - root `parentCapability` MUST equal its `invocationTarget` (the resource); when a
   resource owner / resource is asserted, root `issuer` MUST equal the resource owner and root
   `invocationTarget` MUST equal the resource.
 
+**Chain length (non-normative).** As in §6.4, this profile does not limit how many times a
+capability may be re-delegated. Earlier drafts listed a 10-hop cap among the invariants above,
+but a longer chain broadens nothing, so it was never an attenuation rule. A verifier may cap how
+many credentials it evaluates for one chain as a local resource limit: each hop may cost a
+signature check and a status-list fetch. The reference implementation takes the same
+`maxChainLength` option here, unset by default, and exports `MAX_DELEGATION_DEPTH` (10) as a
+suggested value. Such a cap is the verifier's policy, not a protocol rule, and a chain it refuses
+is not thereby invalid elsewhere.
+
 A verifying resource SHOULD assert its own identity as the expected resource when it evaluates a
 chain (the `resource` context of `evaluateDelegationChain`), so that a chain minted for a
 different resource fails at the root check instead of being accepted by an unrelated Verifier.
@@ -877,10 +909,10 @@ interface ProofMeta {
   did: string;          // Server's DID (signer)
   kid: string;          // Key ID used for signing
   ts: number;           // Unix epoch seconds when proof was generated
-  nonce: string;        // Session nonce (prevents cross-session replay)
+  nonce: string;        // Fresh random nonce per proof (replay protection, §5.5)
   audience: string;     // Session audience
   sessionId: string;    // Session identifier
-  requestHash: string;  // SHA-256 of canonicalized request
+  requestHash: string;  // SHA-256 of the canonicalized request (§7.3)
   responseHash?: string; // SHA-256 of canonicalized response. Present on success
                          // AND on needs_authorization challenges (binds the
                          // challenge content, incl. authorizationUrl); ABSENT on
@@ -905,14 +937,36 @@ interface ProofMeta {
 2. **Hash**: Compute SHA-256 of the canonical JSON bytes (UTF-8 encoded)
 3. **Format**: `sha256:<64-char-lowercase-hex>`
 
-Request canonicalization includes:
+Request canonicalization covers the JSON-RPC request as sent: its `method` and `params`.
+The envelope members `jsonrpc` and `id` are not covered.
+Two kinds of member are removed before canonicalizing:
+
+1. `params._meta`, if present.
+   `_meta` is intermediary-mutable transport metadata that also carries proofs (§7.6), so it is never signed.
+   Only that top-level member is removed; values nested under other `params` members are not touched.
+2. For `method: "tools/call"`, every member of `params.arguments` whose name begins with `_kyaos`: the KYA-OS control arguments (`_kyaos_delegation`, `_kyaos_proof`, `_kyaos_approvals`).
+   They carry the credentials that authorize the call, each authenticated on its own, and the holder-of-key request proof and approval grants are themselves bound to this hash, so covering them would make the hash depend on its own output.
+   Tool handlers SHOULD NOT receive control arguments, so that the covered request is the call the tool executes.
+   An absent `params.arguments` is covered as `{}`, since a server cannot tell it from an empty one.
+
+Every other `params` member (`name`, `task`, and any future member) is covered.
+When `params` is absent the covered request is `{ "method": ... }`.
+For a tool call:
 ```json
 {
   "method": "tools/call",
-  "params": { /* sorted keys, no whitespace */ }
+  "params": { "name": "echo", "arguments": { /* minus _kyaos* members */ } }
 }
 ```
 
+A client, a PEP or a third-party auditor recomputes `requestHash` this way from the request it sent or received.
+Rule 1 is the rule Entity Card request proofs use (SPEC-ENTITY-CARD §8.3).
+Appendix C.1 gives vectors.
+
+**Legacy shape in 1.x.** The 1.x releases of the reference implementation (`@kya-os/mcp`) still emit `requestHash` over the legacy shape `{"method": <tool name>, "params": <arguments>}` for every proof over a tool call: response and outcome proofs (§7.4), the approval `requestHash` of a step-up challenge, and holder-of-key request proofs.
+Their verifiers accept a `requestHash` over either shape of the call they hold, so a producer that follows this section verifies against them; the reference producers switch to the covered request above in 2.0.0.
+The legacy shape is deprecated: it hashes a tool named after a JSON-RPC method like that method's request, and it has no room for `params` members other than the arguments.
+
 Response canonicalization is selected by the proof's response-proof profile, named by the signature-covered `prf` claim (§7.2):
 
 - **body** (`prf` ABSENT — the original profile): the `data` field only (excludes `_meta`).
@@ -1243,7 +1297,7 @@ interface NeedsAuthorizationError {
   message: string;
   authorizationUrl: string;  // URL where user can grant authorization
   resumeToken: string;       // Token to resume flow after authorization
-  expiresAt: number;         // Unix epoch when resumeToken expires
+  expiresAt: number;         // Unix timestamp in seconds when resumeToken expires
   scopes: string[];          // Scopes being requested
   display?: {
     title?: string;
@@ -1422,7 +1476,7 @@ and the residual risk an operator carries.
 
 - Nonces MUST be cryptographically random (16 bytes minimum entropy)
 - Nonce cache MUST persist across server restarts (use external storage)
-- Nonce cache TTL MUST exceed session TTL
+- Nonce cache retention MUST cover the timestamp acceptance window (§5.5); it need not reach the session TTL
 - Distributed deployments MUST use atomic check-and-set operations
 
 ### 11.3 Timestamp Skew Attacks
@@ -1684,7 +1738,11 @@ purpose/scope authorization out of band. Bundle contents cannot authorize their
 own signer or bootstrap their own trust root. A verifier MUST distinguish
 `valid`, `invalid`, and `indeterminate`, MUST keep authorization-as-observed
 separate from current authorization/revocation, and MUST NOT consume a live
-nonce cache when verifying historical proof artifacts.
+nonce cache when verifying historical proof artifacts. A verifier MUST NOT
+ignore a verification-policy constraint (checkpoint-bounded key validity,
+required assurance profile, key revocation mode), and a constraint it cannot
+evaluate for the artifacts at hand MUST NOT leave the affected dimension
+`valid`.
 
 Sensitive payloads SHOULD be encrypted in a separate evidence provider and
 referenced by opaque randomized identifiers and ciphertext commitments. The
@@ -1784,6 +1842,35 @@ These test vectors enable interoperability testing across implementations.
 sha256:5057521f310b536837b619f0ac040ef8064f8c597da8ec22a56801b435744033
 ```
 
+**Covered request (§7.3).**
+`requestHash` covers a request's `method` and `params` minus `params._meta` and, on a `tools/call`, minus the `_kyaos*` control arguments; an absent `arguments` is covered as `{}`.
+Each of these requests covers to the input above and hashes to the same value:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"_kyaos_proof":{"jws":"...","meta":{}}},"_meta":{"traceparent":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}}}
+```
+
+```json
+{"method":"tools/call","params":{"name":"echo"}}
+```
+
+Business arguments stay covered:
+
+**Input JSON:**
+```json
+{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"echo","arguments":{"msg":"hi","_kyaos_delegation":{"id":"urn:uuid:1111-aaaa"}},"_meta":{"progressToken":7}}}
+```
+
+**Covered request, JCS canonicalized:**
+```json
+{"method":"tools/call","params":{"arguments":{"msg":"hi"},"name":"echo"}}
+```
+
+**KYA-OS Format:**
+```
+sha256:c8f3d59959c9247211de8c76b94ef17f0c279f09362350ced67f69ecdb89d6c7
+```
+
 ### C.2 did:key Derivation
 
 **Ed25519 Public Key (32 bytes, hex):**
@@ -1813,7 +1900,7 @@ did:key:z6Mko6jQvza2BSKRcrbJwgwbL9KYDn1isCUV5Lnq7gSTTKJq
 
 **Verification Method ID:**
 ```
-did:key:z6Mko6jQvza2BSKRcrbJwgwbL9KYDn1isCUV5Lnq7gSTTKJq#keys-1
+did:key:z6Mko6jQvza2BSKRcrbJwgwbL9KYDn1isCUV5Lnq7gSTTKJq#z6Mko6jQvza2BSKRcrbJwgwbL9KYDn1isCUV5Lnq7gSTTKJq
 ```
 
 ### C.3 JWS Structure
@@ -1824,7 +1911,7 @@ A valid detached proof JWS has the following structure:
 ```json
 {
   "alg": "EdDSA",
-  "kid": "did:key:z6Mk...#keys-1"
+  "kid": "did:key:z6Mk...#z6Mk..."
 }
 ```
 

package/dist/audit/adapters/legacy-audit-log.d.ts

@@ -17,4 +17,3 @@ export declare class LegacyAuditSinkAdapter extends AuditLogProvider {
     logAuditRecord(context: AuditContext): Promise<void>;
     logEvent(context: AuditEventContext): Promise<void>;
 }
-//# sourceMappingURL=legacy-audit-log.d.ts.map

package/dist/audit/adapters/mcp.d.ts

@@ -102,4 +102,3 @@ export declare class McpAuditEventAdapter {
     }): Promise<void>;
     private context;
 }
-//# sourceMappingURL=mcp.d.ts.map

package/dist/audit/adapters/mcp.js

@@ -1,5 +1,16 @@
-function boundedReference(value, maxLength = 256) {
-    return value.slice(0, maxLength);
+import { boundedAuditReference } from './references.js';
+/** Bounds every caller-supplied reference so a hostile one cannot keep the event out of the ledger. */
+async function boundedAuthorization(authorization) {
+    const bounded = { ...authorization };
+    for (const field of ['scopeId', 'delegationRef', 'grantRef', 'policyId', 'policyVersion']) {
+        const value = authorization[field];
+        if (value !== undefined)
+            bounded[field] = await boundedAuditReference(value);
+    }
+    if (authorization.verificationCode !== undefined) {
+        bounded.verificationCode = await boundedAuditReference(authorization.verificationCode, 128);
+    }
+    return bounded;
 }
 /** Privacy-minimal translation from MCP lifecycle signals to binding-neutral events. */
 export class McpAuditEventAdapter {
@@ -12,7 +23,7 @@ export class McpAuditEventAdapter {
     async session(phase, input) {
         await this.trail.record({
             eventType: `session.${phase}`,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'session' },
             outcome: input.succeeded ? 'succeeded' : 'failed',
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -26,11 +37,11 @@ export class McpAuditEventAdapter {
     async tool(phase, input) {
         await this.trail.record({
             eventType: `tool.call.${phase}`,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: {
                 category: 'tool.call',
                 ...(this.options.includeToolNames
-                    ? { name: boundedReference(input.toolName) }
+                    ? { name: await boundedAuditReference(input.toolName) }
                     : {}),
             },
             outcome: input.outcome,
@@ -42,7 +53,7 @@ export class McpAuditEventAdapter {
     async proof(phase, input) {
         await this.trail.record({
             eventType: `proof.${phase}`,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'proof' },
             outcome: input.outcome,
             evidence: [],
@@ -61,7 +72,7 @@ export class McpAuditEventAdapter {
             : `authorization.${phase}`;
         await this.trail.record({
             eventType,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'authorization' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -71,24 +82,24 @@ export class McpAuditEventAdapter {
                 ...(input.policyDigest === undefined ? {} : { policyDigest: input.policyDigest }),
                 ...(input.grantRef === undefined
                     ? {}
-                    : { grantRef: boundedReference(input.grantRef) }),
+                    : { grantRef: await boundedAuditReference(input.grantRef) }),
             },
         });
     }
     async delegation(phase, input) {
         await this.trail.record({
             eventType: `delegation.${phase}`,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'delegation' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
             evidence: [],
             details: {
                 family: 'delegation', phase,
-                delegationRef: boundedReference(input.delegationRef),
+                delegationRef: await boundedAuditReference(input.delegationRef),
                 ...(input.parentRef === undefined
                     ? {}
-                    : { parentRef: boundedReference(input.parentRef) }),
+                    : { parentRef: await boundedAuditReference(input.parentRef) }),
             },
         });
     }
@@ -98,7 +109,7 @@ export class McpAuditEventAdapter {
             : `consent.${phase}`;
         await this.trail.record({
             eventType: eventType,
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'consent' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -107,7 +118,7 @@ export class McpAuditEventAdapter {
                 family: 'consent', phase,
                 ...(input.consentRef === undefined
                     ? {}
-                    : { consentRef: boundedReference(input.consentRef) }),
+                    : { consentRef: await boundedAuditReference(input.consentRef) }),
             },
         });
     }
@@ -120,7 +131,7 @@ export class McpAuditEventAdapter {
         };
         await this.trail.record({
             eventType: eventTypes[phase],
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'configuration' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -147,7 +158,7 @@ export class McpAuditEventAdapter {
         };
         await this.trail.record({
             eventType: eventTypes[phase],
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'audit.ledger' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -177,7 +188,7 @@ export class McpAuditEventAdapter {
         };
         await this.trail.record({
             eventType: eventTypes[phase],
-            ...this.context(input.context),
+            ...(await this.context(input.context)),
             action: { category: 'audit.administration' },
             outcome: input.outcome,
             ...(input.reasonCode === undefined ? {} : { reason: { code: input.reasonCode } }),
@@ -194,7 +205,7 @@ export class McpAuditEventAdapter {
             },
         });
     }
-    context(context) {
+    async context(context) {
         if (context === undefined)
             return {};
         return {
@@ -204,9 +215,13 @@ export class McpAuditEventAdapter {
                 : { responsibleParty: context.responsibleParty }),
             ...(context.authorization === undefined
                 ? {}
-                : { authorization: context.authorization }),
-            ...(context.correlationId === undefined ? {} : { correlationId: context.correlationId }),
-            ...(context.causationId === undefined ? {} : { causationId: context.causationId }),
+                : { authorization: await boundedAuthorization(context.authorization) }),
+            ...(context.correlationId === undefined
+                ? {}
+                : { correlationId: await boundedAuditReference(context.correlationId) }),
+            ...(context.causationId === undefined
+                ? {}
+                : { causationId: await boundedAuditReference(context.causationId) }),
         };
     }
 }