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

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

@@ -75,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
  *
@@ -132,6 +149,18 @@ 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
  */
@@ -251,8 +280,8 @@ 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?: {
@@ -275,8 +304,8 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "none";
     } | undefined;
 }, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
     riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
     oauthProvider?: string | undefined;
     authorization?: {
@@ -360,8 +389,8 @@ 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?: {
@@ -384,8 +413,8 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "none";
     } | undefined;
 }, {
-    requiresDelegation: boolean;
     requiredScopes: string[];
+    requiresDelegation: boolean;
     riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
     oauthProvider?: string | undefined;
     authorization?: {
@@ -470,8 +499,8 @@ 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?: {
@@ -494,8 +523,8 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "none";
         } | undefined;
     }, {
-        requiresDelegation: boolean;
         requiredScopes: string[];
+        requiresDelegation: boolean;
         riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
         oauthProvider?: string | undefined;
         authorization?: {
@@ -523,18 +552,18 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         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?: {
@@ -558,14 +587,14 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | 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?: {
@@ -589,8 +618,8 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | undefined;
     }>;
     metadata?: {
-        version?: string | undefined;
         lastUpdated?: string | undefined;
+        version?: string | undefined;
         source?: string | undefined;
     } | undefined;
 }>;
@@ -603,15 +632,15 @@ export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     requiredScopes: string[];
     toolName: string;
-    reason?: string | undefined;
-    authorizationUrl?: string | undefined;
     consentUrl?: string | undefined;
+    authorizationUrl?: string | undefined;
+    reason?: string | undefined;
 }, {
     requiredScopes: string[];
     toolName: string;
-    reason?: string | undefined;
-    authorizationUrl?: string | undefined;
     consentUrl?: string | undefined;
+    authorizationUrl?: string | undefined;
+    reason?: string | undefined;
 }>;
 /**
  * Type Guards
@@ -620,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
  */
@@ -650,6 +691,13 @@ export declare function createDelegationRequiredError(toolName: string, required
  * 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): ToolProtection;
+export declare function normalizeToolProtection(raw: ToolProtection | PartialToolProtection): ToolProtection;

package/dist/tool-protection/index.js

@@ -14,6 +14,8 @@ exports.isToolProtection = isToolProtection;
 exports.isToolProtectionMap = isToolProtectionMap;
 exports.isToolProtectionResponse = isToolProtectionResponse;
 exports.isDelegationRequiredErrorData = isDelegationRequiredErrorData;
+exports.isAuthorizationRequirement = isAuthorizationRequirement;
+exports.hasOAuthAuthorization = hasOAuthAuthorization;
 exports.validateToolProtection = validateToolProtection;
 exports.validateToolProtectionMap = validateToolProtectionMap;
 exports.validateToolProtectionResponse = validateToolProtectionResponse;
@@ -90,6 +92,18 @@ function isToolProtectionResponse(obj) {
 function isDelegationRequiredErrorData(obj) {
     return exports.DelegationRequiredErrorDataSchema.safeParse(obj).success;
 }
+/**
+ * Type guard to check if an object is a valid AuthorizationRequirement
+ */
+function isAuthorizationRequirement(obj) {
+    return exports.AuthorizationRequirementSchema.safeParse(obj).success;
+}
+/**
+ * Type guard to check if a ToolProtection has OAuth authorization
+ */
+function hasOAuthAuthorization(protection) {
+    return protection.authorization?.type === 'oauth';
+}
 /**
  * Validation Functions
  */
@@ -143,31 +157,44 @@ function createDelegationRequiredError(toolName, requiredScopes, consentUrl) {
  * 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)
  */
 function normalizeToolProtection(raw) {
-    // If authorization is already present, return as is
+    // Ensure we have required fields (provide defaults for partial input)
+    const normalized = {
+        requiresDelegation: raw.requiresDelegation ?? false,
+        requiredScopes: raw.requiredScopes ?? [],
+        ...(raw.riskLevel && { riskLevel: raw.riskLevel }),
+        ...(raw.oauthProvider && { oauthProvider: raw.oauthProvider }),
+    };
+    // If authorization is already present, use it
     if (raw.authorization) {
-        return raw;
+        normalized.authorization = raw.authorization;
+        return normalized;
     }
     // Migrate oauthProvider to authorization
     if (raw.oauthProvider) {
-        return {
-            ...raw,
-            authorization: {
-                type: 'oauth',
-                provider: raw.oauthProvider,
-            },
-            // Keep oauthProvider for backward compatibility until Phase 3
+        normalized.authorization = {
+            type: 'oauth',
+            provider: raw.oauthProvider,
         };
+        // Keep oauthProvider for backward compatibility until Phase 3
+        return normalized;
     }
     // 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) {
+    if (normalized.requiresDelegation && !normalized.authorization && !normalized.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 normalized;
     }
-    return raw;
+    return normalized;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.5.3-canary.20",
+  "version": "1.5.3-canary.21",
   "description": "Shared contracts, types, and schemas for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/tool-protection/index.ts

@@ -89,6 +89,25 @@ export interface ToolProtection {
  */
 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; // null explicitly clears the field
+  authorization?: AuthorizationRequirement | null; // null explicitly clears the field
+};
+
 /**
  * Tool Protection Response
  *
@@ -155,6 +174,20 @@ 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
  */
@@ -232,6 +265,22 @@ export function isDelegationRequiredErrorData(obj: any): obj is DelegationRequir
   return DelegationRequiredErrorDataSchema.safeParse(obj).success;
 }
 
+/**
+ * Type guard to check if an object is a valid AuthorizationRequirement
+ */
+export function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement {
+  return AuthorizationRequirementSchema.safeParse(obj).success;
+}
+
+/**
+ * Type guard to check if a ToolProtection has OAuth authorization
+ */
+export function hasOAuthAuthorization(
+  protection: ToolProtection
+): protection is ToolProtection & { authorization: { type: 'oauth' } } {
+  return protection.authorization?.type === 'oauth';
+}
+
 /**
  * Validation Functions
  */
@@ -307,37 +356,51 @@ export function createDelegationRequiredError(
 /**
  * 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 function normalizeToolProtection(
-  raw: ToolProtection
+  raw: ToolProtection | PartialToolProtection
 ): ToolProtection {
-  // If authorization is already present, return as is
+  // Ensure we have required fields (provide defaults for partial input)
+  const normalized: ToolProtection = {
+    requiresDelegation: raw.requiresDelegation ?? false,
+    requiredScopes: raw.requiredScopes ?? [],
+    ...(raw.riskLevel && { riskLevel: raw.riskLevel }),
+    ...(raw.oauthProvider && { oauthProvider: raw.oauthProvider }),
+  };
+
+  // If authorization is already present, use it
   if (raw.authorization) {
-    return raw;
+    normalized.authorization = raw.authorization;
+    return normalized;
   }
 
   // Migrate oauthProvider to authorization
   if (raw.oauthProvider) {
-    return {
-      ...raw,
-      authorization: {
-        type: 'oauth',
-        provider: raw.oauthProvider,
-      },
-      // Keep oauthProvider for backward compatibility until Phase 3
+    normalized.authorization = {
+      type: 'oauth',
+      provider: raw.oauthProvider,
     };
+    // Keep oauthProvider for backward compatibility until Phase 3
+    return normalized;
   }
 
   // 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) {
+  if (normalized.requiresDelegation && !normalized.authorization && !normalized.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 normalized;
   }
 
-  return raw;
+  return normalized;
 }