KYA-OS MCP

Multi-instance deployments

The in-memory defaults are single-process only. For a load-balanced / multi-instance deployment, inject a durable Redis / Durable Object / DB-backed implementation for every runtime-state seam — the nonce cache (NonceCacheProvider) together with the consent stores (GrantStore, PendingFlowStore, SessionStore) — so replay protection, grants, pending OAuth flows, and sessions are shared across instances and survive restarts.

Delegation grants must retain their original signed evidence: credentialJwt for VC-JWTs, or delegationCredential for object VCs. wrapWithDelegation revalidates that evidence with the same verifier as a directly presented credential on every reuse, including chain resolution, audience, scope, expiry, and configured status/revocation checks. Store providers must preserve these fields and return only active grants; cache availability alone does not authorize a request. Grant expiry is bounded by the earliest credential or constraint expiry in the verified chain.

Upgrade compatibility: legacy grants without signed evidence intentionally return needs_authorization; re-present a valid delegation or complete the normal consent flow to replace them. Do not reconstruct unsigned credentials from cached metadata. Under holderBinding: 'enforce', did:key session retries also require a fresh holder proof. off and warn retain their documented session behavior, and non-did:key binding remains deferred; neither provides an enforced proof-of-possession guarantee for those requests. Status and chain providers now receive reads on grant reuse as they do on direct calls, and an unavailable required provider prevents reuse. This does not strengthen a provider's own status-cache freshness policy.

VC-JWT envelope exp and nbf are checked on every verification, including signature-cache hits and grant reuse. Omitted claims remain supported. A present claim must be a finite NumericDate. An expired envelope denies authorization even when the embedded VC is otherwise current, and verified envelope expiry can shorten the cached grant's lifetime. nbf allows JWT_NBF_LEEWAY_SECONDS (30 seconds) of clock skew; exp allows none.

Delegation issuers: each re-delegation must be signed by its parent's subject. The issuerDid inside a credential is only a claim, so the chain walk also checks who signed it. Set delegation.trustedRootIssuers to the DIDs allowed to issue root delegations, the Responsible Party for the whole chain. With it set, a chain whose root is signed by any other DID is rejected, including when a stored grant is reused. Without it, any issuer is accepted, including an agent signing a delegation for itself, and the middleware logs a warning at startup. A root whose claimed issuerDid differs from its signer is still accepted, and logged.

Nonce providers: give your NonceCacheProvider an atomic consume(nonce, ttlSeconds, agentDid?). It must record an unseen (agentDid, nonce), return literal true only to the call that recorded it, and reject on storage failure. Implement the claim in the shared backend with a conditional insert and expiry, not with a local mutex around remote reads and writes. Eventually consistent KV alone cannot provide it. The bundled memory provider implements consume, but it protects only one cache instance and loses its state on restart. consume is optional: a provider without it keeps working by falling back to has then add, which cannot stop concurrent duplicates of one signed request, and a warning is logged once. Set requireAtomicNonce: true on the middleware, ProofVerifier, SessionManager or consumeFromNonceCacheProvider to refuse that fallback; each then throws at construction for a provider without consume. Any result other than literal true, or a storage failure, denies admission. withKyaOs takes the same nonceCache and requireAtomicNonce options (and responseProofProfile) and passes them to the middleware.

Providers must honor the requested retention duration. The verifiers retain nonces through the final accepted second, including future timestamps and clock skew, while preserving a longer configured TTL. The detached verifier also covers later increases up to its supported setTimestampSkew maximum. Custom card consumeNonceIfFresh callbacks must honor the new third minTtlSec argument; the bundled card cache and provider adapter do so. Instances sharing a replay namespace must agree on the longest proof-acceptance policy and retain state accordingly. Retire old non-atomic writers before claiming atomic protection. Preserve or extend existing records through the full remaining acceptance window; merely keeping their old, shorter TTLs is insufficient. If the backend cannot extend them safely, pause affected admission and wait out that window before cutover. Do not clear records while their proofs may still be accepted.

---

Run the example servers

git clone https://github.com/decentralized-identity/kya-os-mcp.git
cd kya-os-mcp && npm install
bash scripts/demo.sh

This starts all example servers and opens MCP Inspector. Connect to any server, call a tool, and inspect the proof in _meta:

Also available: outbound-delegation (gateway pattern), verify-proof (standalone verification), statuslist (revocation lifecycle), 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.

Integrations

KYA-OS integrates through typed seams — the adapter pattern is the whole model. Every external dependency is a port with an in-memory or reference default; bind your own backend, or drop in a shipped adapter. Adding one is "implement this interface" (or, for a self-contained system, "drop a folder under src/integrations/") — contributions welcome.

cheqd: a fully-worked on-chain integration

cheqd is the reference for what filling the seams looks like end to end — one package binds three at once: DID resolution (did:cheqd), revocation (on-chain StatusList2021), and audit anchoring (DID-Linked Resources). Enabling the resolver is a small config change:

import { cheqdResolver } from '@kya-os/mcp/cheqd';

await withKyaOs(server, {
  crypto,
  delegation: {
    didResolvers: { cheqd: cheqdResolver({ resolverUrl: 'https://resolver.cheqd.net' }) },
  },
});

Its full reference (registrar writes, did:web <-> did:cheqd linkage, DID-Linked Resource helpers, live testnet E2E) lives in src/integrations/cheqd/README.md; see examples/cheqd-dlr for a complete operator flow.