@kya-os/mcp 1.6.1 → 1.9.0

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

@@ -16,76 +16,21 @@
  */
 import { RuntimeFetchProvider, NoopFetchProvider } from "../providers/runtime-fetch.js";
 import { NoopAuditLogProvider } from "../providers/audit-log.js";
-import { SessionManager, } from "../session/manager.js";
+import { MemoryGrantStore } from "../providers/grant-store.js";
+import { SessionManager } from "../session/manager.js";
 import { ProofGenerator, } 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 { 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.
  *
@@ -103,10 +48,13 @@ function extractPolicyPrincipal(del) {
  * @returns Middleware components for session management and proof generation
  *
  * @remarks
- * **Single-process only**: This middleware stores session state in memory using closure
- * variables (`activeSessionId`, `sessionNonces`). It is NOT suitable for multi-instance
- * deployments behind a load balancer. For distributed deployments, implement a custom
- * `SessionStore` backed by Redis, DynamoDB, or similar and pass it via `config.session`.
+ * **Session resolution**: proof generation resolves the session from the explicit
+ * `sessionId` threaded into each wrapper. A single-process `activeSessionId`
+ * fallback (the established handshake/auto session) is consulted ONLY when no
+ * sessionId was threaded — e.g. non-KYA-OS clients (MCP Inspector) and the
+ * transport auto-proof path; a KYA-OS-aware call never depends on it. By default
+ * sessions live in an in-memory Map; for multi-instance deployments inject a
+ * durable `SessionStore` via `config.session.sessionStore`.
  */
 export function createKyaOsMiddleware(config, cryptoProvider) {
     const identity = {
@@ -126,6 +74,19 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
     const proofGenerator = new ProofGenerator(identity, cryptoProvider);
     const delegationConfig = config.delegation;
     const auditLog = config.auditLog ?? new NoopAuditLogProvider();
+    // Emit the proof under the legacy bare key as well, by default, for pre-1.1
+    // 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;
+    // 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).
+    const grantStore = config.grantStore ?? new MemoryGrantStore();
+    if (!config.grantStore) {
+        logger.warn("[kya-os] Using MemoryGrantStore — grants are lost on restart and not " +
+            "shared across instances. Inject a Redis / Durable Object / DB-backed " +
+            "GrantStore via config.grantStore for production / multi-instance use.");
+    }
     // Holder binding (spec §11.8). Built once so all tools share one replay cache.
     // The verifier derives the subject key from the did:key DID directly, so its
     // fetchProvider is unused on the phase-1 path — a never-called stub keeps
@@ -142,645 +103,46 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                     ? new RuntimeFetchProvider()
                     : new NoopFetchProvider()),
         });
-    // Session map: sessionId → last nonce (for proof generation)
-    const sessionNonces = new Map();
-    // Active session tracking — set after handshake (manual or auto)
-    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);
-        if (result.success && result.session) {
-            sessionNonces.set(result.session.sessionId, result.session.nonce);
-            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.
-     */
-    async function ensureSession() {
-        if (activeSessionId) {
-            const existing = await sessionManager.getSession(activeSessionId);
-            if (existing)
-                return activeSessionId;
-        }
-        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;
-            sessionNonces.set(result.session.sessionId, result.session.nonce);
-            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 as _meta (rendered by MCP Inspector, invisible to LLMs)
-                result._meta = { 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 = { ...(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;
-    }
-    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 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;
-            }
-            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,
     };