@kya-os/mcp 1.16.2 → 1.18.0

package/CHANGELOG.md

@@ -7,6 +7,647 @@ Versioning: https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-10-08
+
+### Added
+
+- **`maxChainLength` for delegation chains.** `validateDelegationChain` and
+  the middleware's `delegation` config take an optional cap on how many
+  credentials one chain may hold, checked before any of them is verified. A
+  resolver could return a chain of any length, and each credential costs a
+  signature check and possibly a DID resolution. It is a local cost limit, not
+  a protocol rule about how far authority may be delegated: it is unset by
+  default, and SPEC.md §6.4 records that the base profile leaves chain length
+  unbounded. The middleware refuses a value that is not a positive integer at
+  startup rather than rejecting every call. The cap applies to the chain
+  `resolveDelegationChain` returns, not to the resolver's own fetches.
+
+### Changed
+
+- **The Entity Card chain limit is opt-in, as on the base profile.**
+  `validateDelegationChain` and `evaluateDelegationChain` in
+  `@kya-os/mcp/card` rejected any chain of more than `MAX_DELEGATION_DEPTH`
+  (10) credentials unless the caller passed a larger `maxDepth`. They now
+  accept any length unless the caller sets `maxChainLength`, the option's name
+  on both profiles. **A verifier that relied on the default now accepts chains
+  of 11 credentials or more; pass `maxChainLength: MAX_DELEGATION_DEPTH` to
+  keep the previous behavior.** A longer chain broadens nothing: every hop
+  still attenuates its parent, so the cap bounded only the verifier's work.
+  SPEC.md §6.10 drops the cap from the attenuation invariants and states it,
+  non-normatively, as a local limit, as §6.4 does for the base profile. A
+  limit that is not a positive integer rejects every chain; previously `NaN`
+  accepted every length.
+
+### Deprecated
+
+- **`maxDepth` on the Entity Card `DelegationChainContext`.** Use
+  `maxChainLength`, which wins when both are set.
+
+### Fixed
+
+- **The `example:*` scripts run from a fresh clone.** They resolved
+  `@kya-os/mcp` to `dist/`, which a clone does not have until `npm run build`,
+  and the node-server and authz-inspector examples, being packages of their
+  own, could not resolve it at all without a per-example install. The scripts
+  and `scripts/demo.sh` now run the examples from `src/` through
+  `tsconfig.examples.json`, so the root `npm install` is all they need. Two
+  scripts are added for the consent-persistence scenarios.
+- **`withKyaOs()` warns when the server is already connected.** It wraps
+  transports by patching `connect()`, so a transport connected before it ran
+  was never wrapped, and its tool results went out without a KYA-OS proof or
+  a transport audit record, silently. It now logs a warning saying so, on MCP
+  SDK 1.3 and later. When the server had no tools before connecting, the
+  warning also explains the SDK's refusal to register `_kyaos`.
+
+### Documentation
+
+- **CONFORMANCE.md L2.17 names the current proof keys.** It told verifiers to
+  read `org.kya-os/proof`, a key no server writes since the role-named keys
+  of SPEC.md §7.6. It now names `org.kya-os/response-proof`, keeps the prior
+  keys as 1.x fallbacks, in that order, and separates the request proof under
+  `org.kya-os/request-proof`.
+- **SPEC.md §6.10 says how to tell the two delegation profiles apart.** The
+  first `@context` entry selects the rule set.
+
+## [1.17.0] - 2026-10-05
+
+### Added
+
+- **Scope helpers in `@kya-os/mcp/delegation`.** `matcherContains(outer,
+  inner)` decides, by sound rules only, whether one scope matcher grants
+  everything another grants. `authorityContains(authority)` builds that check
+  once for a whole list of matchers. `scopeAuthority(credential)` returns a
+  credential's flat scopes and CRISP matchers as one list of matchers.
+  `crispScopes(credential)` returns its CRISP matchers. Scope attenuation
+  below is built on them.
+- **Signer binding options for `ProofVerifier.verifyProof`.** An optional
+  fourth argument, `{ expectedDid, expectedAudience }` (type
+  `ProofVerificationOptions`), rejects a proof from another signer
+  (`DID_MISMATCH`) or addressed to another audience (`AUDIENCE_MISMATCH`);
+  `expectedAudience` may list several DIDs. Omitting it verifies as before.
+- **`withKyaOs` takes `nonceCache`, `requireAtomicNonce`, and
+  `responseProofProfile`.** The adapter could not pass them to the middleware,
+  and its `session` option documented a top-level `nonceCache` that did not
+  exist. Each replica of a multi-replica deployment therefore kept a private
+  in-memory nonce cache and accepted a handshake replayed from another
+  replica (SPEC.md §5.5, §11.2; SPEC-MCP-EXTENSION.md §10.4),
+  `requireAtomicNonce` was unreachable, and envelope-profile proofs could not
+  be enabled. All three now pass through to `createKyaOsMiddleware`. Each is
+  optional, and leaving it out keeps the previous default.
+- **`KyaOsCallContext.principal` and `KyaOsCallContext.approvals`.**
+  `wrapWithDelegation` fills them for the handler it wraps; see the
+  `withPolicyGate` entry under Security. Both are optional members.
+- **`verifyApprovalQuorum` takes several request hashes.** Its `requestHash`
+  argument may be a list of hashes that identify the one suspended action; a
+  grant over any of them counts. A single string works as before.
+
+- **Audit verification and delivery hooks, all optional.**
+  `AuditArtifactVerifier` gains `verifySignedCheckpoint` (a checkpoint without
+  its leaves), `verifyCurrentKeys` (over `AuditSignedArtifacts`), a
+  `maxClockSkewMs` option, and an optional
+  `AuditVerificationContext` argument on `verifyEntries`, `verifyCheckpoint`,
+  and `verifyObservation` that carries the checkpoints a policy's checkpoint
+  bounds name. `applyRequiredAuditProfile` applies a policy's
+  `requiredAuditProfile` to a report. `AUDIT_REASON_CODES` gains
+  `KEY_BOUNDARY_UNRESOLVED`, `KEY_NOT_CURRENT`, `MERKLE_PROOF_MISSING`,
+  `OBSERVATION_FUTURE_DATED`, and `REQUIRED_PROFILE_UNMET`. On the write path,
+  `AuditOutboxItemKey` and `auditOutboxItemKey` identify an outbox item by
+  source and event ID, `AuditOutboxProvider.capabilities.keyedBySource` opts an
+  adapter into receiving that key, `AuditTrailConfiguration` gains
+  `onAcknowledgementFailure`, `AuditSourceStateProvider` gains an optional
+  `abandonClaim`, and `MemoryAuditSourceState` takes a `redeliveryWindow`.
+  Every new provider member is optional, so existing adapters still implement
+  their interfaces.
+
+### Changed
+
+- **SPEC.md: the `did:key` verification method id is `<did>#<multibase>`.**
+  §4.3, the §6.2 example and Appendix C.2 and C.3 gave `<did>#keys-1`, which
+  contradicts the W3C did:key method and which no standard resolver,
+  including this one, resolves. They, and `CONFORMANCE.md` L1.1, now give the
+  W3C form. No code changes.
+- **`json-canonicalize` 3.0.1.** Entity Card proofs (the request hash and the
+  covered claims) and cheqd DLR content still canonicalize through
+  `json-canonicalize`. 3.x throws on `NaN` and `Infinity`, as RFC 8785
+  §3.2.2.3 requires, where 2.0.0 wrote `null`; every JSON value canonicalizes
+  to the same bytes as before. A received JSON-RPC request cannot carry those
+  values, so verifying calls is unaffected. Minting a card proof, or preparing
+  DLR content, with a non-finite number now fails instead of hashing `null`:
+  the rule `canonicalizeJson` already applies to response proofs and audit
+  records. The package also ships dual ESM/CJS builds.
+- **Built with TypeScript 6.0.** The emitted JavaScript and declaration files
+  are byte-identical to the 5.9 build.
+- **Declaration maps are no longer published.** The `.d.ts.map` files pointed
+  at `src/`, which the package does not include, so Go to Definition already
+  fell back to the `.d.ts`. Types are unchanged. JavaScript source maps stay:
+  under `node --enable-source-maps`, or an error tracker that applies source
+  maps, stack traces still name the `src/*.ts` file and line. The package drops
+  from 691 to 525 files and from 2.69 MB to 2.47 MB unpacked.
+
+### Security
+
+- **Scope attenuation across scope representations.** `validateScopeAttenuation`
+  treated a parent credential that restricts scope only through
+  `constraints.crisp.scopes` matchers as unrestricted, because its flat scope
+  list was empty. A re-delegated child could then claim any flat scope (for
+  example `admin:root` under a parent limited to the `safe:` prefix), and the
+  chain validated. Both credentials are now read as one typed authority (flat
+  scopes as `exact` matchers, plus CRISP matchers), and every scope and matcher
+  the child grants must be proven inside the parent's authority by sound
+  containment rules; anything unprovable is rejected. Sound narrowings that
+  were rejected before are now accepted: a flat scope that a parent's matcher
+  grants, an `exact` matcher for a parent's flat scope, and a narrower `prefix`
+  or `path-prefix` under the parent's. A malformed scope entry proves nothing,
+  so it fails closed instead of throwing. A parent with no scopes of either
+  kind stays scope-unrestricted, as before (SPEC.md §6.3, §6.4).
+- **`verifyProofDetached` replay and skew bypass.** The signature was checked
+  over the payload the caller supplied, while the timestamp and replay checks
+  read `proof.meta`, which that payload did not bind: an accepted proof with a
+  fresh `meta.nonce`, `ts` or hash verified again. The supplied payload must
+  now equal the payload rebuilt from `meta` byte for byte
+  (`INVALID_JWS_PAYLOAD`). A caller that passes the canonical payload, as the
+  method documents, sees no change.
+- **`ProofGenerator.verifyProof` checks `meta` through the signature.** It
+  verified the JWS against its embedded payload and compared the hashes in the
+  unsigned `meta`, so a proof with rewritten `meta.requestHash` and
+  `meta.responseHash` verified for a different call, and one without
+  `meta.responseHash` accepted any response. It now verifies the signature
+  over the payload rebuilt from `meta`, requires a response exactly when the
+  proof binds one (the rule `ProofVerifier` already applied), and checks
+  `meta.did` and `meta.kid` against its identity. It still checks the artifact
+  only, with no freshness or replay state. Proofs it minted verify as before.
+- **The embedded JWS payload must be the signed one.** Verification put the
+  payload rebuilt from `meta` in place of the JWS's own payload segment
+  without looking at that segment, so an intermediary could rewrite the
+  embedded `aud`, `responseHash` or `outcome` that JWT tooling and audit
+  stores read, and the proof still verified. `CryptoService.verifyJWS` with a
+  detached payload now also requires an embedded payload that differs from it
+  to verify under the same signature, which only the signed payload does
+  (SPEC.md §7.4: the `meta` block and the decoded payload reconcile exactly).
+  A JWS without a payload segment (`header..signature`) verifies as before,
+  and so does every proof this library mints.
+- **`kid` must belong to `did`.** A proof signed with one DID's key could name
+  another DID as its signer (`iss`/`sub`) and verify against the key its `kid`
+  named. `ProofVerifier` now rejects a DID URL `kid` whose DID is not
+  `meta.did` (`KID_DID_MISMATCH`), as the Entity Card verifier already did
+  (SPEC-ENTITY-CARD.md §8). A relative `kid` is unaffected.
+- **The `withKyaOs` transport no longer re-signs results a wrapper already
+  proved.** It ran `wrapWithProof` again over every non-error `tools/call`
+  result. A `needs_authorization` challenge from `wrapWithDelegation` (not an
+  error result) lost its signed `outcome: "needs_authorization"` proof to an
+  outcome-less one, which SPEC.md §7.2 reads as `allowed`, and the audit trail
+  gained a started and succeeded lifecycle for a call that never ran. A
+  delegated call lost its scope-bearing proof and was recorded twice. Once a
+  middleware is connected to the transport, its wrappers and outcome paths
+  stamp what they return with a random per-middleware token in a private
+  `_meta` member, and the transport passes a stamped result through untouched.
+  The stamp lives in `_meta` because the MCP SDK re-creates the result object
+  when it validates it. The transport removes it from every result before the
+  message is sent, so it never reaches the wire. A result without the stamp
+  is proved and audited as before, whatever proof, `proofError` or
+  `org.kya-os/audit` members it carries: those are removed first, so content
+  relayed from an upstream server cannot suppress this server's proof and
+  audit events or ship its own proof in their place. Other `_meta` members are
+  kept. A middleware used without the transport stamps nothing.
+- **`withPolicyGate` composed inside `wrapWithDelegation` sees the verified
+  call.** The delegation gate strips every `_kyaos*` argument before its
+  handler runs. The policy gate then projected its principal from the already
+  stripped `_kyaos_delegation`, so engines saw `agentDid: "unknown"` and no
+  delegated scopes (a deny-list engine allowed everything), and
+  `_kyaos_approvals` never arrived, so no step-up could be satisfied. The
+  delegation gate now passes the authenticated principal and scopes (for a
+  durable grant, those of its re-verified credential) and the approvals in the
+  call context, and the policy gate prefers them. Approvals stay outside the
+  holder-binding request hash. A policy gate used on its own behaves as
+  before.
+- **did:key and base58 input is bounded before decoding.** The did:key path
+  decoded the whole counterparty-supplied DID before checking it was a 34-byte
+  key, and `base58Decode` had no input limit and quadratic cost: one 100 KB
+  `did:key:z…` in a tool call held the event loop for seconds. A did:key whose
+  base58 part is longer than 64 characters (an Ed25519 key is always 47) is
+  now rejected unread, and its payload must be exactly the prefix and 32-byte
+  key. `publicKeyMultibase` and `publicKeyBase58` in DID documents are decoded
+  only up to 1024 characters, enough for any published public key.
+  `base58Decode` takes that bound as a new optional `maxLength` argument (the
+  package root exports 1024 as `MAX_BASE58_DECODE_LENGTH`), and a `maxLength`
+  that is not a non-negative integer throws a `RangeError`. Called without
+  it, `base58Decode` decodes any length, as before. Its byte conversion is now
+  linear; accumulating the digits stays quadratic, which the bound keeps
+  small. Every well-formed Ed25519 did:key and verification method resolves
+  as before.
+- **`GenericOidcAdapter` accepts only a real token response.** Any 2xx JSON
+  body from the token endpoint was a successful authorization, including `{}`
+  and the HTTP 200 `{"error":"bad_verification_code"}` some providers return
+  for a bad or replayed code. The body must now be a JSON object with no
+  `error` member and a non-empty string `access_token` (RFC 6749 §5.1). A
+  non-Bearer `token_type` (some providers send `bot`) is accepted. The granted
+  scopes are read strictly: an absent `scope` means the requested scopes
+  (RFC 6749 §5.1), a string is split on whitespace, so `""` grants none, a
+  list of strings is taken as is, and any other `scope` fails the
+  authorization instead of granting the requested scopes.
+- **`DefaultPolicyEngine` step-up counts distinct, allowed approvers.** One
+  approver listed twice in `humanApprovals` satisfied a quorum of two, and
+  `stepUpApprovers` was returned in the step-up challenge but not enforced.
+  Only distinct approvers, and only those on the allowlist when one is set,
+  now count toward `stepUpQuorum`. `verifyApprovalQuorum` reports the verified
+  approvers as `QuorumResult.approvers`, the set `humanApprovals` should be
+  built from. It always sets the field; the field is optional, so code that
+  builds its own `QuorumResult` still compiles. The `stepUpQuorum` value
+  itself is read as before, and distinct, allowed approvals decide as before.
+- **Small-order Ed25519 public keys are rejected.** Under such a key one
+  signature verifies for every message, so anyone could sign as a did:key
+  built from it, and OpenSSL, WebCrypto and `jose` all accept it.
+  `NodeCryptoProvider` and `WebCryptoProvider` now refuse the small-order
+  encodings libsodium blocks, and so does every path that imports a key
+  itself: VC-JWT verification, Entity Card proofs and their HTTP message
+  signatures, and `CompactJwsAuditSignatureVerifier`. Those check the imported
+  key rather than the JWK, because Node's JWK import tolerates junk in `x`.
+  The audit verifier cannot read back a public key its resolver imported as
+  non-extractable, and verifies under such a key as before.
+  `NodeCryptoProvider` also decodes keys strictly, as `WebCryptoProvider`
+  already did: a 64-byte key or a key with trailing junk no longer verifies.
+  ASCII whitespace in a key is still ignored, as both decoders did, so a key
+  read from a file with its newline verifies as before, and so does a 32-byte
+  key in base64, unpadded base64, or base64url.
+- **Strict canonicalization never honours `toJSON`.** `canonicalizeJson` and
+  `canonicalizeJsonBytes` validated their input and then serialized it with
+  `json-canonicalize`, which hands any object with a `toJSON` member to
+  `JSON.stringify`: `{"toJSON":"x", ...}` came out unsorted (not RFC 8785),
+  and a hidden `toJSON` function, or one on an array, replaced the value that
+  was hashed or signed. They now serialize the validated value themselves, in
+  one pass linear in the size of the input. Properties JSON does not carry
+  (non-enumerable ones, and an array's non-index ones such as a `toJSON`) are
+  ignored, as before, and never consulted, so `'abc'.match(/b/)` still
+  serializes as `["b"]`. An accessor array element is now refused, as an
+  accessor member already was, because the value checked could differ from
+  the value written. Output is byte-identical to `json-canonicalize` for plain
+  JSON (anything `JSON.parse` returns or an object literal builds), and the
+  conformance vectors are unchanged.
+
+- **Graph revocation is checked for the whole chain.** `validateDelegationChain`
+  asked its `RevocationChecker` about the leaf only, so a leaf minted after an
+  ancestor's revocation, and therefore never registered in the graph, still
+  validated. Every credential in the verified chain is now checked, root
+  first, and a checker that throws fails the chain instead of throwing.
+
+- **Revocation is recorded in the graph.** `revokeDelegation` only flipped a
+  status bit when `credentialStatusId` had the form `<list>#<digits>`, and
+  otherwise reported success while recording nothing, so a delegation whose
+  status id was a `urn:uuid:` read as live after revocation (SPEC.md §6.5 step
+  1). `DelegationNode` gains an optional `revoked` flag, which revocation sets,
+  restore clears, and `isRevoked` honours alongside the status bit, and
+  `registerDelegation` accepts an optional structured `credentialStatus` so no
+  id has to be parsed. A status id that names no list entry still registers
+  and revokes without error, as before; it now also reads as revoked. Both
+  fields are optional, so existing storage providers keep working. One that
+  persists a fixed set of node fields must also store `revoked`: revocation
+  reads the node back, and revoking a delegation that has no status list
+  entry through a provider that dropped the mark now throws, naming that
+  requirement, instead of reporting success while recording nothing. With an
+  entry, the status bit still records it.
+
+- **Registering a delegation id again cannot replace it.** `registerDelegation`
+  overwrote the stored node whenever an id was registered again, dropping its
+  `credentialStatusId`, revocation and children: re-registering a revoked
+  ancestor read its whole subtree as live again, and re-registering a node
+  under its own descendant left a parent cycle that `getChain` walked forever.
+  A repeat registration that matches the stored node in every registered field
+  (`parentId`, `issuerDid`, `subjectDid`, `credentialStatusId`,
+  `credentialStatus`) is now a no-op that returns the stored node, children
+  and revocation intact, so retries stay safe. One that differs in any of them
+  throws, as does a delegation naming itself as parent, on the non-atomic path
+  and in `MemoryDelegationGraphStorage.registerNodeAtomic`; the memory store's
+  chain walk throws on a cycle. A custom `AtomicDelegationGraphStorageProvider`
+  should apply the same rule, since only it can close the race between the
+  manager's check and its write.
+
+- **First status list creation is serialized with updates.** A status list was
+  created on first allocation outside its update lock, so a concurrent
+  allocation could replace a list that had just recorded a revocation with a
+  fresh, empty one (SPEC.md §11.10). Creation now runs inside the list's lock
+  and re-reads the list there.
+
+- **`did:web` host labels cannot smuggle in another URL.** The host label is
+  percent-decoded, and what it decoded to was used unchecked:
+  `did:web:trusted.example%40attacker.example` fetched its document from
+  `attacker.example`, and `%2F`, `%3F` and `%23` injected a path, query or
+  fragment. A host that decodes to `@`, `/`, `\`, `?`, `#`, whitespace, a
+  control character, or a `:` beyond one port separator (a bracketed IPv6
+  literal keeps its own colons) is now rejected, as is a path component that
+  decodes to a separator, a dot-segment or nothing (SPEC.md §4.4). A malformed
+  escape returns `null` instead of throwing. Ports, IPv4 and IPv6 literals and
+  percent-encoded internationalized hosts resolve as before.
+
+- **Unreadable validity bounds fail closed.** An `expirationDate` that did not
+  parse (`2020-02-30T25:00:00Z`) and a non-numeric `constraints.notAfter` or
+  `notBefore` were read as no bound at all, so the credential never expired;
+  a `notAfter` of `0` was skipped the same way. A present bound that cannot be
+  read now places the credential outside its validity window. Basic checks
+  also accepted any delegation `status` other than `revoked` and `expired`
+  (`suspended`, or none), though the type allows only `active`, `revoked` and
+  `expired`; only `active` passes now.
+
+- **VC-JWT verification no longer throws on hostile input.** A JOSE header or
+  claims set that is not a JSON object (`null`, an array), a `kid` that is not
+  a string, and a DID resolver that throws all escaped `verifyDelegationJwt`
+  as exceptions, so a caller outside a `try` recorded no rejection. Each now
+  returns a failed result.
+
+- **CIMD documents can no longer speak for another origin's DID.**
+  `cardFromClientMetadata` accepted any declared `_meta["org.kya-os/did"]`,
+  and `verifyCimdBind` took the DID from the DID document rather than the card,
+  so a document at `https://attacker.example/clients/x` declaring
+  `did:web:victim.example:clients:acme` produced a victim-id card whose bind
+  check passed. `cardFromClientMetadata` now rejects a declared `did:web`
+  whose origin (host and port) differs from the `client_id`'s. Every
+  same-origin shape the CIMD draft allows still derives a card: a root with a
+  trailing slash, a query, an explicit `:443`, a root DID declared on a path
+  `client_id`, and a declared `did:key`. `verifyCimdBind(cimd, didDoc,
+  expectedDid?)` takes an optional third argument (pass the card's `id`) and
+  then also requires `didDoc.id` to be that DID and `client_id` to be its HTTPS
+  form, compared as normalized URLs. Two-argument calls behave exactly as
+  before, so they cannot detect a card/document mismatch.
+
+- **`resolveCard` no longer conflates distinct `did:web` DIDs.** The identity
+  binding percent-decoded each segment and rejoined with `:`, so
+  `did:web:host:users:alice%3Aagent` accepted Alice's card
+  `did:web:host:users:alice:agent`, and `did:web:host:8443` accepted a card for
+  the port-form `did:web:host%3A8443`. DIDs are now compared in canonical
+  encoded form: host lowercased, each segment decoded and re-encoded, so two
+  spellings of one DID still match.
+
+- **`MaxAmount` attenuation compares exact decimals.** Limits were truncated to
+  six fractional digits, so `100.0000009` passed as a narrowing of `100`, and a
+  child `0.0000009` under a parent `0.0000001` (both scaled to zero) passed
+  too. Both limits are now scaled to the longer fraction and compared exactly
+  (SPEC.md §6.10).
+
+- **Audit checkpoints no longer sign a rewritten history.**
+  `AuditCheckpointBuilder.createCheckpoint` compared the journal with the latest
+  checkpoint only when both had the same tree size. A journal that had been
+  rewritten or restored and had since grown got a new signed checkpoint chained
+  to the old one, which it does not extend: a split view carrying the
+  recorder's own signature. The builder now checks that the journal still holds
+  the latest checkpoint's exact tree as its prefix and fails with
+  `AUDIT_CHECKPOINT_CONFLICT` otherwise.
+
+- **Audit verification policies are enforced instead of ignored.** The
+  `validFromCheckpoint` / `validUntilCheckpoint` bounds (on recorder, observer,
+  and exporter keys and on trusted ledger epochs), `requiredAuditProfile`, and
+  `keyRevocationMode` were schema-valid but never read, so an entry signed after
+  its key's validity boundary verified, and a bundle without checkpoints passed
+  an AAP-4 policy with exit code 0. Checkpoint bounds now place each artifact by
+  tree position against checkpoints resolved by digest; a bound that cannot be
+  placed (a missing boundary, one in another epoch, or any bound on an exporter
+  key, since an export has no ledger position) makes the dimension
+  `indeterminate`, never `valid`. A required profile marks each dimension it
+  depends on `invalid` unless it is `valid`. Under `keyRevocationMode`
+  `current` or `both`, every signing key must also still be valid at
+  `verifiedAt`, reported in `currentAuthorization` (`AUDIT_KEY_NOT_CURRENT`);
+  `as_observed` is unchanged. Every policy that 1.16 accepted is still
+  accepted; none is rejected for the constraints it uses.
+
+- **A predecessor epoch ends at the terminal checkpoint its successor
+  committed.** The bundle verifier only checked that the committed terminal
+  checkpoint was present, so a stale authority that kept checkpointing the old
+  epoch after rollover verified as valid. A predecessor checkpoint over a larger
+  tree than that terminal now reports `AUDIT_CHECKPOINT_FORK_DETECTED`. Entries
+  past the terminal alone are not a fork, since the terminal checkpoint's own
+  `checkpoint.created` event follows it.
+
+- **The recorder fails closed when its journal moves backwards.** After a
+  failover to a lagging primary or a restore, `AuditRecorderService` appended on
+  the lower head and signed a second, different entry at an already receipted
+  sequence. A head read below this recorder's own commits is now raised to its
+  committed head for the compare-and-append, so a stale read replica still only
+  costs a retry, and a journal whose compare-and-append answer reports a head
+  below that committed head, or a different digest at a sequence it already
+  reported, fails with `AUDIT_JOURNAL_FAILURE` before anything is appended.
+
+- **Hostile references can no longer keep an MCP audit event out of the
+  ledger.** `McpAuditEventAdapter` truncated references by UTF-16 code units and
+  passed context references through unbounded, so a presented credential ID
+  with a lone surrogate, a split surrogate pair, or more than 256 characters
+  made the event fail canonicalization or schema validation, even in
+  best-effort mode, and a rejected delegation went unrecorded. Every caller
+  reference, including `authorization.*` and correlation/causation IDs, is now
+  kept verbatim when well-formed and within bounds, and otherwise recorded as
+  the `sha256:` digest of its UTF-8 encoding. An over-long tool name or
+  reference that 1.16 truncated is recorded as that digest instead.
+  `wrapWithDelegation` still truncates a rejected credential's ID to 256 code
+  units before the adapter sees it, as in 1.16.
+
+- **A failed append no longer disposes evidence a committed entry still uses.**
+  The recorder's cleanup after a failed append disposed every submitted
+  evidence object, including one that already existed and that an earlier
+  committed entry references (a session's shared actor object, for example).
+  Only objects that the failed submission newly stored are disposed now, and
+  never one that a concurrent submission to the same recorder held at the same
+  time, since that submission may have committed a reference to it.
+
+- **A projection built from a forked history is never reported verified.**
+  `AuditProjectionWorker.reconcile` reported a lagging projection as `pending`
+  without checking its offset digest, and `synchronize` appended entries that do
+  not chain from that offset. Reconciliation now compares the offset with the
+  journal entry at that sequence (`gap_detected` on mismatch), and
+  synchronization fails with `AUDIT_PROJECTION_CONFLICT` instead of extending a
+  foreign prefix.
+
+### Fixed
+
+- **A `requestHash` over the request as sent now verifies.** SPEC.md §7.3 and
+  Appendix C.1 describe `requestHash` over the `tools/call` request, while the
+  middleware hashes `{method: <tool name>, params: <arguments>}`, so a client
+  recomputing the hash from the request it sent always got
+  `CONTENT_BINDING_MISMATCH`, and a holder-of-key request proof minted that
+  way never bound at the PEP. Every verifier of a received request hash now
+  accepts either shape of the same call: `ProofVerifier` content binding,
+  `ProofGenerator.verifyProof`, the holder-binding check of
+  `wrapWithDelegation` and durable-grant resolution, and step-up approval
+  grants in `withPolicyGate`. The caller may hold the request in either shape
+  (`{method: "tools/call", params: {name, arguments}}` as sent, or the legacy
+  shape), and both hashes are derived from it; the §7.3 shape leaves out
+  `params._meta` and the `_kyaos*` control arguments. Producers are
+  unchanged: response and outcome proofs, the `requestHash` of a
+  `needs_approval` challenge, and `generateRequestProof` still emit the
+  legacy shape, so verifiers of earlier releases keep accepting them. Each
+  accepted hash covers the same tool name and business arguments, so no proof
+  over a different call is admitted. §7.3 now states the control-argument and
+  `_meta` exclusions, and Appendix C.1 gives covered-request vectors.
+- **`fetchPublicKeyFromDID` resolves the `kid` proofs carry.** It prefixed `#`
+  to every `kid`, so a full DID URL (`did:key:z…#z…`, the form this library
+  mints) never matched. A DID URL `kid` must now name the DID being resolved
+  (`KID_DID_MISMATCH` otherwise) and match the verification method id; a bare
+  fragment is still resolved against the DID.
+- **`MemoryResumeTokenStore` stays bounded.** A token is minted for every
+  unauthorized call, and was deleted only when that exact token was read after
+  it expired; fulfilled tokens were never deleted. `create()` now drops expired
+  tokens and `fulfill()` deletes the token. A challenge's `expiresAt` is now
+  the expiry the store enforces, read back from the store: it came from
+  `authorization.resumeTokenTtl`, so a configured hour was advertised for a
+  token the default store expires after 10 minutes. `resumeTokenTtl` is now
+  the fallback for a store that cannot report a future expiry in
+  milliseconds.
+- **Expired sessions no longer switch off the single-session fallback.** The
+  fallback counted every stored session, live or expired, and nothing swept
+  them, so once a second session had existed proofs stopped for every
+  unthreaded call. A count above one now sweeps expired sessions first (at
+  most once a minute). Concurrent first calls under `autoSession` share one
+  auto-created session instead of racing into two.
+- **Proofs keep handler `_meta` keys.** Attaching a proof, or a `proofError`
+  in the middleware or the transport, replaced `_meta` and dropped keys such
+  as `traceparent` and `io.modelcontextprotocol/related-task`. They are now
+  merged (SPEC.md §7.6). The proof, `proofError` and `org.kya-os/audit`
+  members are the exception: only the middleware sets them, so a handler's
+  copies are still dropped when a proof or proof error is attached, and a
+  relayed upstream result cannot place them next to this server's proof.
+- **The transport matches proofs to responses only.** A server-initiated
+  request (for example `elicitation/create`) whose id equalled a pending
+  `tools/call` id consumed that call's entry, and the tool response shipped
+  unproven. Entries for cancelled calls are also dropped on
+  `notifications/cancelled`.
+- **SPEC.md: nonce retention is bounded by the acceptance window.** §5.2, §5.5
+  and §11.2 required nonces to be kept for the session TTL plus a minute,
+  while §5.2 also recommended 60 seconds. A nonce presented after its
+  timestamp leaves the acceptance window is rejected on that timestamp, so the
+  longer retention bought memory and denial-of-service exposure and no
+  protection. §5.5 now requires retention until `ts + skew` plus a margin, for
+  the widest skew the verifier may apply, which is what the reference
+  implementation already does, and says why the bound holds on every
+  nonce-checked path. CONFORMANCE.md L2.5 follows, and L2.11 describes the
+  per-proof nonce and both request-hash shapes.
+- **In-memory replay and pending-flow stores evict on their own.**
+  `MemoryNonceCacheProvider`, the default replay store for `withKyaOs` and
+  `SessionManager`, and `MemoryPendingFlowStore` freed expired entries only on
+  an explicit `cleanup()`, which nothing schedules, so every handshake nonce
+  and abandoned authorization flow stayed resident. Both now sweep expired
+  entries as they are written to: every 1000 writes, or after a minute. A live
+  entry is never swept, and `cleanup()` works as before.
+- **`@kya-os/mcp/providers` bundles for browsers and Workers again.** The
+  entry documented for `WebCryptoProvider` also exports `NodeCryptoProvider`,
+  which imported `node:crypto` at module load and broke every browser bundle.
+  `node:crypto` now loads on first use; the exports are unchanged.
+- **cheqd DLR content hashes are always computed.** `prepareCheqdDlrResource`
+  returned a caller-supplied `contentHash` as the artifact's content address
+  without checking it against the bytes being anchored. The hash is now
+  always computed from the canonical content bytes, and a supplied one that
+  differs throws. Canonicalization of the content is unchanged.
+
+- **Status list indexes stay inside the list.** `updateStatus` parsed
+  `statusListIndex` with `parseInt`, so revoking `"5abc"` flipped bit 5, which
+  belongs to another credential, while `checkStatus` already parsed strictly.
+  Both now share the strict parser. `allocateStatusEntry` also handed out
+  indexes past the end of the list, which no read or revocation could reach;
+  it now throws once the list is full (SPEC.md §6.7).
+
+- **A status list with an unreadable validity window is not fresh.** A
+  `validUntil` / `validFrom` (or `expirationDate` / `issuanceDate`) that was
+  present but not a parseable date was treated as absent, so the list read as
+  live. It now reads as not fresh (L3 → L2); the revocation bit is still read.
+
+- **Card schemas match the published JSON Schemas.** `CapabilityAttestation`
+  stripped unknown members (the JSON Schema allows them), dropping sidecar
+  fields such as `credentialStatus` before the capability verifier saw them;
+  extra members are now preserved. `DelegationCredentialSchema.type` accepted
+  any string array; it now requires `VerifiableCredential` and
+  `DelegationCredential`, so another VC with a ZCAP-shaped subject is not read
+  as a delegation hop. `schemas/card-delegation-credential.json` enforces the
+  same two types it already documented.
+
+- **`getInclusionProof` works for sequence 1.** The entry lookup started its
+  range read after sequence 1 for any sequence up to 1, so the first entry after
+  genesis could never be proven.
+
+- **`listEntries` pages are bounded by the head they echo.** The head was read
+  after the page, so a concurrent append could return `nextAfterSequence: null`
+  with a head beyond the last entry, contrary to SPEC-AUDIT-READ §2.2. The head
+  is now read first and bounds the page.
+
+- **Subset replay bundles verify.** A checkpoint was verified only against every
+  leaf of its tree, and included checkpoints had to link directly, so a
+  legitimate export of a sequence range or of non-adjacent checkpoints was
+  invalid. Without its complete prefix, a checkpoint is now verified by
+  signature, digest, trust, and declared range, and each covered entry needs a
+  verified inclusion proof (`AUDIT_MERKLE_PROOF_MISSING` otherwise).
+  Checkpoints that could have omitted ones between them may be bound by a
+  verified consistency proof instead of a direct `previousCheckpointDigest`
+  link, the rule independent observers already apply.
+
+- **Concurrent checkpoints on one builder chain in order.** Two concurrent
+  `createCheckpoint` calls at different sizes could both chain to the same
+  predecessor. A builder now serializes its calls per ledger epoch. The
+  `AuditCheckpointStore` contract is unchanged.
+
+- **A failed checkpoint lifecycle hook runs again.** When `onCheckpointCreated`
+  threw after the checkpoint was stored, a retry returned the stored checkpoint
+  without calling the hook, losing the lifecycle event. The builder's next
+  `createCheckpoint` call now runs the hook again for every checkpoint whose
+  hook failed, oldest first and before any newer checkpoint's, even when the
+  ledger has grown in between; the hook should be idempotent on the checkpoint
+  digest. A hook that completed is not repeated.
+
+- **A future-dated observation is not fresh.** With a freshness requirement,
+  an observation dated after `verifiedAt` passed. One dated beyond the clock
+  skew allowance (`maxClockSkewMs`, default 120 s) is now `invalid` with
+  `AUDIT_OBSERVATION_FUTURE_DATED`.
+
+- **Redelivering a stable event ID returns the original receipt.**
+  `MemoryAuditSourceState` dropped the claims of receipted events, so an
+  at-least-once redelivery after later events got a new source sequence and was
+  rejected as `AUDIT_EVENT_ID_CONFLICT`. Receipted claims are now retained for a
+  bounded `redeliveryWindow` (default 1024 per source). Different content under
+  a retained event ID is still an `AuditProtocolError` with
+  `AUDIT_EVENT_ID_CONFLICT`, now raised by the source state; it was a plain
+  `Error` there before.
+
+- **Rejected input no longer consumes a source sequence.** The trail claimed a
+  source sequence before validating the event, so schema-invalid input, a lone
+  surrogate, or an unreferenced evidence object left a permanent gap and a
+  broken `previousSourceEventDigest` link. Validation now runs first, and a
+  claim whose event cannot be emitted is released through the optional
+  `abandonClaim`.
+
+- **Source state no longer leaks behind an open gap.** One unreceipted sequence
+  stopped `MemoryAuditSourceState` from pruning anything after it. It now keeps
+  only pending events plus the redelivery window.
+
+- **A replica that loses the cold-start genesis race recovers.** When every read
+  was stale, the losing genesis surfaced as an idempotency conflict and failed
+  with `AUDIT_EVENT_ID_CONFLICT`; it is now validated against the epoch
+  configuration like any raced genesis.
+
+- **A committed outbox item is never reported as a delivery failure.** If
+  `markDelivered` threw after the recorder committed, `flush()` called
+  `markFailed` and `onDeliveryFailure`. The item now counts as delivered, the
+  error goes to the new `onAcknowledgementFailure` callback, and redelivery
+  resolves to the same receipt.
+
+- **Outbox items are identified by source and event ID.** Event IDs are unique
+  only within a source, but `MemoryAuditOutbox` keyed items by event ID alone,
+  so one source could acknowledge or displace another's pending item.
+  `markDelivered` and `markFailed` now accept an `AuditOutboxItemKey` as well as
+  a bare event ID, and the trail passes the key to an outbox that declares
+  `capabilities.keyedBySource`, as `MemoryAuditOutbox` now does. An adapter
+  that implements `markDelivered(eventId: string)` still type-checks and still
+  receives the bare event ID, and so does a `MemoryAuditOutbox` subclass that
+  overrides `markDelivered` or `markFailed`: the memory outbox declares the
+  capability only for its own implementations, unless the subclass declares it
+  again. `MemoryAuditOutbox` throws on a bare event ID that more than one source
+  has pending instead of guessing.
+
+- **Default audit event IDs are random.** `audit_<time>_<counter>` was unique
+  only per trail instance, so two trails sharing an outbox collided. Defaults
+  are now `audit_<uuid>`; `eventIdFactory` still overrides them.
+
+### Deprecated
+
+- **The legacy request-hash shape.** `requestHash` over
+  `{method: <tool name>, params: <arguments>}` is deprecated in favour of the
+  SPEC.md §7.3 covered `tools/call` request. Producers switch to the §7.3
+  shape in 2.0.0; verifiers accept both until then.
+- `ProofVerifier.verifyProofDetached`. The payload it takes must now equal the
+  payload rebuilt from `proof.meta`, so it adds nothing over `verifyProof`.
+
 ## [1.16.2] - 2026-09-21
 
 ### Changed