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

package/dist/handshake.d.ts

@@ -12,15 +12,15 @@ export declare const MCPClientInfoSchema: z.ZodObject<{
     persistentId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    title?: string | undefined;
     version?: string | undefined;
+    title?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
 }, {
     name: string;
-    title?: string | undefined;
     version?: string | undefined;
+    title?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
@@ -39,8 +39,8 @@ export declare const MCPClientSessionInfoSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     clientId: string;
-    title?: string | undefined;
     version?: string | undefined;
+    title?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
@@ -49,8 +49,8 @@ export declare const MCPClientSessionInfoSchema: z.ZodObject<{
 }, {
     name: string;
     clientId: string;
-    title?: string | undefined;
     version?: string | undefined;
+    title?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
@@ -73,16 +73,16 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
         clientId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         clientId?: string | undefined;
     }, {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -97,8 +97,8 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -113,8 +113,8 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -149,8 +149,8 @@ export declare const SessionContextSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -159,8 +159,8 @@ export declare const SessionContextSchema: z.ZodObject<{
     }, {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -168,19 +168,19 @@ export declare const SessionContextSchema: z.ZodObject<{
         capabilities?: Record<string, unknown> | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    createdAt: number;
     nonce: string;
     audience: string;
     timestamp: number;
     sessionId: string;
-    createdAt: number;
     lastActivity: number;
     ttlMinutes: number;
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -191,18 +191,18 @@ export declare const SessionContextSchema: z.ZodObject<{
     clientDid?: string | undefined;
     userDid?: string | undefined;
 }, {
+    createdAt: number;
     nonce: string;
     audience: string;
     timestamp: number;
     sessionId: string;
-    createdAt: number;
     lastActivity: number;
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
+        title?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;

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[];
     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[];
     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[];
     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[];
     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,28 +414,121 @@ 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[];
         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[];
         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, {
-        lastUpdated?: string | undefined;
         version?: string | undefined;
+        lastUpdated?: string | undefined;
         source?: string | undefined;
     }, {
-        lastUpdated?: string | undefined;
         version?: string | undefined;
+        lastUpdated?: string | undefined;
         source?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -172,10 +537,29 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         requiredScopes: string[];
         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;
         version?: string | undefined;
+        lastUpdated?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }, {
@@ -184,10 +568,29 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         requiredScopes: string[];
         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;
         version?: string | undefined;
+        lastUpdated?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }>;
@@ -200,15 +603,15 @@ export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     requiredScopes: string[];
     toolName: string;
-    consentUrl?: string | undefined;
-    authorizationUrl?: string | undefined;
     reason?: string | undefined;
+    authorizationUrl?: string | undefined;
+    consentUrl?: string | undefined;
 }, {
     requiredScopes: string[];
     toolName: string;
-    consentUrl?: string | undefined;
-    authorizationUrl?: string | undefined;
     reason?: string | undefined;
+    authorizationUrl?: string | undefined;
+    consentUrl?: string | undefined;
 }>;
 /**
  * Type Guards
@@ -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;