@kya-os/mcp 1.5.0 → 1.6.0

package/dist/authz/oidc/oidc-adapter.js

@@ -0,0 +1,131 @@
+import { base64url } from 'jose';
+import { createNeedsAuthorizationError, } from '../../types/protocol.js';
+import { requirementMatchesAdapter } from '../adapter.js';
+import { buildAuthorizeUrl } from './authorize.js';
+import { computeS256Challenge } from './pkce.js';
+/**
+ * Reference generic-OIDC authorization-server adapter.
+ *
+ * Implements {@link AuthorizationServerAdapter} for a standards-only OpenID
+ * Connect / OAuth 2.1 provider. No named vendor identity provider appears
+ * here; concrete commercial providers are downstream adapters binding the same
+ * port. The pure pieces (authorize URL, PKCE) run inline; the single IdP HTTP
+ * call (token
+ * exchange) goes through an injectable fetch seam, so the adapter is fully
+ * deterministic under test with no network.
+ *
+ * The PKCE code verifier is held server-side keyed by the resume token and is
+ * never placed in the authorization URL — only the S256 challenge travels.
+ */
+export class GenericOidcAdapter {
+    config;
+    type = 'oauth';
+    pending = new Map();
+    fetchImpl;
+    constructor(config) {
+        this.config = config;
+        this.fetchImpl = config.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    isRequired(protection) {
+        return requirementMatchesAdapter(this.type, protection);
+    }
+    async initiateFlow(params) {
+        const requiredScopes = params.protection.requirement.type === 'oauth'
+            ? (params.protection.requirement.requiredScopes ?? this.config.scopes)
+            : this.config.scopes;
+        const scopes = unique([...this.config.scopes, ...requiredScopes]);
+        const codeVerifier = randomToken(32);
+        const codeChallenge = await computeS256Challenge(codeVerifier);
+        const resumeToken = randomToken(24);
+        this.pending.set(resumeToken, {
+            agentDid: params.agentDid,
+            scopes,
+            state: params.state,
+            codeVerifier,
+            redirectUri: params.redirectUri,
+        });
+        const authorizationUrl = buildAuthorizeUrl({
+            authorizationEndpoint: this.config.authorizationEndpoint,
+            clientId: this.config.clientId,
+            redirectUri: params.redirectUri,
+            scopes,
+            state: params.state,
+            codeChallenge,
+            resource: this.config.resource,
+        });
+        return createNeedsAuthorizationError({
+            message: `Authorization required for "${params.protection.toolName}".`,
+            authorizationUrl,
+            resumeToken,
+            expiresAt: nowMs() + (this.config.resumeTokenTtlMs ?? 600_000),
+            scopes,
+        });
+    }
+    async verifyAuthorization(flowState, result) {
+        const pending = this.pending.get(flowState);
+        if (!pending) {
+            return { valid: false, reason: 'unknown or expired resume token' };
+        }
+        const { code, state } = (result ?? {});
+        if (!code) {
+            return { valid: false, reason: 'missing authorization code' };
+        }
+        if (state !== pending.state) {
+            return { valid: false, reason: 'state mismatch' };
+        }
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: pending.redirectUri,
+            client_id: this.config.clientId,
+            code_verifier: pending.codeVerifier,
+        });
+        if (this.config.resource)
+            body.set('resource', this.config.resource);
+        if (this.config.clientSecret)
+            body.set('client_secret', this.config.clientSecret);
+        let token;
+        try {
+            const response = await this.fetchImpl(this.config.tokenEndpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+                body: body.toString(),
+            });
+            if (!response.ok) {
+                return { valid: false, reason: `token endpoint returned ${response.status}` };
+            }
+            token = (await response.json());
+        }
+        catch (error) {
+            return { valid: false, reason: `token exchange failed: ${error.message}` };
+        }
+        // One-time use: a resume token is consumed on verification.
+        this.pending.delete(flowState);
+        const grantedScopes = token.scope ? token.scope.split(' ') : pending.scopes;
+        return {
+            valid: true,
+            credential: {
+                agent_did: pending.agentDid,
+                user_did: '',
+                scopes: grantedScopes,
+                authorization: { type: 'oauth', provider: 'generic-oidc' },
+            },
+        };
+    }
+    /** Test/inspection seam: the pending code verifier for a resume token, if any. */
+    pendingVerifierFor(resumeToken) {
+        return this.pending.get(resumeToken)?.codeVerifier;
+    }
+}
+function randomToken(byteLength) {
+    const bytes = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(bytes);
+    return base64url.encode(bytes);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function nowMs() {
+    return Date.now();
+}
+//# sourceMappingURL=oidc-adapter.js.map

package/dist/authz/oidc/oidc-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-adapter.js","sourceRoot":"","sources":["../../../src/authz/oidc/oidc-adapter.ts"],"names":[],"mappings":"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"}

package/dist/authz/oidc/pkce.d.ts

@@ -0,0 +1,20 @@
+/**
+ * PKCE (RFC 7636), S256 only.
+ *
+ * KYA-OS mandates the S256 challenge method — `plain` is never accepted. These
+ * helpers are runtime-neutral and dependency-free beyond jose's base64url and
+ * the Web Crypto API (available in Node 20+, edge runtimes, and browsers). No
+ * Node-specific import, matching the package's runtime-neutral convention.
+ */
+export type S256 = 'S256';
+/** True only for the S256 challenge method. */
+export declare function isS256ChallengeMethod(method: string): method is S256;
+/** Compute the S256 code challenge for a verifier: BASE64URL(SHA-256(verifier)). */
+export declare function computeS256Challenge(codeVerifier: string): Promise<string>;
+/**
+ * Verify a code verifier against its S256 challenge. Returns false on any
+ * mismatch; never throws. The compare is length-checked and constant-time over
+ * the challenge string.
+ */
+export declare function verifyS256Challenge(codeVerifier: string, codeChallenge: string): Promise<boolean>;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/authz/oidc/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../../src/authz/oidc/pkce.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,IAAI,CAEpE;AAED,oFAAoF;AACpF,wBAAsB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/authz/oidc/pkce.js

@@ -0,0 +1,29 @@
+import { base64url } from 'jose';
+/** True only for the S256 challenge method. */
+export function isS256ChallengeMethod(method) {
+    return method === 'S256';
+}
+/** Compute the S256 code challenge for a verifier: BASE64URL(SHA-256(verifier)). */
+export async function computeS256Challenge(codeVerifier) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier));
+    return base64url.encode(new Uint8Array(digest));
+}
+/**
+ * Verify a code verifier against its S256 challenge. Returns false on any
+ * mismatch; never throws. The compare is length-checked and constant-time over
+ * the challenge string.
+ */
+export async function verifyS256Challenge(codeVerifier, codeChallenge) {
+    const expected = await computeS256Challenge(codeVerifier);
+    return timingSafeEqual(expected, codeChallenge);
+}
+/** Length-checked constant-time string compare. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+//# sourceMappingURL=pkce.js.map

package/dist/authz/oidc/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../../src/authz/oidc/pkce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAajC,+CAA+C;AAC/C,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,MAAM,KAAK,MAAM,CAAC;AAC3B,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,YAAoB;IAC7D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7F,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,YAAoB,EACpB,aAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAC1D,OAAO,eAAe,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAED,mDAAmD;AACnD,SAAS,eAAe,CAAC,CAAS,EAAE,CAAS;IAC3C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/authz/registry.d.ts

@@ -0,0 +1,29 @@
+import type { AuthorizationServerAdapter } from './adapter.js';
+import type { AuthorizationRequirement, ToolProtection } from './requirement.js';
+/**
+ * Routes a tool's protection to exactly one {@link AuthorizationServerAdapter},
+ * keyed by requirement type. Mirrors the provider-registry lifecycle (register
+ * / get / list / resolve / seal) so the authorization seam composes the same
+ * pluggable, sealed way the rest of the protocol does. In-memory and
+ * dependency-free.
+ */
+export declare class AuthorizationServerRegistry {
+    private readonly adapters;
+    private sealed;
+    /** Register an adapter for its requirement type. Throws on duplicate or when sealed. */
+    register(adapter: AuthorizationServerAdapter): void;
+    /** The adapter registered for a requirement type, if any. */
+    get(type: AuthorizationRequirement['type']): AuthorizationServerAdapter | undefined;
+    /** All registered adapters, in registration order. */
+    list(): AuthorizationServerAdapter[];
+    /**
+     * Resolve the adapter that must run for a tool protection. Returns undefined
+     * when the tool needs no authorization (`type: 'none'`) or no adapter is
+     * registered for its requirement type.
+     */
+    resolve(protection: ToolProtection): AuthorizationServerAdapter | undefined;
+    /** Freeze the registry; subsequent registration throws. */
+    seal(): void;
+    isSealed(): boolean;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/authz/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/authz/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEjF;;;;;;GAMG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2E;IACpG,OAAO,CAAC,MAAM,CAAS;IAEvB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,IAAI;IAUnD,6DAA6D;IAC7D,GAAG,CAAC,IAAI,EAAE,wBAAwB,CAAC,MAAM,CAAC,GAAG,0BAA0B,GAAG,SAAS;IAInF,sDAAsD;IACtD,IAAI,IAAI,0BAA0B,EAAE;IAIpC;;;;OAIG;IACH,OAAO,CAAC,UAAU,EAAE,cAAc,GAAG,0BAA0B,GAAG,SAAS;IAM3E,2DAA2D;IAC3D,IAAI,IAAI,IAAI;IAIZ,QAAQ,IAAI,OAAO;CAGpB"}

package/dist/authz/registry.js

@@ -0,0 +1,48 @@
+/**
+ * Routes a tool's protection to exactly one {@link AuthorizationServerAdapter},
+ * keyed by requirement type. Mirrors the provider-registry lifecycle (register
+ * / get / list / resolve / seal) so the authorization seam composes the same
+ * pluggable, sealed way the rest of the protocol does. In-memory and
+ * dependency-free.
+ */
+export class AuthorizationServerRegistry {
+    adapters = new Map();
+    sealed = false;
+    /** Register an adapter for its requirement type. Throws on duplicate or when sealed. */
+    register(adapter) {
+        if (this.sealed) {
+            throw new Error('AuthorizationServerRegistry is sealed; cannot register further adapters.');
+        }
+        if (this.adapters.has(adapter.type)) {
+            throw new Error(`An adapter for type "${adapter.type}" is already registered.`);
+        }
+        this.adapters.set(adapter.type, adapter);
+    }
+    /** The adapter registered for a requirement type, if any. */
+    get(type) {
+        return this.adapters.get(type);
+    }
+    /** All registered adapters, in registration order. */
+    list() {
+        return [...this.adapters.values()];
+    }
+    /**
+     * Resolve the adapter that must run for a tool protection. Returns undefined
+     * when the tool needs no authorization (`type: 'none'`) or no adapter is
+     * registered for its requirement type.
+     */
+    resolve(protection) {
+        if (protection.requirement.type === 'none')
+            return undefined;
+        const adapter = this.adapters.get(protection.requirement.type);
+        return adapter?.isRequired(protection) ? adapter : undefined;
+    }
+    /** Freeze the registry; subsequent registration throws. */
+    seal() {
+        this.sealed = true;
+    }
+    isSealed() {
+        return this.sealed;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/authz/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/authz/registry.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,OAAO,2BAA2B;IACrB,QAAQ,GAAG,IAAI,GAAG,EAAgE,CAAC;IAC5F,MAAM,GAAG,KAAK,CAAC;IAEvB,wFAAwF;IACxF,QAAQ,CAAC,OAAmC;QAC1C,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,CAAC,IAAI,0BAA0B,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,6DAA6D;IAC7D,GAAG,CAAC,IAAsC;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,sDAAsD;IACtD,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,UAA0B;QAChC,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,SAAS,CAAC;QAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/D,OAAO,OAAO,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,CAAC;IAED,2DAA2D;IAC3D,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/authz/requirement.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export declare const AuthorizationRequirementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    provider: z.ZodString;
+    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"mdl">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"idv">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"credential">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"none">;
+}, z.core.$strip>], "type">;
+export type AuthorizationRequirement = z.infer<typeof AuthorizationRequirementSchema>;
+/**
+ * Binds a tool to the authorization it requires. The PEP consults the
+ * requirement before dispatching a tool, and an adapter turns an unmet
+ * requirement into a `needs_authorization` challenge.
+ */
+export declare const ToolProtectionSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    requirement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"mdl">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"idv">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"credential">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
+export type ToolProtection = z.infer<typeof ToolProtectionSchema>;
+//# sourceMappingURL=requirement.d.ts.map

package/dist/authz/requirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement.d.ts","sourceRoot":"","sources":["../../src/authz/requirement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+BxB,eAAO,MAAM,8BAA8B;;;;;;;;;;;;2BAMzC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/authz/requirement.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/**
+ * Authorization requirement vocabulary.
+ *
+ * An {@link AuthorizationRequirement} describes *what kind* of authorization a
+ * tool needs, independent of any concrete authorization server. It is the
+ * neutral input an {@link AuthorizationServerAdapter} dispatches on — the same
+ * separation the policy layer draws between a neutral request and a pluggable
+ * engine. Concrete adapters (a generic-OIDC reference adapter ships in this
+ * package; vendor adapters live downstream) implement the behavior for a given
+ * `type`.
+ *
+ * The variants mirror the authorization methods the protocol anticipates:
+ * `oauth` (an authorization-code/OIDC flow), `mdl` (an ISO mDL presentation),
+ * `idv` (an identity-verification flow), `credential` (a directly held
+ * verifiable credential), and `none` (no authorization required).
+ */
+const oauthRequirement = z.object({
+    type: z.literal('oauth'),
+    /** The provider id an adapter registry resolves to a concrete adapter. */
+    provider: z.string().min(1),
+    /** Scopes the flow must obtain; omitted means the adapter's default set. */
+    requiredScopes: z.array(z.string()).optional(),
+});
+const mdlRequirement = z.object({ type: z.literal('mdl') });
+const idvRequirement = z.object({ type: z.literal('idv') });
+const credentialRequirement = z.object({ type: z.literal('credential') });
+const noneRequirement = z.object({ type: z.literal('none') });
+export const AuthorizationRequirementSchema = z.discriminatedUnion('type', [
+    oauthRequirement,
+    mdlRequirement,
+    idvRequirement,
+    credentialRequirement,
+    noneRequirement,
+]);
+/**
+ * Binds a tool to the authorization it requires. The PEP consults the
+ * requirement before dispatching a tool, and an adapter turns an unmet
+ * requirement into a `needs_authorization` challenge.
+ */
+export const ToolProtectionSchema = z.object({
+    toolName: z.string().min(1),
+    requirement: AuthorizationRequirementSchema,
+});
+//# sourceMappingURL=requirement.js.map

package/dist/authz/requirement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement.js","sourceRoot":"","sources":["../../src/authz/requirement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC5D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC5D,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AAC1E,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE9D,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACzE,gBAAgB;IAChB,cAAc;IACd,cAAc;IACd,qBAAqB;IACrB,eAAe;CAChB,CAAC,CAAC;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,WAAW,EAAE,8BAA8B;CAC5C,CAAC,CAAC"}

package/dist/delegation/chain-enforcement.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Delegation chain enforcement — framework-agnostic core (E3 · #2888).
+ *
+ * The leaf→root chain walk, scope-attenuation, audience binding, confused-deputy
+ * guard (KYA-OS §11.6), and ancestor-revocation rules, lifted out of the
+ * `with-kya-os` middleware closure so the SAME logic runs in every host (MCP
+ * middleware, an HTTP PEP, the conformance harness) against one implementation
+ * rather than a per-transport fork.
+ *
+ * Dependencies are injected as ports (interface-first): a per-credential
+ * verifier, an optional ancestor resolver, and an optional graph-backed
+ * `RevocationChecker`. Nothing here imports a transport or framework.
+ */
+import { type DelegationCredential } from "../types/protocol.js";
+/** Union of a credential's delegation scopes and its constraint scopes. */
+export declare function getDelegationScopes(credential: DelegationCredential): string[];
+/**
+ * A child re-delegation may only narrow (attenuate) its parent's authority.
+ * Enforces flat-scope subset AND crisp-matcher subset (by matcher+resource),
+ * failing closed on any widening. Pure; never throws.
+ */
+export declare function validateScopeAttenuation(parentCredential: DelegationCredential, childCredential: DelegationCredential): {
+    valid: boolean;
+    reason?: string;
+};
+/** Per-credential verifier port (signature / schema / expiry / own status). */
+export interface DelegationCredentialVerifierPort {
+    verifyDelegationCredential(credential: DelegationCredential, options?: {
+        skipSignature?: boolean;
+    }): Promise<{
+        valid: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Graph-backed ancestor-revocation port. The reference adapter is
+ * `CascadingRevocationManager` (./cascading-revocation), whose `isRevoked()`
+ * walks root→target over the delegation graph + StatusList, detecting a
+ * cascade-revoked ANCESTOR independently of how the chain was resolved.
+ *
+ * Wiring this is the E3.1 correctness fix: the prior closure checked only each
+ * credential's OWN `credentialStatus` bit via the resolver, so an ancestor
+ * cascade-revocation that hadn't flipped the leaf's own bit could be missed.
+ */
+export interface RevocationChecker {
+    isRevoked(delegationId: string): Promise<{
+        revoked: boolean;
+        reason?: string;
+        revokedAncestor?: string;
+    }>;
+}
+export interface ChainEnforcementDeps {
+    /** The verifying server's DID — every chain credential's audience must include it. */
+    serverDid: string;
+    /** Per-credential verifier (signature / schema / expiry / own status). */
+    verifier: DelegationCredentialVerifierPort;
+    /**
+     * Resolve ancestor credentials for a re-delegated leaf. May return ancestors
+     * only (root→parent) or the full chain (root→leaf). Required when the leaf has
+     * a `parentId`.
+     */
+    resolveDelegationChain?: (leafCredential: DelegationCredential) => Promise<DelegationCredential[]>;
+    /**
+     * Whether a StatusList resolver is configured downstream. A credential bearing
+     * `credentialStatus` is rejected when false (fail-closed).
+     */
+    statusListConfigured: boolean;
+    /** Optional graph-backed ancestor-revocation check (see {@link RevocationChecker}). */
+    revocationChecker?: RevocationChecker;
+}
+export interface ChainValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Validate a delegation credential and (if re-delegated) its full chain:
+ * structural shape, per-credential verification, audience binding to the server,
+ * the §11.6 re-delegation audience-constraint requirement, parent↔child linkage
+ * (parentId + issuerDid==parent.subjectDid), cycle detection, scope attenuation,
+ * and — when a {@link RevocationChecker} is supplied — graph-backed ancestor
+ * revocation. Never throws on a malformed input; returns `{ valid, reason }`.
+ */
+export declare function validateDelegationChain(leafCredential: DelegationCredential, deps: ChainEnforcementDeps, options?: {
+    skipSignature?: boolean;
+}): Promise<ChainValidationResult>;
+//# sourceMappingURL=chain-enforcement.d.ts.map

package/dist/delegation/chain-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-enforcement.d.ts","sourceRoot":"","sources":["../../src/delegation/chain-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAG9B,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAS9E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,oBAAoB,EACtC,eAAe,EAAE,oBAAoB,GACpC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA8CrC;AAED,+EAA+E;AAC/E,MAAM,WAAW,gCAAgC;IAC/C,0BAA0B,CACxB,UAAU,EAAE,oBAAoB,EAChC,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;CACjD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,gCAAgC,CAAC;IAC3C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,CACvB,cAAc,EAAE,oBAAoB,KACjC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;IACrC;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,cAAc,EAAE,oBAAoB,EACpC,IAAI,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAkLhC"}