@kya-os/contracts 1.7.13 → 1.7.14

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;
@@ -351,6 +386,10 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -382,6 +421,10 @@ export declare const ToolProtectionSchema: z.ZodObject<{
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -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;
@@ -495,6 +550,10 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -526,6 +585,10 @@ export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObje
         type: "oauth";
         provider: string;
         requiredScopes?: string[] | undefined;
+    } | {
+        type: "oauth2";
+        provider: string;
+        requiredScopes?: string[] | undefined;
     } | {
         type: "password";
         provider: string;
@@ -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;
@@ -640,6 +715,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -671,6 +750,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -702,12 +785,12 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
         source: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         version?: string | undefined;
-        source?: string | undefined;
         lastUpdated?: string | undefined;
+        source?: string | undefined;
     }, {
         version?: string | undefined;
-        source?: string | undefined;
         lastUpdated?: string | undefined;
+        source?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     toolProtections: Record<string, {
@@ -717,6 +800,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -744,8 +831,8 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
     }>;
     metadata?: {
         version?: string | undefined;
-        source?: string | undefined;
         lastUpdated?: string | undefined;
+        source?: string | undefined;
     } | undefined;
 }, {
     toolProtections: Record<string, {
@@ -755,6 +842,10 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
             type: "oauth";
             provider: string;
             requiredScopes?: string[] | undefined;
+        } | {
+            type: "oauth2";
+            provider: string;
+            requiredScopes?: string[] | undefined;
         } | {
             type: "password";
             provider: string;
@@ -782,8 +873,8 @@ export declare const ToolProtectionResponseSchema: z.ZodObject<{
     }>;
     metadata?: {
         version?: string | undefined;
-        source?: string | undefined;
         lastUpdated?: string | undefined;
+        source?: string | undefined;
     } | undefined;
 }>;
 export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
@@ -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,8 @@ function getAuthorizationTypeLabel(auth) {
 function getAuthorizationTypeKey(auth) {
     switch (auth.type) {
         case 'oauth':
-            return `oauth:${auth.provider}`;
+        case 'oauth2':
+            return `oauth2:${auth.provider}`;
         case 'password':
             return `password:${auth.provider}`;
         case 'mdl':
@@ -341,26 +355,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<{

package/dist/well-known/index.d.ts

@@ -300,14 +300,14 @@ export declare const DIDDocumentSchema: z.ZodObject<{
         type: string;
         id: string;
         controller: string;
-        publicKeyBase64?: string | undefined;
         publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
     }, {
         type: string;
         id: string;
         controller: string;
-        publicKeyBase64?: string | undefined;
         publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
     }>, "many">;
     authentication: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     assertionMethod: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -329,19 +329,19 @@ export declare const DIDDocumentSchema: z.ZodObject<{
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    '@context': string[];
     verificationMethod: {
         type: string;
         id: string;
         controller: string;
-        publicKeyBase64?: string | undefined;
         publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
     }[];
+    '@context': string[];
     authentication?: string[] | undefined;
     assertionMethod?: string[] | undefined;
+    keyAgreement?: string[] | undefined;
     capabilityInvocation?: string[] | undefined;
     capabilityDelegation?: string[] | undefined;
-    keyAgreement?: string[] | undefined;
     service?: {
         type: string;
         id: string;
@@ -349,19 +349,19 @@ export declare const DIDDocumentSchema: z.ZodObject<{
     }[] | undefined;
 }, {
     id: string;
-    '@context': string[];
     verificationMethod: {
         type: string;
         id: string;
         controller: string;
-        publicKeyBase64?: string | undefined;
         publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
     }[];
+    '@context': string[];
     authentication?: string[] | undefined;
     assertionMethod?: string[] | undefined;
+    keyAgreement?: string[] | undefined;
     capabilityInvocation?: string[] | undefined;
     capabilityDelegation?: string[] | undefined;
-    keyAgreement?: string[] | undefined;
     service?: {
         type: string;
         id: string;
@@ -395,7 +395,7 @@ export declare const AgentDocumentSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     capabilities: {
-        'mcp-i': ("delegation" | "handshake" | "signing" | "verification" | "proof-generation")[];
+        'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
     } & {
         [k: string]: string[];
     };
@@ -408,7 +408,7 @@ export declare const AgentDocumentSchema: z.ZodObject<{
     } | undefined;
 }, {
     capabilities: {
-        'mcp-i': ("delegation" | "handshake" | "signing" | "verification" | "proof-generation")[];
+        'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
     } & {
         [k: string]: string[];
     };
@@ -656,6 +656,7 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         completions?: Record<string, unknown> | undefined;
         experimental?: Record<string, unknown> | undefined;
     } | undefined;
+    $schema?: string | undefined;
     tools?: "dynamic" | {
         name: string;
         title?: string | undefined;
@@ -667,7 +668,7 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         required: boolean;
         schemes: string[];
     } | undefined;
-    $schema?: string | undefined;
+    instructions?: string | undefined;
     iconUrl?: string | undefined;
     documentationUrl?: string | undefined;
     prompts?: "dynamic" | {
@@ -693,7 +694,6 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         roots?: Record<string, unknown> | undefined;
         elicitation?: Record<string, unknown> | undefined;
     } | undefined;
-    instructions?: string | undefined;
     _meta?: Record<string, unknown> | undefined;
 }, {
     version: string;
@@ -722,6 +722,7 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         completions?: Record<string, unknown> | undefined;
         experimental?: Record<string, unknown> | undefined;
     } | undefined;
+    $schema?: string | undefined;
     tools?: "dynamic" | {
         name: string;
         title?: string | undefined;
@@ -733,7 +734,7 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         required: boolean;
         schemes: string[];
     } | undefined;
-    $schema?: string | undefined;
+    instructions?: string | undefined;
     iconUrl?: string | undefined;
     documentationUrl?: string | undefined;
     prompts?: "dynamic" | {
@@ -759,7 +760,6 @@ export declare const MCPServerCardSchema: z.ZodObject<{
         roots?: Record<string, unknown> | undefined;
         elicitation?: Record<string, unknown> | undefined;
     } | undefined;
-    instructions?: string | undefined;
     _meta?: Record<string, unknown> | undefined;
 }>;
 /** Legacy MCP Server Config Schema */
@@ -780,8 +780,8 @@ export declare const MCPServerConfigSchema: z.ZodObject<{
     transport: "sse" | "stdio" | "http";
     metadata?: Record<string, unknown> | undefined;
     version?: string | undefined;
-    agentDid?: string | undefined;
     capabilities?: string[] | undefined;
+    agentDid?: string | undefined;
     description?: string | undefined;
     requiresAuth?: boolean | undefined;
     authProvider?: string | undefined;
@@ -791,8 +791,8 @@ export declare const MCPServerConfigSchema: z.ZodObject<{
     transport: "sse" | "stdio" | "http";
     metadata?: Record<string, unknown> | undefined;
     version?: string | undefined;
-    agentDid?: string | undefined;
     capabilities?: string[] | undefined;
+    agentDid?: string | undefined;
     description?: string | undefined;
     requiresAuth?: boolean | undefined;
     authProvider?: string | undefined;
@@ -929,10 +929,10 @@ export declare const WellKnownConfigSchema: z.ZodObject<{
     protocolVersion?: string | undefined;
     description?: string | undefined;
     serviceEndpoint?: string | undefined;
+    instructions?: string | undefined;
     serviceName?: string | undefined;
     iconUrl?: string | undefined;
     documentationUrl?: string | undefined;
-    instructions?: string | undefined;
     requiresAuth?: boolean | undefined;
     serviceTitle?: string | undefined;
     serverVersion?: string | undefined;
@@ -942,10 +942,10 @@ export declare const WellKnownConfigSchema: z.ZodObject<{
     protocolVersion?: string | undefined;
     description?: string | undefined;
     serviceEndpoint?: string | undefined;
+    instructions?: string | undefined;
     serviceName?: string | undefined;
     iconUrl?: string | undefined;
     documentationUrl?: string | undefined;
-    instructions?: string | undefined;
     requiresAuth?: boolean | undefined;
     serviceTitle?: string | undefined;
     serverVersion?: string | undefined;

package/package.json

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