@kya-os/cli 2.0.0 → 2.0.2

package/node_modules/@kya-os/contracts/dist/tool-protection/index.d.ts

@@ -0,0 +1,1369 @@
+/**
+ * MCP-I Tool Protection Specification
+ *
+ * Core types for tool protection with delegation requirements.
+ *
+ * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).
+ * DelegationCredential (VC) is created when user confirms on Consent Screen.
+ *
+ * @module @kya-os/contracts/tool-protection
+ */
+import { z } from 'zod';
+/**
+ * Authorization Requirement - what auth is needed BEFORE consent screen.
+ *
+ * Types: none (2 screens), oauth/password/mdl/idv (3 screens), verifiable_credential (future).
+ * The VC output is always a DelegationCredential created on consent confirmation.
+ */
+export type AuthorizationRequirement = {
+    /**
+     * @deprecated Use 'oauth2' instead. Will be removed in v2.0.0.
+     */
+    type: 'oauth';
+    provider: string;
+    requiredScopes?: string[];
+} | {
+    /** OAuth 2.0 provider authentication (canonical) */
+    type: 'oauth2';
+    provider: string;
+    requiredScopes?: string[];
+} | {
+    type: 'password';
+    provider: string;
+} | {
+    type: 'mdl';
+    issuer: string;
+    credentialType?: string;
+} | {
+    type: 'idv';
+    provider: string;
+    verificationLevel?: 'basic' | 'enhanced' | 'loa3';
+} | {
+    /** Require user to present an existing VC */
+    type: 'verifiable_credential';
+    credentialType: string;
+    issuer?: string;
+} | {
+    /**
+     * @deprecated Use 'verifiable_credential' instead. Will be removed in v2.0.0.
+     * This is an alias for 'verifiable_credential' for backward compatibility.
+     */
+    type: 'credential';
+    credentialType: string;
+    issuer?: string;
+} | {
+    /** WebAuthn/Passkey authentication */
+    type: 'webauthn';
+    rpId?: string;
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+} | {
+    /** Sign-In with Ethereum (EIP-4361) */
+    type: 'siwe';
+    chainId?: number;
+    domain?: string;
+} | {
+    /** API Key from per-user vault */
+    type: 'apikey';
+    envVarNames: string[];
+    headerMapping: Record<string, string>;
+} | {
+    type: 'none';
+};
+/** Canonical authorization type values for type safety */
+export declare const AUTHORIZATION_TYPES: {
+    /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */
+    readonly OAUTH: "oauth";
+    /** OAuth 2.0 provider authentication (canonical) */
+    readonly OAUTH2: "oauth2";
+    readonly PASSWORD: "password";
+    readonly MDL: "mdl";
+    readonly IDV: "idv";
+    readonly VERIFIABLE_CREDENTIAL: "verifiable_credential";
+    /** WebAuthn/Passkey authentication */
+    readonly WEBAUTHN: "webauthn";
+    /** Sign-In with Ethereum (EIP-4361) */
+    readonly SIWE: "siwe";
+    /** API Key from per-user vault */
+    readonly APIKEY: "apikey";
+    readonly NONE: "none";
+};
+export type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];
+/**
+ * Tool Protection Definition
+ *
+ * Defines the protection requirements for a tool as per MCP-I spec.
+ * This is the canonical definition that all implementations must follow.
+ */
+export interface ToolProtection {
+    /**
+     * Whether this tool requires explicit delegation from the user
+     */
+    requiresDelegation: boolean;
+    /**
+     * The scopes required to execute this tool
+     * Format: "resource:action" (e.g., "files:read", "payment:send")
+     */
+    requiredScopes: string[];
+    /**
+     * Risk level classification for the tool
+     * Used to determine appropriate authorization flows
+     */
+    riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * OAuth provider name for this tool (Phase 2+)
+     * If specified, this tool will use the specified OAuth provider.
+     * If not specified, provider will be resolved via fallback strategies.
+     * @example "github", "google", "microsoft"
+     * @deprecated Use `authorization` field instead. Will be removed in Phase 3.
+     */
+    oauthProvider?: string;
+    /**
+     * Authorization requirement for this tool
+     * If requiresDelegation=true, authorization must be specified (or inferred from legacy fields)
+     */
+    authorization?: AuthorizationRequirement;
+}
+/**
+ * Tool Protection Map
+ *
+ * A mapping of tool names to their protection configurations.
+ * This is how tool protections are typically stored and transmitted.
+ */
+export type ToolProtectionMap = Record<string, ToolProtection>;
+/**
+ * Partial tool protection for updates (all fields optional)
+ * Use this when accepting partial updates to tool protection settings
+ */
+export type PartialToolProtection = Partial<ToolProtection>;
+/**
+ * Tool protection with explicit optional fields
+ * Useful when TypeScript's Partial<T> doesn't preserve optional property access
+ * Supports explicit null values to clear fields
+ */
+export type ToolProtectionUpdate = {
+    requiresDelegation?: boolean;
+    requiredScopes?: string[];
+    riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+    oauthProvider?: string | null;
+    authorization?: AuthorizationRequirement | null;
+};
+/**
+ * Tool Protection Response
+ *
+ * The response format when querying for tool protections.
+ * Used by tool protection services and APIs.
+ */
+export interface ToolProtectionResponse {
+    /**
+     * The tool protections keyed by tool name
+     */
+    toolProtections: ToolProtectionMap;
+    /**
+     * Optional metadata about the response
+     */
+    metadata?: {
+        /**
+         * When this configuration was last updated
+         */
+        lastUpdated?: string;
+        /**
+         * Version of the configuration
+         */
+        version?: string;
+        /**
+         * Source of the configuration
+         */
+        source?: string;
+    };
+}
+/**
+ * Delegation Required Error Data
+ *
+ * The standardized error data returned when a tool requires delegation
+ * but none was provided. This is part of the MCP-I error protocol.
+ */
+export interface DelegationRequiredErrorData {
+    /**
+     * The name of the tool that requires delegation
+     */
+    toolName: string;
+    /**
+     * The scopes required for this tool
+     */
+    requiredScopes: string[];
+    /**
+     * URL where the user can provide consent/delegation
+     */
+    consentUrl?: string;
+    /**
+     * Alternative field for consent URL (for compatibility)
+     */
+    authorizationUrl?: string;
+    /**
+     * Additional context about why delegation is required
+     */
+    reason?: string;
+}
+/**
+ * Auth Required Error Data
+ *
+ * Machine-readable error returned when a tool requires per-user auth
+ * (vault secret, OAuth, credential) but none is configured and no
+ * static env fallback exists. MCP clients use this to present
+ * actionable guidance (e.g., "Add your PulseMCP API key" with a link).
+ *
+ * Closes VAULT-11
+ */
+export interface AuthRequiredErrorData {
+    /** Discriminator — always "auth_required" */
+    error: 'auth_required';
+    /** Which auth mechanism is missing */
+    type: 'apikey' | 'oauth' | 'credential';
+    /** For apikey: which env vars are missing */
+    envVarNames?: string[];
+    /** Dashboard URL where the user can configure the missing auth */
+    configUrl: string;
+    /** Human-readable fallback message */
+    message: string;
+}
+export declare const AuthRequiredErrorDataSchema: z.ZodObject<{
+    error: z.ZodLiteral<"auth_required">;
+    type: z.ZodEnum<["apikey", "oauth", "credential"]>;
+    envVarNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    configUrl: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    type: "credential" | "oauth" | "apikey";
+    error: "auth_required";
+    configUrl: string;
+    envVarNames?: string[] | undefined;
+}, {
+    message: string;
+    type: "credential" | "oauth" | "apikey";
+    error: "auth_required";
+    configUrl: string;
+    envVarNames?: string[] | undefined;
+}>;
+/**
+ * Error class thrown when required auth is missing and no fallback exists.
+ *
+ * Caught by the tool-call handler in agent.ts and serialized as a
+ * machine-readable MCP tool result so clients can present actionable UI.
+ */
+export declare class AuthRequiredError extends Error {
+    readonly type: AuthRequiredErrorData['type'];
+    readonly envVarNames?: string[];
+    readonly configUrl: string;
+    constructor(opts: {
+        type: AuthRequiredErrorData['type'];
+        envVarNames?: string[];
+        configUrl: string;
+        message?: string;
+    });
+    /** Serialize to the wire format MCP clients expect */
+    toJSON(): AuthRequiredErrorData;
+}
+/**
+ * Legacy tool protection format (pre-authorization field)
+ * Used during migration period to support both old and new formats
+ */
+export type LegacyToolProtection = Omit<ToolProtection, 'authorization'> & {
+    oauthProvider?: string;
+};
+/**
+ * Union type for both legacy and new formats
+ * Useful during migration period when accepting tool protection input
+ */
+export type ToolProtectionInput = ToolProtection | LegacyToolProtection;
+/**
+ * Zod Schemas for Validation
+ */
+export declare const AuthorizationRequirementSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    provider: z.ZodString;
+    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "oauth";
+    provider: string;
+    requiredScopes?: string[] | undefined;
+}, {
+    type: "oauth";
+    provider: string;
+    requiredScopes?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"oauth2">;
+    provider: z.ZodString;
+    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "oauth2";
+    provider: string;
+    requiredScopes?: string[] | undefined;
+}, {
+    type: "oauth2";
+    provider: string;
+    requiredScopes?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"password">;
+    provider: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "password";
+    provider: string;
+}, {
+    type: "password";
+    provider: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"mdl">;
+    issuer: z.ZodString;
+    credentialType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "mdl";
+    issuer: string;
+    credentialType?: string | undefined;
+}, {
+    type: "mdl";
+    issuer: string;
+    credentialType?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"idv">;
+    provider: z.ZodString;
+    verificationLevel: z.ZodOptional<z.ZodEnum<["basic", "enhanced", "loa3"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "idv";
+    provider: string;
+    verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+}, {
+    type: "idv";
+    provider: string;
+    verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"verifiable_credential">;
+    credentialType: z.ZodString;
+    issuer: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "verifiable_credential";
+    credentialType: string;
+    issuer?: string | undefined;
+}, {
+    type: "verifiable_credential";
+    credentialType: string;
+    issuer?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"credential">;
+    credentialType: z.ZodString;
+    issuer: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "credential";
+    credentialType: string;
+    issuer?: string | undefined;
+}, {
+    type: "credential";
+    credentialType: string;
+    issuer?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"webauthn">;
+    rpId: z.ZodOptional<z.ZodString>;
+    userVerification: z.ZodOptional<z.ZodEnum<["required", "preferred", "discouraged"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "webauthn";
+    rpId?: string | undefined;
+    userVerification?: "required" | "preferred" | "discouraged" | undefined;
+}, {
+    type: "webauthn";
+    rpId?: string | undefined;
+    userVerification?: "required" | "preferred" | "discouraged" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"siwe">;
+    chainId: z.ZodOptional<z.ZodNumber>;
+    domain: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "siwe";
+    chainId?: number | undefined;
+    domain?: string | undefined;
+}, {
+    type: "siwe";
+    chainId?: number | undefined;
+    domain?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"apikey">;
+    envVarNames: z.ZodArray<z.ZodString, "many">;
+    headerMapping: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "apikey";
+    envVarNames: string[];
+    headerMapping: Record<string, string>;
+}, {
+    type: "apikey";
+    envVarNames: string[];
+    headerMapping: Record<string, string>;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"none">;
+}, "strip", z.ZodTypeAny, {
+    type: "none";
+}, {
+    type: "none";
+}>]>;
+export declare const ToolProtectionSchema: z.ZodObject<{
+    requiresDelegation: z.ZodBoolean;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+    oauthProvider: z.ZodOptional<z.ZodString>;
+    authorization: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"password">;
+        provider: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "password";
+        provider: string;
+    }, {
+        type: "password";
+        provider: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"mdl">;
+        issuer: z.ZodString;
+        credentialType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    }, {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"idv">;
+        provider: z.ZodString;
+        verificationLevel: z.ZodOptional<z.ZodEnum<["basic", "enhanced", "loa3"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    }, {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"verifiable_credential">;
+        credentialType: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }, {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"credential">;
+        credentialType: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }, {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"webauthn">;
+        rpId: z.ZodOptional<z.ZodString>;
+        userVerification: z.ZodOptional<z.ZodEnum<["required", "preferred", "discouraged"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    }, {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"siwe">;
+        chainId: z.ZodOptional<z.ZodNumber>;
+        domain: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    }, {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"apikey">;
+        envVarNames: z.ZodArray<z.ZodString, "many">;
+        headerMapping: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    }, {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, "strip", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        type: "none";
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    authorization?: {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
+    } | {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    } | {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    } | {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    } | {
+        type: "none";
+    } | undefined;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
+}, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    authorization?: {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
+    } | {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    } | {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    } | {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    } | {
+        type: "none";
+    } | undefined;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
+}>;
+export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    requiresDelegation: z.ZodBoolean;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+    oauthProvider: z.ZodOptional<z.ZodString>;
+    authorization: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"password">;
+        provider: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "password";
+        provider: string;
+    }, {
+        type: "password";
+        provider: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"mdl">;
+        issuer: z.ZodString;
+        credentialType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    }, {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"idv">;
+        provider: z.ZodString;
+        verificationLevel: z.ZodOptional<z.ZodEnum<["basic", "enhanced", "loa3"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    }, {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"verifiable_credential">;
+        credentialType: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }, {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"credential">;
+        credentialType: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }, {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"webauthn">;
+        rpId: z.ZodOptional<z.ZodString>;
+        userVerification: z.ZodOptional<z.ZodEnum<["required", "preferred", "discouraged"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    }, {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"siwe">;
+        chainId: z.ZodOptional<z.ZodNumber>;
+        domain: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    }, {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"apikey">;
+        envVarNames: z.ZodArray<z.ZodString, "many">;
+        headerMapping: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    }, {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, "strip", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        type: "none";
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    authorization?: {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
+    } | {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    } | {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    } | {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    } | {
+        type: "none";
+    } | undefined;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
+}, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    authorization?: {
+        type: "oauth";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
+    } | {
+        type: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "webauthn";
+        rpId?: string | undefined;
+        userVerification?: "required" | "preferred" | "discouraged" | undefined;
+    } | {
+        type: "siwe";
+        chainId?: number | undefined;
+        domain?: string | undefined;
+    } | {
+        type: "apikey";
+        envVarNames: string[];
+        headerMapping: Record<string, string>;
+    } | {
+        type: "none";
+    } | undefined;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
+}>>;
+export declare const ToolProtectionResponseSchema: z.ZodObject<{
+    toolProtections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        requiresDelegation: z.ZodBoolean;
+        requiredScopes: z.ZodArray<z.ZodString, "many">;
+        riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+        oauthProvider: z.ZodOptional<z.ZodString>;
+        authorization: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            provider: z.ZodString;
+            requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        }, {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"oauth2">;
+            provider: z.ZodString;
+            requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        }, {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"password">;
+            provider: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: "password";
+            provider: string;
+        }, {
+            type: "password";
+            provider: string;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"mdl">;
+            issuer: z.ZodString;
+            credentialType: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        }, {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"idv">;
+            provider: z.ZodString;
+            verificationLevel: z.ZodOptional<z.ZodEnum<["basic", "enhanced", "loa3"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        }, {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"verifiable_credential">;
+            credentialType: z.ZodString;
+            issuer: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        }, {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"credential">;
+            credentialType: z.ZodString;
+            issuer: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        }, {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"webauthn">;
+            rpId: z.ZodOptional<z.ZodString>;
+            userVerification: z.ZodOptional<z.ZodEnum<["required", "preferred", "discouraged"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        }, {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"siwe">;
+            chainId: z.ZodOptional<z.ZodNumber>;
+            domain: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        }, {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"apikey">;
+            envVarNames: z.ZodArray<z.ZodString, "many">;
+            headerMapping: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        }, {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"none">;
+        }, "strip", z.ZodTypeAny, {
+            type: "none";
+        }, {
+            type: "none";
+        }>]>>;
+    }, "strip", z.ZodTypeAny, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        authorization?: {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
+        } | {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        } | {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        } | {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        } | {
+            type: "none";
+        } | undefined;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
+    }, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        authorization?: {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
+        } | {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        } | {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        } | {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        } | {
+            type: "none";
+        } | undefined;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        lastUpdated: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    }, {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    toolProtections: Record<string, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        authorization?: {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
+        } | {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        } | {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        } | {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        } | {
+            type: "none";
+        } | undefined;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
+    }>;
+    metadata?: {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    } | undefined;
+}, {
+    toolProtections: Record<string, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        authorization?: {
+            type: "oauth";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
+        } | {
+            type: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "webauthn";
+            rpId?: string | undefined;
+            userVerification?: "required" | "preferred" | "discouraged" | undefined;
+        } | {
+            type: "siwe";
+            chainId?: number | undefined;
+            domain?: string | undefined;
+        } | {
+            type: "apikey";
+            envVarNames: string[];
+            headerMapping: Record<string, string>;
+        } | {
+            type: "none";
+        } | undefined;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
+    }>;
+    metadata?: {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    } | undefined;
+}>;
+export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    consentUrl: z.ZodOptional<z.ZodString>;
+    authorizationUrl: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    requiredScopes: string[];
+    authorizationUrl?: string | undefined;
+    reason?: string | undefined;
+    consentUrl?: string | undefined;
+}, {
+    toolName: string;
+    requiredScopes: string[];
+    authorizationUrl?: string | undefined;
+    reason?: string | undefined;
+    consentUrl?: string | undefined;
+}>;
+/**
+ * Type Guards
+ */
+export declare function isToolProtection(obj: any): obj is ToolProtection;
+export declare function isToolProtectionMap(obj: any): obj is ToolProtectionMap;
+export declare function isToolProtectionResponse(obj: any): obj is ToolProtectionResponse;
+export declare function isDelegationRequiredErrorData(obj: any): obj is DelegationRequiredErrorData;
+/**
+ * Type guard to check if an object is a valid AuthorizationRequirement
+ */
+export declare function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement;
+/**
+ * Type guard to check if a ToolProtection has OAuth authorization
+ * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)
+ */
+export declare function hasOAuthAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'oauth' | 'oauth2';
+    };
+};
+/**
+ * Type guard to check if a ToolProtection has password authorization
+ */
+export declare function hasPasswordAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'password';
+    };
+};
+/**
+ * Type guard to check if a ToolProtection requires a Verifiable Credential
+ *
+ * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)
+ */
+export declare function hasVerifiableCredentialAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'verifiable_credential' | 'credential';
+    };
+};
+/**
+ * Type guard to check if a ToolProtection has API Key (vault) authorization
+ */
+export declare function hasApiKeyAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'apikey';
+    };
+};
+/**
+ * Validation Functions
+ */
+export declare function validateToolProtection(obj: any): ToolProtection;
+export declare function validateToolProtectionMap(obj: any): ToolProtectionMap;
+export declare function validateToolProtectionResponse(obj: any): ToolProtectionResponse;
+export declare function validateDelegationRequiredErrorData(obj: any): DelegationRequiredErrorData;
+/**
+ * Utility Functions
+ */
+/**
+ * Check if a tool requires delegation
+ */
+export declare function toolRequiresDelegation(toolName: string, protections: ToolProtectionMap): boolean;
+/**
+ * Get required scopes for a tool
+ */
+export declare function getToolRequiredScopes(toolName: string, protections: ToolProtectionMap): string[];
+/**
+ * Get risk level for a tool
+ */
+export declare function getToolRiskLevel(toolName: string, protections: ToolProtectionMap): ToolProtection['riskLevel'] | undefined;
+/**
+ * Create a delegation required error
+ */
+export declare function createDelegationRequiredError(toolName: string, requiredScopes: string[], consentUrl?: string): DelegationRequiredErrorData;
+/**
+ * Normalize tool protection configuration
+ * Migrates legacy oauthProvider field to authorization object
+ *
+ * - Migrates `oauthProvider` → `authorization: { type: 'oauth', provider: ... }`
+ * - Ensures `authorization` field is present when `requiresDelegation=true`
+ * - Returns fully normalized ToolProtection object
+ *
+ * @param raw - Raw tool protection data (may have legacy fields or be partial)
+ * @returns Normalized ToolProtection object
+ *
+ * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
+ */
+export declare function normalizeToolProtection(raw: ToolProtection | PartialToolProtection): ToolProtection;
+/** Consent provider types - stored in delegation metadata to track auth method used */
+export declare const CONSENT_PROVIDER_TYPES: {
+    /** Consent-only mode - no authentication, just clickwrap agreement */
+    readonly NONE: "none";
+    /** OAuth2 provider authentication */
+    readonly OAUTH2: "oauth2";
+    /** Password-based authentication (email/password, username/password) */
+    readonly PASSWORD: "password";
+    /** @deprecated Use PASSWORD instead. Alias for backward compatibility */
+    readonly CREDENTIAL: "credential";
+    /** Email magic link authentication */
+    readonly MAGIC_LINK: "magic_link";
+    /** One-time password (SMS/email code) */
+    readonly OTP: "otp";
+};
+export type ConsentProviderType = (typeof CONSENT_PROVIDER_TYPES)[keyof typeof CONSENT_PROVIDER_TYPES];
+/**
+ * Determine consent provider type based on available identity information
+ *
+ * This is the single source of truth for consent provider type determination.
+ *
+ * @param hasOAuthIdentity - Whether OAuth identity is available
+ * @param isPasswordFlow - Whether this is a password/credential flow
+ * @param isMagicLinkFlow - Whether this is a magic link flow
+ * @param isOtpFlow - Whether this is an OTP flow
+ * @returns The consent provider type
+ */
+export declare function determineConsentProviderType(hasOAuthIdentity: boolean, isPasswordFlow?: boolean, isMagicLinkFlow?: boolean, isOtpFlow?: boolean): ConsentProviderType;
+/**
+ * Get a human-readable label for an authorization requirement type
+ */
+export declare function getAuthorizationTypeLabel(auth: AuthorizationRequirement): string;
+/**
+ * Get a unique key for an authorization requirement (for React keys, caching, etc.)
+ */
+export declare function getAuthorizationTypeKey(auth: AuthorizationRequirement): string;
+/**
+ * Normalize authorization requirement type
+ *
+ * Normalizes deprecated types to their canonical equivalents:
+ * - 'oauth' → 'oauth2'
+ * - 'credential' → 'verifiable_credential'
+ *
+ * This function should be called at runtime boundaries when processing
+ * authorization requirements.
+ *
+ * @param auth - Authorization requirement (may contain deprecated types)
+ * @param options - Normalization options
+ * @returns Normalized authorization requirement
+ *
+ * @example
+ * ```typescript
+ * const normalized = normalizeAuthorizationType(
+ *   { type: 'oauth', provider: 'github' },
+ *   { warn: true }
+ * );
+ * // Returns: { type: 'oauth2', provider: 'github' }
+ * // Logs: DEPRECATION warning
+ * ```
+ */
+export declare function normalizeAuthorizationType(auth: AuthorizationRequirement, options?: {
+    warn?: boolean;
+    logger?: (message: string) => void;
+}): AuthorizationRequirement;