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

package/dist/index.d.ts

@@ -21,12 +21,12 @@ export { SessionRegistrationService, createSessionRegistrationService, } from ".
 export type { SessionRegistrationServiceConfig, SessionRegistrationResult, } from "./services/session-registration.service";
 export { OAuthConfigService } from "./services/oauth-config.service";
 export type { OAuthConfigServiceConfig } from "./services/oauth-config.service";
-export { OAuthService } from "./services/oauth-service";
-export type { OAuthServiceConfig } from "./services/oauth-service";
+export { OAuthService, defaultSecretResolver } from "./services/oauth-service";
+export type { OAuthServiceConfig, SecretResolver } 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";
@@ -68,4 +68,5 @@ export type { UserDidStorage, UserDidManagerConfig, UserKeyPair, OAuthIdentity,
 export { IdpTokenResolver } from "./identity/idp-token-resolver";
 export type { IdpTokenResolverConfig } from "./identity/idp-token-resolver";
 export type { IIdpTokenStorage, TokenUsageMetadata, IdpTokensWithMetadata, } from "./identity/idp-token-storage.interface";
+export { logger, createDefaultConsoleLogger, type Logger, type Level, } from "./logging";
 //# sourceMappingURL=index.d.ts.map

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.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;
+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.defaultSecretResolver = 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.createDefaultConsoleLogger = exports.logger = 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 = exports.isIndexSet = void 0;
 // Base providers
 var base_1 = require("./providers/base");
 Object.defineProperty(exports, "CryptoProvider", { enumerable: true, get: function () { return base_1.CryptoProvider; } });
@@ -63,6 +63,7 @@ Object.defineProperty(exports, "OAuthConfigService", { enumerable: true, get: fu
 // OAuth Service (Phase 1)
 var oauth_service_1 = require("./services/oauth-service");
 Object.defineProperty(exports, "OAuthService", { enumerable: true, get: function () { return oauth_service_1.OAuthService; } });
+Object.defineProperty(exports, "defaultSecretResolver", { enumerable: true, get: function () { return oauth_service_1.defaultSecretResolver; } });
 // Tool Context Builder (Phase 1)
 var tool_context_builder_1 = require("./services/tool-context-builder");
 Object.defineProperty(exports, "ToolContextBuilder", { enumerable: true, get: function () { return tool_context_builder_1.ToolContextBuilder; } });
@@ -73,6 +74,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; } });
@@ -180,4 +182,8 @@ Object.defineProperty(exports, "UserDidManager", { enumerable: true, get: functi
 // IDP Token Resolver (Phase 1 - MH-7, updated for CRED-003)
 var idp_token_resolver_1 = require("./identity/idp-token-resolver");
 Object.defineProperty(exports, "IdpTokenResolver", { enumerable: true, get: function () { return idp_token_resolver_1.IdpTokenResolver; } });
+// Logger (transport-aware logging)
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logging_1.logger; } });
+Object.defineProperty(exports, "createDefaultConsoleLogger", { enumerable: true, get: function () { return logging_1.createDefaultConsoleLogger; } });
 //# sourceMappingURL=index.js.map

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/oauth-service.d.ts

@@ -4,11 +4,39 @@
  * Handles OAuth token exchange and refresh using PKCE (Proof Key for Code Exchange).
  * Supports both direct PKCE exchange with OAuth providers and proxy mode via AgentShield.
  *
+ * MCP-I Provider Registry Model:
+ * - Client secrets are NOT sent via the API response
+ * - Agents receive metadata.clientSecretName from AgentShield
+ * - Secrets are resolved at runtime from secure storage (Cloudflare Worker env)
+ * - The SecretResolver interface enables platform-specific secret resolution
+ *
  * @package @kya-os/mcp-i-core
  */
 import type { FetchProvider } from "../providers/base.js";
 import type { OAuthConfigService } from "./oauth-config.service.js";
-import type { IdpTokens } from "@kya-os/contracts/config";
+import type { IdpTokens, OAuthProvider } from "@kya-os/contracts/config";
+/**
+ * Secret Resolver Interface
+ *
+ * Platform-specific interface for resolving secrets from secure storage.
+ * Implementations:
+ * - Cloudflare Workers: Resolves from env bindings
+ * - Node.js: Resolves from process.env
+ * - Other platforms: Custom implementations
+ */
+export interface SecretResolver {
+    /**
+     * Resolve a secret by its name from secure storage
+     * @param secretName - The name/key of the secret (e.g., 'KYA_PROD_MYPROJ_GITHUB_CLIENT_SECRET')
+     * @returns The secret value, or undefined if not found
+     */
+    resolveSecret(secretName: string): Promise<string | undefined>;
+}
+/**
+ * Default secret resolver that uses environment variables
+ * Used when no custom resolver is provided
+ */
+export declare const defaultSecretResolver: SecretResolver;
 export interface OAuthServiceConfig {
     /** OAuth config service for fetching provider configurations */
     configService: OAuthConfigService;
@@ -22,6 +50,12 @@ export interface OAuthServiceConfig {
     projectId: string;
     /** Optional logger callback for diagnostics */
     logger?: (message: string, data?: unknown) => void;
+    /**
+     * Optional secret resolver for MCP-I provider-registry model
+     * Used to resolve client secrets from secure storage
+     * Default: Uses environment variables (process.env)
+     */
+    secretResolver?: SecretResolver;
 }
 /**
  * Service for OAuth token exchange and refresh
@@ -29,6 +63,17 @@ export interface OAuthServiceConfig {
 export declare class OAuthService {
     private config;
     constructor(config: OAuthServiceConfig);
+    /**
+     * Resolve client secret for a provider using the MCP-I provider-registry model
+     *
+     * Resolution order:
+     * 1. If metadata.clientSecretName exists, resolve from secure storage
+     * 2. Fall back to clientSecret field (legacy/backward compatibility)
+     *
+     * @param providerConfig - The OAuth provider configuration
+     * @returns The resolved client secret, or undefined if not available
+     */
+    resolveClientSecret(providerConfig: OAuthProvider): Promise<string | undefined>;
     /**
      * Exchange authorization code for IDP tokens using PKCE
      *

package/dist/services/oauth-service.js

@@ -5,10 +5,29 @@
  * Handles OAuth token exchange and refresh using PKCE (Proof Key for Code Exchange).
  * Supports both direct PKCE exchange with OAuth providers and proxy mode via AgentShield.
  *
+ * MCP-I Provider Registry Model:
+ * - Client secrets are NOT sent via the API response
+ * - Agents receive metadata.clientSecretName from AgentShield
+ * - Secrets are resolved at runtime from secure storage (Cloudflare Worker env)
+ * - The SecretResolver interface enables platform-specific secret resolution
+ *
  * @package @kya-os/mcp-i-core
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuthService = void 0;
+exports.OAuthService = exports.defaultSecretResolver = void 0;
+/**
+ * Default secret resolver that uses environment variables
+ * Used when no custom resolver is provided
+ */
+exports.defaultSecretResolver = {
+    async resolveSecret(secretName) {
+        // For Node.js environments, check process.env
+        if (typeof process !== "undefined" && process.env) {
+            return process.env[secretName];
+        }
+        return undefined;
+    },
+};
 /**
  * Service for OAuth token exchange and refresh
  */
@@ -22,8 +41,55 @@ class OAuthService {
             agentShieldApiKey: config.agentShieldApiKey,
             projectId: config.projectId,
             logger: config.logger || (() => { }),
+            secretResolver: config.secretResolver || exports.defaultSecretResolver,
         };
     }
+    /**
+     * Resolve client secret for a provider using the MCP-I provider-registry model
+     *
+     * Resolution order:
+     * 1. If metadata.clientSecretName exists, resolve from secure storage
+     * 2. Fall back to clientSecret field (legacy/backward compatibility)
+     *
+     * @param providerConfig - The OAuth provider configuration
+     * @returns The resolved client secret, or undefined if not available
+     */
+    async resolveClientSecret(providerConfig) {
+        // MCP-I Provider Registry model: resolve secret by name
+        if (providerConfig.metadata?.clientSecretName) {
+            const secretName = providerConfig.metadata.clientSecretName;
+            this.config.logger("[OAuthService] Resolving client secret by name", {
+                secretName,
+                version: providerConfig.metadata.clientSecretVersion,
+            });
+            const secret = await this.config.secretResolver.resolveSecret(secretName);
+            if (secret) {
+                this.config.logger("[OAuthService] Client secret resolved successfully", {
+                    secretName,
+                });
+                return secret;
+            }
+            this.config.logger("[OAuthService] Client secret not found in secure storage", {
+                secretName,
+            });
+            // Fall through to try clientSecret field
+        }
+        // Legacy model: use clientSecret directly (if provided)
+        // DEPRECATED: This path is for backward compatibility only
+        // New deployments should use metadata.clientSecretName with secure storage
+        if (providerConfig.clientSecret) {
+            this.config.logger("[OAuthService] DEPRECATED: Using legacy clientSecret field - " +
+                "migrate to metadata.clientSecretName for better security", {
+                telemetry: {
+                    event: "oauth.deprecated_client_secret_used",
+                    hasMetadata: !!providerConfig.metadata,
+                    hasSecretName: !!providerConfig.metadata?.clientSecretName,
+                },
+            });
+            return providerConfig.clientSecret;
+        }
+        return undefined;
+    }
     /**
      * Exchange authorization code for IDP tokens using PKCE
      *
@@ -60,10 +126,13 @@ class OAuthService {
      * Exchange token directly with OAuth provider using PKCE
      */
     async exchangeTokenPKCE(providerConfig, code, codeVerifier, redirectUri) {
+        // Resolve client secret using MCP-I provider-registry model
+        const clientSecret = await this.resolveClientSecret(providerConfig);
         this.config.logger("[OAuthService] Exchanging token with PKCE", {
             provider: providerConfig.authorizationUrl,
             tokenUrl: providerConfig.tokenUrl,
-            hasClientSecret: !!providerConfig.clientSecret,
+            hasClientSecret: !!clientSecret,
+            resolvedViaSecretName: !!providerConfig.metadata?.clientSecretName,
         });
         // Build token exchange parameters
         // Note: GitHub OAuth Apps require client_secret even with PKCE
@@ -75,10 +144,10 @@ class OAuthService {
             client_id: providerConfig.clientId,
             code_verifier: codeVerifier,
         };
-        // Include client_secret if provider has one configured
+        // Include client_secret if resolved (either from secure storage or legacy field)
         // This is required for GitHub OAuth Apps and other providers that need it
-        if (providerConfig.clientSecret) {
-            params.client_secret = providerConfig.clientSecret;
+        if (clientSecret) {
+            params.client_secret = clientSecret;
         }
         const response = await this.config.fetchProvider.fetch(providerConfig.tokenUrl, {
             method: "POST",

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.1",
+  "version": "1.4.4",
   "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.2",
+    "@kya-os/contracts": "^1.7.7",
     "jose": "^5.6.3",
     "json-canonicalize": "^2.0.0",
     "zod": "^3.25.76"