@kya-os/contracts 1.7.2 → 1.7.3

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

@@ -12,12 +12,25 @@ import { z } from 'zod';
  * Authorization Requirement (Discriminated Union)
  *
  * Defines the type of authorization required for a tool.
- * Extensible design to support OAuth, MDL, IDV, credentials, etc.
+ * Extensible design to support OAuth, password auth, MDL, IDV, verifiable credentials, etc.
+ *
+ * ## Type Naming Clarification
+ *
+ * - `oauth` - OAuth 2.0 provider authentication (GitHub, Google, etc.)
+ * - `password` - Username/password or API key authentication (HardwareWorld, etc.)
+ * - `verifiable_credential` - W3C Verifiable Credential requirement (preferred)
+ * - `credential` - **DEPRECATED** alias for `verifiable_credential` (for backward compatibility)
+ * - `mdl` - Mobile Driver's License (ISO 18013-5)
+ * - `idv` - Identity Verification provider (Stripe, Onfido, etc.)
+ * - `none` - Consent-only (clickwrap agreement, no authentication)
  */
 export type AuthorizationRequirement = {
     type: 'oauth';
     provider: string;
     requiredScopes?: string[];
+} | {
+    type: 'password';
+    provider: string;
 } | {
     type: 'mdl';
     issuer: string;
@@ -27,12 +40,40 @@ export type AuthorizationRequirement = {
     provider: string;
     verificationLevel?: 'basic' | 'enhanced' | 'loa3';
 } | {
+    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
+ * Use these constants instead of string literals for type safety
+ */
+export declare const AUTHORIZATION_TYPES: {
+    /** OAuth 2.0 provider authentication */
+    readonly OAUTH: "oauth";
+    /** Username/password or API key authentication */
+    readonly PASSWORD: "password";
+    /** Mobile Driver's License (ISO 18013-5) */
+    readonly MDL: "mdl";
+    /** Identity Verification provider */
+    readonly IDV: "idv";
+    /** W3C Verifiable Credential requirement (preferred) */
+    readonly VERIFIABLE_CREDENTIAL: "verifiable_credential";
+    /** @deprecated Use VERIFIABLE_CREDENTIAL instead */
+    readonly CREDENTIAL: "credential";
+    /** Consent-only (clickwrap agreement) */
+    readonly NONE: "none";
+};
+export type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];
 /**
  * Tool Protection Definition
  *
@@ -176,6 +217,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 +250,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 +298,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 +331,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 +363,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 +382,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 +393,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 +413,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 +424,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 +442,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 +475,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 +507,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 +526,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 +537,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 +557,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 +568,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 +587,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 +620,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 +652,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 +671,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 +682,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 +702,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 +713,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 +748,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 +759,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 +786,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 +797,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 +813,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 +842,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 +899,62 @@ 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
+ *
+ * These constants define the authentication method used during consent:
+ * - NONE: Consent-only mode (clickwrap) - user agrees without authentication
+ * - OAUTH2: OAuth provider authentication (GitHub, Google, etc.)
+ * - PASSWORD: Password-based authentication (email/password, username/password)
+ * - CREDENTIAL: Alias for PASSWORD (legacy compatibility)
+ * - MAGIC_LINK: Email magic link authentication
+ * - OTP: One-time password authentication
+ *
+ * NOTE: This is distinct from AUTHORIZATION_TYPES which define what a TOOL requires.
+ * CONSENT_PROVIDER_TYPES define what authentication method the USER 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;