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

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export type { OAuthServiceConfig } from "./services/oauth-service";
 export { ToolContextBuilder } from "./services/tool-context-builder";
 export type { ToolContextBuilderConfig } from "./services/tool-context-builder";
 export { OAuthProviderRegistry } from "./services/oauth-provider-registry";
-export { ProviderResolver, ConsentOnlyModeError, } from "./services/provider-resolver";
+export { ProviderResolver, ConsentOnlyModeError, CredentialAuthModeError, } from "./services/provider-resolver";
 export { ProviderValidator, ProviderValidationError, } from "./services/provider-validator";
 export { OAuthTokenRetrievalService } from "./services/oauth-token-retrieval.service";
 export type { OAuthTokenRetrievalServiceConfig } from "./services/oauth-token-retrieval.service";
@@ -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.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.CredentialAuthModeError = 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 = exports.DelegationGraphManager = void 0;
 // Base providers
 var base_1 = require("./providers/base");
 Object.defineProperty(exports, "CryptoProvider", { enumerable: true, get: function () { return base_1.CryptoProvider; } });
@@ -73,6 +73,7 @@ Object.defineProperty(exports, "OAuthProviderRegistry", { enumerable: true, get:
 var provider_resolver_1 = require("./services/provider-resolver");
 Object.defineProperty(exports, "ProviderResolver", { enumerable: true, get: function () { return provider_resolver_1.ProviderResolver; } });
 Object.defineProperty(exports, "ConsentOnlyModeError", { enumerable: true, get: function () { return provider_resolver_1.ConsentOnlyModeError; } });
+Object.defineProperty(exports, "CredentialAuthModeError", { enumerable: true, get: function () { return provider_resolver_1.CredentialAuthModeError; } });
 // Provider Validator (Phase 3)
 var provider_validator_1 = require("./services/provider-validator");
 Object.defineProperty(exports, "ProviderValidator", { enumerable: true, get: function () { return provider_validator_1.ProviderValidator; } });
@@ -104,6 +105,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/logging/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Logging module exports
+ */
+export { logger, createDefaultConsoleLogger, type Logger, type Level, } from "./logger";
+//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Logging module exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultConsoleLogger = exports.logger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
+Object.defineProperty(exports, "createDefaultConsoleLogger", { enumerable: true, get: function () { return logger_1.createDefaultConsoleLogger; } });
+//# sourceMappingURL=index.js.map

package/dist/logging/logger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Transport-aware Logger for MCP-I
+ *
+ * Provides a lightweight, dependency-free logging interface that:
+ * - Maps log levels correctly for Cloudflare Workers (so wrangler tail shows correct severities)
+ * - Routes all logs to stderr for stdio transport (so stdout remains protocol-only)
+ * - Supports runtime configuration of log level and transport mode
+ */
+export type Level = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    configure: (opts?: {
+        level?: Level;
+        transport?: string;
+        forceStderr?: boolean;
+    }) => void;
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+}
+/**
+ * Create a default console logger with transport-aware behavior
+ *
+ * - Cloudflare Workers: Maps levels to console.debug/info/warn/error
+ * - stdio transport: Routes all levels to console.error (stderr) to keep stdout protocol-only
+ */
+export declare function createDefaultConsoleLogger(): Logger;
+/**
+ * Default singleton logger instance
+ * Configure via logger.configure() before use
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Transport-aware Logger for MCP-I
+ *
+ * Provides a lightweight, dependency-free logging interface that:
+ * - Maps log levels correctly for Cloudflare Workers (so wrangler tail shows correct severities)
+ * - Routes all logs to stderr for stdio transport (so stdout remains protocol-only)
+ * - Supports runtime configuration of log level and transport mode
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.createDefaultConsoleLogger = createDefaultConsoleLogger;
+const SEVERITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/**
+ * Create a default console logger with transport-aware behavior
+ *
+ * - Cloudflare Workers: Maps levels to console.debug/info/warn/error
+ * - stdio transport: Routes all levels to console.error (stderr) to keep stdout protocol-only
+ */
+function createDefaultConsoleLogger() {
+    let level = "info";
+    let forceStderr = false;
+    function shouldLog(l) {
+        return SEVERITY[l] >= SEVERITY[level];
+    }
+    function write(l, ...args) {
+        if (!shouldLog(l))
+            return;
+        if (forceStderr) {
+            // stdio transport: all logs go to stderr (console.error)
+            // This ensures stdout remains protocol-only
+            console.error(...args);
+            return;
+        }
+        // Cloudflare Workers: map to appropriate console method
+        switch (l) {
+            case "debug":
+                if (typeof console.debug === "function") {
+                    console.debug(...args);
+                }
+                else {
+                    console.log(...args);
+                }
+                break;
+            case "info":
+                if (typeof console.info === "function") {
+                    console.info(...args);
+                }
+                else {
+                    console.log(...args);
+                }
+                break;
+            case "warn":
+                if (typeof console.warn === "function") {
+                    console.warn(...args);
+                }
+                else {
+                    console.error(...args);
+                }
+                break;
+            case "error":
+                console.error(...args);
+                break;
+        }
+    }
+    return {
+        configure(opts = {}) {
+            if (opts.level)
+                level = opts.level;
+            // Handle transport-based stderr routing
+            // - stdio transport: force all logs to stderr (stdout is protocol-only)
+            // - sse/http transports: use normal console routing
+            // - explicit forceStderr overrides transport-based behavior
+            if (opts.forceStderr === true) {
+                forceStderr = true;
+            }
+            else if (opts.forceStderr === false) {
+                forceStderr = false;
+            }
+            else if (opts.transport === "stdio") {
+                forceStderr = true;
+            }
+            else if (opts.transport === "sse" || opts.transport === "http") {
+                // Reset to normal console routing for non-stdio transports
+                forceStderr = false;
+            }
+        },
+        debug: (...a) => write("debug", ...a),
+        info: (...a) => write("info", ...a),
+        warn: (...a) => write("warn", ...a),
+        error: (...a) => write("error", ...a),
+    };
+}
+/**
+ * Default singleton logger instance
+ * Configure via logger.configure() before use
+ */
+exports.logger = createDefaultConsoleLogger();
+//# sourceMappingURL=logger.js.map

package/dist/services/access-control.service.js

@@ -708,8 +708,8 @@ function authorizationMatches(delegationAuth, toolAuth) {
             return true;
         return delegationAuth.provider === toolAuth.provider;
     }
-    // For credential, compare credentialType (undefined in toolAuth means "any type is acceptable")
-    if (delegationAuth.type === "credential") {
+    // For verifiable_credential, compare credentialType
+    if (delegationAuth.type === "verifiable_credential") {
         // If tool doesn't specify a credential type, any type is acceptable
         if (!toolAuth.credentialType)
             return true;

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/dist/services/provider-resolver.d.ts

@@ -17,6 +17,17 @@ export declare class ConsentOnlyModeError extends Error {
     readonly toolProtection: ToolProtection;
     constructor(toolProtection: ToolProtection);
 }
+/**
+ * Error thrown when a tool requires credential/password-based authentication
+ * This is NOT an error condition - it's a signal to use credential auth flow
+ * (username/password, email/password, etc.) instead of OAuth
+ */
+export declare class CredentialAuthModeError extends Error {
+    readonly toolProtection: ToolProtection;
+    /** The credential provider ID configured for this tool */
+    readonly provider: string;
+    constructor(toolProtection: ToolProtection, provider: string);
+}
 /**
  * Resolves OAuth provider for tools with priority-based fallback strategy
  *
@@ -39,6 +50,17 @@ export declare class ProviderResolver {
      * @returns true if consent-only mode
      */
     isConsentOnlyMode(toolProtection: ToolProtection): boolean;
+    /**
+     * Check if a tool is configured for credential/password-based authentication
+     * This includes username/password, email/password, etc.
+     *
+     * @param toolProtection - Tool protection configuration
+     * @returns Object with isCredential flag and optional provider ID
+     */
+    isCredentialAuthMode(toolProtection: ToolProtection): {
+        isCredential: boolean;
+        provider?: string;
+    };
     /**
      * Resolve OAuth provider for a tool
      *
@@ -46,6 +68,7 @@ export declare class ProviderResolver {
      * @param projectId - Project ID for fetching provider config
      * @returns Provider name (never null - throws if cannot resolve)
      * @throws ConsentOnlyModeError if tool is consent-only (not a real error)
+     * @throws CredentialAuthModeError if tool requires password/credential auth
      * @throws Error if provider cannot be resolved
      */
     resolveProvider(toolProtection: ToolProtection, projectId: string): Promise<string>;

package/dist/services/provider-resolver.js

@@ -8,7 +8,7 @@
  * @package @kya-os/mcp-i-core
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderResolver = exports.ConsentOnlyModeError = void 0;
+exports.ProviderResolver = exports.CredentialAuthModeError = exports.ConsentOnlyModeError = void 0;
 /**
  * Error thrown when a tool is configured for consent-only mode (no OAuth needed)
  * This is NOT an error condition - it's a signal to skip OAuth flow
@@ -22,6 +22,23 @@ class ConsentOnlyModeError extends Error {
     }
 }
 exports.ConsentOnlyModeError = ConsentOnlyModeError;
+/**
+ * Error thrown when a tool requires credential/password-based authentication
+ * This is NOT an error condition - it's a signal to use credential auth flow
+ * (username/password, email/password, etc.) instead of OAuth
+ */
+class CredentialAuthModeError extends Error {
+    toolProtection;
+    /** The credential provider ID configured for this tool */
+    provider;
+    constructor(toolProtection, provider) {
+        super(`Tool requires credential authentication with provider "${provider}"`);
+        this.toolProtection = toolProtection;
+        this.name = "CredentialAuthModeError";
+        this.provider = provider;
+    }
+}
+exports.CredentialAuthModeError = CredentialAuthModeError;
 /**
  * Resolves OAuth provider for tools with priority-based fallback strategy
  *
@@ -53,6 +70,23 @@ class ProviderResolver {
         }
         return false;
     }
+    /**
+     * Check if a tool is configured for credential/password-based authentication
+     * This includes username/password, email/password, etc.
+     *
+     * @param toolProtection - Tool protection configuration
+     * @returns Object with isCredential flag and optional provider ID
+     */
+    isCredentialAuthMode(toolProtection) {
+        // Check explicit authorization.type === 'password'
+        if (toolProtection.authorization?.type === "password") {
+            return {
+                isCredential: true,
+                provider: toolProtection.authorization.provider || "credentials",
+            };
+        }
+        return { isCredential: false };
+    }
     /**
      * Resolve OAuth provider for a tool
      *
@@ -60,14 +94,21 @@ class ProviderResolver {
      * @param projectId - Project ID for fetching provider config
      * @returns Provider name (never null - throws if cannot resolve)
      * @throws ConsentOnlyModeError if tool is consent-only (not a real error)
+     * @throws CredentialAuthModeError if tool requires password/credential auth
      * @throws Error if provider cannot be resolved
      */
     async resolveProvider(toolProtection, projectId) {
-        // Priority 0: Check for consent-only mode (no OAuth required)
+        // Priority 0a: Check for consent-only mode (no OAuth required)
         if (this.isConsentOnlyMode(toolProtection)) {
             console.error(`[ProviderResolver] Tool is consent-only mode (authorization.type=none), skipping OAuth resolution`);
             throw new ConsentOnlyModeError(toolProtection);
         }
+        // Priority 0b: Check for credential/password auth mode (not OAuth)
+        const credentialCheck = this.isCredentialAuthMode(toolProtection);
+        if (credentialCheck.isCredential) {
+            console.error(`[ProviderResolver] Tool requires credential auth (authorization.type=password), provider="${credentialCheck.provider}"`);
+            throw new CredentialAuthModeError(toolProtection, credentialCheck.provider);
+        }
         // Priority 1: Tool-specific provider (Phase 2+ preferred)
         if (toolProtection.oauthProvider) {
             // Ensure registry is loaded before checking

package/dist/services/tool-context-builder.js

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolContextBuilder = void 0;
 const oauth_required_error_js_1 = require("../types/oauth-required-error.js");
+const provider_resolver_js_1 = require("./provider-resolver.js");
 /**
  * Builder for tool execution context
  *
@@ -53,7 +54,18 @@ class ToolContextBuilder {
             provider = await this.resolveProvider(toolProtection);
         }
         catch (error) {
-            // Provider resolution failed - cannot build context
+            // ConsentOnlyModeError and CredentialAuthModeError are NOT errors
+            // They're signals about what auth flow to use - re-throw for caller to handle
+            if (error instanceof provider_resolver_js_1.ConsentOnlyModeError ||
+                error instanceof provider_resolver_js_1.CredentialAuthModeError) {
+                this.config.logger("[ToolContextBuilder] Special auth mode detected, re-throwing", {
+                    toolName,
+                    errorType: error.name,
+                    message: error.message,
+                });
+                throw error;
+            }
+            // Other provider resolution errors - cannot build context
             this.config.logger("[ToolContextBuilder] Provider not resolved", {
                 toolName,
                 userDid: userDid.substring(0, 20) + "...",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/mcp-i-core",
-  "version": "1.4.0",
+  "version": "1.4.3",
   "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.6",
     "jose": "^5.6.3",
     "json-canonicalize": "^2.0.0",
     "zod": "^3.25.76"