@kya-os/mcp 1.7.0 → 1.9.0

package/dist/middleware/with-kya-os.js

@@ -17,76 +17,20 @@
 import { RuntimeFetchProvider, NoopFetchProvider } from "../providers/runtime-fetch.js";
 import { NoopAuditLogProvider } from "../providers/audit-log.js";
 import { MemoryGrantStore } from "../providers/grant-store.js";
-import { SessionManager, } from "../session/manager.js";
-import { ProofGenerator, KYA_OS_PROOF_META_KEY, LEGACY_PROOF_META_KEY, } from "../proof/generator.js";
-import { validateHandshakeFormat } from "../session/manager.js";
-import { DelegationCredentialVerifier, } from "../delegation/vc-verifier.js";
-import { createDidKeyResolver } from "../delegation/did-key-resolver.js";
-import { assertHolderBinding, isHolderBindingApplicable, isKyaOsControlArg, toHolderBindingRequest, } from "../delegation/holder-binding.js";
+import { SessionManager } from "../session/manager.js";
+import { ProofGenerator, } from "../proof/generator.js";
 import { ProofVerifier } from "../proof/verifier.js";
 import { SystemClockProvider } from "../providers/system-clock.js";
 import { MemoryNonceCacheProvider } from "../providers/memory.js";
-import { scopeSatisfies } from "../delegation/scope-matcher.js";
-import { createDidWebResolver } from "../delegation/did-web-resolver.js";
-import { validateDelegationChain as validateDelegationChainCore, getDelegationScopes, } from "../delegation/chain-enforcement.js";
-import { createNeedsAuthorizationError, createNeedsApprovalError, } from "../types/protocol.js";
 import { logger } from "../logging/index.js";
-import { RiskClassifier } from "../policy/classifier.js";
-import { DefaultPolicyEngine } from "../policy/default-engine.js";
-import { verifyApprovalQuorum } from "../policy/approval.js";
-import { buildPolicyRequest } from "../policy/projection.js";
-import { KYA_OS_ERROR_CODES } from "../errors.js";
-import { canonicalizeJSON, parseVCJWT } from "../delegation/utils.js";
-import { base64urlDecodeToBytes, base64urlEncodeFromBytes, bytesToBase64 } from "../utils/base64.js";
-export const KYA_OS_ACTIONS = ["handshake", "identity", "reputation"];
-/**
- * Strip control characters and cap length on caller-derived values before they
- * are interpolated into client-facing reasons or log lines. A hostile
- * credential could otherwise embed newlines / control chars in an id or scope to
- * forge or corrupt log entries (log injection) or break a terminal. The fixed
- * parts of a reason contain no control chars, so sanitizing the whole assembled
- * string at the emission boundary is equivalent to sanitizing each interpolated
- * value, and is idempotent.
- */
-function sanitizeForMessage(value, maxLen = 256) {
-    const s = typeof value === "string" ? value : String(value);
-    // Replace C0/C1 control chars (incl. CR, LF, TAB, ESC, DEL) with U+FFFD so a
-    // hostile id/scope cannot forge log lines or break a terminal. Filtered by
-    // code point to keep this source ASCII-only (no literal control chars).
-    let out = "";
-    for (const ch of s) {
-        const code = ch.codePointAt(0) ?? 0;
-        out += code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? "\uFFFD" : ch;
-    }
-    return out.length > maxLen ? `${out.slice(0, maxLen)}\u2026` : out;
-}
-/** Best-effort projection of a delegation VC into policy principal facts. */
-function extractPolicyPrincipal(del) {
-    if (!del || typeof del !== "object") {
-        return { agentDid: "unknown", delegatedScopes: [] };
-    }
-    try {
-        const vc = del;
-        const subject = vc.credentialSubject;
-        const agentDid = subject?.delegation?.subjectDid ?? subject?.id ?? "unknown";
-        const responsibleParty = subject?.delegation?.controller;
-        let delegatedScopes = [];
-        try {
-            delegatedScopes = getDelegationScopes(vc);
-        }
-        catch {
-            delegatedScopes = [];
-        }
-        return {
-            agentDid,
-            ...(responsibleParty ? { responsibleParty } : {}),
-            delegatedScopes,
-        };
-    }
-    catch {
-        return { agentDid: "unknown", delegatedScopes: [] };
-    }
-}
+import { createGrantResolution } from "./with-kya-os.grants.js";
+import { createPolicyGate } from "./with-kya-os.policy-gate.js";
+import { createDelegationGate } from "./with-kya-os.delegation-gate.js";
+import { createSessionProof } from "./with-kya-os.session.js";
+import { createProtocol } from "./with-kya-os.protocol.js";
+// The public type surface lives in `./with-kya-os.types.ts`; re-export it here so
+// `import { KyaOsConfig, ... } from './with-kya-os'` continues to resolve unchanged.
+export * from "./with-kya-os.types.js";
 /**
  * Create KYA-OS middleware for a standard MCP SDK Server.
  *
@@ -134,16 +78,6 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
     // back-compat. The value is identical under both keys and `_meta` is never
     // hashed (§7.6), so the mirror is purely additive.
     const emitLegacyProofKey = config.emitLegacyProofKey ?? true;
-    /**
-     * Place a detached proof into a `_meta` object: always under the namespaced
-     * key, and (when {@link emitLegacyProofKey}) mirrored under the legacy bare
-     * key. The single place both emit paths build `_meta`, so they cannot drift.
-     */
-    const withProofMeta = (base, proof) => ({
-        ...base,
-        [KYA_OS_PROOF_META_KEY]: proof,
-        ...(emitLegacyProofKey ? { [LEGACY_PROOF_META_KEY]: proof } : {}),
-    });
     // Durable grant store for the no-paste retry. Defaults to in-memory; inject a
     // shared, durable store for multi-instance / restart survival (mirrors the
     // nonceCache precedent and its production warning).
@@ -169,826 +103,46 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                     ? new RuntimeFetchProvider()
                     : new NoopFetchProvider()),
         });
-    // Single-process fallback for the established (handshake or auto) session, used
-    // ONLY when no sessionId was threaded into the wrapper — e.g. non-KYA-OS clients
-    // (MCP Inspector) and the transport auto-proof path, which never thread one. The
-    // PRIMARY resolver is the explicit `sessionId` parameter, so a KYA-OS-aware call
-    // never depends on this fallback. The per-session proof nonce lives on the
-    // session record (`session.nonce`), so no separate nonce map is needed.
-    let activeSessionId;
-    const handshakeTool = {
-        name: "_kyaos_handshake",
-        description: "KYA-OS identity handshake — establishes a cryptographic session",
-        inputSchema: {
-            type: "object",
-            properties: {
-                nonce: { type: "string", description: "Client-generated unique nonce" },
-                audience: {
-                    type: "string",
-                    description: "Intended audience (server DID or URL)",
-                },
-                timestamp: { type: "number", description: "Unix epoch seconds" },
-                agentDid: {
-                    type: "string",
-                    description: "Client agent DID (optional)",
-                },
-            },
-            required: ["nonce", "audience", "timestamp"],
-        },
-    };
-    const kyaOsTool = {
-        name: "_kyaos",
-        description: "KYA-OS protocol — identity verification, session handshake, and server metadata",
-        inputSchema: {
-            type: "object",
-            properties: {
-                action: {
-                    type: "string",
-                    enum: [...KYA_OS_ACTIONS],
-                    description: "Protocol operation to perform",
-                },
-                nonce: { type: "string", description: "Client-generated unique nonce" },
-                audience: {
-                    type: "string",
-                    description: "Intended audience (server DID or URL)",
-                },
-                timestamp: { type: "number", description: "Unix epoch seconds" },
-                agentDid: {
-                    type: "string",
-                    description: "Client agent DID (optional)",
-                },
-            },
-            required: ["action"],
-        },
+    // The constructed collaborators, threaded into each sub-factory.
+    const deps = {
+        identity,
+        config,
+        cryptoProvider,
+        sessionManager,
+        proofGenerator,
+        auditLog,
+        grantStore,
+        delegationConfig,
+        holderBindingMode,
+        holderBindingVerifier,
+        emitLegacyProofKey,
     };
-    async function handleHandshake(args) {
-        if (!validateHandshakeFormat(args)) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            success: false,
-                            error: {
-                                code: KYA_OS_ERROR_CODES.handshake_failed,
-                                message: "Invalid handshake format: requires nonce (string), audience (string), and timestamp (positive integer)",
-                            },
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const result = await sessionManager.validateHandshake(args);
-        // Cache the established session as the single-process fallback for callers
-        // that do not thread a sessionId (e.g. the transport auto-proof path).
-        if (result.success && result.session) {
-            activeSessionId = result.session.sessionId;
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        success: result.success,
-                        ...(result.session && {
-                            sessionId: result.session.sessionId,
-                            serverDid: identity.did,
-                            serverKid: identity.kid,
-                        }),
-                        ...(result.error && { error: result.error }),
-                    }),
-                },
-            ],
-            ...(result.error && { isError: true }),
-        };
-    }
-    async function handleIdentity() {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        did: identity.did,
-                        kid: identity.kid,
-                        name: config.identity.agentName ?? identity.did,
-                        capabilities: ["handshake", "signing", "verification"],
-                        protocolVersion: "1.0.0",
-                        clockSkewSeconds: sessionManager.getStats().config.timestampSkewSeconds,
-                    }),
-                },
-            ],
-        };
-    }
-    async function handleKyaOs(args) {
-        const action = typeof args.action === "string"
-            ? args.action
-            : undefined;
-        switch (action) {
-            case "handshake":
-                return handleHandshake(args);
-            case "identity":
-                return handleIdentity();
-            case "reputation":
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: false,
-                                error: {
-                                    code: KYA_OS_ERROR_CODES.runtime_error,
-                                    message: 'action: "reputation" is not yet implemented.',
-                                },
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            default:
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: false,
-                                error: {
-                                    code: KYA_OS_ERROR_CODES.invalid_request,
-                                    message: `Unknown _kyaos action: "${action ?? "(missing)"}". Valid actions: ${KYA_OS_ACTIONS.join(", ")}`,
-                                },
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-        }
-    }
-    /**
-     * Auto-create a session for proof generation when no handshake has occurred.
-     * In production, KYA-OS-aware runtimes should execute handshake before tool calls.
-     * This convenience mode allows non-KYA-OS clients (like MCP Inspector) to
-     * still see proofs without manual handshake.
-     *
-     * SINGLE-SESSION ONLY: the auto-proof transport path does not thread a
-     * sessionId, so it relies on the shared `activeSessionId`. That is only an
-     * unambiguous attribution when exactly one session exists. With multiple
-     * concurrent sessions and no threaded id, borrowing `activeSessionId` would
-     * sign the proof with another client's session/nonce/audience — so this
-     * refuses to borrow and returns undefined (the caller skips the proof). The
-     * `autoSession` create path is unaffected (it makes the single session).
-     */
-    async function ensureSession() {
-        if (activeSessionId) {
-            const existing = await sessionManager.getSession(activeSessionId);
-            if (existing) {
-                if (sessionManager.getStats().activeSessions <= 1) {
-                    return activeSessionId;
-                }
-                // Ambiguous: more than one session and none threaded — do NOT borrow.
-                logger.warn("[kya-os] Multiple sessions active and no sessionId threaded; skipping " +
-                    "proof attribution to avoid signing with another client's session. " +
-                    "Thread the sessionId (the auto-proof path is single-session only).");
-                return undefined;
-            }
-        }
-        if (!config.autoSession)
-            return undefined;
-        // Generate a server-side session with cryptographically random nonce (SPEC.md §4)
-        const nonceBytes = await cryptoProvider.randomBytes(16);
-        const nonce = base64urlEncodeFromBytes(nonceBytes);
-        const timestamp = Math.floor(Date.now() / 1000);
-        const result = await sessionManager.validateHandshake({
-            nonce,
-            audience: identity.did,
-            timestamp,
-        });
-        if (result.success && result.session) {
-            activeSessionId = result.session.sessionId;
-            return activeSessionId;
-        }
-        return undefined;
-    }
-    function wrapWithProof(toolName, handler) {
-        return async (args, sessionId, context) => {
-            const result = await handler(args, sessionId, context);
-            if (result.isError) {
-                return result;
-            }
-            // Resolve session: explicit param → active session → auto-create
-            const resolvedSessionId = sessionId ?? await ensureSession();
-            if (!resolvedSessionId) {
-                return result;
-            }
-            const session = await sessionManager.getSession(resolvedSessionId);
-            if (!session) {
-                return result;
-            }
-            try {
-                const request = { method: toolName, params: args };
-                const response = { data: result.content };
-                const proof = await proofGenerator.generateProof(request, response, session, { scopeId: context?.scopeId });
-                // Attach proof under the namespaced _meta key (rendered by MCP
-                // Inspector, invisible to LLMs), plus the legacy bare key when enabled.
-                // Other _meta keys may coexist (SEP-414).
-                result._meta = withProofMeta({}, proof);
-                // Hand the verified call to the audit sink. A sink failure MUST NOT
-                // break the tool response, so it is logged and swallowed.
-                try {
-                    await auditLog.logAuditRecord({
-                        identity: { did: identity.did, kid: identity.kid },
-                        session: { sessionId: session.sessionId, audience: session.audience },
-                        requestHash: proof.meta.requestHash,
-                        responseHash: proof.meta.responseHash,
-                        verified: "yes",
-                        scopeId: proof.meta.scopeId,
-                    });
-                }
-                catch (auditError) {
-                    logger.error("[kya-os] Audit log failed", {
-                        tool: toolName,
-                        error: auditError instanceof Error
-                            ? auditError.message
-                            : String(auditError),
-                    });
-                }
-            }
-            catch (error) {
-                logger.error("[kya-os] Proof generation failed", {
-                    tool: toolName,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-                result._meta = {
-                    proofError: "Proof generation failed — response is unproven",
-                };
-            }
-            return result;
-        };
-    }
-    /**
-     * Attach a signed proof recording an authorization OUTCOME to a response, so
-     * rejected or pending privileged attempts leave a verifiable, non-repudiable
-     * forensic record (these previously produced no proof). Used for `denied`,
-     * `step_up_required`, and `needs_authorization` outcomes.
-     *
-     * When `responseData` is provided (e.g. the `needs_authorization` challenge
-     * content), the proof binds a `responseHash` over it — so the signed proof
-     * also attests the response body (notably the consent `authorizationUrl`),
-     * letting a verifier detect a tampered/MITM-swapped URL. Pure denials and
-     * step-ups pass no `responseData` (there is no response body to bind).
-     *
-     * Best-effort: if no session can be resolved or proof generation fails, the
-     * original response is returned unchanged.
-     */
-    async function attachOutcomeProof(response, toolName, args, sessionId, reason, outcome = "denied", paramsOverride, responseData) {
-        try {
-            const resolvedSessionId = sessionId ?? (await ensureSession());
-            if (!resolvedSessionId)
-                return response;
-            const session = await sessionManager.getSession(resolvedSessionId);
-            if (!session)
-                return response;
-            // Prefer the caller's already-stripped args so the signed requestHash
-            // matches the needs_approval / resumeToken requestHash exactly.
-            let cleanArgs;
-            if (paramsOverride !== undefined) {
-                cleanArgs = paramsOverride;
-            }
-            else {
-                cleanArgs = {};
-                for (const [k, v] of Object.entries(args)) {
-                    if (k !== "_kyaos_delegation")
-                        cleanArgs[k] = v;
-                }
-            }
-            const request = { method: toolName, params: cleanArgs };
-            const proofResponse = responseData !== undefined ? { data: responseData } : undefined;
-            const proof = await proofGenerator.generateProof(request, proofResponse, session, {
-                outcome,
-                reason: sanitizeForMessage(reason),
-            });
-            response._meta = withProofMeta(response._meta ?? {}, proof);
-        }
-        catch (error) {
-            logger.error("[kya-os] Outcome proof generation failed", {
-                tool: toolName,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-        return response;
-    }
-    /**
-     * Deterministic grant id from (agentDid, sessionId, sorted scopes). Stable for
-     * the same tuple so a repeated VC-paste UPSERTS one grant rather than piling
-     * duplicate rows in a durable store.
-     */
-    async function grantId(agentDid, sessionId, scopes) {
-        const key = `${agentDid}|${sessionId ?? ""}|${[...scopes].sort().join(",")}`;
-        const digest = await cryptoProvider.hash(new TextEncoder().encode(key));
-        return `grant_${digest.replace(/^sha256:/, "")}`;
-    }
-    /** Grant expiry (ms epoch) derived from the VC, or undefined for no expiry. */
-    function delegationExpiryMs(vc) {
-        if (vc.expirationDate) {
-            const parsed = Date.parse(vc.expirationDate);
-            if (!Number.isNaN(parsed))
-                return parsed;
-        }
-        const notAfter = vc.credentialSubject?.delegation?.constraints?.notAfter;
-        if (typeof notAfter === "number")
-            return notAfter * 1000;
-        return undefined;
-    }
-    /**
-     * Resolve a durable, agent-anchored grant for a no-delegation call — BUT ONLY
-     * behind a verified holder-of-key proof. The agent DID is taken from the
-     * `_kyaos_proof` and re-proven per request (possession of the subject key over
-     * THIS request), never trusted from a bearer hint. This is the single most
-     * security-sensitive gate of the durable-consent change: without it, any
-     * caller who knows agent A's DID could replay A's grant (confused-deputy
-     * escalation, spec §A.4). Returns undefined unless possession is proven.
-     */
-    async function resolveAgentGrant(toolName, args, sessionId, scopeId) {
-        if (!holderBindingVerifier)
-            return undefined; // inert unless holder binding is on
-        const proofArg = args["_kyaos_proof"];
-        if (proofArg === undefined)
-            return undefined;
-        let parsedProof = proofArg;
-        if (typeof proofArg === "string") {
-            try {
-                parsedProof = JSON.parse(proofArg);
-            }
-            catch {
-                return undefined;
-            }
-        }
-        const proof = parsedProof;
-        const agentDid = proof?.meta?.did;
-        if (typeof agentDid !== "string" || !isHolderBindingApplicable(agentDid)) {
-            return undefined;
-        }
-        const binding = await assertHolderBinding({
-            proof,
-            subjectDid: agentDid,
-            request: toHolderBindingRequest(toolName, args),
-            expectedAudience: identity.did,
-            proofVerifier: holderBindingVerifier,
-        });
-        if (binding.status !== "bound")
-            return undefined;
-        const grants = await grantStore.getByAgent(agentDid, [scopeId]);
-        // A session-bound grant is usable only from its own session; an
-        // agent-anchored (session-less) grant is portable across transports.
-        return grants.find((g) => g.sessionId === undefined || g.sessionId === sessionId);
-    }
-    /**
-     * Resolve an existing durable grant for a no-delegation (retry) call, so a
-     * fresh instance with empty memory authorizes the retry from the shared store.
-     * Fail-closed, holder-of-key first (agent-anchored, portable), then the
-     * session bearer capability (never crosses sessions). Returns undefined to
-     * fall through to the needs_authorization challenge.
-     */
-    async function resolveExistingGrant(toolName, args, sessionId, scopeId) {
-        const agentGrant = await resolveAgentGrant(toolName, args, sessionId, scopeId);
-        if (agentGrant)
-            return agentGrant;
-        if (sessionId) {
-            const [sessionGrant] = await grantStore.getBySession(sessionId, [scopeId]);
-            if (sessionGrant)
-                return sessionGrant;
-        }
-        return undefined;
-    }
-    /**
-     * Mint a durable grant from a freshly-verified delegation so the NEXT call —
-     * on any instance — resolves via {@link resolveExistingGrant} without
-     * re-pasting the VC. Best-effort: a store failure must not break the
-     * already-authorized response.
-     */
-    async function bindGrantOnSuccess(vc, delegationArg, isVCJWT, sessionId, scopeId) {
-        try {
-            const agentDid = vc.credentialSubject?.id;
-            if (!agentDid)
-                return;
-            // A session-less grant minted with holder binding OFF is unresolvable on
-            // retry (getByAgent needs a holder-of-key proof; getBySession needs a
-            // sessionId), so DON'T bind it — that would only orphan a row in a durable
-            // store. Durability for such flows comes from re-presenting the delegation,
-            // not from a grant. Enable holderBinding 'enforce' or thread a sessionId to
-            // use the grant-backed no-paste retry. (review F4)
-            if (holderBindingMode === "off" && sessionId === undefined) {
-                logger.debug(`[kya-os] Skipping an unresolvable session-less grant for scope "${scopeId}" (holderBinding 'off', no sessionId).`);
-                return;
-            }
-            let delegatedScopes;
-            try {
-                delegatedScopes = getDelegationScopes(vc);
-            }
-            catch {
-                delegatedScopes = [];
-            }
-            // Store the EXACT required scope alongside the delegated scopes. The retry
-            // queries by the tool's exact scopeId, but the delegation may have granted
-            // a prefix/regex scope (e.g. "cart:*"); the store's exact `coversScopes`
-            // would never match the wildcard, so the no-paste retry would silently
-            // re-challenge. Including scopeId makes the grant resolvable. (review F1)
-            const scopes = Array.from(new Set([scopeId, ...delegatedScopes]));
-            const userDid = vc.credentialSubject?.delegation?.controller;
-            const expiresAt = delegationExpiryMs(vc);
-            const grant = {
-                id: await grantId(agentDid, sessionId, scopes),
-                agentDid,
-                ...(userDid !== undefined ? { userDid } : {}),
-                scopes,
-                ...(sessionId !== undefined ? { sessionId } : {}),
-                authorization: { type: "delegation" },
-                ...(isVCJWT && typeof delegationArg === "string"
-                    ? { credentialJwt: delegationArg }
-                    : {}),
-                issuedAt: Date.now(),
-                ...(expiresAt !== undefined ? { expiresAt } : {}),
-                status: "active",
-            };
-            await grantStore.bind(grant);
-        }
-        catch (error) {
-            logger.error("[kya-os] Grant bind failed", {
-                scope: scopeId,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    function wrapWithDelegation(toolName, config, handler) {
-        const didKeyResolver = createDidKeyResolver();
-        const fetchProvider = delegationConfig?.fetchProvider ??
-            (typeof globalThis.fetch === "function"
-                ? new RuntimeFetchProvider()
-                : undefined);
-        const didWebResolver = fetchProvider
-            ? createDidWebResolver(fetchProvider)
-            : undefined;
-        const didResolver = {
-            async resolve(did) {
-                const customResolver = delegationConfig?.didResolver;
-                if (customResolver) {
-                    const resolved = await customResolver.resolve(did);
-                    if (resolved) {
-                        return resolved;
-                    }
-                }
-                if (did.startsWith("did:key:")) {
-                    return didKeyResolver.resolve(did);
-                }
-                if (did.startsWith("did:web:")) {
-                    return didWebResolver?.resolve(did) ?? null;
-                }
-                return null;
-            },
-        };
-        const signatureVerifier = async (vc, publicKeyJwk) => {
-            const proof = vc.proof;
-            if (!proof) {
-                return { valid: false, reason: "Missing proof" };
-            }
-            const proofValue = proof["proofValue"];
-            if (!proofValue) {
-                return { valid: false, reason: "Missing proofValue in proof" };
-            }
-            // Reconstruct the unsigned VC (without proof) for signature verification
-            const vcRecord = vc;
-            const vcWithoutProof = {};
-            for (const [k, v] of Object.entries(vcRecord)) {
-                if (k !== "proof")
-                    vcWithoutProof[k] = v;
-            }
-            const canonical = canonicalizeJSON(vcWithoutProof);
-            const data = new TextEncoder().encode(canonical);
-            // Decode signature from base64url proof value
-            const sigBytes = base64urlDecodeToBytes(proofValue);
-            // Get public key from JWK (x is base64url-encoded raw key bytes)
-            const jwk = publicKeyJwk;
-            if (!jwk.x) {
-                return { valid: false, reason: "No x field in publicKeyJwk" };
-            }
-            // Convert base64url key to standard base64 for the crypto provider
-            const pubKeyBytes = base64urlDecodeToBytes(jwk.x);
-            const pubKeyBase64 = bytesToBase64(pubKeyBytes);
-            const valid = await cryptoProvider.verify(data, sigBytes, pubKeyBase64);
-            return {
-                valid,
-                reason: valid ? undefined : "Signature verification failed",
-            };
-        };
-        const verifier = new DelegationCredentialVerifier({
-            didResolver,
-            signatureVerifier,
-            statusListResolver: delegationConfig?.statusListResolver,
-        });
-        const buildDelegationErrorResponse = (error, reason) => ({
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ error, reason: sanitizeForMessage(reason) }),
-                },
-            ],
-            isError: true,
-        });
-        // Thin adapter over the framework-agnostic core (E3.1 · chain-enforcement.ts).
-        // The walk/attenuation/audience/§11.6/revocation rules live in one place;
-        // this binds the host's injected verifier + server DID + resolver + the
-        // optional graph-backed RevocationChecker.
-        const validateDelegationChain = (leafCredential, options) => validateDelegationChainCore(leafCredential, {
-            serverDid: identity.did,
-            verifier,
-            resolveDelegationChain: delegationConfig?.resolveDelegationChain,
-            statusListConfigured: !!delegationConfig?.statusListResolver,
-            revocationChecker: delegationConfig?.revocationChecker,
-        }, options);
-        return async (args, sessionId) => {
-            const delegationArg = args["_kyaos_delegation"];
-            if (delegationArg === undefined || delegationArg === null) {
-                // No delegation pasted — a durable grant may already authorize this call
-                // (the no-paste retry), even on a fresh instance with empty memory.
-                // Holder-of-key first (agent-anchored, proof-gated), then the session
-                // bearer capability. On a hit, skip the challenge and run the handler
-                // with exactly the call shape a verified delegation would have produced.
-                const existingGrant = await resolveExistingGrant(toolName, args, sessionId, config.scopeId);
-                if (existingGrant) {
-                    const grantArgs = {};
-                    for (const [k, v] of Object.entries(args)) {
-                        if (!isKyaOsControlArg(k))
-                            grantArgs[k] = v;
-                    }
-                    logger.debug(`[kya-os] Grant resolved for "${toolName}" (scope "${config.scopeId}") — no re-paste required`);
-                    return handler(grantArgs, sessionId, { scopeId: config.scopeId });
-                }
-                // No delegation provided — return needs_authorization response
-                const tokenBytes = await cryptoProvider.randomBytes(16);
-                const hex = Array.from(tokenBytes)
-                    .map((b) => b.toString(16).padStart(2, "0"))
-                    .join("");
-                const resumeToken = [
-                    hex.slice(0, 8),
-                    hex.slice(8, 12),
-                    hex.slice(12, 16),
-                    hex.slice(16, 20),
-                    hex.slice(20),
-                ].join("-");
-                const expiresAt = Math.floor(Date.now() / 1000) + 300;
-                const authError = createNeedsAuthorizationError({
-                    message: `Tool "${toolName}" requires delegation with scope: ${config.scopeId}`,
-                    authorizationUrl: config.consentUrl,
-                    resumeToken,
-                    expiresAt,
-                    scopes: [config.scopeId],
-                });
-                // Sign the challenge (outcome=needs_authorization). The proof binds a
-                // responseHash over the EMITTED challenge content — including the
-                // authorizationUrl. A verifier that recomputes the response hash over the
-                // content it received (ProofVerifier.verifyProof(proof, jwk, { request,
-                // response })) thereby detects a tampered/MITM-swapped consent URL; the
-                // signature alone proves authenticity, not content-match. config.format-
-                // Challenge lets a server render the challenge (e.g. a markdown link for
-                // LLM clients) BEFORE signing, so the proof binds exactly what the client
-                // receives. A throwing hook falls back to the default challenge (never
-                // -32603). Best-effort: attachOutcomeProof no-ops if no session resolves.
-                const defaultChallengeContent = [
-                    { type: "text", text: JSON.stringify(authError) },
-                ];
-                let challengeContent = defaultChallengeContent;
-                if (config.formatChallenge) {
-                    try {
-                        challengeContent = config.formatChallenge(authError);
-                    }
-                    catch (error) {
-                        logger.error("[kya-os] formatChallenge threw; using the default challenge", {
-                            tool: toolName,
-                            error: error instanceof Error ? error.message : String(error),
-                        });
-                        challengeContent = defaultChallengeContent;
-                    }
-                }
-                return attachOutcomeProof({ content: challengeContent }, toolName, args, sessionId, authError.message, "needs_authorization", undefined, challengeContent);
-            }
-            // Accept delegation as either a JSON object (embedded proof) or a
-            // VC-JWT string (compact JWT). The Cloudflare consent service issues
-            // VC-JWTs; examples use embedded proofs. Support both transparently.
-            let vc;
-            let isVCJWT = false;
-            if (typeof delegationArg === "string") {
-                const parsed = parseVCJWT(delegationArg);
-                if (!parsed || !parsed.payload.vc) {
-                    return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.delegation_invalid, "Invalid VC-JWT format"), toolName, args, sessionId, "Invalid VC-JWT format");
-                }
-                vc = parsed.payload.vc;
-                // VC-JWTs don't have an embedded proof — the JWT signature is the
-                // proof. Add a marker so basic validation (which checks for proof
-                // presence) passes. The actual signature is in the JWT envelope.
-                if (!vc.proof) {
-                    vc = { ...vc, proof: { type: 'JwtProof2020', jwt: delegationArg } };
-                }
-                isVCJWT = true;
-            }
-            else {
-                vc = delegationArg;
-            }
-            // For VC-JWTs the embedded-signature check is skipped (the JWT envelope
-            // signature is the proof); schema/expiry/status/scope checks still apply.
-            // validateDelegationChain performs the shape check and returns
-            // { valid, reason } for malformed input, never throwing on normal or
-            // structurally-malformed credentials. This try/catch is therefore a PURE
-            // BACKSTOP — it fires only on a truly unexpected throw (e.g. a hostile
-            // getter/Proxy accessor or a provider fault): it logs the detail
-            // server-side and returns a GENERIC reason, so no internal/implementation
-            // detail (stack, raw error text) leaks to the client or the signed proof.
-            const verificationResult = await (async () => {
-                try {
-                    return await validateDelegationChain(vc, { skipSignature: isVCJWT });
-                }
-                catch (error) {
-                    logger.error("[kya-os] Unexpected error verifying delegation", {
-                        tool: toolName,
-                        error: error instanceof Error ? error.message : String(error),
-                        stack: error instanceof Error ? error.stack : undefined,
-                    });
-                    return { valid: false, reason: "Delegation credential could not be verified" };
-                }
-            })();
-            if (!verificationResult.valid) {
-                const reason = verificationResult.reason ?? "Unknown delegation validation error";
-                logger.warn(`[kya-os] Delegation verification failed for "${toolName}": ${sanitizeForMessage(reason)}`);
-                return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.delegation_invalid, reason), toolName, args, sessionId, reason);
-            }
-            // Holder binding (spec §11.8): the delegation is valid, but a valid
-            // *credential* is a bearer token until we also prove the caller holds the
-            // delegation SUBJECT's key. Opt-in via `delegation.holderBinding`. did:key
-            // subjects are bound here; did:web is deferred to cnf binding (phase 2) and
-            // logged, never rejected. Runs after identity is established, before scope.
-            if (holderBindingMode !== "off" && holderBindingVerifier) {
-                const subjectDid = vc.credentialSubject?.id;
-                if (subjectDid && isHolderBindingApplicable(subjectDid)) {
-                    const proofArg = args["_kyaos_proof"];
-                    if (proofArg === undefined) {
-                        const reason = "Holder-of-key proof (_kyaos_proof) is required for this delegation subject";
-                        logger.warn(`[kya-os] Holder binding: "${toolName}" called without _kyaos_proof`);
-                        if (holderBindingMode === "enforce") {
-                            return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.holder_binding_failed, reason), toolName, args, sessionId, reason);
-                        }
-                    }
-                    else {
-                        let parsedProof = proofArg;
-                        if (typeof proofArg === "string") {
-                            try {
-                                parsedProof = JSON.parse(proofArg);
-                            }
-                            catch {
-                                parsedProof = {};
-                            }
-                        }
-                        const binding = await assertHolderBinding({
-                            proof: parsedProof,
-                            subjectDid,
-                            request: toHolderBindingRequest(toolName, args),
-                            expectedAudience: identity.did,
-                            proofVerifier: holderBindingVerifier,
-                        });
-                        if (binding.status !== "bound") {
-                            const reason = binding.reason ??
-                                "Holder-of-key proof did not bind the delegation subject";
-                            logger.warn(`[kya-os] Holder binding ${binding.status} for "${toolName}": ${sanitizeForMessage(reason)}`);
-                            if (holderBindingMode === "enforce") {
-                                return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.holder_binding_failed, reason), toolName, args, sessionId, reason);
-                            }
-                        }
-                    }
-                }
-                else if (subjectDid) {
-                    // Non-did:key subject — phase 1 cannot pin its key; defer to cnf
-                    // binding (phase 2) rather than reject legitimate traffic.
-                    logger.warn(`[kya-os] Holder binding: subject "${subjectDid}" is not did:key; deferring to cnf binding (phase 2)`);
-                }
-            }
-            // Safe to call directly: the structural guard + validateDelegationChain
-            // above guarantee a well-formed credential here, and scopeSatisfies is
-            // bounded (ReDoS-guarded) and returns rather than throws.
-            const scopeResult = scopeSatisfies(config.scopeId, vc);
-            if (scopeResult.usedNonExactMatcher) {
-                logger.warn(`[kya-os] Scope "${config.scopeId}" for "${toolName}" granted via a non-exact ` +
-                    `(prefix/regex) matcher. Verify this is intended — non-exact matchers widen authority.`);
-            }
-            if (!scopeResult.satisfied) {
-                const reason = `Required scope "${config.scopeId}" not in delegation scopes`;
-                logger.warn(`[kya-os] Delegation missing required scope "${config.scopeId}" for "${toolName}"`);
-                return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.insufficient_scope, reason), toolName, args, sessionId, reason);
-            }
-            // Strip the reserved _kyaos* control namespace before passing to the
-            // handler — same predicate the bound request hash uses, so the handler
-            // receives exactly the call the subject signed (no smuggled control arg).
-            const cleanArgs = {};
-            for (const [k, v] of Object.entries(args)) {
-                if (!isKyaOsControlArg(k))
-                    cleanArgs[k] = v;
-            }
-            // Mint a durable grant from this verified delegation so the next call —
-            // on any instance — resolves via resolveExistingGrant with no re-paste.
-            await bindGrantOnSuccess(vc, delegationArg, isVCJWT, sessionId, config.scopeId);
-            logger.debug(`[kya-os] Delegation verified for "${toolName}", scope "${config.scopeId}"`);
-            return handler(cleanArgs, sessionId, { scopeId: config.scopeId });
-        };
-    }
-    const defaultRiskClassifier = new RiskClassifier();
-    const defaultPolicyEngine = new DefaultPolicyEngine();
-    /**
-     * Per-action policy / step-up gate. Composed AFTER wrapWithDelegation (which
-     * enforces identity + scope); this wrapper adds the PROPORTIONALITY layer:
-     * classify the action's risk, ask a pluggable PolicyEngine, and either allow,
-     * deny (with a signed denial proof), or require N-of-M human approval
-     * (needs_approval) before the handler runs. It forces a decision point — it
-     * does not itself supply judgment.
-     */
-    function withPolicyGate(toolName, handler, opts = {}) {
-        const engine = opts.engine ?? defaultPolicyEngine;
-        const classifier = opts.classifier ?? defaultRiskClassifier;
-        const approvalsKey = opts.approvalsArgKey ?? "_kyaos_approvals";
-        const isValidApprovalSignature = opts.isValidApprovalSignature ?? (async () => false);
-        return async (args, sessionId) => {
-            // Drop the reserved _kyaos* namespace plus the (possibly custom) approvals
-            // key, so no control arg reaches the handler.
-            const cleanArgs = {};
-            for (const [k, v] of Object.entries(args)) {
-                if (!isKyaOsControlArg(k) && k !== approvalsKey)
-                    cleanArgs[k] = v;
-            }
-            const namespace = opts.resolveNamespace?.(args) ?? toolName;
-            const risk = classifier.classify({ toolName, namespace });
-            const principal = extractPolicyPrincipal(args["_kyaos_delegation"]);
-            const policyRequest = buildPolicyRequest({
-                principal: {
-                    agentDid: principal.agentDid,
-                    ...(principal.responsibleParty
-                        ? { responsibleParty: principal.responsibleParty }
-                        : {}),
-                },
-                action: { toolName },
-                resource: { namespace },
-                delegatedScopes: principal.delegatedScopes,
-                scopeMatched: opts.scopeMatched ?? false,
-                risk,
-            });
-            const decision = await engine.evaluate(policyRequest);
-            if (decision.decision === "allow") {
-                return handler(cleanArgs, sessionId);
-            }
-            if (decision.decision === "deny") {
-                const denied = {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: KYA_OS_ERROR_CODES.policy_denied,
-                                reason: sanitizeForMessage(decision.reason),
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-                return attachOutcomeProof(denied, toolName, args, sessionId, decision.reason, "denied", cleanArgs);
-            }
-            // step_up: verify any supplied approval grants, bound to this exact action.
-            const requestHash = await proofGenerator.hashRequest({
-                method: toolName,
-                params: cleanArgs,
-            });
-            const grants = Array.isArray(args[approvalsKey])
-                ? args[approvalsKey]
-                : [];
-            const quorumResult = await verifyApprovalQuorum(grants, requestHash, decision.quorum, isValidApprovalSignature);
-            if (quorumResult.satisfied) {
-                return handler(cleanArgs, sessionId);
-            }
-            const needsApproval = createNeedsApprovalError({
-                message: `Tool "${toolName}" requires ${decision.quorum.n}-of-N approval before it may proceed (${sanitizeForMessage(decision.reason)}).`,
-                resumeToken: `step_up:${requestHash}`,
-                expiresAt: Math.floor(Date.now() / 1000) + 300,
-                requestHash,
-                quorum: decision.quorum,
-            });
-            const stepUp = {
-                content: [{ type: "text", text: JSON.stringify(needsApproval) }],
-                isError: true,
-            };
-            return attachOutcomeProof(stepUp, toolName, args, sessionId, decision.reason, "step_up_required", cleanArgs);
-        };
-    }
+    // Session establishment + proof attachment (owns the activeSessionId fallback);
+    // the `_kyaos` protocol surface routes to its handshake handler.
+    const session = createSessionProof(deps);
+    const protocol = createProtocol(deps, {
+        handleHandshake: session.handleHandshake,
+    });
+    // Durable-grant resolution (the no-paste retry). Depends only on the immutable
+    // deps above, so it lifts out cleanly with no shared session state.
+    const { resolveExistingGrant, bindGrantOnSuccess } = createGrantResolution(deps);
+    const { wrapWithDelegation } = createDelegationGate(deps, {
+        attachOutcomeProof: session.attachOutcomeProof,
+        resolveExistingGrant,
+        bindGrantOnSuccess,
+    });
+    const { withPolicyGate } = createPolicyGate(deps, {
+        attachOutcomeProof: session.attachOutcomeProof,
+    });
     return {
         identity: config.identity,
         sessionManager,
         proofGenerator,
-        kyaOsTool,
-        handshakeTool,
-        handleKyaOs,
-        handleHandshake,
-        wrapWithProof,
+        kyaOsTool: protocol.kyaOsTool,
+        handshakeTool: protocol.handshakeTool,
+        handleKyaOs: protocol.handleKyaOs,
+        handleHandshake: session.handleHandshake,
+        wrapWithProof: session.wrapWithProof,
         wrapWithDelegation,
         withPolicyGate,
     };