@kya-os/contracts 1.7.1 → 1.7.3

package/dist/tool-protection/index.js

@@ -9,13 +9,15 @@
  * @module @kya-os/contracts/tool-protection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = exports.AuthorizationRequirementSchema = void 0;
+exports.CONSENT_PROVIDER_TYPES = exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = exports.AuthorizationRequirementSchema = exports.AUTHORIZATION_TYPES = void 0;
 exports.isToolProtection = isToolProtection;
 exports.isToolProtectionMap = isToolProtectionMap;
 exports.isToolProtectionResponse = isToolProtectionResponse;
 exports.isDelegationRequiredErrorData = isDelegationRequiredErrorData;
 exports.isAuthorizationRequirement = isAuthorizationRequirement;
 exports.hasOAuthAuthorization = hasOAuthAuthorization;
+exports.hasPasswordAuthorization = hasPasswordAuthorization;
+exports.hasVerifiableCredentialAuthorization = hasVerifiableCredentialAuthorization;
 exports.validateToolProtection = validateToolProtection;
 exports.validateToolProtectionMap = validateToolProtectionMap;
 exports.validateToolProtectionResponse = validateToolProtectionResponse;
@@ -25,7 +27,31 @@ exports.getToolRequiredScopes = getToolRequiredScopes;
 exports.getToolRiskLevel = getToolRiskLevel;
 exports.createDelegationRequiredError = createDelegationRequiredError;
 exports.normalizeToolProtection = normalizeToolProtection;
+exports.determineConsentProviderType = determineConsentProviderType;
+exports.normalizeAuthorizationType = normalizeAuthorizationType;
+exports.getAuthorizationTypeLabel = getAuthorizationTypeLabel;
+exports.getAuthorizationTypeKey = getAuthorizationTypeKey;
 const zod_1 = require("zod");
+/**
+ * Canonical authorization type values
+ * Use these constants instead of string literals 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',
+};
 /**
  * Zod Schemas for Validation
  */
@@ -35,6 +61,10 @@ exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
         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(),
+    }),
     zod_1.z.object({
         type: zod_1.z.literal('mdl'),
         issuer: zod_1.z.string(),
@@ -45,6 +75,12 @@ exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
         provider: zod_1.z.string(),
         verificationLevel: zod_1.z.enum(['basic', 'enhanced', 'loa3']).optional(),
     }),
+    zod_1.z.object({
+        type: zod_1.z.literal('verifiable_credential'),
+        credentialType: zod_1.z.string(),
+        issuer: zod_1.z.string().optional(),
+    }),
+    // Backward compatibility: 'credential' is an alias for 'verifiable_credential'
     zod_1.z.object({
         type: zod_1.z.literal('credential'),
         credentialType: zod_1.z.string(),
@@ -104,6 +140,20 @@ function isAuthorizationRequirement(obj) {
 function hasOAuthAuthorization(protection) {
     return protection.authorization?.type === 'oauth';
 }
+/**
+ * Type guard to check if a ToolProtection has password authorization
+ */
+function hasPasswordAuthorization(protection) {
+    return protection.authorization?.type === 'password';
+}
+/**
+ * Type guard to check if a ToolProtection requires a Verifiable Credential
+ * Handles both 'verifiable_credential' and legacy 'credential' types
+ */
+function hasVerifiableCredentialAuthorization(protection) {
+    const type = protection.authorization?.type;
+    return type === 'verifiable_credential' || type === 'credential';
+}
 /**
  * Validation Functions
  */
@@ -198,3 +248,133 @@ function normalizeToolProtection(raw) {
     }
     return normalized;
 }
+// =============================================================================
+// CONSENT PROVIDER TYPES
+// =============================================================================
+/**
+ * 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.
+ */
+exports.CONSENT_PROVIDER_TYPES = {
+    /** Consent-only mode - no authentication, just clickwrap agreement */
+    NONE: 'none',
+    /** OAuth2 provider authentication */
+    OAUTH2: 'oauth2',
+    /** Password-based authentication (email/password, username/password) */
+    PASSWORD: 'password',
+    /** @deprecated Use PASSWORD instead. Alias for backward compatibility */
+    CREDENTIAL: 'credential',
+    /** Email magic link authentication */
+    MAGIC_LINK: 'magic_link',
+    /** One-time password (SMS/email code) */
+    OTP: 'otp',
+};
+/**
+ * Determine consent provider type based on available identity information
+ *
+ * This is the single source of truth for consent provider type determination.
+ *
+ * @param hasOAuthIdentity - Whether OAuth identity is available
+ * @param isPasswordFlow - Whether this is a password/credential flow
+ * @param isMagicLinkFlow - Whether this is a magic link flow
+ * @param isOtpFlow - Whether this is an OTP flow
+ * @returns The consent provider type
+ */
+function determineConsentProviderType(hasOAuthIdentity, isPasswordFlow = false, isMagicLinkFlow = false, isOtpFlow = false) {
+    if (isPasswordFlow) {
+        return exports.CONSENT_PROVIDER_TYPES.PASSWORD;
+    }
+    if (isMagicLinkFlow) {
+        return exports.CONSENT_PROVIDER_TYPES.MAGIC_LINK;
+    }
+    if (isOtpFlow) {
+        return exports.CONSENT_PROVIDER_TYPES.OTP;
+    }
+    if (hasOAuthIdentity) {
+        return exports.CONSENT_PROVIDER_TYPES.OAUTH2;
+    }
+    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
+ */
+function getAuthorizationTypeLabel(auth) {
+    switch (auth.type) {
+        case 'oauth':
+            return auth.provider
+                ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1)
+                : 'OAuth Provider';
+        case 'password':
+            return 'Password Authentication';
+        case 'mdl':
+            return "Mobile Driver's License";
+        case 'idv':
+            return 'Identity Verification';
+        case 'verifiable_credential':
+        case 'credential':
+            return auth.credentialType || 'Verifiable Credential';
+        case 'none':
+            return 'Consent Only';
+        default:
+            // TypeScript exhaustiveness check
+            const _exhaustive = auth;
+            return 'Unknown';
+    }
+}
+/**
+ * Get a unique key for an authorization requirement (for React keys, caching, etc.)
+ */
+function getAuthorizationTypeKey(auth) {
+    switch (auth.type) {
+        case 'oauth':
+            return `oauth:${auth.provider}`;
+        case 'password':
+            return `password:${auth.provider}`;
+        case 'mdl':
+            return `mdl:${auth.issuer}:${auth.credentialType || ''}`;
+        case 'idv':
+            return `idv:${auth.provider}:${auth.verificationLevel || ''}`;
+        case 'verifiable_credential':
+        case 'credential':
+            return `vc:${auth.issuer || 'any'}:${auth.credentialType}`;
+        case 'none':
+            return 'none';
+        default:
+            // TypeScript exhaustiveness check
+            const _exhaustive = auth;
+            return 'unknown';
+    }
+}

package/package.json

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