@kya-os/mcp-i-core 1.3.24 → 1.3.25

package/dist/identity/user-did-manager.d.ts

@@ -13,7 +13,7 @@
  * 2. Session storage lookup
  * 3. Return null (session stays anonymous)
  */
-import { CryptoProvider } from '../providers/base';
+import { CryptoProvider } from "../providers/base";
 /**
  * OAuth identity for persistent user DID lookup
  */

package/dist/identity/user-did-manager.js

@@ -56,7 +56,7 @@ class UserDidManager {
                 }
             }
             catch (error) {
-                console.warn('[UserDidManager] OAuth key pair lookup failed:', error);
+                console.warn("[UserDidManager] OAuth key pair lookup failed:", error);
             }
         }
         // Check session storage if available
@@ -69,7 +69,7 @@ class UserDidManager {
                 }
             }
             catch (error) {
-                console.warn('[UserDidManager] Session key pair lookup failed:', error);
+                console.warn("[UserDidManager] Session key pair lookup failed:", error);
             }
         }
         return null;
@@ -96,13 +96,16 @@ class UserDidManager {
             return this.sessionDidCache.get(sessionId);
         }
         // PRIORITY 1: If OAuth identity provided, check for persistent user DID mapping
-        if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage?.getByOAuth) {
+        if (oauthIdentity &&
+            oauthIdentity.provider &&
+            oauthIdentity.subject &&
+            this.config.storage?.getByOAuth) {
             try {
                 const persistentUserDid = await this.config.storage.getByOAuth(oauthIdentity.provider, oauthIdentity.subject);
                 if (persistentUserDid) {
-                    console.log('[UserDidManager] Found persistent user DID from OAuth mapping:', {
+                    console.error("[UserDidManager] Found persistent user DID from OAuth mapping:", {
                         provider: oauthIdentity.provider,
-                        userDid: persistentUserDid.substring(0, 20) + '...',
+                        userDid: persistentUserDid.substring(0, 20) + "...",
                     });
                     // Cache it for this session
                     this.sessionDidCache.set(sessionId, persistentUserDid);
@@ -113,7 +116,7 @@ class UserDidManager {
                         }
                         catch (error) {
                             // Log but continue - DID is cached and will be returned
-                            console.warn('[UserDidManager] Failed to cache persistent DID in session storage:', error);
+                            console.warn("[UserDidManager] Failed to cache persistent DID in session storage:", error);
                         }
                     }
                     return persistentUserDid;
@@ -121,7 +124,7 @@ class UserDidManager {
             }
             catch (error) {
                 // Log but continue - will check session storage or generate new DID
-                console.warn('[UserDidManager] OAuth lookup failed, falling back to session storage:', error);
+                console.warn("[UserDidManager] OAuth lookup failed, falling back to session storage:", error);
             }
         }
         // PRIORITY 2: Check session storage if available
@@ -131,18 +134,21 @@ class UserDidManager {
                 if (storedDid) {
                     this.sessionDidCache.set(sessionId, storedDid);
                     // If OAuth identity provided but no persistent mapping found, create one now
-                    if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage.setByOAuth) {
+                    if (oauthIdentity &&
+                        oauthIdentity.provider &&
+                        oauthIdentity.subject &&
+                        this.config.storage.setByOAuth) {
                         try {
                             await this.config.storage.setByOAuth(oauthIdentity.provider, oauthIdentity.subject, storedDid, 90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
                             );
-                            console.log('[UserDidManager] Created persistent OAuth mapping for existing user DID:', {
+                            console.error("[UserDidManager] Created persistent OAuth mapping for existing user DID:", {
                                 provider: oauthIdentity.provider,
-                                userDid: storedDid.substring(0, 20) + '...',
+                                userDid: storedDid.substring(0, 20) + "...",
                             });
                         }
                         catch (error) {
                             // Log but continue - mapping creation failed, but DID is still valid
-                            console.warn('[UserDidManager] Failed to create OAuth mapping:', error);
+                            console.warn("[UserDidManager] Failed to create OAuth mapping:", error);
                         }
                     }
                     return storedDid;
@@ -150,7 +156,7 @@ class UserDidManager {
             }
             catch (error) {
                 // Log but continue - session will be anonymous
-                console.warn('[UserDidManager] Storage.get failed:', error);
+                console.warn("[UserDidManager] Storage.get failed:", error);
             }
         }
         // PHASE 5: No ephemeral DID generation - session stays anonymous
@@ -176,21 +182,23 @@ class UserDidManager {
                 await this.config.storage.set(sessionId, userDid, 1800); // 30 minutes TTL
             }
             catch (error) {
-                console.warn('[UserDidManager] Failed to store user DID in session storage:', error);
+                console.warn("[UserDidManager] Failed to store user DID in session storage:", error);
             }
         }
         // Create OAuth mapping if provided
-        if (oauthIdentity?.provider && oauthIdentity?.subject && this.config.storage?.setByOAuth) {
+        if (oauthIdentity?.provider &&
+            oauthIdentity?.subject &&
+            this.config.storage?.setByOAuth) {
             try {
                 await this.config.storage.setByOAuth(oauthIdentity.provider, oauthIdentity.subject, userDid, 90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
                 );
-                console.log('[UserDidManager] Created OAuth → DID mapping:', {
+                console.error("[UserDidManager] Created OAuth → DID mapping:", {
                     provider: oauthIdentity.provider,
-                    userDid: userDid.substring(0, 20) + '...',
+                    userDid: userDid.substring(0, 20) + "...",
                 });
             }
             catch (error) {
-                console.warn('[UserDidManager] Failed to create OAuth mapping:', error);
+                console.warn("[UserDidManager] Failed to create OAuth mapping:", error);
             }
         }
     }
@@ -217,7 +225,7 @@ class UserDidManager {
             // Generate did:web (requires web server setup)
             // For now, fall back to did:key
             // TODO: Implement did:web generation if needed
-            console.warn('[UserDidManager] did:web not yet implemented, using did:key');
+            console.warn("[UserDidManager] did:web not yet implemented, using did:key");
         }
         // Generate Ed25519 keypair for user DID
         const keyPair = await this.config.crypto.generateKeyPair();
@@ -258,21 +266,21 @@ class UserDidManager {
      * Simple implementation for did:key generation
      */
     base58Encode(bytes) {
-        const alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+        const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
         let num = BigInt(0);
         // Convert bytes to big integer
         for (let i = 0; i < bytes.length; i++) {
             num = num * BigInt(256) + BigInt(bytes[i]);
         }
         // Convert to base58
-        let result = '';
+        let result = "";
         while (num > 0) {
             result = alphabet[Number(num % BigInt(58))] + result;
             num = num / BigInt(58);
         }
         // Add leading zeros
         for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
-            result = '1' + result;
+            result = "1" + result;
         }
         return result;
     }
@@ -280,9 +288,9 @@ class UserDidManager {
      * Convert base64 string to Uint8Array
      */
     base64ToBytes(base64) {
-        if (typeof Buffer !== 'undefined') {
+        if (typeof Buffer !== "undefined") {
             // Node.js environment
-            return new Uint8Array(Buffer.from(base64, 'base64'));
+            return new Uint8Array(Buffer.from(base64, "base64"));
         }
         else {
             // Browser/Workers environment
@@ -323,7 +331,7 @@ class UserDidManager {
             }
             catch (error) {
                 // Log but continue - cache is already cleared
-                console.warn('[UserDidManager] Storage.delete failed, continuing:', error);
+                console.warn("[UserDidManager] Storage.delete failed, continuing:", error);
             }
         }
     }

package/dist/index.d.ts

@@ -26,8 +26,8 @@ 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 } from "./services/provider-resolver";
-export { ProviderValidator, ProviderValidationError } from "./services/provider-validator";
+export { ProviderResolver, ConsentOnlyModeError, } 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";
 export { BatchDelegationService } from "./services/batch-delegation.service";
@@ -52,7 +52,7 @@ export { CascadingRevocationManager, createCascadingRevocationManager, type Revo
 export { MemoryStatusListStorage } from "./delegation/storage/memory-statuslist-storage";
 export { MemoryDelegationGraphStorage } from "./delegation/storage/memory-graph-storage";
 export { createDidKeyResolver, isEd25519DidKey, extractPublicKeyFromDidKey, publicKeyToJwk, resolveDidKeySync, } from "./delegation/did-key-resolver";
-export { base58Encode, base58Decode, isValidBase58, } from "./utils/base58";
+export { base58Encode, base58Decode, isValidBase58 } from "./utils/base58";
 export { SchemaVerifier, createSchemaVerifier, type SchemaMetadata, type FieldComplianceResult, type SchemaComplianceReport, type FullComplianceReport, } from "./compliance/schema-verifier";
 export { SCHEMA_REGISTRY, getAllSchemas, getSchemasByCategory, getSchemaById, getCriticalSchemas, getSchemaStats, } from "./compliance/schema-registry";
 export { canonicalizeJSON, createUnsignedVCJWT, completeVCJWT, parseVCJWT, type VCJWTHeader, type VCJWTPayload, type EncodeVCAsJWTOptions, } from "./delegation/utils";

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.createCascadingRevocationManager = 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.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 = void 0;
+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;
 // Base providers
 var base_1 = require("./providers/base");
 Object.defineProperty(exports, "CryptoProvider", { enumerable: true, get: function () { return base_1.CryptoProvider; } });
@@ -72,6 +72,7 @@ Object.defineProperty(exports, "OAuthProviderRegistry", { enumerable: true, get:
 // Provider Resolver (Phase 2)
 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; } });
 // 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; } });

package/dist/runtime/base.js

@@ -113,14 +113,14 @@ class MCPIRuntimeBase {
                 userDid = resolvedDid ?? undefined;
                 if (this.config.audit?.enabled) {
                     if (userDid) {
-                        console.log("[MCP-I] Resolved existing user DID for session:", {
+                        console.error("[MCP-I] Resolved existing user DID for session:", {
                             userDid: userDid.substring(0, 20) + "...",
                             hasOAuth: !!oauthIdentity,
                             provider: oauthIdentity?.provider,
                         });
                     }
                     else {
-                        console.log("[MCP-I] Session started anonymous (no userDid):", {
+                        console.error("[MCP-I] Session started anonymous (no userDid):", {
                             sessionId: sessionId.substring(0, 8) + "...",
                             hasOAuth: !!oauthIdentity,
                         });
@@ -219,7 +219,7 @@ class MCPIRuntimeBase {
             await this.userDidManager.setUserDidForSession(sessionId, userDid, oauthIdentity);
         }
         if (this.config.audit?.enabled) {
-            console.log("[MCP-I] Session identity updated (Phase 5):", {
+            console.error("[MCP-I] Session identity updated (Phase 5):", {
                 sessionId: sessionId.substring(0, 8) + "...",
                 userDid: userDid.substring(0, 20) + "...",
                 provider: oauthIdentity?.provider,
@@ -248,7 +248,7 @@ class MCPIRuntimeBase {
             // Get agent identity to check protection
             const identity = await this.getIdentity();
             if (this.config.audit?.enabled) {
-                console.log("[MCP-I] Checking tool protection:", {
+                console.error("[MCP-I] Checking tool protection:", {
                     tool: toolName,
                     agentDid: identity.did.slice(0, 20) + "...",
                     hasDelegation: !!(session?.delegationToken || session?.consentProof),
@@ -312,7 +312,7 @@ class MCPIRuntimeBase {
                     // Verify delegation token with AccessControlApiService
                     try {
                         if (this.config.audit?.enabled) {
-                            console.log("[MCP-I] 🔐 Verifying delegation token with AccessControlApiService", {
+                            console.error("[MCP-I] 🔐 Verifying delegation token with AccessControlApiService", {
                                 tool: toolName,
                                 agentDid: identity.did.slice(0, 20) + "...",
                                 hasDelegationToken: !!delegationToken,
@@ -331,7 +331,7 @@ class MCPIRuntimeBase {
                         if (session?.userDid) {
                             verifyRequest.user_did = session.userDid;
                             if (this.config.audit?.enabled) {
-                                console.log("[MCP-I] 🔐 Including user_did in verification request", {
+                                console.error("[MCP-I] 🔐 Including user_did in verification request", {
                                     userDid: session.userDid.slice(0, 20) + "...",
                                 });
                             }
@@ -442,7 +442,7 @@ class MCPIRuntimeBase {
                             }
                             // User identifier validation passed (direct match or trusted AgentShield verification)
                             if (this.config.audit?.enabled) {
-                                console.log("[MCP-I] ✅ User identifier validation PASSED", {
+                                console.error("[MCP-I] ✅ User identifier validation PASSED", {
                                     tool: toolName,
                                     agentDid: identity.did.slice(0, 20) + "...",
                                     userDid: sessionUserDid.substring(0, 20) + "...",
@@ -530,7 +530,7 @@ class MCPIRuntimeBase {
                             }
                             // Authorization method validation passed
                             if (this.config.audit?.enabled) {
-                                console.log("[MCP-I] ✅ Authorization method validation PASSED", {
+                                console.error("[MCP-I] ✅ Authorization method validation PASSED", {
                                     tool: toolName,
                                     agentDid: identity.did.slice(0, 20) + "...",
                                     authType: delegationAuth.type,
@@ -541,7 +541,7 @@ class MCPIRuntimeBase {
                         // If credential is missing entirely (KV/Memory verifiers), skip validation for backward compatibility
                         // Verification succeeded
                         if (this.config.audit?.enabled) {
-                            console.log("[MCP-I] ✅ Delegation verification SUCCEEDED", {
+                            console.error("[MCP-I] ✅ Delegation verification SUCCEEDED", {
                                 tool: toolName,
                                 agentDid: identity.did.slice(0, 20) + "...",
                                 delegationId: verificationResult.data.delegation_id,
@@ -614,7 +614,7 @@ class MCPIRuntimeBase {
             else {
                 // No protection required - tool can be executed freely
                 if (this.config.audit?.enabled) {
-                    console.log("[MCP-I] Tool protection check passed (no delegation required)", {
+                    console.error("[MCP-I] Tool protection check passed (no delegation required)", {
                         tool: toolName,
                         agentDid: identity.did.slice(0, 20) + "...",
                         reason: "Tool not configured to require delegation",
@@ -1120,7 +1120,7 @@ class MCPIRuntimeBase {
             this.config.audit.logFunction(logLine);
         }
         else {
-            console.log("[AUDIT]", logLine);
+            console.error("[AUDIT]", logLine);
         }
     }
     createDIDDocument(identity) {

package/dist/services/provider-resolver.d.ts

@@ -9,10 +9,19 @@
 import type { ToolProtection } from "@kya-os/contracts/tool-protection";
 import type { OAuthProviderRegistry } from "./oauth-provider-registry.js";
 import type { OAuthConfigService } from "./oauth-config.service.js";
+/**
+ * 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
+ */
+export declare class ConsentOnlyModeError extends Error {
+    readonly toolProtection: ToolProtection;
+    constructor(toolProtection: ToolProtection);
+}
 /**
  * Resolves OAuth provider for tools with priority-based fallback strategy
  *
  * Priority order:
+ * 0. Check for consent-only mode (authorization.type === 'none') - skip OAuth
  * 1. Tool-specific oauthProvider field (Phase 2+ preferred)
  * 2. Scope prefix inference (fallback)
  * 3. Project-configured provider from AgentShield dashboard
@@ -22,12 +31,21 @@ export declare class ProviderResolver {
     private registry;
     private configService;
     constructor(registry: OAuthProviderRegistry, configService: OAuthConfigService);
+    /**
+     * Check if a tool is configured for consent-only mode
+     * Consent-only means delegation is required but no OAuth provider is needed
+     *
+     * @param toolProtection - Tool protection configuration
+     * @returns true if consent-only mode
+     */
+    isConsentOnlyMode(toolProtection: ToolProtection): boolean;
     /**
      * Resolve OAuth provider for a tool
      *
      * @param toolProtection - Tool protection configuration
      * @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 Error if provider cannot be resolved
      */
     resolveProvider(toolProtection: ToolProtection, projectId: string): Promise<string>;

package/dist/services/provider-resolver.js

@@ -8,11 +8,25 @@
  * @package @kya-os/mcp-i-core
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderResolver = void 0;
+exports.ProviderResolver = 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
+ */
+class ConsentOnlyModeError extends Error {
+    toolProtection;
+    constructor(toolProtection) {
+        super("Tool is configured for consent-only mode (no OAuth provider required)");
+        this.toolProtection = toolProtection;
+        this.name = "ConsentOnlyModeError";
+    }
+}
+exports.ConsentOnlyModeError = ConsentOnlyModeError;
 /**
  * Resolves OAuth provider for tools with priority-based fallback strategy
  *
  * Priority order:
+ * 0. Check for consent-only mode (authorization.type === 'none') - skip OAuth
  * 1. Tool-specific oauthProvider field (Phase 2+ preferred)
  * 2. Scope prefix inference (fallback)
  * 3. Project-configured provider from AgentShield dashboard
@@ -25,15 +39,35 @@ class ProviderResolver {
         this.registry = registry;
         this.configService = configService;
     }
+    /**
+     * Check if a tool is configured for consent-only mode
+     * Consent-only means delegation is required but no OAuth provider is needed
+     *
+     * @param toolProtection - Tool protection configuration
+     * @returns true if consent-only mode
+     */
+    isConsentOnlyMode(toolProtection) {
+        // Check explicit authorization.type === 'none'
+        if (toolProtection.authorization?.type === "none") {
+            return true;
+        }
+        return false;
+    }
     /**
      * Resolve OAuth provider for a tool
      *
      * @param toolProtection - Tool protection configuration
      * @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 Error if provider cannot be resolved
      */
     async resolveProvider(toolProtection, projectId) {
+        // Priority 0: 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 1: Tool-specific provider (Phase 2+ preferred)
         if (toolProtection.oauthProvider) {
             // Ensure registry is loaded before checking
@@ -54,7 +88,7 @@ class ProviderResolver {
                 await this.registry.loadFromAgentShield(projectId);
             }
             if (this.registry.hasProvider(inferredProvider)) {
-                console.log(`[ProviderResolver] Inferred provider "${inferredProvider}" from scopes`);
+                console.error(`[ProviderResolver] Inferred provider "${inferredProvider}" from scopes`);
                 return inferredProvider;
             }
         }

package/dist/services/tool-protection.service.d.ts

@@ -4,11 +4,23 @@
  * This service manages tool protection configuration from AgentShield API with
  * efficient caching and automatic synchronization support.
  *
+ * CONFIGURATION PRECEDENCE (highest to lowest):
+ * ---------------------------------------------
+ * 1. Remote config (AgentShield API) - WINS (source of truth)
+ * 2. Local config (localConfig) - Base defaults, overridden by remote
+ * 3. Framework defaults
+ *
+ * OFFLINE FALLBACK (only when API unavailable):
+ * ---------------------------------------------
+ * 1. Stale cache (if allowStaleCache=true and within maxStaleCacheAge)
+ * 2. offlineFallbackConfig (explicit offline-only config)
+ * 3. failSafeBehavior (deny-all or allow-all)
+ *
  * CORE FUNCTIONALITY:
  * -------------------
- * 1. Fetches tool protection config from AgentShield API
- * 2. Caches responses with configurable TTL (default 5 minutes)
- * 3. Falls back to local config if API unavailable
+ * 1. Fetches tool protection config from AgentShield API (remote wins)
+ * 2. Merges with local config (local serves as base defaults)
+ * 3. Caches responses with configurable TTL (default 5 minutes)
  * 4. Provides delegation requirement checking before tool execution
  *
  * SYNCHRONIZATION WITH AGENTSHIELD:
@@ -133,6 +145,16 @@ export declare class ToolProtectionService {
      * @param options.bypassCDNCache When true, adds cache-busting to bypass CDN caches (used by clearAndRefresh)
      */
     private fetchFromApi;
+    /**
+     * Parse tool protections from API response
+     *
+     * Extracts tool protection configs from merged config format:
+     * { data: { config: { toolProtection: { tools: {...} } } } }
+     *
+     * @param response API response from AgentShield
+     * @returns Record of tool name to ToolProtection
+     */
+    private parseToolProtectionsFromResponse;
     /**
      * Clear the cache for a project or agent (useful for testing or manual refresh)
      *