@kya-os/contracts 1.7.2 → 1.7.4

package/dist/tool-protection/index.d.ts

@@ -1,23 +1,27 @@
 /**
  * MCP-I Tool Protection Specification
  *
- * This module defines the core tool protection types as specified in the
- * MCP-I protocol. These are pure specification types that define how tools
- * can be protected with delegation requirements and scopes.
+ * 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 (Discriminated Union)
+ * Authorization Requirement - what auth is needed BEFORE consent screen.
  *
- * Defines the type of authorization required for a tool.
- * Extensible design to support OAuth, MDL, IDV, credentials, etc.
+ * 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 = {
     type: 'oauth';
     provider: string;
     requiredScopes?: string[];
+} | {
+    type: 'password';
+    provider: string;
 } | {
     type: 'mdl';
     issuer: string;
@@ -27,12 +31,33 @@ export type AuthorizationRequirement = {
     provider: string;
     verificationLevel?: 'basic' | 'enhanced' | 'loa3';
 } | {
+    /** FUTURE: Require user to present an existing VC (not yet implemented) */
+    type: 'verifiable_credential';
+    credentialType: string;
+    issuer?: string;
+} | {
+    /**
+     * @deprecated Use `verifiable_credential` instead. Kept for backward compatibility.
+     */
     type: 'credential';
     credentialType: string;
     issuer?: string;
 } | {
     type: 'none';
 };
+/** Canonical authorization type values for type safety */
+export declare const AUTHORIZATION_TYPES: {
+    readonly OAUTH: "oauth";
+    readonly PASSWORD: "password";
+    readonly MDL: "mdl";
+    readonly IDV: "idv";
+    /** FUTURE: Not yet implemented */
+    readonly VERIFIABLE_CREDENTIAL: "verifiable_credential";
+    /** @deprecated Use VERIFIABLE_CREDENTIAL */
+    readonly CREDENTIAL: "credential";
+    readonly NONE: "none";
+};
+export type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];
 /**
  * Tool Protection Definition
  *
@@ -176,6 +201,15 @@ export declare const AuthorizationRequirementSchema: z.ZodDiscriminatedUnion<"ty
     type: "oauth";
     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;
@@ -200,6 +234,18 @@ export declare const AuthorizationRequirementSchema: z.ZodDiscriminatedUnion<"ty
     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;
@@ -236,6 +282,15 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "oauth";
         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;
@@ -260,6 +315,18 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         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;
@@ -280,12 +347,17 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "none";
     }>]>>;
 }, "strip", z.ZodTypeAny, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
     authorization?: {
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
     } | {
         type: "mdl";
         issuer: string;
@@ -294,6 +366,10 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "idv";
         provider: string;
         verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
     } | {
         type: "credential";
         credentialType: string;
@@ -301,15 +377,18 @@ export declare const ToolProtectionSchema: z.ZodObject<{
     } | {
         type: "none";
     } | undefined;
-    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-    oauthProvider?: string | undefined;
 }, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
     authorization?: {
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
     } | {
         type: "mdl";
         issuer: string;
@@ -318,6 +397,10 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "idv";
         provider: string;
         verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
     } | {
         type: "credential";
         credentialType: string;
@@ -325,8 +408,6 @@ export declare const ToolProtectionSchema: z.ZodObject<{
     } | {
         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;
@@ -345,6 +426,15 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "oauth";
         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;
@@ -369,6 +459,18 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         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;
@@ -389,12 +491,17 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "none";
     }>]>>;
 }, "strip", z.ZodTypeAny, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
     authorization?: {
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
     } | {
         type: "mdl";
         issuer: string;
@@ -403,6 +510,10 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "idv";
         provider: string;
         verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
     } | {
         type: "credential";
         credentialType: string;
@@ -410,15 +521,18 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
     } | {
         type: "none";
     } | undefined;
-    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-    oauthProvider?: string | undefined;
 }, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    oauthProvider?: string | undefined;
     authorization?: {
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "password";
+        provider: string;
     } | {
         type: "mdl";
         issuer: string;
@@ -427,6 +541,10 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "idv";
         provider: string;
         verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "verifiable_credential";
+        credentialType: string;
+        issuer?: string | undefined;
     } | {
         type: "credential";
         credentialType: string;
@@ -434,8 +552,6 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
     } | {
         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<{
@@ -455,6 +571,15 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             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;
@@ -479,6 +604,18 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             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;
@@ -499,12 +636,17 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "none";
         }>]>>;
     }, "strip", z.ZodTypeAny, {
-        requiresDelegation: boolean;
         requiredScopes: string[];
+        requiresDelegation: boolean;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
         authorization?: {
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
         } | {
             type: "mdl";
             issuer: string;
@@ -513,6 +655,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "idv";
             provider: string;
             verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
         } | {
             type: "credential";
             credentialType: string;
@@ -520,15 +666,18 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             type: "none";
         } | undefined;
-        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-        oauthProvider?: string | undefined;
     }, {
-        requiresDelegation: boolean;
         requiredScopes: string[];
+        requiresDelegation: boolean;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
         authorization?: {
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
         } | {
             type: "mdl";
             issuer: string;
@@ -537,6 +686,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "idv";
             provider: string;
             verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
         } | {
             type: "credential";
             credentialType: string;
@@ -544,30 +697,33 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             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;
+        version?: string | undefined;
         source?: string | undefined;
     }, {
-        version?: string | undefined;
         lastUpdated?: string | undefined;
+        version?: string | undefined;
         source?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     toolProtections: Record<string, {
-        requiresDelegation: boolean;
         requiredScopes: string[];
+        requiresDelegation: boolean;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
         authorization?: {
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
         } | {
             type: "mdl";
             issuer: string;
@@ -576,6 +732,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "idv";
             provider: string;
             verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
         } | {
             type: "credential";
             credentialType: string;
@@ -583,22 +743,25 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             type: "none";
         } | undefined;
-        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-        oauthProvider?: string | undefined;
     }>;
     metadata?: {
-        version?: string | undefined;
         lastUpdated?: string | undefined;
+        version?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }, {
     toolProtections: Record<string, {
-        requiresDelegation: boolean;
         requiredScopes: string[];
+        requiresDelegation: boolean;
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+        oauthProvider?: string | undefined;
         authorization?: {
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "password";
+            provider: string;
         } | {
             type: "mdl";
             issuer: string;
@@ -607,6 +770,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "idv";
             provider: string;
             verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "verifiable_credential";
+            credentialType: string;
+            issuer?: string | undefined;
         } | {
             type: "credential";
             credentialType: string;
@@ -614,12 +781,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             type: "none";
         } | undefined;
-        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-        oauthProvider?: string | undefined;
     }>;
     metadata?: {
-        version?: string | undefined;
         lastUpdated?: string | undefined;
+        version?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }>;
@@ -632,15 +797,15 @@ export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     requiredScopes: string[];
     toolName: string;
+    consentUrl?: string | undefined;
     authorizationUrl?: string | undefined;
     reason?: string | undefined;
-    consentUrl?: string | undefined;
 }, {
     requiredScopes: string[];
     toolName: string;
+    consentUrl?: string | undefined;
     authorizationUrl?: string | undefined;
     reason?: string | undefined;
-    consentUrl?: string | undefined;
 }>;
 /**
  * Type Guards
@@ -661,6 +826,23 @@ export declare function hasOAuthAuthorization(protection: ToolProtection): prote
         type: 'oauth';
     };
 };
+/**
+ * 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
+ * Handles both 'verifiable_credential' and legacy 'credential' types
+ */
+export declare function hasVerifiableCredentialAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'verifiable_credential' | 'credential';
+    };
+};
 /**
  * Validation Functions
  */
@@ -701,3 +883,49 @@ export declare function createDelegationRequiredError(toolName: string, required
  * // 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;
+/**
+ * Normalize authorization requirement to use canonical type names
+ *
+ * Migrates legacy 'credential' type to 'verifiable_credential'
+ * This ensures consistent type usage across the codebase.
+ *
+ * @param auth - The authorization requirement (may have legacy type)
+ * @returns Normalized authorization requirement with canonical type
+ */
+export declare function normalizeAuthorizationType(auth: AuthorizationRequirement): AuthorizationRequirement;
+/**
+ * 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;