@kya-os/contracts 1.7.13 → 1.7.15

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

@@ -16,9 +16,17 @@ import { z } from 'zod';
  * The VC output is always a DelegationCredential created on consent confirmation.
  */
 export type AuthorizationRequirement = {
+    /**
+     * @deprecated Use 'oauth2' instead. Will be removed in v2.0.0.
+     */
     type: 'oauth';
     provider: string;
     requiredScopes?: string[];
+} | {
+    /** OAuth 2.0 provider authentication (canonical) */
+    type: 'oauth2';
+    provider: string;
+    requiredScopes?: string[];
 } | {
     type: 'password';
     provider: string;
@@ -48,7 +56,10 @@ export type AuthorizationRequirement = {
 };
 /** Canonical authorization type values for type safety */
 export declare const AUTHORIZATION_TYPES: {
+    /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */
     readonly OAUTH: "oauth";
+    /** OAuth 2.0 provider authentication (canonical) */
+    readonly OAUTH2: "oauth2";
     readonly PASSWORD: "password";
     readonly MDL: "mdl";
     readonly IDV: "idv";
@@ -199,6 +210,18 @@ export declare const AuthorizationRequirementSchema: z.ZodDiscriminatedUnion<"ty
     type: "oauth";
     provider: string;
     requiredScopes?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"oauth2">;
+    provider: z.ZodString;
+    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "oauth2";
+    provider: string;
+    requiredScopes?: string[] | undefined;
+}, {
+    type: "oauth2";
+    provider: string;
+    requiredScopes?: string[] | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"password">;
     provider: z.ZodString;
@@ -280,6 +303,18 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"password">;
         provider: z.ZodString;
@@ -345,12 +380,18 @@ 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: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -373,15 +414,19 @@ 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: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -404,8 +449,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;
@@ -424,6 +467,18 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        provider: z.ZodString;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
+    }, {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"password">;
         provider: z.ZodString;
@@ -489,12 +544,18 @@ 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: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -517,15 +578,19 @@ 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: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -548,8 +613,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<{
@@ -569,6 +632,18 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"oauth2">;
+            provider: z.ZodString;
+            requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
+        }, {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"password">;
             provider: z.ZodString;
@@ -634,12 +709,18 @@ 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: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -662,15 +743,19 @@ 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: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -693,30 +778,34 @@ 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, {
+        lastUpdated?: string | undefined;
         version?: string | undefined;
         source?: string | undefined;
-        lastUpdated?: string | undefined;
     }, {
+        lastUpdated?: string | undefined;
         version?: string | undefined;
         source?: string | undefined;
-        lastUpdated?: 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: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -739,22 +828,26 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             type: "none";
         } | undefined;
-        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-        oauthProvider?: string | undefined;
     }>;
     metadata?: {
+        lastUpdated?: string | undefined;
         version?: string | undefined;
         source?: string | undefined;
-        lastUpdated?: 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: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -777,13 +870,11 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         } | {
             type: "none";
         } | undefined;
-        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
-        oauthProvider?: string | undefined;
     }>;
     metadata?: {
+        lastUpdated?: string | undefined;
         version?: string | undefined;
         source?: string | undefined;
-        lastUpdated?: string | undefined;
     } | undefined;
 }>;
 export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
@@ -795,15 +886,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
@@ -818,10 +909,11 @@ export declare function isDelegationRequiredErrorData(obj: any): obj is Delegati
 export declare function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement;
 /**
  * Type guard to check if a ToolProtection has OAuth authorization
+ * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)
  */
 export declare function hasOAuthAuthorization(protection: ToolProtection): protection is ToolProtection & {
     authorization: {
-        type: 'oauth';
+        type: 'oauth' | 'oauth2';
     };
 };
 /**
@@ -921,21 +1013,24 @@ export declare function getAuthorizationTypeKey(auth: AuthorizationRequirement):
 /**
  * Normalize authorization requirement type
  *
- * Normalizes deprecated 'credential' type to 'verifiable_credential' and emits
- * deprecation warnings. This function should be called at runtime boundaries
- * when processing authorization requirements.
+ * Normalizes deprecated types to their canonical equivalents:
+ * - 'oauth' → 'oauth2'
+ * - 'credential' → 'verifiable_credential'
+ *
+ * This function should be called at runtime boundaries when processing
+ * authorization requirements.
  *
- * @param auth - Authorization requirement (may contain deprecated 'credential' type)
+ * @param auth - Authorization requirement (may contain deprecated types)
  * @param options - Normalization options
  * @returns Normalized authorization requirement
  *
  * @example
  * ```typescript
  * const normalized = normalizeAuthorizationType(
- *   { type: 'credential', credentialType: 'delegation' },
+ *   { type: 'oauth', provider: 'github' },
  *   { warn: true }
  * );
- * // Returns: { type: 'verifiable_credential', credentialType: 'delegation' }
+ * // Returns: { type: 'oauth2', provider: 'github' }
  * // Logs: DEPRECATION warning
  * ```
  */

package/dist/tool-protection/index.js

@@ -35,7 +35,10 @@ exports.normalizeAuthorizationType = normalizeAuthorizationType;
 const zod_1 = require("zod");
 /** Canonical authorization type values for type safety */
 exports.AUTHORIZATION_TYPES = {
+    /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */
     OAUTH: 'oauth',
+    /** OAuth 2.0 provider authentication (canonical) */
+    OAUTH2: 'oauth2',
     PASSWORD: 'password',
     MDL: 'mdl',
     IDV: 'idv',
@@ -46,11 +49,19 @@ exports.AUTHORIZATION_TYPES = {
  * Zod Schemas for Validation
  */
 exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
+    // Deprecated: 'oauth' is an alias for 'oauth2'
+    // Will be removed in v2.0.0. Use 'oauth2' instead.
     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(),
     }),
+    // OAuth 2.0 provider authentication (canonical)
+    zod_1.z.object({
+        type: zod_1.z.literal('oauth2'),
+        provider: zod_1.z.string(),
+        requiredScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
     zod_1.z.object({
         type: zod_1.z.literal('password'),
         provider: zod_1.z.string(),
@@ -127,9 +138,10 @@ function isAuthorizationRequirement(obj) {
 }
 /**
  * Type guard to check if a ToolProtection has OAuth authorization
+ * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)
  */
 function hasOAuthAuthorization(protection) {
-    return protection.authorization?.type === 'oauth';
+    return protection.authorization?.type === 'oauth' || protection.authorization?.type === 'oauth2';
 }
 /**
  * Type guard to check if a ToolProtection has password authorization
@@ -290,6 +302,7 @@ function determineConsentProviderType(hasOAuthIdentity, isPasswordFlow = false,
 function getAuthorizationTypeLabel(auth) {
     switch (auth.type) {
         case 'oauth':
+        case 'oauth2':
             return auth.provider
                 ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1)
                 : 'OAuth Provider';
@@ -318,7 +331,10 @@ function getAuthorizationTypeLabel(auth) {
 function getAuthorizationTypeKey(auth) {
     switch (auth.type) {
         case 'oauth':
+            // Keep original key format for backward compatibility with existing cache entries
             return `oauth:${auth.provider}`;
+        case 'oauth2':
+            return `oauth2:${auth.provider}`;
         case 'password':
             return `password:${auth.provider}`;
         case 'mdl':
@@ -341,26 +357,45 @@ function getAuthorizationTypeKey(auth) {
 /**
  * Normalize authorization requirement type
  *
- * Normalizes deprecated 'credential' type to 'verifiable_credential' and emits
- * deprecation warnings. This function should be called at runtime boundaries
- * when processing authorization requirements.
+ * Normalizes deprecated types to their canonical equivalents:
+ * - 'oauth' → 'oauth2'
+ * - 'credential' → 'verifiable_credential'
+ *
+ * This function should be called at runtime boundaries when processing
+ * authorization requirements.
  *
- * @param auth - Authorization requirement (may contain deprecated 'credential' type)
+ * @param auth - Authorization requirement (may contain deprecated types)
  * @param options - Normalization options
  * @returns Normalized authorization requirement
  *
  * @example
  * ```typescript
  * const normalized = normalizeAuthorizationType(
- *   { type: 'credential', credentialType: 'delegation' },
+ *   { type: 'oauth', provider: 'github' },
  *   { warn: true }
  * );
- * // Returns: { type: 'verifiable_credential', credentialType: 'delegation' }
+ * // Returns: { type: 'oauth2', provider: 'github' }
  * // Logs: DEPRECATION warning
  * ```
  */
 function normalizeAuthorizationType(auth, options = {}) {
     const { warn = true, logger = console.warn } = options;
+    // Normalize 'oauth' to 'oauth2'
+    if (auth.type === 'oauth') {
+        if (warn) {
+            logger(`DEPRECATION: Authorization type 'oauth' is deprecated and will be removed in v2.0.0. ` +
+                `Please update to 'oauth2'. ` +
+                `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/oauth-to-oauth2.md`);
+        }
+        // Normalize to oauth2
+        const normalized = {
+            type: 'oauth2',
+            provider: auth.provider,
+            ...(auth.requiredScopes !== undefined && { requiredScopes: auth.requiredScopes }),
+        };
+        return normalized;
+    }
+    // Normalize 'credential' to 'verifiable_credential'
     if (auth.type === 'credential') {
         if (warn) {
             logger(`DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. ` +

package/dist/verifier.d.ts

@@ -20,8 +20,8 @@ export declare const AgentContextSchema: z.ZodObject<{
     confidence: "verified";
     registry: string;
     verifiedAt: number;
-    subject?: string | undefined;
     delegationRef?: string | undefined;
+    subject?: string | undefined;
 }, {
     did: string;
     kid: string;
@@ -30,8 +30,8 @@ export declare const AgentContextSchema: z.ZodObject<{
     registry: string;
     verifiedAt: number;
     scopes?: string[] | undefined;
-    subject?: string | undefined;
     delegationRef?: string | undefined;
+    subject?: string | undefined;
 }>;
 export declare const VerifierResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
@@ -54,8 +54,8 @@ export declare const VerifierResultSchema: z.ZodObject<{
         confidence: "verified";
         registry: string;
         verifiedAt: number;
-        subject?: string | undefined;
         delegationRef?: string | undefined;
+        subject?: string | undefined;
     }, {
         did: string;
         kid: string;
@@ -64,8 +64,8 @@ export declare const VerifierResultSchema: z.ZodObject<{
         registry: string;
         verifiedAt: number;
         scopes?: string[] | undefined;
-        subject?: string | undefined;
         delegationRef?: string | undefined;
+        subject?: string | undefined;
     }>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodString;
@@ -100,8 +100,8 @@ export declare const VerifierResultSchema: z.ZodObject<{
         confidence: "verified";
         registry: string;
         verifiedAt: number;
-        subject?: string | undefined;
         delegationRef?: string | undefined;
+        subject?: string | undefined;
     } | undefined;
 }, {
     success: boolean;
@@ -120,8 +120,8 @@ export declare const VerifierResultSchema: z.ZodObject<{
         registry: string;
         verifiedAt: number;
         scopes?: string[] | undefined;
-        subject?: string | undefined;
         delegationRef?: string | undefined;
+        subject?: string | undefined;
     } | undefined;
 }>;
 export declare const StructuredErrorSchema: z.ZodObject<{