@kya-os/mcp-i-core 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -43,6 +43,8 @@ export type { ToolProtection, ToolProtectionConfig, ToolProtectionServiceConfig,
 export { DelegationRequiredError } from "./types/tool-protection";
 export { OAuthRequiredError } from "./types/oauth-required-error";
 export type { OAuthRequiredErrorOptions } from "./types/oauth-required-error";
+export { DelegationErrorFormatter, createDelegationErrorFormatter, } from "./services/delegation-error-formatter";
+export type { DelegationErrorFormatOptions, DelegationErrorResult, ClientMessageTemplate, ClientMessagesConfig, } from "./services/delegation-error-formatter";
 export { DelegationCredentialIssuer, createDelegationIssuer, type IssueDelegationOptions, type VCSigningFunction, type IdentityProvider as DelegationIdentityProvider, } from "./delegation/vc-issuer";
 export { DelegationCredentialVerifier, createDelegationVerifier, type DelegationVCVerificationResult, type VerifyDelegationVCOptions, type DIDResolver, type DIDDocument, type VerificationMethod, type StatusListResolver, type SignatureVerificationFunction, } from "./delegation/vc-verifier";
 export { StatusList2021Manager, createStatusListManager, type StatusListStorageProvider, type StatusListIdentityProvider, } from "./delegation/statuslist-manager";

package/dist/index.js

@@ -20,8 +20,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CascadingRevocationManager = exports.createDelegationGraph = exports.DelegationGraphManager = exports.isIndexSet = exports.BitstringManager = exports.createStatusListManager = exports.StatusList2021Manager = exports.createDelegationVerifier = exports.DelegationCredentialVerifier = exports.createDelegationIssuer = exports.DelegationCredentialIssuer = exports.OAuthRequiredError = exports.DelegationRequiredError = exports.NoOpToolProtectionCache = exports.InMemoryToolProtectionCache = exports.createProofVerificationError = exports.PROOF_VERIFICATION_ERROR_CODES = exports.ProofVerificationError = exports.migrateLegacyKeys = exports.StorageKeyHelpers = exports.createStorageProviders = exports.NoOpOAuthConfigCache = exports.InMemoryOAuthConfigCache = exports.BatchDelegationService = exports.OAuthTokenRetrievalService = exports.ProviderValidationError = exports.ProviderValidator = exports.ConsentOnlyModeError = exports.ProviderResolver = exports.OAuthProviderRegistry = exports.ToolContextBuilder = exports.OAuthService = exports.OAuthConfigService = exports.createSessionRegistrationService = exports.SessionRegistrationService = exports.authorizationMatches = exports.AccessControlApiService = exports.ProofVerifier = exports.CryptoService = exports.ToolProtectionService = exports.MCPIRuntimeBase = exports.MemoryIdentityProvider = exports.MemoryNonceCacheProvider = exports.MemoryStorageProvider = exports.IdentityProvider = exports.NonceCacheProvider = exports.StorageProvider = exports.FetchProvider = exports.ClockProvider = exports.CryptoProvider = void 0;
-exports.IdpTokenResolver = exports.UserDidManager = exports.fetchRemoteConfig = exports.bytesToBase64 = exports.base64urlDecodeToString = exports.base64urlDecodeToBytes = exports.base64urlEncodeFromString = exports.base64urlEncodeFromBytes = exports.parseVCJWT = exports.completeVCJWT = exports.createUnsignedVCJWT = exports.canonicalizeJSON = exports.getSchemaStats = exports.getCriticalSchemas = exports.getSchemaById = exports.getSchemasByCategory = exports.getAllSchemas = exports.SCHEMA_REGISTRY = exports.createSchemaVerifier = exports.SchemaVerifier = exports.isValidBase58 = exports.base58Decode = exports.base58Encode = exports.resolveDidKeySync = exports.publicKeyToJwk = exports.extractPublicKeyFromDidKey = exports.isEd25519DidKey = exports.createDidKeyResolver = exports.MemoryDelegationGraphStorage = exports.MemoryStatusListStorage = exports.createCascadingRevocationManager = void 0;
+exports.DelegationGraphManager = exports.isIndexSet = exports.BitstringManager = exports.createStatusListManager = exports.StatusList2021Manager = exports.createDelegationVerifier = exports.DelegationCredentialVerifier = exports.createDelegationIssuer = exports.DelegationCredentialIssuer = exports.createDelegationErrorFormatter = exports.DelegationErrorFormatter = exports.OAuthRequiredError = exports.DelegationRequiredError = exports.NoOpToolProtectionCache = exports.InMemoryToolProtectionCache = exports.createProofVerificationError = exports.PROOF_VERIFICATION_ERROR_CODES = exports.ProofVerificationError = exports.migrateLegacyKeys = exports.StorageKeyHelpers = exports.createStorageProviders = exports.NoOpOAuthConfigCache = exports.InMemoryOAuthConfigCache = exports.BatchDelegationService = exports.OAuthTokenRetrievalService = exports.ProviderValidationError = exports.ProviderValidator = exports.ConsentOnlyModeError = exports.ProviderResolver = exports.OAuthProviderRegistry = exports.ToolContextBuilder = exports.OAuthService = exports.OAuthConfigService = exports.createSessionRegistrationService = exports.SessionRegistrationService = exports.authorizationMatches = exports.AccessControlApiService = exports.ProofVerifier = exports.CryptoService = exports.ToolProtectionService = exports.MCPIRuntimeBase = exports.MemoryIdentityProvider = exports.MemoryNonceCacheProvider = exports.MemoryStorageProvider = exports.IdentityProvider = exports.NonceCacheProvider = exports.StorageProvider = exports.FetchProvider = exports.ClockProvider = exports.CryptoProvider = void 0;
+exports.IdpTokenResolver = exports.UserDidManager = exports.fetchRemoteConfig = exports.bytesToBase64 = exports.base64urlDecodeToString = exports.base64urlDecodeToBytes = exports.base64urlEncodeFromString = exports.base64urlEncodeFromBytes = exports.parseVCJWT = exports.completeVCJWT = exports.createUnsignedVCJWT = exports.canonicalizeJSON = exports.getSchemaStats = exports.getCriticalSchemas = exports.getSchemaById = exports.getSchemasByCategory = exports.getAllSchemas = exports.SCHEMA_REGISTRY = exports.createSchemaVerifier = exports.SchemaVerifier = exports.isValidBase58 = exports.base58Decode = exports.base58Encode = exports.resolveDidKeySync = exports.publicKeyToJwk = exports.extractPublicKeyFromDidKey = exports.isEd25519DidKey = exports.createDidKeyResolver = exports.MemoryDelegationGraphStorage = exports.MemoryStatusListStorage = exports.createCascadingRevocationManager = exports.CascadingRevocationManager = exports.createDelegationGraph = void 0;
 // Base providers
 var base_1 = require("./providers/base");
 Object.defineProperty(exports, "CryptoProvider", { enumerable: true, get: function () { return base_1.CryptoProvider; } });
@@ -104,6 +104,10 @@ var tool_protection_1 = require("./types/tool-protection");
 Object.defineProperty(exports, "DelegationRequiredError", { enumerable: true, get: function () { return tool_protection_1.DelegationRequiredError; } });
 var oauth_required_error_1 = require("./types/oauth-required-error");
 Object.defineProperty(exports, "OAuthRequiredError", { enumerable: true, get: function () { return oauth_required_error_1.OAuthRequiredError; } });
+// Delegation Error Formatter (client-specific messages)
+var delegation_error_formatter_1 = require("./services/delegation-error-formatter");
+Object.defineProperty(exports, "DelegationErrorFormatter", { enumerable: true, get: function () { return delegation_error_formatter_1.DelegationErrorFormatter; } });
+Object.defineProperty(exports, "createDelegationErrorFormatter", { enumerable: true, get: function () { return delegation_error_formatter_1.createDelegationErrorFormatter; } });
 // Delegation (W3C VC-based)
 var vc_issuer_1 = require("./delegation/vc-issuer");
 Object.defineProperty(exports, "DelegationCredentialIssuer", { enumerable: true, get: function () { return vc_issuer_1.DelegationCredentialIssuer; } });

package/dist/services/delegation-error-formatter.d.ts

@@ -0,0 +1,124 @@
+/**
+ * DelegationErrorFormatter - Formats delegation error messages for MCP clients
+ *
+ * This service provides a single source of truth for formatting delegation
+ * required error messages. It supports:
+ * - Default message templates
+ * - Client-specific message customization (claude, chatgpt, cursor, etc.)
+ * - Template interpolation with placeholders
+ * - Markdown support toggle per client
+ *
+ * @module @kya-os/mcp-i-core/services/delegation-error-formatter
+ */
+import type { ClientMessageTemplate, ClientMessagesConfig } from "@kya-os/contracts/config";
+export type { ClientMessageTemplate, ClientMessagesConfig };
+/**
+ * Options for formatting a delegation error message
+ */
+export interface DelegationErrorFormatOptions {
+    /** Name of the tool that requires delegation */
+    toolName: string;
+    /** URL where user can provide consent/delegation */
+    consentUrl?: string;
+    /** Scopes required for the tool */
+    scopes?: string[];
+    /** Client ID (e.g., "claude", "chatgpt", "cursor") - used for client-specific messages */
+    clientId?: string;
+}
+/**
+ * Options for formatting an OAuth error message
+ */
+export interface OAuthErrorFormatOptions {
+    /** Name of the tool that requires OAuth */
+    toolName: string;
+    /** OAuth authorization URL */
+    oauthUrl?: string;
+    /** OAuth provider name (e.g., "GitHub", "Google") */
+    provider?: string;
+    /** Scopes required for the tool */
+    scopes?: string[];
+    /** Client ID (e.g., "claude", "chatgpt", "cursor") - used for client-specific messages */
+    clientId?: string;
+}
+/**
+ * Result of formatting a delegation error
+ */
+export interface DelegationErrorResult {
+    /** Formatted message to display to the user */
+    message: string;
+    /** Consent URL (may be modified with extra params) */
+    consentUrl?: string;
+}
+/**
+ * Result of formatting an OAuth error
+ */
+export interface OAuthErrorResult {
+    /** Formatted message to display to the user */
+    message: string;
+    /** OAuth URL (may be modified with extra params) */
+    oauthUrl?: string;
+}
+/**
+ * Service for formatting delegation error messages
+ *
+ * Provides consistent message formatting across different deployment patterns
+ * (agent, adapter) while supporting client-specific customization.
+ *
+ * @example
+ * ```typescript
+ * const formatter = new DelegationErrorFormatter();
+ * const { message } = formatter.format({
+ *   toolName: "checkout",
+ *   consentUrl: "https://example.com/consent",
+ *   clientId: "claude"
+ * });
+ * ```
+ */
+export declare class DelegationErrorFormatter {
+    private config?;
+    constructor(config?: ClientMessagesConfig);
+    /**
+     * Update the configuration
+     */
+    setConfig(config: ClientMessagesConfig): void;
+    /**
+     * Format a delegation error message
+     *
+     * @param options - Formatting options including toolName, consentUrl, and clientId
+     * @returns Formatted message and potentially modified consent URL
+     */
+    format(options: DelegationErrorFormatOptions): DelegationErrorResult;
+    /**
+     * Format an OAuth error message
+     *
+     * @param options - Formatting options including toolName, oauthUrl, provider, and clientId
+     * @returns Formatted message and potentially modified OAuth URL
+     */
+    formatOAuth(options: OAuthErrorFormatOptions): OAuthErrorResult;
+    /**
+     * Get the template for a specific client, merging with defaults
+     */
+    private getTemplate;
+    /**
+     * Build URL with extra parameters if configured
+     * Used for both consent URLs and OAuth URLs
+     */
+    private buildUrl;
+    /**
+     * Interpolate placeholders in a template string
+     *
+     * Uses a function replacement to avoid special pattern interpretation.
+     * JavaScript's String.replace() interprets patterns like $&, $', $` in the
+     * replacement string. Using () => value prevents this.
+     */
+    private interpolate;
+    /**
+     * Strip markdown links, converting [text](url) to plain "text: url"
+     */
+    private stripMarkdownLinks;
+}
+/**
+ * Create a delegation error formatter with optional configuration
+ */
+export declare function createDelegationErrorFormatter(config?: ClientMessagesConfig): DelegationErrorFormatter;
+//# sourceMappingURL=delegation-error-formatter.d.ts.map

package/dist/services/delegation-error-formatter.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * DelegationErrorFormatter - Formats delegation error messages for MCP clients
+ *
+ * This service provides a single source of truth for formatting delegation
+ * required error messages. It supports:
+ * - Default message templates
+ * - Client-specific message customization (claude, chatgpt, cursor, etc.)
+ * - Template interpolation with placeholders
+ * - Markdown support toggle per client
+ *
+ * @module @kya-os/mcp-i-core/services/delegation-error-formatter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationErrorFormatter = void 0;
+exports.createDelegationErrorFormatter = createDelegationErrorFormatter;
+/**
+ * Default message template (matches original adapter/agent behavior)
+ */
+const DEFAULT_TEMPLATE = {
+    message: `Authorization required.
+
+[Authorize {toolName}]({consentUrl})
+
+Retry after authorizing.`,
+    noUrlMessage: `Authorization required for "{toolName}" but no consent URL is available.
+
+Please contact the administrator to configure delegation for this tool.`,
+    oauthMessage: `Authorization required.
+
+[Sign in with {provider}]({oauthUrl})
+
+Retry after authorizing.`,
+    noOAuthUrlMessage: `Authorization required for "{toolName}" but no {provider} URL is available.
+
+Please contact the administrator to configure OAuth for this tool.`,
+    supportsMarkdown: true,
+};
+/**
+ * Service for formatting delegation error messages
+ *
+ * Provides consistent message formatting across different deployment patterns
+ * (agent, adapter) while supporting client-specific customization.
+ *
+ * @example
+ * ```typescript
+ * const formatter = new DelegationErrorFormatter();
+ * const { message } = formatter.format({
+ *   toolName: "checkout",
+ *   consentUrl: "https://example.com/consent",
+ *   clientId: "claude"
+ * });
+ * ```
+ */
+class DelegationErrorFormatter {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Update the configuration
+     */
+    setConfig(config) {
+        this.config = config;
+    }
+    /**
+     * Format a delegation error message
+     *
+     * @param options - Formatting options including toolName, consentUrl, and clientId
+     * @returns Formatted message and potentially modified consent URL
+     */
+    format(options) {
+        const { toolName, consentUrl, scopes, clientId } = options;
+        // Get the appropriate template for this client
+        const template = this.getTemplate(clientId);
+        // Build the final consent URL with any extra params
+        const finalUrl = this.buildUrl(consentUrl, template);
+        // Choose message based on whether we have a consent URL
+        let message;
+        if (finalUrl) {
+            const messageTemplate = template.message ?? DEFAULT_TEMPLATE.message;
+            message = this.interpolate(messageTemplate, {
+                toolName,
+                consentUrl: finalUrl,
+                scopes: scopes?.join(", ") ?? "",
+            });
+            // If client doesn't support markdown, convert markdown links to plain text
+            if (template.supportsMarkdown === false) {
+                message = this.stripMarkdownLinks(message);
+            }
+        }
+        else {
+            const noUrlTemplate = template.noUrlMessage ?? DEFAULT_TEMPLATE.noUrlMessage;
+            message = this.interpolate(noUrlTemplate, {
+                toolName,
+                consentUrl: "",
+                scopes: scopes?.join(", ") ?? "",
+            });
+        }
+        return { message, consentUrl: finalUrl };
+    }
+    /**
+     * Format an OAuth error message
+     *
+     * @param options - Formatting options including toolName, oauthUrl, provider, and clientId
+     * @returns Formatted message and potentially modified OAuth URL
+     */
+    formatOAuth(options) {
+        const { toolName, oauthUrl, provider = "OAuth", scopes, clientId } = options;
+        // Get the appropriate template for this client
+        const template = this.getTemplate(clientId);
+        // Build the final OAuth URL with any extra params
+        const finalUrl = this.buildUrl(oauthUrl, template);
+        // Choose message based on whether we have an OAuth URL
+        let message;
+        if (finalUrl) {
+            const messageTemplate = template.oauthMessage ?? DEFAULT_TEMPLATE.oauthMessage;
+            message = this.interpolate(messageTemplate, {
+                toolName,
+                oauthUrl: finalUrl,
+                provider,
+                scopes: scopes?.join(", ") ?? "",
+            });
+            // If client doesn't support markdown, convert markdown links to plain text
+            if (template.supportsMarkdown === false) {
+                message = this.stripMarkdownLinks(message);
+            }
+        }
+        else {
+            const noUrlTemplate = template.noOAuthUrlMessage ?? DEFAULT_TEMPLATE.noOAuthUrlMessage;
+            message = this.interpolate(noUrlTemplate, {
+                toolName,
+                oauthUrl: "",
+                provider,
+                scopes: scopes?.join(", ") ?? "",
+            });
+        }
+        return { message, oauthUrl: finalUrl };
+    }
+    /**
+     * Get the template for a specific client, merging with defaults
+     */
+    getTemplate(clientId) {
+        const defaultTemplate = this.config?.default ?? {};
+        // If no client ID or no client-specific config, use default
+        if (!clientId || !this.config?.clients?.[clientId]) {
+            return {
+                ...DEFAULT_TEMPLATE,
+                ...defaultTemplate,
+            };
+        }
+        // Merge: DEFAULT_TEMPLATE < config.default < config.clients[clientId]
+        return {
+            ...DEFAULT_TEMPLATE,
+            ...defaultTemplate,
+            ...this.config.clients[clientId],
+        };
+    }
+    /**
+     * Build URL with extra parameters if configured
+     * Used for both consent URLs and OAuth URLs
+     */
+    buildUrl(baseUrl, template) {
+        if (!baseUrl)
+            return undefined;
+        // If no extra params, return as-is
+        if (!template.extraParams || Object.keys(template.extraParams).length === 0) {
+            return baseUrl;
+        }
+        // Add extra params to URL
+        try {
+            const url = new URL(baseUrl);
+            for (const [key, value] of Object.entries(template.extraParams)) {
+                url.searchParams.set(key, value);
+            }
+            return url.toString();
+        }
+        catch {
+            // If URL parsing fails, return original
+            return baseUrl;
+        }
+    }
+    /**
+     * Interpolate placeholders in a template string
+     *
+     * Uses a function replacement to avoid special pattern interpretation.
+     * JavaScript's String.replace() interprets patterns like $&, $', $` in the
+     * replacement string. Using () => value prevents this.
+     */
+    interpolate(template, values) {
+        let result = template;
+        for (const [key, value] of Object.entries(values)) {
+            // Use function replacement to prevent special pattern interpretation
+            // e.g., URLs containing $& would otherwise get corrupted
+            result = result.replace(new RegExp(`\\{${key}\\}`, "g"), () => value);
+        }
+        return result;
+    }
+    /**
+     * Strip markdown links, converting [text](url) to plain "text: url"
+     */
+    stripMarkdownLinks(text) {
+        // Match [link text](url) and convert to "link text: url"
+        return text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1: $2");
+    }
+}
+exports.DelegationErrorFormatter = DelegationErrorFormatter;
+/**
+ * Create a delegation error formatter with optional configuration
+ */
+function createDelegationErrorFormatter(config) {
+    return new DelegationErrorFormatter(config);
+}
+//# sourceMappingURL=delegation-error-formatter.js.map

package/dist/services/index.d.ts

@@ -4,4 +4,6 @@ export { AccessControlApiService, authorizationMatches, } from './access-control
 export type { AccessControlApiServiceConfig, AccessControlApiServiceMetrics, } from './access-control.service.js';
 export { SessionRegistrationService, createSessionRegistrationService, } from './session-registration.service.js';
 export type { SessionRegistrationServiceConfig, SessionRegistrationResult, } from './session-registration.service.js';
+export { DelegationErrorFormatter, createDelegationErrorFormatter, } from './delegation-error-formatter.js';
+export type { DelegationErrorFormatOptions, DelegationErrorResult, OAuthErrorFormatOptions, OAuthErrorResult, ClientMessageTemplate, ClientMessagesConfig, } from './delegation-error-formatter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/services/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSessionRegistrationService = exports.SessionRegistrationService = exports.authorizationMatches = exports.AccessControlApiService = exports.CryptoService = void 0;
+exports.createDelegationErrorFormatter = exports.DelegationErrorFormatter = exports.createSessionRegistrationService = exports.SessionRegistrationService = exports.authorizationMatches = exports.AccessControlApiService = exports.CryptoService = void 0;
 var crypto_service_js_1 = require("./crypto.service.js");
 Object.defineProperty(exports, "CryptoService", { enumerable: true, get: function () { return crypto_service_js_1.CryptoService; } });
 var access_control_service_js_1 = require("./access-control.service.js");
@@ -9,4 +9,7 @@ Object.defineProperty(exports, "authorizationMatches", { enumerable: true, get:
 var session_registration_service_js_1 = require("./session-registration.service.js");
 Object.defineProperty(exports, "SessionRegistrationService", { enumerable: true, get: function () { return session_registration_service_js_1.SessionRegistrationService; } });
 Object.defineProperty(exports, "createSessionRegistrationService", { enumerable: true, get: function () { return session_registration_service_js_1.createSessionRegistrationService; } });
+var delegation_error_formatter_js_1 = require("./delegation-error-formatter.js");
+Object.defineProperty(exports, "DelegationErrorFormatter", { enumerable: true, get: function () { return delegation_error_formatter_js_1.DelegationErrorFormatter; } });
+Object.defineProperty(exports, "createDelegationErrorFormatter", { enumerable: true, get: function () { return delegation_error_formatter_js_1.createDelegationErrorFormatter; } });
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/mcp-i-core",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Core runtime and types for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,7 @@
     "prepublishOnly": "npm run build && node ../create-mcpi-app/scripts/validate-no-workspace.js"
   },
   "dependencies": {
-    "@kya-os/contracts": "^1.7.0",
+    "@kya-os/contracts": "^1.7.2",
     "jose": "^5.6.3",
     "json-canonicalize": "^2.0.0",
     "zod": "^3.25.76"