@kya-os/contracts 1.5.3-canary.16 → 1.5.3-canary.17

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
  *
@@ -34,8 +59,14 @@ export interface ToolProtection {
      * 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
@@ -104,37 +135,278 @@ export interface DelegationRequiredErrorData {
 /**
  * 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<{
@@ -142,16 +414,109 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         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>;
@@ -168,10 +533,29 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
     }>>;
 }, "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?: {
         lastUpdated?: string | undefined;
@@ -180,10 +564,29 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
     } | 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?: {
         lastUpdated?: string | undefined;
@@ -243,3 +646,10 @@ 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
+ *
+ * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
+ */
+export declare function normalizeToolProtection(raw: ToolProtection): ToolProtection;

package/dist/tool-protection/index.js

@@ -9,7 +9,7 @@
  * @module @kya-os/contracts/tool-protection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = void 0;
+exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = exports.AuthorizationRequirementSchema = void 0;
 exports.isToolProtection = isToolProtection;
 exports.isToolProtectionMap = isToolProtectionMap;
 exports.isToolProtectionResponse = isToolProtectionResponse;
@@ -22,15 +22,42 @@ exports.toolRequiresDelegation = toolRequiresDelegation;
 exports.getToolRequiredScopes = getToolRequiredScopes;
 exports.getToolRiskLevel = getToolRiskLevel;
 exports.createDelegationRequiredError = createDelegationRequiredError;
+exports.normalizeToolProtection = normalizeToolProtection;
 const zod_1 = require("zod");
 /**
  * Zod Schemas for Validation
  */
+exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({
+        type: zod_1.z.literal('oauth'),
+        provider: zod_1.z.string(),
+        requiredScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('mdl'),
+        issuer: zod_1.z.string(),
+        credentialType: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('idv'),
+        provider: zod_1.z.string(),
+        verificationLevel: zod_1.z.enum(['basic', 'enhanced', 'loa3']).optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('credential'),
+        credentialType: zod_1.z.string(),
+        issuer: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('none'),
+    }),
+]);
 exports.ToolProtectionSchema = zod_1.z.object({
     requiresDelegation: zod_1.z.boolean(),
     requiredScopes: zod_1.z.array(zod_1.z.string()),
     riskLevel: zod_1.z.enum(['low', 'medium', 'high', 'critical']).optional(),
-    oauthProvider: zod_1.z.string().optional() // Phase 2: Tool-specific OAuth provider
+    oauthProvider: zod_1.z.string().optional(), // Phase 2: Tool-specific OAuth provider
+    authorization: exports.AuthorizationRequirementSchema.optional(),
 });
 exports.ToolProtectionMapSchema = zod_1.z.record(zod_1.z.string(), exports.ToolProtectionSchema);
 exports.ToolProtectionResponseSchema = zod_1.z.object({
@@ -112,3 +139,35 @@ function createDelegationRequiredError(toolName, requiredScopes, consentUrl) {
         authorizationUrl: consentUrl // Include both for compatibility
     };
 }
+/**
+ * Normalize tool protection configuration
+ * Migrates legacy oauthProvider field to authorization object
+ *
+ * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
+ */
+function normalizeToolProtection(raw) {
+    // If authorization is already present, return as is
+    if (raw.authorization) {
+        return raw;
+    }
+    // Migrate oauthProvider to authorization
+    if (raw.oauthProvider) {
+        return {
+            ...raw,
+            authorization: {
+                type: 'oauth',
+                provider: raw.oauthProvider,
+            },
+            // Keep oauthProvider for backward compatibility until Phase 3
+        };
+    }
+    // Default for requiresDelegation=true without specific auth: type='none' (consent only)
+    // But ONLY if authorization is missing entirely
+    if (raw.requiresDelegation && !raw.authorization && !raw.oauthProvider) {
+        // We don't automatically set type='none' here to allow
+        // ProviderResolver to do its scope inference fallback logic.
+        // The fallback logic will eventually be moved into an AuthorizationService.
+        return raw;
+    }
+    return raw;
+}