@kya-os/mcp 1.3.1 → 1.4.0

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

@@ -14,51 +14,102 @@
  * internally by `withKyaOs()` and for advanced use cases like the
  * low-level `Server` API or custom request handler patterns.
  */
-import { FetchProvider, } from "../providers/base.js";
+import { RuntimeFetchProvider } from "../providers/runtime-fetch.js";
+import { NoopAuditLogProvider } from "../providers/audit-log.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 { scopeSatisfies } from "../delegation/scope-matcher.js";
 import { createDidWebResolver } from "../delegation/did-web-resolver.js";
 import { verifyDelegationAudience } from "../delegation/audience-validator.js";
-import { createNeedsAuthorizationError, extractDelegationFromVC, } from "../types/protocol.js";
+import { createNeedsAuthorizationError, createNeedsApprovalError, extractDelegationFromVC, } 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 { 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"];
-class RuntimeFetchProvider extends FetchProvider {
-    async resolveDID() {
-        return null;
-    }
-    async fetchStatusList() {
-        return null;
-    }
-    async fetchDelegationChain() {
-        return [];
-    }
-    async fetch(url, options) {
-        if (typeof globalThis.fetch !== "function") {
-            throw new Error("Global fetch is not available in this runtime");
-        }
-        return globalThis.fetch(url, options);
-    }
-}
 function getDelegationScopes(credential) {
     const scopes = new Set();
     for (const scope of credential.credentialSubject.delegation.scopes ?? []) {
         scopes.add(scope);
     }
-    for (const scope of credential.credentialSubject.delegation.constraints.scopes ?? []) {
+    for (const scope of credential.credentialSubject.delegation.constraints?.scopes ?? []) {
         scopes.add(scope);
     }
     return Array.from(scopes);
 }
+/**
+ * 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: [] };
+    }
+}
 function validateScopeAttenuation(parentCredential, childCredential) {
     const parentScopes = getDelegationScopes(parentCredential);
     const childScopes = getDelegationScopes(childCredential);
     const childDelegation = childCredential.credentialSubject.delegation;
+    // CRISP matcher attenuation: getDelegationScopes does NOT see constraints.crisp.scopes,
+    // so a re-delegation could otherwise widen authority by introducing a broad
+    // prefix/regex matcher (e.g. resource:"" matches every scope). Require the child's
+    // crisp matchers to be a subset of the parent's (by matcher+resource). Fail closed.
+    const crispKey = (s) => `${s.matcher}\u0000${s.resource}`;
+    const parentCrisp = new Set((parentCredential.credentialSubject.delegation.constraints.crisp?.scopes ?? []).map(crispKey));
+    const widenedCrisp = (childDelegation.constraints.crisp?.scopes ?? []).filter((s) => !parentCrisp.has(crispKey(s)));
+    if (widenedCrisp.length > 0) {
+        return {
+            valid: false,
+            reason: `Delegation ${childDelegation.id} introduces crisp scope matcher(s) absent from parent ${parentCredential.credentialSubject.delegation.id}: ${widenedCrisp
+                .map((s) => `${s.matcher}:${s.resource}`)
+                .join(", ")}`,
+        };
+    }
     if (parentScopes.length === 0) {
         return { valid: true };
     }
@@ -100,11 +151,6 @@ function validateScopeAttenuation(parentCredential, childCredential) {
  * deployments behind a load balancer. For distributed deployments, implement a custom
  * `SessionStore` backed by Redis, DynamoDB, or similar and pass it via `config.session`.
  */
-// Module-level warn-once flags for unsafe configuration. Per-process,
-// not per-session, so long-running servers don't spam logs on every new
-// session.
-let warnedAudienceOptOut = false;
-let warnedLegacyUnsafeDelegation = false;
 export function createKyaOsMiddleware(config, cryptoProvider) {
     const identity = {
         did: config.identity.did,
@@ -118,6 +164,7 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
     });
     const proofGenerator = new ProofGenerator(identity, cryptoProvider);
     const delegationConfig = config.delegation;
+    const auditLog = config.auditLog ?? new NoopAuditLogProvider();
     // Session map: sessionId → last nonce (for proof generation)
     const sessionNonces = new Map();
     // Active session tracking — set after handshake (manual or auto)
@@ -299,8 +346,8 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
         return undefined;
     }
     function wrapWithProof(toolName, handler) {
-        return async (args, sessionId) => {
-            const result = await handler(args, sessionId);
+        return async (args, sessionId, context) => {
+            const result = await handler(args, sessionId, context);
             if (result.isError) {
                 return result;
             }
@@ -316,9 +363,29 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
             try {
                 const request = { method: toolName, params: args };
                 const response = { data: result.content };
-                const proof = await proofGenerator.generateProof(request, response, session);
+                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", {
@@ -332,21 +399,59 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
             return result;
         };
     }
-    function wrapWithDelegation(toolName, config, handler) {
-        const legacyUnsafeDelegationEnabled = delegationConfig?.allowLegacyUnsafeDelegation === true;
-        if (legacyUnsafeDelegationEnabled && !warnedLegacyUnsafeDelegation) {
-            warnedLegacyUnsafeDelegation = true;
-            console.warn("⚠️  KYA-OS: allowLegacyUnsafeDelegation=true disables delegation-chain " +
-                "resolution and StatusList revocation checks. This is unsafe for production. " +
-                "See SECURITY.md (Unsafe Delegation Modes).");
+    /**
+     * 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 };
         }
-        if (delegationConfig?.requireAudienceOnRedelegation === false &&
-            !warnedAudienceOptOut) {
-            warnedAudienceOptOut = true;
-            console.warn("⚠️  KYA-OS: requireAudienceOnRedelegation=false disables confused-deputy " +
-                "protection on re-delegations. The default is true as of 1.3.x. " +
-                "See SECURITY.md (Unsafe Delegation Modes).");
+        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"
@@ -416,20 +521,34 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({ error, reason }),
+                    text: JSON.stringify({ error, reason: sanitizeForMessage(reason) }),
                 },
             ],
             isError: true,
         });
         const validateDelegationChain = async (leafCredential, options) => {
+            // Shape guard (validate* never-throw contract): a structurally malformed
+            // leaf returns a { valid, reason } result rather than letting
+            // extractDelegationFromVC OR the downstream scopeSatisfies check throw.
+            // Requires both credentialSubject.delegation AND .constraints (the
+            // verifier's own invariant) — the legacy-unsafe path can reach
+            // scopeSatisfies, which runs OUTSIDE the wrapper's try/catch backstop, so a
+            // constraints-less leaf must be rejected here. A hostile getter/Proxy
+            // accessor still throws → caught by the backstop, by design.
+            const leafDelegationObj = leafCredential?.credentialSubject?.delegation;
+            if (!leafDelegationObj ||
+                typeof leafDelegationObj !== "object" ||
+                !leafDelegationObj.constraints ||
+                typeof leafDelegationObj.constraints !== "object") {
+                return {
+                    valid: false,
+                    reason: "Malformed delegation credential: missing credentialSubject.delegation or its constraints",
+                };
+            }
             const leafDelegation = extractDelegationFromVC(leafCredential);
             let chain = [leafCredential];
             if (leafDelegation.parentId) {
                 if (!delegationConfig?.resolveDelegationChain) {
-                    if (legacyUnsafeDelegationEnabled) {
-                        logger.warn(`[kya-os] Legacy delegation mode enabled: accepting parent-linked credential ${leafDelegation.id} without resolveDelegationChain`);
-                        return { valid: true };
-                    }
                     return {
                         valid: false,
                         reason: `Delegation ${leafDelegation.id} references parent ${leafDelegation.parentId} but no resolveDelegationChain handler is configured`,
@@ -475,21 +594,12 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                 }
                 seenIds.add(delegation.id);
                 if (credential.credentialStatus && !delegationConfig?.statusListResolver) {
-                    if (legacyUnsafeDelegationEnabled) {
-                        logger.warn(`[kya-os] Legacy delegation mode enabled: skipping status-list verification for ${delegation.id}`);
-                    }
-                    else {
-                        return {
-                            valid: false,
-                            reason: `Delegation ${delegation.id} has credentialStatus but no statusListResolver is configured`,
-                        };
-                    }
+                    return {
+                        valid: false,
+                        reason: `Delegation ${delegation.id} has credentialStatus but no statusListResolver is configured`,
+                    };
                 }
-                const skipStatusForLegacy = legacyUnsafeDelegationEnabled &&
-                    !!credential.credentialStatus &&
-                    !delegationConfig?.statusListResolver;
                 const credentialVerification = await verifier.verifyDelegationCredential(credential, {
-                    ...(skipStatusForLegacy ? { skipStatus: true } : {}),
                     ...(options?.skipSignature ? { skipSignature: true } : {}),
                 });
                 if (!credentialVerification.valid) {
@@ -504,21 +614,14 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                         reason: `Delegation ${delegation.id} audience does not include server DID ${identity.did}`,
                     };
                 }
-                // When requireAudienceOnRedelegation is enabled, every non-root
-                // credential in the chain MUST have an audience constraint.
-                // This prevents confused-deputy attacks where re-delegated
-                // credentials are forwarded to unintended servers.
-                //
-                // Defaults to `true`. Set explicitly to `false` to preserve
-                // legacy behavior (logged once per process — see opt-out warning
-                // below).
-                const requireAudienceOnRedelegation = delegationConfig?.requireAudienceOnRedelegation !== false;
-                if (requireAudienceOnRedelegation &&
-                    delegation.parentId &&
-                    !delegation.constraints.audience) {
+                // Every non-root credential in the chain MUST carry an `audience`
+                // constraint binding it to the verifying server. This closes the
+                // confused-deputy class where a re-delegated credential is forwarded
+                // to an unintended server (KYA-OS §11.6). Unconditional as of 1.4.0.
+                if (delegation.parentId && !delegation.constraints.audience) {
                     return {
                         valid: false,
-                        reason: `Delegation ${delegation.id} is a re-delegation (parentId: ${delegation.parentId}) but has no audience constraint. Re-delegations must include an audience when requireAudienceOnRedelegation is enabled`,
+                        reason: `Delegation ${delegation.id} is a re-delegation (parentId: ${delegation.parentId}) but has no audience constraint. Re-delegations MUST include an audience constraint (KYA-OS §11.6)`,
                     };
                 }
                 if (!previousDelegation || !previousCredential) {
@@ -583,9 +686,33 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                     expiresAt,
                     scopes: [config.scopeId],
                 });
-                return {
-                    content: [{ type: "text", text: JSON.stringify(authError) }],
-                };
+                // 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
@@ -595,7 +722,7 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
             if (typeof delegationArg === "string") {
                 const parsed = parseVCJWT(delegationArg);
                 if (!parsed || !parsed.payload.vc) {
-                    return buildDelegationErrorResponse(KYA_OS_ERROR_CODES.delegation_invalid, "Invalid VC-JWT format");
+                    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
@@ -609,20 +736,45 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
             else {
                 vc = delegationArg;
             }
-            // For VC-JWTs, skip the embedded proof/signature check — the JWT
-            // envelope signature is the proof. Basic checks (schema, expiry,
-            // status, scopes) still apply.
-            const verificationResult = await validateDelegationChain(vc, {
-                skipSignature: isVCJWT,
-            });
+            // 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) {
-                logger.warn(`[kya-os] Delegation verification failed for "${toolName}": ${verificationResult.reason}`);
-                return buildDelegationErrorResponse(KYA_OS_ERROR_CODES.delegation_invalid, verificationResult.reason ?? "Unknown delegation validation error");
+                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);
+            }
+            // 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.`);
             }
-            const scopes = getDelegationScopes(vc);
-            if (!scopes.includes(config.scopeId)) {
+            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 buildDelegationErrorResponse(KYA_OS_ERROR_CODES.insufficient_scope, `Required scope "${config.scopeId}" not in delegation scopes`);
+                return attachOutcomeProof(buildDelegationErrorResponse(KYA_OS_ERROR_CODES.insufficient_scope, reason), toolName, args, sessionId, reason);
             }
             // Strip _kyaos_delegation from args before passing to handler
             const cleanArgs = {};
@@ -631,7 +783,93 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
                     cleanArgs[k] = v;
             }
             logger.debug(`[kya-os] Delegation verified for "${toolName}", scope "${config.scopeId}"`);
-            return handler(cleanArgs, sessionId);
+            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) => {
+            const controlKeys = new Set(["_kyaos_delegation", approvalsKey]);
+            const cleanArgs = {};
+            for (const [k, v] of Object.entries(args)) {
+                if (!controlKeys.has(k))
+                    cleanArgs[k] = v;
+            }
+            const namespace = opts.resolveNamespace?.(args) ?? toolName;
+            const risk = classifier.classify({ toolName, namespace });
+            const principal = extractPolicyPrincipal(args["_kyaos_delegation"]);
+            const policyRequest = {
+                principal: {
+                    agentDid: principal.agentDid,
+                    ...(principal.responsibleParty
+                        ? { responsibleParty: principal.responsibleParty }
+                        : {}),
+                },
+                action: { toolName },
+                resource: { namespace },
+                context: {
+                    delegatedScopes: principal.delegatedScopes,
+                    scopeMatched: opts.scopeMatched ?? false,
+                    humanApprovals: [],
+                    ...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);
         };
     }
     return {
@@ -644,6 +882,7 @@ export function createKyaOsMiddleware(config, cryptoProvider) {
         handleHandshake,
         wrapWithProof,
         wrapWithDelegation,
+        withPolicyGate,
     };
 }
 //# sourceMappingURL=with-kya-os.js.map