@kya-os/mcp 1.14.2 → 1.16.0

package/CHANGELOG.md

@@ -7,6 +7,101 @@ Versioning: https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-09-19
+
+### Added
+
+- **`path-prefix` CRISP scope matcher.** `prefix` is character-level and right
+  for scope identifiers, but applied to a resource path it lets a grant for
+  `notes` authorize `notesx/secret.md`. `path-prefix` matches the path itself
+  or anything beneath it as a `/`-separated path, with an optional trailing `/`
+  or `/*`; an empty base grants nothing. Added to `matchScope`, the `CrispScope`
+  type, `schemas/delegation-credential.json`, and SPEC.md §6.3/§6.4.1.
+
+### Fixed
+
+- **`DelegationVCVerificationResult.stage` names the failing check.** A failed
+  verdict from `verifyDelegationCredential` / `verifyDelegationJwt` reported
+  `stage: "complete"` once both the signature and status checks had run, leaving
+  only the `checks` flags to say which one failed. It now reports `"signature"` or
+  `"status"`; `"complete"` accompanies `valid: true` only.
+- The revocation reason names the status method on the credential
+  (`Credential revoked via <credentialStatus.type> (…)`) instead of always
+  saying `StatusList2021`.
+- `schemas/well-known-mcpi.json`: `version` accepts the three-part protocol
+  version the reference implementation advertises (`1.0.0`); `endpoints.handshake`
+  is no longer required — it belongs to the legacy 1.x session profile
+  (SPEC-MCP-EXTENSION.md §4).
+
+### Documentation
+
+- SPEC.md §10: the discovery example now validates against the schema
+  (`serverDid`, not `did`; schema capability names; `statusListCredential`;
+  camelCase advisory fields) and says when `endpoints.handshake` applies.
+- CONFORMANCE.md: names the three ladders (Core L1–L3, Card L1–L3, AAP-0–4) and
+  asks claims to say which; the Entity Card section uses the terminal `_meta`
+  key names (`org.kya-os/response-proof`, `org.kya-os/request-proof` carrying
+  `prf: "org.kya-os/proof.v1"`).
+
+## [1.15.0] - 2026-08-25
+
+### Added
+
+- **Response-proof `envelope` profile** (`org.kya-os/response-proof.envelope`).
+  The `body` profile binds `responseHash` over the response body only, leaving
+  result members such as `structuredContent`, `isError` and `resultType`
+  unauthenticated - an in-path intermediary could rewrite them under a still
+  valid proof. The envelope profile covers the ENTIRE result object with the
+  top-level `_meta` member removed, mirroring the request side's
+  `{method, params minus _meta}` rule, so every present and future result
+  member is authenticated while `_meta` stays intermediary-mutable (which is
+  what keeps attach-after-sign sound). The profile is discriminated by a `prf`
+  claim COVERED by the JWS signature, so a proof cannot be silently downgraded
+  to body semantics, and `validateDetachedProof` rejects unknown `prf` values
+  fail-closed. Verification always derives the profile from the proof's own
+  claim, never from configuration, so one verifier accepts both.
+- **Conformance vector-set immutability.** `conformance/SUITE-MANIFEST.json`
+  pins the vector set by hash, `scripts/suite-hash.mjs` computes and checks it,
+  and CI enforces it as its own line - a published vector set can no longer be
+  edited in place without the check failing. Suite is at 1.1.0.
+- **`DEPRECATIONS.md`** - an internal ledger of deferred breaking changes.
+
+### Fixed
+
+- **Sessionless request proofs now bind.** `generateRequestProof` defaulted
+  `meta.sessionId` to `''` when the caller omitted it, but `sessionId` is a
+  required non-empty string in the proof meta schema, so the proof failed
+  validation as `INVALID_PROOF_STRUCTURE` and `assertHolderBinding` returned
+  `unbound` for the LEGITIMATE holder - indistinguishable from the thief the
+  gate exists to catch. `sessionId` is documented as optional and a request
+  proof routinely precedes any handshake on a stateless core, so this was the
+  normal path rather than an edge case. It failed closed (nothing was wrongly
+  admitted), but phase-1 holder binding was unusable without a `sessionId` the
+  signature never said was mandatory. A per-proof id is now minted when none is
+  supplied; verification, the schema and the conformance vectors are unchanged.
+- The `prf` claim is derived only from the profile option, and the proof schema
+  id is bumped accordingly.
+- A challenge proof that the degraded-audit `isError` flip would have broken is
+  now stripped rather than emitted.
+- `suite-hash` hashes the committed blob bytes rather than the working tree, so
+  a dirty checkout cannot produce a passing hash.
+
+### Changed
+
+- **Response-proof profiles are named by mechanism, not sequence**:
+  `org.kya-os/response-proof.v2` -> `.envelope`, `.v1` -> `.body`, and
+  `RESPONSE_PROOF_PROFILE_V2`/`_V1` -> `_ENVELOPE`/`_BODY`. The sequence
+  framing was wrong on its own terms - original proofs carry no profile
+  identifier at all, so the first wire identifier would have debuted as `.v2`
+  naming a v1 that never existed. **No published API changes**: these
+  identifiers and constants are new in this release and never shipped in
+  1.14.2, so nothing downstream can be pinned to the old names. The
+  request-proof profile keeps its shipped `org.kya-os/proof.v1` name.
+- Conformance vectors use semantic names and a more robust signature-tamper
+  case.
+- Dependency bumps across the minor-and-patch group.
+- README restructures `did:cheqd` into a hierarchical Integrations section.
+
 ## [1.14.2] - 2026-08-19
 
 ### Fixed

package/CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 **Compliance levels for KYA-OS implementations**
 
-Version: 1.0.0
+Version: 1.1.0
 Status: Stable
 
 ---
@@ -11,6 +11,17 @@ Status: Stable
 
 This document defines three compliance levels for KYA-OS implementations. Each level builds on the previous, with increasing capability requirements. Implementations MUST pass all tests for a given level to claim conformance at that level.
 
+Three independent ladders live in this document, and two of them reuse the
+names L1–L3. A conformance claim MUST name its ladder:
+
+| Ladder | Levels | Measures |
+|--------|--------|----------|
+| Core (this section onward) | Core L1 / L2 / L3 | Crypto primitives, the legacy session-bound proof, W3C delegation credentials |
+| Entity Card (§ Entity Card Conformance) | Card L1 / L2 / L3 | The typed card and the stateless `org.kya-os/proof.v1` request proof |
+| Audit Assurance Profile (§ Audit Assurance Profile conformance) | AAP-0 … AAP-4 | Auditability mechanics an implementation can truthfully advertise |
+
+A bare "L2" is ambiguous; write "Core L2", "Card L2", or "AAP-2".
+
 ---
 
 ## Level 1 — Core Crypto
@@ -411,7 +422,7 @@ so it is reproducible against any implementation without re-signing.
 
 | File | Category | Positive | Negative |
 |------|----------|----------|----------|
-| `vectors/signed-proof.json` | Detached proof verification | valid signature + in-window ts | tampered signature, tampered meta, wrong key, timestamp skew exceeded |
+| `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/did-key-resolution.json` | did:key resolution | valid Ed25519 | malformed multibase, wrong method |
@@ -430,6 +441,11 @@ protocol, and `negotiation` exercises the MCP extension admission gate
 A `fail` vector passes the suite only when the implementation correctly **rejects**
 it. The runner exits non-zero on any mismatch.
 
+**On the envelope-profile vectors (`signed-proof/envelope-*`, `prf-stripped-downgrade`, `unknown-profile`; suite ≥ 1.1.0).**
+These exercise the `org.kya-os/response-proof.envelope` profile (SPEC.md §7.3): `responseHash` covers the full result envelope with the top-level `_meta` member removed, discriminated by a signature-covered `prf` claim.
+Their inputs carry an OPTIONAL `expected` member (`{ request, response }`) — the content the verifier "received" — which a conformant verifier re-hashes under the proof's own `prf` profile and reconciles against the bound hashes.
+Vectors without `expected` remain pure signature/skew checks.
+
 **On `signed-proof/tampered-meta`.**
 The proof's `meta` block mirrors the claims signed inside the JWS, but it is a convenience for consumers that read the proof without decoding the token, not an authoritative copy.
 This vector leaves the JWS byte-identical to `valid-basic` and alters only the mirrored `meta.requestHash`, so the JWS signature still verifies.
@@ -457,6 +473,16 @@ pnpm run conformance:generate
 
 Re-running mints fresh keys but preserves every positive/negative relationship by
 construction.
+Because fresh keys change the committed bytes, regenerated output MUST NOT be committed over an existing `suiteVersion` (see [Suite versioning and immutability](#suite-versioning-and-immutability)).
+
+### Suite versioning and immutability
+
+The committed vector set is immutable at a given `suiteVersion`: the vector bytes may only change together with a `suiteVersion` bump.
+`conformance/SUITE-MANIFEST.json` pins the current set (`suiteVersion`, `vectorSetHash`, `vectorCount`, per-file hashes) and is the anchor CI verifies against.
+The hash recipe: SHA-256 each vector file's raw committed bytes, sort the `[filename, hex]` pairs by filename, canonicalize the array with RFC 8785 (JCS), SHA-256 that, prefix with `sha256:`.
+CI enforces the invariant twice: a vitest guard (`conformance/__tests__/suite-immutability.test.ts`) and a dedicated step running `node conformance/suite-hash.mjs --check`.
+To change vectors intentionally, bump `suiteVersion` (including the in-file `version` fields), regenerate the manifest with `node conformance/suite-hash.mjs --json`, and keep `pinnedAt` current.
+The SIGNED public suite manifest published by the Conformance Attestation Program is a separate artifact built on this committed one.
 
 ### Running the harness against YOUR implementation
 
@@ -521,8 +547,9 @@ deployment satisfies its operational durability or independence claims.
 The Entity Card is a **distinct, newer layer** on top of the Level 1–3 ladder above:
 a typed, DID-anchored card plus a stateless, sender-constrained per-request proof.
 It is orthogonal to the legacy session-bound proof — the two coexist, each under
-its OWN distinct `_meta` key (`_meta['org.kya-os/proof']` for the legacy
-session-bound proof, `_meta['org.kya-os/proof.v1']` for the stateless card proof),
+its OWN distinct `_meta` key (`_meta["org.kya-os/response-proof"]` for the legacy
+session-bound proof, historically `org.kya-os/proof`; `_meta["org.kya-os/request-proof"]`
+for the stateless card proof, whose object carries `prf: "org.kya-os/proof.v1"`),
 and each verifier reads its own key and ignores the other. Its
 conformance vectors live in the SAME harness under two categories, wired to the two
 adapter methods `verifyCardProof` and `verifyEntityCard`.

package/README.md

@@ -265,182 +265,52 @@ flows, and sessions are shared across instances and survive restarts.
 
 ---
 
-## Optional did:cheqd and DID-Linked Resources
+## Integrations
 
-`did:cheqd` support is additive and opt-in. Existing `did:key` and `did:web`
-flows remain unchanged, and operators can keep `did:web` as their canonical
-identifier while linking to a cheqd DID over time.
+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.
 
-### Resolver configuration
+### Modules
+
+| Module | Adds | Docs |
+| --- | --- | --- |
+| **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) |
+
+Enabling a module is a small config change. cheqd, for example, is a resolver
+you register under `didResolvers`:
 
 ```typescript
-import { RuntimeFetchProvider, withKyaOs, NodeCryptoProvider } from '@kya-os/mcp';
 import { cheqdResolver } from '@kya-os/mcp/cheqd';
 
-const crypto = new NodeCryptoProvider();
-const fetchProvider = new RuntimeFetchProvider();
-const didResolvers = {
-  cheqd: cheqdResolver({ resolverUrl: 'https://resolver.cheqd.net' }),
-};
-
 await withKyaOs(server, {
   crypto,
   delegation: {
-    fetchProvider,
-    didResolvers,
-  },
-});
-```
-
-`did:cheqd` is resolved only when a resolver for the `cheqd` DID method is
-explicitly supplied. The core middleware and fetch provider use the generic
-`didResolvers` registry; cheqd-specific URL/cache/header options live in the
-`cheqdResolver()` factory from `@kya-os/mcp/cheqd`.
-`RuntimeFetchProvider` accepts the same registry when it is used directly by a
-standalone verifier or operator script.
-Unsupported methods, malformed DIDs, fetch failures, invalid JSON, malformed DID
-Documents, and DID id mismatches fail closed by returning `null`. The resolver
-accepts both raw DID Documents and Universal Resolver-style DID Resolution
-Results (`{ didDocument: ... }`).
-
-### Registrar writes
-
-Registrar writes are explicit operator/admin actions. The package exposes
-`CheqdDidRegistrarClient` for cheqd DID Registrar `/create`, `/update`, and
-`/{did}/create-resource` flows, using cheqd's client-managed-secret pattern:
-the registrar returns a serialized payload, your signer signs it, and the
-signature is submitted back. Private keys are not sent to the registrar.
-
-```typescript
-import {
-  CheqdDidRegistrarClient,
-  createLocalEd25519CheqdRegistrarSigner,
-} from '@kya-os/mcp/cheqd';
-import {
-  NodeCryptoProvider,
-} from '@kya-os/mcp';
-
-const crypto = new NodeCryptoProvider();
-const registrar = new CheqdDidRegistrarClient({
-  registrarUrl: 'https://did-registrar-staging.cheqd.net/1.0',
-  fetchProvider,
-  // Optional static or async auth headers for private registrar deployments.
-  // headers: async () => ({ Authorization: `Bearer ${token}` }),
-});
-
-const signer = createLocalEd25519CheqdRegistrarSigner({
-  cryptoProvider: crypto,
-  privateKey: process.env.CHEQD_DID_PRIVATE_KEY_BASE64!,
-  verificationMethodId: 'did:cheqd:testnet:...#key-1',
-  signatureEncoding: 'base64url',
-});
-```
-
-For mainnet, run or contract against your own fee-payer registrar deployment and
-provide the signer hook from your KMS/HSM boundary. The local Ed25519 helper is
-for simple controlled deployments and tests; it still signs locally and sends
-only signatures to the registrar.
-
-Runtime proof generation does not perform registrar writes. Create/update/DLR
-publishing should be triggered by an explicit operator workflow, deployment
-step, or admin tool.
-
-### DID linkage
-
-For `did:web` <-> `did:cheqd` binding, publish reciprocal `alsoKnownAs` values
-and verify both DID Documents with `verifyDidLinkage()`. `buildDidWebDocument`
-can include the `did:cheqd` reference on the `did:web` side, while
-`updateCheqdAlsoKnownAs()` updates the cheqd side through the registrar.
-
-```typescript
-import { verifyDidLinkage } from '@kya-os/mcp';
-import { updateCheqdAlsoKnownAs } from '@kya-os/mcp/cheqd';
-
-await updateCheqdAlsoKnownAs({
-  didWeb: 'did:web:agent.example.com',
-  didCheqd: 'did:cheqd:testnet:...',
-  resolver: cheqdResolver,
-  registrar,
-  signer,
-  verificationMethodId: 'did:cheqd:testnet:...#key-1',
-});
-
-const linkage = verifyDidLinkage({
-  primaryDid: 'did:web:agent.example.com',
-  secondaryDid: 'did:cheqd:testnet:...',
-  primaryDidDocument: didWebDocument,
-  secondaryDidDocument: didCheqdDocument,
-});
-```
-
-### DID-Linked Resource helpers
-
-DID-Linked Resource helpers are intended for durable manifests only. Supported
-artifact types are:
-
-- `CapabilityManifest`
-- `ConformanceManifest`
-- `AccessHashManifest`
-- `TrustConfigManifest`
-
-`prepareCheqdDlrResource()` validates the artifact, canonicalizes its `content`
-with JSON Canonicalization Scheme, computes or validates a `sha256:<64 hex>`
-content hash, and returns a registrar resource body. Updates are modeled as new
-resource versions under the same resource `name` and `type`; prior resources are
-not overwritten. Do not write high-volume tool calls, raw operational logs, or
-normal runtime proof events to cheqd; keep those in your normal audit/hash
-stores.
-
-```typescript
-import { prepareCheqdDlrResource } from '@kya-os/mcp/cheqd';
-
-const prepared = await prepareCheqdDlrResource({
-  type: 'TrustConfigManifest',
-  subjectDid: 'did:cheqd:testnet:...',
-  name: 'agent-trust-config',
-  resourceType: 'TrustConfigManifest',
-  version: '2026-06-01',
-  content: {
-    acceptedDidMethods: ['did:web', 'did:key', 'did:cheqd'],
-    requiredLinkage: { type: 'alsoKnownAs', bidirectional: true },
+    didResolvers: { cheqd: cheqdResolver({ resolverUrl: 'https://resolver.cheqd.net' }) },
   },
-}, crypto);
-
-await registrar.createResource({
-  did: 'did:cheqd:testnet:...',
-  resource: prepared.resource,
-  signer,
-  verificationMethodId: 'did:cheqd:testnet:...#key-1',
 });
 ```
 
-See [examples/cheqd-dlr](./examples/cheqd-dlr/) for a complete operator flow.
-
-### Live cheqd registrar E2E tests
-
-Live registrar coverage is opt-in because it performs real writes to cheqd
-testnet. The default endpoint is the cheqd-published testnet staging registrar;
-override it only with another testnet registrar. The live test creates a testnet
-DID, adds a realistic `did:web` alias via `alsoKnownAs`, then publishes one
-resource for each supported KYA DLR artifact type.
-
-```powershell
-$env:KYA_OS_CHEQD_E2E = '1'
-npm run test:e2e:cheqd:testnet
-Remove-Item Env:\KYA_OS_CHEQD_E2E
-```
+Its full reference (registrar writes, `did:web` <-> `did:cheqd` linkage,
+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.
 
-Optional environment variables:
+### Adapter seams (bring your own)
 
-| Variable | Default |
-| --- | --- |
-| `KYA_OS_CHEQD_TESTNET_REGISTRAR_URL` | `https://did-registrar-staging.cheqd.net/1.0` |
-| `KYA_OS_CHEQD_TESTNET_RESOLVER_URL` | `https://resolver.cheqd.net` |
-| `KYA_OS_CHEQD_E2E_TIMEOUT_MS` | `180000` |
+Every external dependency is a typed interface with an in-memory default, so you
+can swap in your own backend without touching the middleware.
 
-Out of scope for this package: replacing `did:web` as the canonical identity,
-writing runtime proof events on-chain, KYC/KYB issuance, reputation VC snapshot
-publication, status-list backend hosting, and external registry changes.
+| 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
 

package/SPEC.md

@@ -548,13 +548,26 @@ interface DelegationConstraints {
     };
     scopes: Array<{
       resource: string;
-      matcher: 'exact' | 'prefix' | 'regex';
+      matcher: 'exact' | 'prefix' | 'path-prefix' | 'regex';
       constraints?: Record<string, unknown>;
     }>;
   };
 }
 ```
 
+#### CRISP scope matchers
+
+| `matcher` | Semantics | Intended value |
+|-----------|-----------|----------------|
+| `exact` | Strict string equality. | Any. Preferred for sensitive resources (§11.4). |
+| `prefix` | Character-level: the value starts with the pattern; one trailing `*` is optional sugar. An empty base grants nothing. | Scope **identifiers** (`repo:` matches `repo:write`). |
+| `path-prefix` | Path-level: the value equals the pattern or lies beneath it as a `/`-separated path. `notes` matches `notes` and `notes/2026/plan.md`, never `notesx/secret.md`. A trailing `/` or `/*` is optional sugar; an empty base grants nothing. | Resource **paths** (files, folders, URL paths). |
+| `regex` | Anchored full-string match; invalid patterns never match. Verifiers bound pattern and value length and reject nested-quantifier patterns. | Any; issuers accepting patterns from untrusted parties SHOULD prefer the other three. |
+
+Verifiers MUST treat `prefix` and `path-prefix` as distinct: applying `prefix`
+to a resource path lets a grant for `notes` authorize `notesx/secret.md`, which
+is a boundary escape, not a match.
+
 ### 6.4 Delegation Graph
 
 Delegations form a directed acyclic graph (DAG):
@@ -582,7 +595,7 @@ Delegations form a directed acyclic graph (DAG):
 
 A `DelegationCredential` may authorize multiple resources, either via a list
 of explicit scope strings (`constraints.scopes[]`) or via pattern matchers
-(`constraints.crisp.scopes[].matcher`: `'exact' | 'prefix' | 'regex'`). When
+(`constraints.crisp.scopes[].matcher`: `'exact' | 'prefix' | 'path-prefix' | 'regex'`). When
 the credential is used to invoke a specific tool or resource, the invocation
 MUST designate the specific scope being exercised, and verifiers MUST confirm
 that the designated scope is a member of (or matches a pattern in) the
@@ -878,6 +891,11 @@ interface ProofMeta {
   outcome?: 'allowed' | 'denied' | 'step_up_required' | 'needs_authorization';
                          // Authorization outcome; ABSENT ⇒ implicitly 'allowed' (success)
   reason?: string;       // Human-readable reason on a non-'allowed' outcome
+  prf?: 'org.kya-os/response-proof.envelope';
+                         // Response-proof profile discriminator, COVERED by the
+                         // JWS signature. ABSENT ⇒ the body profile (body-only
+                         // responseHash, the original wire shape). Verifiers
+                         // MUST reject any other value (fail-closed; §7.3).
 }
 ```
 
@@ -895,7 +913,16 @@ Request canonicalization includes:
 }
 ```
 
-Response canonicalization is the `data` field only (excludes `_meta`).
+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`).
+  Under MCP carriage, `data` is the result's `content` array; result members outside it are NOT covered.
+- **envelope** (`prf: "org.kya-os/response-proof.envelope"`): the ENTIRE result object with the top-level `_meta` member removed, mirroring the request side's `{method, params minus _meta}` rule.
+  This authenticates result members such as `structuredContent`, `isError`, and `resultType` that the body profile leaves uncovered, while `_meta` stays intermediary-mutable — which is what lets the proof itself be attached there after signing.
+
+A verifier derives the profile from the received proof's own `prf` claim, never from configuration, and MUST reject an unrecognized `prf` outright.
+Because `prf` is covered by the signature, stripping it from an envelope-profile proof breaks verification — a downgrade to body-only semantics is a hard failure, not a silent fallback.
+Producers default to the body profile (wire compatibility with existing verifiers); the envelope profile is an explicit opt-in (`responseProofProfile` in the middleware configuration).
 
 ### 7.4 JWS Compact Serialization
 
@@ -927,6 +954,9 @@ BASE64URL(header) . BASE64URL(payload) . BASE64URL(signature)
 }
 ```
 
+An envelope-profile proof (§7.3) additionally carries its `prf` claim in this payload — profile selection is signed, never advisory.
+Every optional `ProofMeta` member present on the proof (`scopeId`, `delegationRef`, `clientDid`, `outcome`, `reason`, `prf`) appears in the payload; the mirrored `meta` block and the decoded payload MUST reconcile exactly.
+
 **Denial** and **step-up** proofs have no response body, so `responseHash` is
 omitted and `outcome` (plus an optional `reason`) is included instead. Keys
 remain RFC 8785-sorted:
@@ -1040,8 +1070,9 @@ verifier treats `_meta` keys that are *not* KYA-OS's proof key:
   `_meta` keys to the application layer rather than discarding them.
 
 Under no policy does a verifier include any non-proof `_meta` key in a hash or
-signature computation. The signature covers the `data`/response body only; it
-never covers `_meta` (§7.3).
+signature computation. The signature covers the profile-selected response
+material only — the `data` body under the body profile, the result envelope minus
+its top-level `_meta` under the envelope profile — and never covers `_meta` itself (§7.3).
 
 > **Note.** The proof object's shape is normatively defined by
 > `schemas/detached-proof.json` (`$schema: draft/2020-12`). The *placement* key
@@ -1275,27 +1306,35 @@ sufficient on its own: the resulting DelegationCredential is still verified per
 
 ## 10. Well-Known Endpoint
 
-KYA-OS servers SHOULD expose `/.well-known/mcp`:
+KYA-OS servers SHOULD expose `/.well-known/mcp`. The normative shape is
+`schemas/well-known-mcpi.json`; the example below validates against it:
 
 ```json
 {
-  "did": "did:web:mcp-server.example.com",
   "version": "1.0.0",
+  "serverDid": "did:web:mcp-server.example.com",
   "capabilities": {
+    "proofs": true,
     "delegation": true,
-    "proof": true,
-    "revocation": true
+    "statusList": true,
+    "crisp": true
   },
-  "supported_did_methods": ["did:key", "did:web", "did:cheqd"],
-  "proof_algorithms": ["EdDSA"],
   "clockSkewSeconds": 120,
   "endpoints": {
-    "handshake": "/_kya-os/handshake",
-    "status_list": "/.well-known/status/1"
-  }
+    "tools": "/mcp"
+  },
+  "statusListCredential": "https://mcp-server.example.com/.well-known/status/1",
+  "supportedDidMethods": ["did:key", "did:web", "did:cheqd"],
+  "proofAlgorithms": ["EdDSA"]
 }
 ```
 
+`serverDid` is the server's own DID, the audience a client binds proofs to.
+`supportedDidMethods` and `proofAlgorithms` are advisory additional properties
+(the schema permits them; it does not require them). Servers running the legacy
+1.x session profile additionally list `endpoints.handshake`
+(SPEC-MCP-EXTENSION.md §4); servers on the stateless card-proof profile omit it.
+
 Servers SHOULD list `did:cheqd` only when cheqd resolution has been explicitly
 configured for that deployment.
 

package/dist/delegation/holder-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"holder-binding.d.ts","sourceRoot":"","sources":["../../src/delegation/holder-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,WAAW,CAMb;AAED,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sEAAsE;IACtE,MAAM,EAAE,cAAc,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAgBxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,KAAK,EAAE,aAAa,CAAC;IACrB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,uFAAuF;IACvF,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACxC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CA4E9B"}
+{"version":3,"file":"holder-binding.d.ts","sourceRoot":"","sources":["../../src/delegation/holder-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,WAAW,CAMb;AAED,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sEAAsE;IACtE,MAAM,EAAE,cAAc,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAuBxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,KAAK,EAAE,aAAa,CAAC;IACrB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,uFAAuF;IACvF,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACxC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CA4E9B"}

package/dist/delegation/holder-binding.js

@@ -69,8 +69,15 @@ export async function generateRequestProof(input) {
     const request = toHolderBindingRequest(toolName, args);
     const nonce = base64urlEncodeFromBytes(await crypto.randomBytes(16));
     const now = Math.floor(Date.now() / 1000);
+    // `sessionId` is optional on the way in (a request proof can precede any
+    // handshake), but `meta.sessionId` is a REQUIRED non-empty string in the
+    // proof schema. Defaulting to '' therefore minted a proof that could never
+    // verify: `assertHolderBinding` rejected the LEGITIMATE holder as
+    // INVALID_PROOF_STRUCTURE, indistinguishably from a thief. Mint a per-proof
+    // id instead, so the sessionless case (the stateless MCP core) works.
+    const boundSessionId = sessionId ?? `req-${base64urlEncodeFromBytes(await crypto.randomBytes(9))}`;
     return generator.generateProof(request, undefined, {
-        sessionId: sessionId ?? '',
+        sessionId: boundSessionId,
         audience,
         nonce,
         timestamp: now,

package/dist/delegation/holder-binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"holder-binding.js","sourceRoot":"","sources":["../../src/delegation/holder-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"holder-binding.js","sourceRoot":"","sources":["../../src/delegation/holder-binding.ts"],"names":[],"mappings":"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"}

package/dist/delegation/scope-matcher.d.ts

@@ -1,12 +1,17 @@
 import type { DelegationCredential } from '../types/protocol.js';
-export type ScopeMatcher = 'exact' | 'prefix' | 'regex';
+export type ScopeMatcher = 'exact' | 'prefix' | 'path-prefix' | 'regex';
 /**
  * Match a single requested scope/resource value against a pattern by matcher kind.
  *
  * - `exact`  : strict string equality.
  * - `prefix` : value starts with the pattern (a single trailing `*` is optional sugar).
  *              An empty base ('' or lone '*') matches nothing — it will NOT grant
- *              universal scope.
+ *              universal scope. Character-level: `notes` matches `notesx/secret.md`.
+ *              Use it for scope ids, where the value is an identifier, not a path.
+ * - `path-prefix` : the value IS the pattern, or lies under it as a `/`-separated
+ *              path (`notes` matches `notes` and `notes/a/b.md`, never
+ *              `notesx/secret.md`). Trailing `/` or `/*` on the pattern is optional
+ *              sugar; an empty base matches nothing. Use it for resource paths.
  * - `regex`  : anchored full-string match; never throws (invalid patterns → false).
  *
  * SECURITY: the regex pattern is supplied by the credential ISSUER. JS `RegExp`
@@ -20,7 +25,7 @@ export declare function matchScope(pattern: string, matcher: ScopeMatcher, value
 export interface ScopeSatisfaction {
     satisfied: boolean;
     /**
-     * True when satisfaction came via a non-exact (prefix|regex) CrispScope matcher.
+     * True when satisfaction came via a non-exact (prefix|path-prefix|regex) CrispScope matcher.
      * Callers should surface a warning — non-exact matchers widen effective authority.
      */
     usedNonExactMatcher: boolean;

package/dist/delegation/scope-matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-matcher.d.ts","sourceRoot":"","sources":["../../src/delegation/scope-matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAc,MAAM,sBAAsB,CAAC;AAY7E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAsBzF;AAkBD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,oBAAoB,GAC/B,iBAAiB,CAUnB"}
+{"version":3,"file":"scope-matcher.d.ts","sourceRoot":"","sources":["../../src/delegation/scope-matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAc,MAAM,sBAAsB,CAAC;AAY7E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA6BzF;AAkBD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,oBAAoB,GAC/B,iBAAiB,CAUnB"}

package/dist/delegation/scope-matcher.js

@@ -12,7 +12,12 @@ const NESTED_QUANTIFIER = /\([^()]*[+*?{][^()]*\)\s*[+*{]/;
  * - `exact`  : strict string equality.
  * - `prefix` : value starts with the pattern (a single trailing `*` is optional sugar).
  *              An empty base ('' or lone '*') matches nothing — it will NOT grant
- *              universal scope.
+ *              universal scope. Character-level: `notes` matches `notesx/secret.md`.
+ *              Use it for scope ids, where the value is an identifier, not a path.
+ * - `path-prefix` : the value IS the pattern, or lies under it as a `/`-separated
+ *              path (`notes` matches `notes` and `notes/a/b.md`, never
+ *              `notesx/secret.md`). Trailing `/` or `/*` on the pattern is optional
+ *              sugar; an empty base matches nothing. Use it for resource paths.
  * - `regex`  : anchored full-string match; never throws (invalid patterns → false).
  *
  * SECURITY: the regex pattern is supplied by the credential ISSUER. JS `RegExp`
@@ -33,6 +38,15 @@ export function matchScope(pattern, matcher, value) {
                 return false;
             return value.startsWith(base);
         }
+        case 'path-prefix': {
+            let base = pattern.endsWith('*') ? pattern.slice(0, -1) : pattern;
+            while (base.endsWith('/'))
+                base = base.slice(0, -1);
+            // Refuse to grant universal scope via an empty/`*`-only prefix.
+            if (base.length === 0)
+                return false;
+            return value === base || value.startsWith(`${base}/`);
+        }
         case 'regex': {
             if (pattern.length > MAX_REGEX_LEN || value.length > MAX_VALUE_LEN)
                 return false;