@kya-os/contracts 1.5.3-canary.2 → 1.5.3-canary.21

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

@@ -8,6 +8,31 @@
  * @module @kya-os/contracts/tool-protection
  */
 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.
+ */
+export type AuthorizationRequirement = {
+    type: 'oauth';
+    provider: string;
+    requiredScopes?: string[];
+} | {
+    type: 'mdl';
+    issuer: string;
+    credentialType?: string;
+} | {
+    type: 'idv';
+    provider: string;
+    verificationLevel?: 'basic' | 'enhanced' | 'loa3';
+} | {
+    type: 'credential';
+    credentialType: string;
+    issuer?: string;
+} | {
+    type: 'none';
+};
 /**
  * Tool Protection Definition
  *
@@ -29,6 +54,19 @@ export interface ToolProtection {
      * 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
@@ -37,6 +75,23 @@ export interface ToolProtection {
  * 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
  *
@@ -94,82 +149,477 @@ export interface DelegationRequiredErrorData {
      */
     reason?: string;
 }
+/**
+ * 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<"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<"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<"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<"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<"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<"none">;
+    }, "strip", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        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: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "none";
+    } | 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: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "none";
+    } | 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<"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<"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<"none">;
+    }, "strip", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        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: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "none";
+    } | 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: "mdl";
+        issuer: string;
+        credentialType?: string | undefined;
+    } | {
+        type: "idv";
+        provider: string;
+        verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+    } | {
+        type: "credential";
+        credentialType: string;
+        issuer?: string | undefined;
+    } | {
+        type: "none";
+    } | 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<"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<"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<"none">;
+        }, "strip", z.ZodTypeAny, {
+            type: "none";
+        }, {
+            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: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "none";
+        } | 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: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "none";
+        } | 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: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "none";
+        } | 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: "mdl";
+            issuer: string;
+            credentialType?: string | undefined;
+        } | {
+            type: "idv";
+            provider: string;
+            verificationLevel?: "basic" | "enhanced" | "loa3" | undefined;
+        } | {
+            type: "credential";
+            credentialType: string;
+            issuer?: string | undefined;
+        } | {
+            type: "none";
+        } | undefined;
     }>;
     metadata?: {
-        version?: string | undefined;
         lastUpdated?: string | undefined;
+        version?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }>;
@@ -182,15 +632,15 @@ export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     requiredScopes: string[];
     toolName: string;
-    reason?: string | undefined;
     consentUrl?: string | undefined;
     authorizationUrl?: string | undefined;
+    reason?: string | undefined;
 }, {
     requiredScopes: string[];
     toolName: string;
-    reason?: string | undefined;
     consentUrl?: string | undefined;
     authorizationUrl?: string | undefined;
+    reason?: string | undefined;
 }>;
 /**
  * Type Guards
@@ -199,6 +649,18 @@ 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
+ */
+export declare function hasOAuthAuthorization(protection: ToolProtection): protection is ToolProtection & {
+    authorization: {
+        type: 'oauth';
+    };
+};
 /**
  * Validation Functions
  */
@@ -225,3 +687,17 @@ export declare function getToolRiskLevel(toolName: string, protections: ToolProt
  * 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;