@kya-os/contracts 1.7.3 → 1.7.6

package/dist/handshake.d.ts

@@ -23,16 +23,16 @@ export declare const MCPClientInfoSchema: z.ZodObject<{
     persistentId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    title?: string | undefined;
     version?: string | undefined;
     platform?: string | undefined;
+    title?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
 }, {
     name: string;
-    title?: string | undefined;
     version?: string | undefined;
     platform?: string | undefined;
+    title?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
 }>;
@@ -50,9 +50,9 @@ export declare const MCPClientSessionInfoSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     clientId: string;
-    title?: string | undefined;
     version?: string | undefined;
     platform?: string | undefined;
+    title?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
     protocolVersion?: string | undefined;
@@ -60,9 +60,9 @@ export declare const MCPClientSessionInfoSchema: z.ZodObject<{
 }, {
     name: string;
     clientId: string;
-    title?: string | undefined;
     version?: string | undefined;
     platform?: string | undefined;
+    title?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
     protocolVersion?: string | undefined;
@@ -84,17 +84,17 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
         clientId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         clientId?: string | undefined;
     }, {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         clientId?: string | undefined;
@@ -102,15 +102,15 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     clientProtocolVersion: z.ZodOptional<z.ZodString>;
     clientCapabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
+    timestamp: number;
     nonce: string;
     audience: string;
-    timestamp: number;
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         clientId?: string | undefined;
@@ -118,15 +118,15 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     clientProtocolVersion?: string | undefined;
     clientCapabilities?: Record<string, unknown> | undefined;
 }, {
+    timestamp: number;
     nonce: string;
     audience: string;
-    timestamp: number;
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         clientId?: string | undefined;
@@ -160,9 +160,9 @@ export declare const SessionContextSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         protocolVersion?: string | undefined;
@@ -170,9 +170,9 @@ export declare const SessionContextSchema: z.ZodObject<{
     }, {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         protocolVersion?: string | undefined;
@@ -204,27 +204,27 @@ export declare const SessionContextSchema: z.ZodObject<{
         name?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    ttlMinutes: number;
+    timestamp: number;
     nonce: string;
     audience: string;
-    timestamp: number;
     sessionId: string;
     createdAt: number;
     lastActivity: number;
-    ttlMinutes: number;
     identityState: "anonymous" | "authenticated";
     agentDid?: string | undefined;
+    serverDid?: string | undefined;
     clientInfo?: {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         protocolVersion?: string | undefined;
         capabilities?: Record<string, unknown> | undefined;
     } | undefined;
-    serverDid?: string | undefined;
     clientDid?: string | undefined;
     userDid?: string | undefined;
     oauthIdentity?: {
@@ -234,26 +234,26 @@ export declare const SessionContextSchema: z.ZodObject<{
         name?: string | undefined;
     } | undefined;
 }, {
+    timestamp: number;
     nonce: string;
     audience: string;
-    timestamp: number;
     sessionId: string;
     createdAt: number;
     lastActivity: number;
     agentDid?: string | undefined;
+    serverDid?: string | undefined;
+    ttlMinutes?: number | undefined;
     clientInfo?: {
         name: string;
         clientId: string;
-        title?: string | undefined;
         version?: string | undefined;
         platform?: string | undefined;
+        title?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         protocolVersion?: string | undefined;
         capabilities?: Record<string, unknown> | undefined;
     } | undefined;
-    ttlMinutes?: number | undefined;
-    serverDid?: string | undefined;
     clientDid?: string | undefined;
     userDid?: string | undefined;
     identityState?: "anonymous" | "authenticated" | undefined;
@@ -346,7 +346,7 @@ export declare const NonceCacheConfigSchema: z.ZodObject<{
         keyPrefix?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    type?: "cloudflare-kv" | "memory" | "redis" | "dynamodb" | undefined;
     redis?: {
         url: string;
         keyPrefix: string;
@@ -362,7 +362,7 @@ export declare const NonceCacheConfigSchema: z.ZodObject<{
         namespace: string;
     } | undefined;
 }, {
-    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    type?: "cloudflare-kv" | "memory" | "redis" | "dynamodb" | undefined;
     redis?: {
         url: string;
         keyPrefix?: string | undefined;

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

@@ -1,28 +1,19 @@
 /**
  * MCP-I Tool Protection Specification
  *
- * This module defines the core tool protection types as specified in the
- * MCP-I protocol. These are pure specification types that define how tools
- * can be protected with delegation requirements and scopes.
+ * Core types for tool protection with delegation requirements.
+ *
+ * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).
+ * DelegationCredential (VC) is created when user confirms on Consent Screen.
  *
  * @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, password auth, MDL, IDV, verifiable credentials, etc.
- *
- * ## Type Naming Clarification
+ * Authorization Requirement - what auth is needed BEFORE consent screen.
  *
- * - `oauth` - OAuth 2.0 provider authentication (GitHub, Google, etc.)
- * - `password` - Username/password or API key authentication (HardwareWorld, etc.)
- * - `verifiable_credential` - W3C Verifiable Credential requirement (preferred)
- * - `credential` - **DEPRECATED** alias for `verifiable_credential` (for backward compatibility)
- * - `mdl` - Mobile Driver's License (ISO 18013-5)
- * - `idv` - Identity Verification provider (Stripe, Onfido, etc.)
- * - `none` - Consent-only (clickwrap agreement, no authentication)
+ * Types: none (2 screens), oauth/password/mdl/idv (3 screens), verifiable_credential (future).
+ * The VC output is always a DelegationCredential created on consent confirmation.
  */
 export type AuthorizationRequirement = {
     type: 'oauth';
@@ -40,12 +31,14 @@ export type AuthorizationRequirement = {
     provider: string;
     verificationLevel?: 'basic' | 'enhanced' | 'loa3';
 } | {
+    /** Require user to present an existing VC */
     type: 'verifiable_credential';
     credentialType: string;
     issuer?: string;
 } | {
     /**
-     * @deprecated Use `verifiable_credential` instead. Kept for backward compatibility.
+     * @deprecated Use 'verifiable_credential' instead. Will be removed in v2.0.0.
+     * This is an alias for 'verifiable_credential' for backward compatibility.
      */
     type: 'credential';
     credentialType: string;
@@ -53,24 +46,13 @@ export type AuthorizationRequirement = {
 } | {
     type: 'none';
 };
-/**
- * Canonical authorization type values
- * Use these constants instead of string literals for type safety
- */
+/** Canonical authorization type values for type safety */
 export declare const AUTHORIZATION_TYPES: {
-    /** OAuth 2.0 provider authentication */
     readonly OAUTH: "oauth";
-    /** Username/password or API key authentication */
     readonly PASSWORD: "password";
-    /** Mobile Driver's License (ISO 18013-5) */
     readonly MDL: "mdl";
-    /** Identity Verification provider */
     readonly IDV: "idv";
-    /** W3C Verifiable Credential requirement (preferred) */
     readonly VERIFIABLE_CREDENTIAL: "verifiable_credential";
-    /** @deprecated Use VERIFIABLE_CREDENTIAL instead */
-    readonly CREDENTIAL: "credential";
-    /** Consent-only (clickwrap agreement) */
     readonly NONE: "none";
 };
 export type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];
@@ -852,7 +834,8 @@ export declare function hasPasswordAuthorization(protection: ToolProtection): pr
 };
 /**
  * Type guard to check if a ToolProtection requires a Verifiable Credential
- * Handles both 'verifiable_credential' and legacy 'credential' types
+ *
+ * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)
  */
 export declare function hasVerifiableCredentialAuthorization(protection: ToolProtection): protection is ToolProtection & {
     authorization: {
@@ -899,20 +882,7 @@ export declare function createDelegationRequiredError(toolName: string, required
  * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
  */
 export declare function normalizeToolProtection(raw: ToolProtection | PartialToolProtection): ToolProtection;
-/**
- * Consent Provider Types
- *
- * These constants define the authentication method used during consent:
- * - NONE: Consent-only mode (clickwrap) - user agrees without authentication
- * - OAUTH2: OAuth provider authentication (GitHub, Google, etc.)
- * - PASSWORD: Password-based authentication (email/password, username/password)
- * - CREDENTIAL: Alias for PASSWORD (legacy compatibility)
- * - MAGIC_LINK: Email magic link authentication
- * - OTP: One-time password authentication
- *
- * NOTE: This is distinct from AUTHORIZATION_TYPES which define what a TOOL requires.
- * CONSENT_PROVIDER_TYPES define what authentication method the USER used.
- */
+/** Consent provider types - stored in delegation metadata to track auth method used */
 export declare const CONSENT_PROVIDER_TYPES: {
     /** Consent-only mode - no authentication, just clickwrap agreement */
     readonly NONE: "none";
@@ -940,16 +910,6 @@ export type ConsentProviderType = (typeof CONSENT_PROVIDER_TYPES)[keyof typeof C
  * @returns The consent provider type
  */
 export declare function determineConsentProviderType(hasOAuthIdentity: boolean, isPasswordFlow?: boolean, isMagicLinkFlow?: boolean, isOtpFlow?: boolean): ConsentProviderType;
-/**
- * Normalize authorization requirement to use canonical type names
- *
- * Migrates legacy 'credential' type to 'verifiable_credential'
- * This ensures consistent type usage across the codebase.
- *
- * @param auth - The authorization requirement (may have legacy type)
- * @returns Normalized authorization requirement with canonical type
- */
-export declare function normalizeAuthorizationType(auth: AuthorizationRequirement): AuthorizationRequirement;
 /**
  * Get a human-readable label for an authorization requirement type
  */
@@ -958,3 +918,28 @@ export declare function getAuthorizationTypeLabel(auth: AuthorizationRequirement
  * Get a unique key for an authorization requirement (for React keys, caching, etc.)
  */
 export declare function getAuthorizationTypeKey(auth: AuthorizationRequirement): string;
+/**
+ * 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.
+ *
+ * @param auth - Authorization requirement (may contain deprecated 'credential' type)
+ * @param options - Normalization options
+ * @returns Normalized authorization requirement
+ *
+ * @example
+ * ```typescript
+ * const normalized = normalizeAuthorizationType(
+ *   { type: 'credential', credentialType: 'delegation' },
+ *   { warn: true }
+ * );
+ * // Returns: { type: 'verifiable_credential', credentialType: 'delegation' }
+ * // Logs: DEPRECATION warning
+ * ```
+ */
+export declare function normalizeAuthorizationType(auth: AuthorizationRequirement, options?: {
+    warn?: boolean;
+    logger?: (message: string) => void;
+}): AuthorizationRequirement;

package/dist/tool-protection/index.js

@@ -2,9 +2,10 @@
 /**
  * MCP-I Tool Protection Specification
  *
- * This module defines the core tool protection types as specified in the
- * MCP-I protocol. These are pure specification types that define how tools
- * can be protected with delegation requirements and scopes.
+ * Core types for tool protection with delegation requirements.
+ *
+ * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).
+ * DelegationCredential (VC) is created when user confirms on Consent Screen.
  *
  * @module @kya-os/contracts/tool-protection
  */
@@ -28,28 +29,17 @@ exports.getToolRiskLevel = getToolRiskLevel;
 exports.createDelegationRequiredError = createDelegationRequiredError;
 exports.normalizeToolProtection = normalizeToolProtection;
 exports.determineConsentProviderType = determineConsentProviderType;
-exports.normalizeAuthorizationType = normalizeAuthorizationType;
 exports.getAuthorizationTypeLabel = getAuthorizationTypeLabel;
 exports.getAuthorizationTypeKey = getAuthorizationTypeKey;
+exports.normalizeAuthorizationType = normalizeAuthorizationType;
 const zod_1 = require("zod");
-/**
- * Canonical authorization type values
- * Use these constants instead of string literals for type safety
- */
+/** Canonical authorization type values for type safety */
 exports.AUTHORIZATION_TYPES = {
-    /** OAuth 2.0 provider authentication */
     OAUTH: 'oauth',
-    /** Username/password or API key authentication */
     PASSWORD: 'password',
-    /** Mobile Driver's License (ISO 18013-5) */
     MDL: 'mdl',
-    /** Identity Verification provider */
     IDV: 'idv',
-    /** W3C Verifiable Credential requirement (preferred) */
     VERIFIABLE_CREDENTIAL: 'verifiable_credential',
-    /** @deprecated Use VERIFIABLE_CREDENTIAL instead */
-    CREDENTIAL: 'credential',
-    /** Consent-only (clickwrap agreement) */
     NONE: 'none',
 };
 /**
@@ -80,7 +70,8 @@ exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
         credentialType: zod_1.z.string(),
         issuer: zod_1.z.string().optional(),
     }),
-    // Backward compatibility: 'credential' is an alias for 'verifiable_credential'
+    // Deprecated: 'credential' is an alias for 'verifiable_credential'
+    // Will be removed in v2.0.0. Use 'verifiable_credential' instead.
     zod_1.z.object({
         type: zod_1.z.literal('credential'),
         credentialType: zod_1.z.string(),
@@ -148,11 +139,12 @@ function hasPasswordAuthorization(protection) {
 }
 /**
  * Type guard to check if a ToolProtection requires a Verifiable Credential
- * Handles both 'verifiable_credential' and legacy 'credential' types
+ *
+ * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)
  */
 function hasVerifiableCredentialAuthorization(protection) {
-    const type = protection.authorization?.type;
-    return type === 'verifiable_credential' || type === 'credential';
+    return (protection.authorization?.type === 'verifiable_credential' ||
+        protection.authorization?.type === 'credential');
 }
 /**
  * Validation Functions
@@ -249,22 +241,9 @@ function normalizeToolProtection(raw) {
     return normalized;
 }
 // =============================================================================
-// CONSENT PROVIDER TYPES
+// CONSENT PROVIDER TYPES - Records what auth method was USED (not required)
 // =============================================================================
-/**
- * Consent Provider Types
- *
- * These constants define the authentication method used during consent:
- * - NONE: Consent-only mode (clickwrap) - user agrees without authentication
- * - OAUTH2: OAuth provider authentication (GitHub, Google, etc.)
- * - PASSWORD: Password-based authentication (email/password, username/password)
- * - CREDENTIAL: Alias for PASSWORD (legacy compatibility)
- * - MAGIC_LINK: Email magic link authentication
- * - OTP: One-time password authentication
- *
- * NOTE: This is distinct from AUTHORIZATION_TYPES which define what a TOOL requires.
- * CONSENT_PROVIDER_TYPES define what authentication method the USER used.
- */
+/** Consent provider types - stored in delegation metadata to track auth method used */
 exports.CONSENT_PROVIDER_TYPES = {
     /** Consent-only mode - no authentication, just clickwrap agreement */
     NONE: 'none',
@@ -305,29 +284,6 @@ function determineConsentProviderType(hasOAuthIdentity, isPasswordFlow = false,
     }
     return exports.CONSENT_PROVIDER_TYPES.NONE;
 }
-// =============================================================================
-// AUTHORIZATION TYPE NORMALIZATION
-// =============================================================================
-/**
- * Normalize authorization requirement to use canonical type names
- *
- * Migrates legacy 'credential' type to 'verifiable_credential'
- * This ensures consistent type usage across the codebase.
- *
- * @param auth - The authorization requirement (may have legacy type)
- * @returns Normalized authorization requirement with canonical type
- */
-function normalizeAuthorizationType(auth) {
-    // Migrate legacy 'credential' to 'verifiable_credential'
-    if (auth.type === 'credential') {
-        return {
-            type: 'verifiable_credential',
-            credentialType: auth.credentialType,
-            issuer: auth.issuer,
-        };
-    }
-    return auth;
-}
 /**
  * Get a human-readable label for an authorization requirement type
  */
@@ -344,7 +300,9 @@ function getAuthorizationTypeLabel(auth) {
         case 'idv':
             return 'Identity Verification';
         case 'verifiable_credential':
+            return auth.credentialType || 'Verifiable Credential';
         case 'credential':
+            // Deprecated: treat as verifiable_credential
             return auth.credentialType || 'Verifiable Credential';
         case 'none':
             return 'Consent Only';
@@ -368,7 +326,9 @@ function getAuthorizationTypeKey(auth) {
         case 'idv':
             return `idv:${auth.provider}:${auth.verificationLevel || ''}`;
         case 'verifiable_credential':
+            return `vc:${auth.issuer || 'any'}:${auth.credentialType}`;
         case 'credential':
+            // Deprecated: treat as verifiable_credential
             return `vc:${auth.issuer || 'any'}:${auth.credentialType}`;
         case 'none':
             return 'none';
@@ -378,3 +338,43 @@ function getAuthorizationTypeKey(auth) {
             return 'unknown';
     }
 }
+/**
+ * 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.
+ *
+ * @param auth - Authorization requirement (may contain deprecated 'credential' type)
+ * @param options - Normalization options
+ * @returns Normalized authorization requirement
+ *
+ * @example
+ * ```typescript
+ * const normalized = normalizeAuthorizationType(
+ *   { type: 'credential', credentialType: 'delegation' },
+ *   { warn: true }
+ * );
+ * // Returns: { type: 'verifiable_credential', credentialType: 'delegation' }
+ * // Logs: DEPRECATION warning
+ * ```
+ */
+function normalizeAuthorizationType(auth, options = {}) {
+    const { warn = true, logger = console.warn } = options;
+    if (auth.type === 'credential') {
+        if (warn) {
+            logger(`DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. ` +
+                `Please update to 'verifiable_credential'. ` +
+                `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/credential-to-verifiable_credential.md`);
+        }
+        // Normalize to verifiable_credential
+        const normalized = {
+            type: 'verifiable_credential',
+            credentialType: auth.credentialType,
+            ...(auth.issuer !== undefined && { issuer: auth.issuer }),
+        };
+        return normalized;
+    }
+    // No normalization needed
+    return auth;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.7.3",
+  "version": "1.7.6",
   "description": "Shared contracts, types, and schemas for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -95,7 +95,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@kya-os/consent": "^0.1.2",
+    "@kya-os/consent": "^0.1.5",
     "zod": "^3.25.76"
   },
   "devDependencies": {