@kya-os/mcp 1.6.1 → 1.9.0

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

@@ -0,0 +1,175 @@
+/**
+ * KYA-OS Middleware — the delegation gate (`wrapWithDelegation`).
+ *
+ * Requires a valid W3C Delegation Credential (or a durable grant / no-paste
+ * retry), enforces holder-of-key binding (spec §11.8) and scope, then strips the
+ * `_kyaos*` control namespace and runs the handler. Extracted from
+ * `./with-kya-os.ts`; verification plumbing lives in `./with-kya-os.delegation-verify.ts`.
+ */
+import { isHolderBindingApplicable, isKyaOsControlArg, assertHolderBinding, toHolderBindingRequest, } from "../delegation/holder-binding.js";
+import { scopeSatisfies } from "../delegation/scope-matcher.js";
+import { parseVCJWT } from "../delegation/utils.js";
+import { logger } from "../logging/index.js";
+import { KYA_OS_ERROR_CODES } from "../errors.js";
+import { sanitizeForMessage } from "./with-kya-os.helpers.js";
+import { createDelegationVerification, } from "./with-kya-os.delegation-verify.js";
+export function createDelegationGate(deps, wiring) {
+    const { identity, holderBindingMode, holderBindingVerifier } = deps;
+    const { attachOutcomeProof, resolveExistingGrant, bindGrantOnSuccess } = wiring;
+    const { validateDelegationChain, buildDelegationErrorResponse, buildNeedsAuthorizationChallenge, } = createDelegationVerification(deps);
+    function wrapWithDelegation(toolName, config, handler) {
+        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 — sign & return the needs_authorization
+                // challenge. The proof binds a responseHash over the EMITTED challenge
+                // content (incl. the authorizationUrl), so a verifier that recomputes it
+                // over the content it received detects a tampered/MITM-swapped consent
+                // URL. Best-effort: attachOutcomeProof no-ops if no session resolves.
+                const { challengeContent, message } = await buildNeedsAuthorizationChallenge(toolName, config);
+                return attachOutcomeProof({ content: challengeContent }, toolName, args, sessionId, 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 });
+        };
+    }
+    return { wrapWithDelegation };
+}
+//# sourceMappingURL=with-kya-os.delegation-gate.js.map

package/dist/middleware/with-kya-os.delegation-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.delegation-gate.js","sourceRoot":"","sources":["../../src/middleware/with-kya-os.delegation-gate.ts"],"names":[],"mappings":"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"}

package/dist/middleware/with-kya-os.delegation-verify.d.ts

@@ -0,0 +1,51 @@
+/**
+ * KYA-OS Middleware — delegation verification plumbing.
+ *
+ * Builds the DID resolver, the embedded-proof signature verifier, the
+ * `DelegationCredentialVerifier`, and the framework-agnostic chain-validation
+ * adapter (chain-enforcement.ts) once per middleware instance. Extracted from
+ * `wrapWithDelegation` so the gate module holds only the request flow.
+ */
+import { type DelegationCredential, type NeedsAuthorizationError } from "../types/protocol.js";
+import type { KyaOsToolHandler } from "./with-kya-os.types.js";
+import type { MiddlewareDeps } from "./with-kya-os.deps.js";
+/** Per-tool delegation-gate config shared by the gate + its challenge builder. */
+export interface DelegationGateConfig {
+    scopeId: string;
+    consentUrl: string;
+    formatChallenge?: (challenge: NeedsAuthorizationError) => Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+export interface DelegationVerification {
+    /**
+     * Thin adapter over the framework-agnostic core (chain-enforcement.ts): binds
+     * the host's injected verifier + server DID + resolver + the optional
+     * graph-backed RevocationChecker. Returns `{ valid, reason }`, never throws on
+     * normal or structurally-malformed credentials.
+     */
+    validateDelegationChain(leafCredential: DelegationCredential, options?: {
+        skipSignature?: boolean;
+    }): Promise<{
+        valid: boolean;
+        reason?: string;
+    }>;
+    /** A structured `{ error, reason }` tool response with a sanitized reason. */
+    buildDelegationErrorResponse(error: string, reason: string): Awaited<ReturnType<KyaOsToolHandler>>;
+    /**
+     * Build the signed-later `needs_authorization` challenge for a call that
+     * arrived without a delegation or resolvable grant: a fresh resume token, a
+     * 5-minute expiry, and the emitted content (respecting `config.formatChallenge`,
+     * which falls back to the default JSON challenge if it throws).
+     */
+    buildNeedsAuthorizationChallenge(toolName: string, config: DelegationGateConfig): Promise<{
+        challengeContent: Array<{
+            type: "text";
+            text: string;
+        }>;
+        message: string;
+    }>;
+}
+export declare function createDelegationVerification(deps: MiddlewareDeps): DelegationVerification;
+//# sourceMappingURL=with-kya-os.delegation-verify.d.ts.map

package/dist/middleware/with-kya-os.delegation-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.delegation-verify.d.ts","sourceRoot":"","sources":["../../src/middleware/with-kya-os.delegation-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAChB,SAAS,EAAE,uBAAuB,KAC/B,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,uBAAuB,CACrB,cAAc,EAAE,oBAAoB,EACpC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GACpC,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,8EAA8E;IAC9E,4BAA4B,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACzC;;;;;OAKG;IACH,gCAAgC,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC;QACT,gBAAgB,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACxD,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,GACnB,sBAAsB,CAuLxB"}

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

@@ -0,0 +1,165 @@
+/**
+ * KYA-OS Middleware — delegation verification plumbing.
+ *
+ * Builds the DID resolver, the embedded-proof signature verifier, the
+ * `DelegationCredentialVerifier`, and the framework-agnostic chain-validation
+ * adapter (chain-enforcement.ts) once per middleware instance. Extracted from
+ * `wrapWithDelegation` so the gate module holds only the request flow.
+ */
+import { createDidKeyResolver } from "../delegation/did-key-resolver.js";
+import { createDidWebResolver } from "../delegation/did-web-resolver.js";
+import { buildDidResolverRegistry, } from "../delegation/did-resolver-registry.js";
+import { getDidMethod } from "../utils/did-helpers.js";
+import { DelegationCredentialVerifier, } from "../delegation/vc-verifier.js";
+import { validateDelegationChain as validateDelegationChainCore } from "../delegation/chain-enforcement.js";
+import { RuntimeFetchProvider } from "../providers/runtime-fetch.js";
+import { canonicalizeJSON } from "../delegation/utils.js";
+import { base64urlDecodeToBytes, bytesToBase64 } from "../utils/base64.js";
+import { createNeedsAuthorizationError, } from "../types/protocol.js";
+import { logger } from "../logging/index.js";
+import { sanitizeForMessage } from "./with-kya-os.helpers.js";
+export function createDelegationVerification(deps) {
+    const { identity, cryptoProvider, delegationConfig } = deps;
+    const didKeyResolver = createDidKeyResolver();
+    const fetchProvider = delegationConfig?.fetchProvider ??
+        (typeof globalThis.fetch === "function"
+            ? new RuntimeFetchProvider()
+            : undefined);
+    const didWebResolver = fetchProvider
+        ? createDidWebResolver(fetchProvider)
+        : undefined;
+    const configuredDidResolvers = buildDidResolverRegistry(delegationConfig?.didResolvers, fetchProvider);
+    const didResolver = {
+        async resolve(did) {
+            const customResolver = delegationConfig?.didResolver;
+            if (customResolver) {
+                const resolved = await customResolver.resolve(did);
+                if (resolved) {
+                    return resolved;
+                }
+            }
+            const method = getDidMethod(did);
+            const configuredResolver = method ? configuredDidResolvers[method] : undefined;
+            if (configuredResolver) {
+                try {
+                    const resolved = await configuredResolver.resolve(did);
+                    if (resolved) {
+                        return resolved;
+                    }
+                }
+                catch {
+                    return null;
+                }
+            }
+            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,
+    });
+    const validateDelegationChain = (leafCredential, options) => validateDelegationChainCore(leafCredential, {
+        serverDid: identity.did,
+        verifier,
+        resolveDelegationChain: delegationConfig?.resolveDelegationChain,
+        statusListConfigured: !!delegationConfig?.statusListResolver,
+        revocationChecker: delegationConfig?.revocationChecker,
+    }, options);
+    async function buildNeedsAuthorizationChallenge(toolName, config) {
+        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],
+        });
+        // config.formatChallenge lets a server render the challenge (e.g. a markdown
+        // link for LLM clients) BEFORE it is signed, so the proof binds exactly what
+        // the client receives. A throwing hook falls back to the default challenge.
+        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 { challengeContent, message: authError.message };
+    }
+    return {
+        validateDelegationChain,
+        buildDelegationErrorResponse,
+        buildNeedsAuthorizationChallenge,
+    };
+}
+//# sourceMappingURL=with-kya-os.delegation-verify.js.map

package/dist/middleware/with-kya-os.delegation-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.delegation-verify.js","sourceRoot":"","sources":["../../src/middleware/with-kya-os.delegation-verify.ts"],"names":[],"mappings":"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"}

package/dist/middleware/with-kya-os.deps.d.ts

@@ -0,0 +1,40 @@
+/**
+ * KYA-OS Middleware — the internal dependency bag.
+ *
+ * `createKyaOsMiddleware` constructs these collaborators once and threads this
+ * bag into each sub-factory (session/proof, grant-resolution, delegation-gate,
+ * policy-gate). Internal to the middleware package — not part of the public API.
+ */
+import type { CryptoProvider } from "../providers/base.js";
+import type { AuditLogProvider } from "../providers/audit-log.js";
+import type { GrantStore } from "../providers/grant-store.js";
+import type { SessionManager } from "../session/manager.js";
+import type { ProofGenerator, ProofAgentIdentity } from "../proof/generator.js";
+import type { ProofVerifier } from "../proof/verifier.js";
+import type { KyaOsConfig, KyaOsDelegationConfig, KyaOsToolHandler } from "./with-kya-os.types.js";
+/**
+ * Attach a signed proof recording an authorization OUTCOME (denied / step-up /
+ * needs-authorization) to a response. Provided by the session/proof sub-factory
+ * and consumed by the delegation- and policy-gate sub-factories, so it is typed
+ * here as the shared internal contract between them.
+ */
+export type AttachOutcomeProof = (response: Awaited<ReturnType<KyaOsToolHandler>>, toolName: string, args: Record<string, unknown>, sessionId: string | undefined, reason: string, outcome?: "denied" | "step_up_required" | "needs_authorization", paramsOverride?: Record<string, unknown>, responseData?: unknown) => Promise<Awaited<ReturnType<KyaOsToolHandler>>>;
+/** The constructed dependencies shared across the middleware sub-factories. */
+export interface MiddlewareDeps {
+    /** Proof-generation identity (DID + key material). */
+    identity: ProofAgentIdentity;
+    /** The full user config (for `identity.agentName`, `autoSession`, …). */
+    config: KyaOsConfig;
+    cryptoProvider: CryptoProvider;
+    sessionManager: SessionManager;
+    proofGenerator: ProofGenerator;
+    auditLog: AuditLogProvider;
+    grantStore: GrantStore;
+    delegationConfig: KyaOsDelegationConfig | undefined;
+    holderBindingMode: "off" | "warn" | "enforce";
+    /** Present iff holder binding is enabled; the inbound per-request proof verifier. */
+    holderBindingVerifier: ProofVerifier | undefined;
+    /** Mirror the proof under the legacy bare `_meta.proof` key (pre-1.1 back-compat). */
+    emitLegacyProofKey: boolean;
+}
+//# sourceMappingURL=with-kya-os.deps.d.ts.map

package/dist/middleware/with-kya-os.deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.deps.d.ts","sourceRoot":"","sources":["../../src/middleware/with-kya-os.deps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EACV,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,qBAAqB,EAC/D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,YAAY,CAAC,EAAE,OAAO,KACnB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAEpD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,yEAAyE;IACzE,MAAM,EAAE,WAAW,CAAC;IACpB,cAAc,EAAE,cAAc,CAAC;IAC/B,cAAc,EAAE,cAAc,CAAC;IAC/B,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACpD,iBAAiB,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,qFAAqF;IACrF,qBAAqB,EAAE,aAAa,GAAG,SAAS,CAAC;IACjD,sFAAsF;IACtF,kBAAkB,EAAE,OAAO,CAAC;CAC7B"}

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

@@ -0,0 +1,9 @@
+/**
+ * KYA-OS Middleware — the internal dependency bag.
+ *
+ * `createKyaOsMiddleware` constructs these collaborators once and threads this
+ * bag into each sub-factory (session/proof, grant-resolution, delegation-gate,
+ * policy-gate). Internal to the middleware package — not part of the public API.
+ */
+export {};
+//# sourceMappingURL=with-kya-os.deps.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.deps.js","sourceRoot":"","sources":["../../src/middleware/with-kya-os.deps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/middleware/with-kya-os.grants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * KYA-OS Middleware — durable-grant resolution (the no-paste retry).
+ *
+ * Resolves and mints agent-anchored / session-bound authorization grants so a
+ * verified delegation need not be re-pasted on the next call — even on a fresh
+ * instance with empty memory. Extracted from `./with-kya-os.ts`; depends only on
+ * the immutable {@link MiddlewareDeps} (no shared session state).
+ */
+import type { Grant } from "../providers/grant-store.js";
+import type { DelegationCredential } from "../types/protocol.js";
+import type { MiddlewareDeps } from "./with-kya-os.deps.js";
+export interface GrantResolution {
+    /**
+     * 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. Returns undefined to fall through to the
+     * needs_authorization challenge.
+     */
+    resolveExistingGrant(toolName: string, args: Record<string, unknown>, sessionId: string | undefined, scopeId: string): Promise<Grant | 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.
+     */
+    bindGrantOnSuccess(vc: DelegationCredential, delegationArg: unknown, isVCJWT: boolean, sessionId: string | undefined, scopeId: string): Promise<void>;
+}
+export declare function createGrantResolution(deps: MiddlewareDeps): GrantResolution;
+//# sourceMappingURL=with-kya-os.grants.d.ts.map

package/dist/middleware/with-kya-os.grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-kya-os.grants.d.ts","sourceRoot":"","sources":["../../src/middleware/with-kya-os.grants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,oBAAoB,CAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,kBAAkB,CAChB,EAAE,EAAE,oBAAoB,EACxB,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CAiK3E"}