@kya-os/contracts 1.7.4 → 1.7.6

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

@@ -31,13 +31,14 @@ export type AuthorizationRequirement = {
     provider: string;
     verificationLevel?: 'basic' | 'enhanced' | 'loa3';
 } | {
-    /** FUTURE: Require user to present an existing VC (not yet implemented) */
+    /** 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;
@@ -51,10 +52,7 @@ export declare const AUTHORIZATION_TYPES: {
     readonly PASSWORD: "password";
     readonly MDL: "mdl";
     readonly IDV: "idv";
-    /** FUTURE: Not yet implemented */
     readonly VERIFIABLE_CREDENTIAL: "verifiable_credential";
-    /** @deprecated Use VERIFIABLE_CREDENTIAL */
-    readonly CREDENTIAL: "credential";
     readonly NONE: "none";
 };
 export type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];
@@ -836,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: {
@@ -911,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
  */
@@ -929,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

@@ -29,9 +29,9 @@ 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 for type safety */
 exports.AUTHORIZATION_TYPES = {
@@ -39,10 +39,7 @@ exports.AUTHORIZATION_TYPES = {
     PASSWORD: 'password',
     MDL: 'mdl',
     IDV: 'idv',
-    /** FUTURE: Not yet implemented */
     VERIFIABLE_CREDENTIAL: 'verifiable_credential',
-    /** @deprecated Use VERIFIABLE_CREDENTIAL */
-    CREDENTIAL: 'credential',
     NONE: 'none',
 };
 /**
@@ -73,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(),
@@ -141,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
@@ -285,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
  */
@@ -324,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';
@@ -348,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';
@@ -358,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.4",
+  "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": {