@kya-os/mcp 1.17.0 → 1.20.0

package/CHANGELOG.md

@@ -7,6 +7,404 @@ Versioning: https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-10-13
+
+1.19.0 was tagged but never published to npm; its changes (listed under
+1.19.0 below) ship to npm for the first time in this release.
+
+### Upgrading — BREAKING without an open KYA-OS transport
+
+- **Every response proof is now made where the KYA-OS transport sends the
+  result, under the default body profile as under the envelope profile, and
+  the wrappers refuse to run without one.** While no KYA-OS transport is open
+  for the middleware, `wrapWithProof`, `wrapWithDelegation`, `withPolicyGate`
+  and `proveOutcome` throw on entry, before they record or run anything, with
+  an error that names `withKyaOs` and `createKyaOsTransport`. A transport
+  counts as open from `start()` until it closes, by `close()` or by its own
+  `onclose`. Once a KYA-OS transport has been created for a middleware, every
+  wrapper result must go out through one. Before, the proofs were signed in
+  the handler, and they did not verify on 2026-07-28 (envelope) or after an
+  SDK reshaped `content` (body). Find your setup:
+  - **`withKyaOs(server, …)` before `server.connect()`, `proofAllTools` left
+    on:** nothing to change.
+  - **The low-level `Server` API with `createKyaOsMiddleware`:** connect
+    through the KYA-OS transport, as this repository's examples now do:
+
+    ```ts
+    await server.connect(createKyaOsTransport(transport, kyaos)); // was server.connect(transport)
+    ```
+
+    The transport proves and audits every tool's result, as `withKyaOs`
+    does, including tools you registered without a wrapper, which went out
+    unproven on 1.19.0. List any to leave unproven in its third argument,
+    which adds to the always-excluded `_kyaos` and `_kyaos_handshake`.
+  - **A script, walkthrough or test that calls a wrapped handler directly:**
+    serve it in process, and read the result a client would receive:
+
+    ```ts
+    const local = serveInProcess(kyaos);
+    const checkout = local.tool('checkout', kyaos.wrapWithDelegation('checkout', consent, handler));
+    const result = await checkout({ item: 'laptop' }); // proved
+    await local.close();
+    ```
+  - **`withKyaOs` with `proofAllTools: false`:** it wraps no transport, so
+    the wrappers refuse. Leave it on and list the tools to leave unproven in
+    `excludeTools`.
+  - **`withKyaOs` called after `connect()`:** the connected transport is not
+    wrapped; call `withKyaOs` first.
+  - **Code that reads the proof inside the handler:** the result
+    `proveOutcome` or a wrapper returns no longer carries one, under either
+    profile. Return it from the handler; the transport adds the proof.
+  - **Results delivered later, such as MCP task results:** a result is
+    proved the first time the same middleware sends it, within
+    `pendingProofTtlMs` (default five minutes, at most 2147483647) of the
+    handler returning. Raise it for task results fetched later; a later or
+    repeated send goes out with `proofError` (see below).
+
+### Added
+
+- **The Entity Card revocation checker can verify a status list's proof.**
+  `createRevocationChecker` fetched a Bitstring status list and read its bits
+  without checking the list's proof, which Bitstring Status List v1.0 requires
+  (§3.2, step 4). Whoever could serve or alter the list could clear a
+  revocation. It now takes an optional `verifyStatusList`: a list it rejects,
+  by returning anything but `true` or by throwing, resolves to revoked and not
+  fresh, like any other unreadable list. `createStatusListProofVerifier({
+  didResolver })` is a ready verifier for `DataIntegrityProof` /
+  `eddsa-jcs-2022` lists. It finds the key that `proof.verificationMethod`
+  names in the issuer's DID document, requires that method to belong to the
+  list's `issuer`, and accepts relative method ids and `publicKeyJwk` or
+  `publicKeyMultibase` keys. It verifies a status list published by
+  builders.kya-os.org, signed by an independent implementation. Without
+  `verifyStatusList` the checker behaves as before. The option becomes
+  required in 2.0, and SPEC.md §6.10 states the requirement.
+- **`createKyaOsTransport` is exported from `@kya-os/mcp`,** next to
+  `createKyaOsMiddleware`, for servers on the low-level `Server` API, which
+  now connect through it. It was only on `@kya-os/mcp/middleware`. Its
+  `Transport` type declares the callbacks as methods, so an SDK 1 or SDK 2
+  transport is accepted, and the wrapper connects to either SDK's server,
+  without a cast.
+- **`serveInProcess(kyaos)` calls wrapped handlers outside an MCP server.**
+  `local.tool(name, handler)` answers as a server would, through a KYA-OS
+  transport, so the result carries its proof; `local.close()` closes the
+  transport. It replaces the examples' own helper.
+- **`pendingProofTtlMs`** on `KyaOsConfig` and `WithKyaOsOptions`: how long a
+  wrapper's result may wait to be sent before its proof is given up (default
+  300000, five minutes; at most 2147483647, about 24.8 days, the longest timer
+  a JavaScript runtime keeps). Memory stays bounded by the caps on waiting
+  proofs.
+
+### Changed
+
+- **Envelope-profile proofs are made at the transport, over the result as it
+  is sent.** On the 2026-07-28 revision, MCP SDK 2 adds `resultType:
+  'complete'` to a tool result after the handler returns it. An
+  envelope-profile proof made in the handler, by `proveOutcome`,
+  `wrapWithProof` or either gate, did not cover that member, so the client's
+  check of the result it received failed. Under the envelope profile these
+  paths now leave the proof to the `withKyaOs` transport, or one built with
+  `createKyaOsTransport`, which makes it in `send()`, after the SDK has
+  finished the result. The proof covers exactly the result the client
+  receives, on 2025-11-25 and on 2026-07-28, with SDK 1 or SDK 2. This
+  supersedes the 1.19.0 advice to set `resultType: 'complete'` on a result
+  before proving it under the envelope profile: that is no longer needed, and
+  a result that sets it is proved as sent.
+  - What a proof claims stays in the middleware. The result carries only a
+    private one-time id, redeemed only on a result that also carries the
+    middleware's stamp, and the session is read again when the proof is made,
+    which takes its audience from it. A result naming no waiting proof, or
+    one whose session is gone by then, goes out without a proof and with
+    `_meta.proofError`, as does an outcome whose proof fails at send.
+  - A waiting proof holds the request's hash, computed when the call was
+    recorded, never the arguments, so a waiting proof is small however large
+    they were, and later changes to the arguments cannot reach what is
+    signed. Arguments that cannot be hashed fail the proof in the handler
+    (`proofError`, `proof.rejected` with `PROOF_GENERATION_FAILED`).
+  - The claims, `_meta` keys and audit events are the ones the handler-side
+    proof had. For a result that is sent, the audit events are recorded in
+    the same order as before: an allowed call's `tool.call.started` in the
+    handler, then `proof.generated` and `tool.call.completed` at send.
+  - A result the SDK never sends (a cancelled call, or an SDK 1 result
+    replaced after an `outputSchema` check) is closed in the audit trail with
+    `proof.rejected` under the new code `PROOF_NOT_SENT`. An allowed call
+    then records `tool.call.failed` with the reason `RESULT_NOT_SENT`, never
+    `tool.call.completed`, since its client did not get the result. An
+    outcome's terminal events were recorded in the handler. This happens five
+    minutes after the handler returned; when the last KYA-OS transport for
+    the middleware closes; or, oldest first, when 10,000 proofs are waiting
+    or they hold about 16 MB of audit context.
+- **Body-profile proofs are made at the transport too, so neither profile
+  signs in the handler.** The MCP SDK also changes `content` after the
+  handler returns. SDK 2, on both revisions, appends a text item when
+  `structuredContent` is not an object and `content` has none. Both SDKs fill
+  in `content: []` when a handler leaves it out. A body-profile proof made in
+  the handler did not cover the appended item, so it failed verification, and
+  over a missing `content` it could not be made at all. The body profile now
+  takes the same path as the envelope profile above: the claims stay in the
+  middleware by request hash, and the transport makes the proof in `send()`
+  over the result as sent, with the same claims, `_meta` keys and audit
+  events, recorded in the same order. `_meta` keeps its place among the
+  result's members. Where the SDK does not reshape the result, the output is
+  byte-identical to 1.19.0. An outcome proof that fails now also says so in
+  `_meta.proofError`, as an allowed call's already did.
+- **A result is proved once, within the window.** A stamped result whose
+  pending proof is no longer waiting, because its window passed, it was
+  evicted, or it was already sent (a task result fetched again), goes out
+  with `proofError`, and the audit trail records `proof.rejected` with the
+  new code `PROOF_EXPIRED`, with the call's audit context when it is still
+  known. That record of closed proofs is bounded too: 10,000 entries and
+  about 4 MB, oldest first, holding no context over 16 KB.
+- **`createKyaOsTransport`'s `exclude` adds to the protocol tools.** The
+  third argument replaced the default `["_kyaos", "_kyaos_handshake"]`, so a
+  caller passing its own list had the protocol tools' results proved. It now
+  adds to them, as `excludeTools` does in `withKyaOs`; the protocol tools
+  are always excluded.
+
+### Security
+
+- **SDK 2's per-tool OAuth scope challenges were bypassed under `withKyaOs`
+  in earlier versions.** SDK 2's `McpServer.connect()` installs
+  the `scopeChallenge` enforcement of `registerTool` only on a transport
+  that has `setScopeChallengeResolver`, and the KYA-OS transport did not
+  pass that member through. A tool registered with, for example,
+  `scopeChallenge: requireScopes('payments:write')` therefore ran, and was
+  even proved, for a token without that scope. The caller should have
+  received a 403. This affected 1.19.0 and earlier:
+  - `withKyaOs` with a server's own `WebStandardStreamableHTTPServerTransport`;
+  - `createMcpHandler` serving a client that negotiates 2025-11-25.
+
+  At 2026-07-28, `createMcpHandler` enforces the challenge at its entry, before
+  the transport. The transport now passes the resolver through, and every
+  other transport member either SDK feature-detects or reads is passed
+  through too.
+- **The private members could leave in a message that is not a result, and
+  a copied stamp and id could make the transport sign chosen content.** The
+  transport removed the lifecycle stamp and pending-proof id only from
+  `result`. A tool that logged a wrapped result in a notification therefore
+  sent both to the client. A tool that relays caller-controlled `_meta` into
+  its own result could then redeem them, and the client got a server-signed
+  proof over content of its choosing, verifying as the wrapped call's
+  response. With envelope-profile proofs at the transport this was possible
+  before this release; with the body profile there too, in this release
+  before the fix. Now:
+  - every outgoing message is cleaned at any depth: its `params`,
+    `result` and `error.data`;
+  - a waiting proof whose id is found anywhere other than its own result is
+    closed, so nothing can redeem it;
+  - on the answer to a `tools/call` the transport tracked, a pending proof
+    left for a different tool is not redeemed. The answer goes out unproven,
+    and the audit trail records `proof.rejected` with the new code
+    `PROOF_TOOL_MISMATCH`.
+
+### Fixed
+
+- **The proof wrappers no longer change the result a handler returns.**
+  `wrapWithProof` set its `_meta` members (the pending-proof id, the
+  lifecycle stamp, `proofError`, the audit marker) on the handler's own
+  object, and its audit-degraded path set `isError: true` on it. A handler
+  that returned one object from every call, a module-level constant or a
+  cached result, found those members on it, and a later call could go out
+  with an earlier call's `isError` and audit marker; a frozen result made the
+  wrapper throw. Every member now goes on a shallow copy of the result with a
+  new `_meta`, in `wrapWithProof` and in the outcome path behind the gates
+  and `proveOutcome`, and the handler's object and its `_meta` are never
+  changed. What the client receives is otherwise the same. Closes #249.
+
+- **The KYA-OS transport passes the SDK's request context through.** It
+  dropped the second argument of `onmessage` and of `send`, and did not
+  expose the inner transport's `sessionId`, `setProtocolVersion`,
+  `setSupportedProtocolVersions` or `hasPerRequestStream`. Under `withKyaOs`,
+  tools lost the request's `sessionId`, `authInfo` and `requestInfo` (SDK 1)
+  and `ctx.http.authInfo` (SDK 2, both revisions); SDK 1 task stores stopped
+  separating tasks by session; and notifications a tool sent during a call
+  lost their `relatedRequestId`, so on Streamable HTTP they missed the
+  request's stream. All of these now pass through unchanged. Closes #248.
+- **The proof's scope is the call's, as the wrapper received it.**
+  `wrapWithProof` read `context.scopeId` and the audit context after the
+  handler ran, so a handler could change the scope a proof claims by changing
+  the context object it was handed. They are now read before the handler
+  runs.
+- **Private members never reach the wire from a nested result.** A wrapped
+  result a handler placed inside its own result, in `structuredContent` for
+  example, carried the lifecycle stamp and the pending-proof id to the
+  client. They are now removed at any depth: the walk is iterative, with no
+  depth limit. A wrapped result serialized into a string, a text item for
+  example, cannot be cleaned that way. Such a result is sent without a
+  proof and with `proofError`, recorded as `proof.rejected` with the new
+  code `PRIVATE_MEMBER_IN_RESULT`. Every waiting proof whose id appears in
+  that string is closed, so it cannot be redeemed.
+
+## [1.19.0] - 2026-10-09
+
+### Added
+
+- **`proveOutcome` proves the authorization outcomes application code
+  decides.** A server that enforces OAuth scopes in its tool handlers
+  returns its own challenges and denials as tool results, and the
+  `withKyaOs` transport sent such an error result unproven. The middleware
+  now has `proveOutcome({ toolName, args, outcome, reason, result,
+  sessionId? })`, which returns a copy of `result` carrying the proof the
+  gates attach to their outcomes: the same claims, the same `_meta` keys,
+  the configured response-proof profile and the same audit events. It runs
+  the gates' own code, and the transport passes its result through as
+  proven. A `needs_authorization` proof binds the result and a denial or
+  step-up proof binds none, as SPEC.md §7.4 has it. The `_kyaos*` control
+  arguments are left out of the signed request, `_meta` members only the
+  middleware may set are dropped, and no session needs to be opened. Under
+  the envelope profile, set `resultType: 'complete'` on the result first: on
+  the 2026-07-28 revision the MCP SDK adds it after the handler returns,
+  outside a proof made there. It is
+  optional on `KyaOsMiddleware`, as `withPolicyGate` is, so structural
+  implementers still type-check; the new `KyaOsOutcomeProver` role requires
+  it. New types: `KyaOsOutcomeProofRequest`, `KyaOsAuthorizationOutcome`,
+  `KyaOsToolResult`.
+- **`formatChallenge` may return the whole challenge result.** Besides the
+  content array, the delegation gate's hook may return `{ content,
+  structuredContent?, isError?, _meta? }` (`KyaOsChallengeResult`; the hook
+  type is `KyaOsChallengeFormatter`). The gate sets all of it before it
+  signs the challenge, so the envelope profile covers `isError` and
+  `structuredContent`; the body profile still covers `content` only.
+  `_meta` members the middleware owns are dropped from what the hook
+  returns. The array form and the default challenge are unchanged; the
+  default challenge still carries no `isError`, unlike the policy gate's
+  step-up.
+- **`toMcpToolCallback` registers a wrapped handler with `registerTool`
+  without a cast.** Passed straight to `McpServer.registerTool`, a
+  `KyaOsToolHandler` needed `as never`, and the SDK's request context then
+  arrived as the KYA-OS session id, so `wrapWithProof` found no session and
+  sent the result unproven. The adapter passes the arguments alone. Types:
+  `McpToolCallback`, `McpToolCallbackResult`.
+
+### Changed
+
+- **A `formatChallenge` hook that returns neither form gets the default
+  challenge**, as a throwing hook does. Before, the value was emitted as
+  `content`, which `McpServer` then rejected as an invalid result.
+- **`wrapWithProof` keeps an outcome proof it is handed.** A result
+  produced by the outcome-proof path, recognized by identity, is returned
+  as it is. Before, a challenge that was not an error result was signed
+  again there as an allowed call. No gate composition in this repository
+  reached that path.
+
+### Fixed
+
+- **An allow result the session fallback cannot attribute says so.** A
+  call that threads no session, which is every call on the `withKyaOs`
+  transport path, is proved under the single established session. With
+  more than one session live the middleware refuses to pick one and the
+  result went out unproven, with only a log line; opening a session in the
+  middleware's `SessionManager` from application code did this to every
+  later allow result. Such a result now carries `_meta.proofError`, the
+  marker a failed proof generation already sets. `isError`, the content and
+  the audit events are unchanged, and a server with no session at all
+  emits what it did before.
+- **Three DID-document readers accept a key published as
+  `publicKeyMultibase`.** `ProofVerifier.fetchPublicKeyFromDID`, the Entity
+  Card `didKeyedJwks` projection, and the conformance adapter's DID-resolution
+  check read only `publicKeyJwk`. A verification method that published its
+  Ed25519 key as `publicKeyMultibase`, the material property of
+  `Ed25519VerificationKey2020` and the form did:cheqd documents use, failed
+  with `PUBLIC_KEY_NOT_FOUND`, projected no key, or failed the check. They now
+  read the key through `verificationMethodJwk`, as the credential verifiers
+  already do: a `publicKeyJwk` is used unchanged, otherwise the key is taken
+  from `publicKeyMultibase` or `publicKeyBase58`, and anything that is not a
+  32-byte Ed25519 key is still refused. The `PUBLIC_KEY_NOT_FOUND` message from
+  `fetchPublicKeyFromDID` now names all three properties. The did:key resolver's
+  output is unchanged.
+- **Conformance suite 1.2.0: the status-list vectors' list verifies, and a
+  list altered after signing must be rejected.** The StatusList2021Credential
+  in `status-list.json` carried a proof that did not verify, and the reference
+  adapter read its bits without checking it. The suite therefore passed an
+  implementation that never checked a list's proof and failed one that did.
+  The list is re-signed, the reference adapter verifies its proof on the
+  delegation credentials' path before reading a bit, and a new negative
+  vector, `status-list/tampered-list`, clears the revoked bit after signing.
+  SPEC.md §6.6 and CONFORMANCE.md L3.11 state the check. The other eight
+  vector files change only their `version`, the suite has 49 vectors, and the
+  library is unchanged.
+
+### Documentation
+
+- **The README says what a response proof does not cover.** `_meta` is
+  outside every response proof (SPEC.md §7.6), so a server should repeat
+  security-relevant hints it carries there, such as an OAuth
+  `resource_metadata`, `scope` or `error`, in `content` or
+  `structuredContent`. The new section on proving application outcomes says
+  so, and says which profile covers which members.
+- **SPEC.md §6.2 states how a base-profile credential is signed.** Its
+  example labels the proof `Ed25519Signature2020`, and CONFORMANCE.md L3.1
+  asked for "Ed25519Signature2020 or equivalent", but the profile has never
+  used the W3C suite of that name. §6.2 now specifies the construction the
+  reference implementation and the vectors use: Ed25519 over the JCS
+  canonicalization of the credential without `proof`, `proofValue` as
+  unpadded base64url, the key found by `proof.verificationMethod`, and the
+  proof options outside the signature. L3.1 and L3.5 point to it. A new
+  conformance test checks the vectors' delegation credentials against that
+  text with `node:crypto` rather than the library's verifier. Moving to a
+  standard cryptosuite stays open in #184.
+
+## [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

package/CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 **Compliance levels for KYA-OS implementations**
 
-Version: 1.1.0
+Version: 1.2.0
 Status: Stable
 
 ---
@@ -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
@@ -225,7 +231,7 @@ Implementation MUST:
 - Include `issuer` as DID string or object with `id`
 - Include `issuanceDate` in ISO 8601 format
 - Include `credentialSubject` with delegation details
-- Include `proof` with Ed25519Signature2020 or equivalent
+- Include `proof` as SPEC.md §6.2 specifies: an Ed25519 signature over the JCS canonicalization of the credential without `proof`, in `proofValue` as unpadded base64url. This is not the W3C `Ed25519Signature2020` suite, despite the `proof.type` value ([#184](https://github.com/decentralized-identity/kya-os-mcp/issues/184))
 
 #### L3.5 — VC Verification
 
@@ -236,12 +242,13 @@ Implementation MUST validate:
 - `issuanceDate` is present and in the past
 - `expirationDate` (if present) is in the future
 - `credentialSubject.delegation` has required fields
-- `proof` is present
+- `proof` is present and verifies as SPEC.md §6.2 specifies
 
 #### L3.11 — StatusList2021 Checking
 
 Implementation MUST:
 - Fetch StatusList2021 credential from `credentialStatus.statusListCredential`
+- Verify the list's `proof` as SPEC.md §6.2 specifies, and reject the credential when it does not verify
 - Decompress and decode the bitstring
 - Check bit at `statusListIndex`
 - Return revoked status if bit is 1
@@ -424,7 +431,7 @@ so it is reproducible against any implementation without re-signing.
 |------|----------|----------|----------|
 | `vectors/signed-proof.json` | Detached proof verification | valid signature + in-window ts; envelope content binding (profile `org.kya-os/response-proof.envelope`) | tampered signature, tampered meta, wrong key, timestamp skew exceeded; tampered `structuredContent` under envelope coverage, `prf` stripped (downgrade), unknown profile |
 | `vectors/delegation-chain.json` | Delegation chain verification | single-hop, two-hop attenuated | broken issuer↔subject linkage, scope widening, tampered signature, audience mismatch |
-| `vectors/status-list.json` | StatusList2021 revocation | active (bit unset) | revoked (bit set) |
+| `vectors/status-list.json` | StatusList2021 revocation | active (bit unset) | revoked (bit set), list altered after signing |
 | `vectors/did-key-resolution.json` | did:key resolution | valid Ed25519 | malformed multibase, wrong method |
 | `vectors/did-web-resolution.json` | did:web resolution | well-formed id-matched document | document id mismatch, not found |
 | `vectors/card-proof.json` | `org.kya-os/proof.v1` holder-of-key proof | valid signed proof, in-window, audience-bound | tampered body, tampered signature, wrong audience, expired, kid⇄did forgery |
@@ -452,6 +459,11 @@ This vector leaves the JWS byte-identical to `valid-basic` and alters only the m
 A conformant verifier MUST reconcile `meta` against the decoded JWS payload and reject on any mismatch.
 Signature validity alone does not pass this vector: it is the `requestHash` counterpart of the `responseHash` recompute rule in L2.11.
 
+**On `status-list/tampered-list` (suite ≥ 1.2.0).**
+This vector carries the revoked credential and its signed list with the revoked bit cleared and the list's proof left as signed.
+A verifier that reads the bits without verifying the list's proof reports the credential active and passes a vector it must reject (L3.11).
+Suites before 1.2.0 shipped a list whose proof did not verify, so an implementation that checked it failed `status-list/active-credential`.
+
 ### Running the reference implementation
 
 ```bash

package/README.md

@@ -54,6 +54,24 @@ npm install @kya-os/mcp
 
 ---
 
+## Upgrading to 1.20: proofs need a KYA-OS transport
+
+> **Breaking for servers without a KYA-OS transport.** From 1.20, every response proof (under the default body profile as under the envelope profile) is made where the KYA-OS transport sends the result, after the MCP SDK has finished it. While no KYA-OS transport is open for the middleware, `wrapWithProof`, `wrapWithDelegation`, `withPolicyGate` and `proveOutcome` throw before they run anything.
+
+| Your setup | What to do |
+|---|---|
+| `withKyaOs(server, …)` before `server.connect()` | Nothing. |
+| Low-level `Server` with `createKyaOsMiddleware` | `await server.connect(createKyaOsTransport(transport, kyaos))`. It proves every tool's result, unwrapped tools included (unproven on 1.19.0); its third argument adds tools to leave unproven. |
+| A script or test that calls a wrapped handler directly | `const local = serveInProcess(kyaos); const call = local.tool('name', handler); await call(args); await local.close();` |
+| `withKyaOs` with `proofAllTools: false` | Leave it on; list tools to leave unproven in `excludeTools`. |
+| `withKyaOs` after `connect()` | Call it before `connect()`. |
+| Reading the proof inside the handler | The transport adds it when the result is sent; read it from what the client receives. |
+| MCP task results fetched later | A result is proved the first time the same middleware sends it, within `pendingProofTtlMs` (default five minutes, at most 2147483647 ms); raise it for later fetches. |
+
+See the [changelog](./CHANGELOG.md) for the details.
+
+---
+
 ## Migrate any MCP server in 2 lines
 
 **Before**, a standard MCP server with no identity or proofs:
@@ -106,6 +124,45 @@ When an agent calls `checkout` without a delegation credential, it gets back a `
 
 > Try it yourself: [examples/consent-basic](./examples/consent-basic/) walks through the full consent flow end-to-end.
 
+### Prove the outcomes your own code decides
+
+A server that enforces authorization itself, checking OAuth scopes in the tool handler for example, returns its own challenges and denials as tool results. `withKyaOs` proves the results it can attribute, but it sends an error result its own gates did not produce as the handler returned it, without a proof. `proveOutcome` gives that result the proof the gates attach to theirs, with the same claims, `_meta` keys and audit events:
+
+```typescript
+import { toMcpToolCallback } from '@kya-os/mcp';
+
+server.registerTool('get_report', { inputSchema }, toMcpToolCallback(async (args) => {
+  if (!grantedScopes.includes('reports:read')) {
+    return kyaos.proveOutcome!({
+      toolName: 'get_report',
+      args,
+      outcome: 'needs_authorization', // or 'step_up_required', 'denied'
+      reason: 'insufficient_scope',
+      result: {
+        content: [{ type: 'text', text: 'Sign in to see this report.' }],
+        structuredContent: { error: 'insufficient_scope', scope: 'reports:read', resource_metadata },
+        isError: true,
+        _meta: { 'mcp/www_authenticate': [`Bearer resource_metadata="${resource_metadata}"`] },
+      },
+    });
+  }
+  return { content: [{ type: 'text', text: report }] };
+}));
+```
+
+- **Build the whole result before proving it**, and return what `proveOutcome` gives you from the handler.
+- **Every proof is made where the result is sent.** The `withKyaOs` transport makes it when it sends the result, after the MCP SDK has finished the result, so it covers what the client receives. Under the default body profile it covers `content`, including a text item SDK 2 appends when `structuredContent` is not an object, and the `content: []` either SDK fills in when a handler leaves it out. Under the envelope response-proof profile (`responseProofProfile: RESPONSE_PROOF_PROFILE_ENVELOPE`) it covers every member except `_meta`, including the `resultType` that SDK 2 adds on the 2026-07-28 revision. This applies to `proveOutcome`, `wrapWithProof` and both gates.
+- **Every wrapper needs an open KYA-OS transport.** `withKyaOs` wraps the transport you connect, unless `proofAllTools` is `false`; for a transport you connect yourself (the low-level `Server` API with `createKyaOsMiddleware`), wrap it with `createKyaOsTransport`, exported from `@kya-os/mcp`. Once a KYA-OS transport has been created for a middleware, every wrapper result must go out through one. While none is open (none was started, or all have closed), the wrappers and `proveOutcome` throw before they run anything, instead of sending a result they cannot prove.
+- **`_meta` is outside every response proof** (SPEC §7.6). Repeat anything a client must be able to trust, such as `resource_metadata`, `scope` and `error`, in `content` or `structuredContent`.
+- A `needs_authorization` proof binds the result; a denial or step-up proof binds none (SPEC §7.4).
+- The result carries private members until the transport sends it, and the transport removes them. One of them is a one-time id: what the proof claims (by request hash) and its session stay in the middleware, and the transport redeems the id once. A result the SDK never sends, such as a cancelled call's, is closed in the audit trail with `proof.rejected` (`PROOF_NOT_SENT`) and, for an allowed call, `tool.call.failed` (`RESULT_NOT_SENT`).
+- **A result is proved once, by the middleware that sends it, within `pendingProofTtlMs`** (default five minutes, at most 2147483647 ms). A task result fetched again, or later than the window, goes out with `proofError`, recorded as `PROOF_EXPIRED`. What the proof claims lives in that middleware's memory, so only the process that recorded the call can make the proof; [#250](https://github.com/decentralized-identity/kya-os-mcp/issues/250) proposes sealed claims so that any process holding the identity could.
+- **Do not serialize a wrapped result into a string.** Its private members cannot be removed from inside the string, so the result that carries it goes out unproven (`PRIVATE_MEMBER_IN_RESULT`), and the serialized result's own proof is voided. Nest the result as an object instead: private members are removed at any depth from every outgoing message (results, notification and request `params`, and error `data`), and a wrapped result that goes out anywhere but as its own answer has its proof closed. On the answer to a `tools/call`, only a proof left for that tool is made.
+- **Connect every server that shares a middleware through a KYA-OS transport.** The refusal checks only that some KYA-OS transport is open for the middleware. A second server sharing it over a plain transport therefore runs its wrappers, and its results leave with the lifecycle stamp and the pending-proof id in `_meta` and no proof. Those proofs are later closed as `PROOF_NOT_SENT`, although the results were sent.
+- Leave `kyaos.sessionManager` alone. A second live session makes the fallback session ambiguous, and allow results then go out unproven, marked with `_meta.proofError`.
+- `wrapWithDelegation`'s `formatChallenge` can return the same `{ content, structuredContent, isError, _meta }` shape for the library's own challenge, and all of it is set before signing.
+- `toMcpToolCallback` adapts any wrapped handler to `registerTool` without a cast. The SDK's request context never reaches the handler as its session id.
+
 ---
 
 ## Turn proofs into a verifiable audit trail
@@ -217,6 +274,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)