@juspay/neurolink 9.58.0 → 9.59.0

package/dist/lib/neurolink.d.ts

@@ -968,6 +968,40 @@ export declare class NeuroLink {
      * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): TypedEventEmitter<NeuroLinkEvents>;
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    checkCredentials(input: {
+        provider: string;
+        model?: string;
+    }): Promise<{
+        provider: string;
+        status: "ok" | "missing" | "expired" | "denied" | "network" | "unknown";
+        detail: string;
+    }>;
     /**
      * Emit tool start event with execution tracking
      * @param toolName - Name of the tool being executed

package/dist/lib/neurolink.js

@@ -52,7 +52,7 @@ import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
-import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/index.js";
+import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { TaskManager } from "./tasks/taskManager.js";
@@ -187,6 +187,13 @@ function isNonRetryableProviderError(error) {
     if (error instanceof AuthorizationError) {
         return true;
     }
+    // Curator P1-1: model-access-denied is permanent for the (provider, model)
+    // pair until the team whitelist changes. Retrying with the same config
+    // would just waste a second roundtrip. Caller / fallback-orchestrator
+    // should pick a different model.
+    if (error instanceof ModelAccessDeniedError) {
+        return true;
+    }
     // Check for HTTP status codes on error objects (e.g., from Vercel AI SDK)
     if (error && typeof error === "object") {
         const err = error;
@@ -6087,6 +6094,87 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    async checkCredentials(input) {
+        const { provider, model } = input;
+        const probeText = "ping";
+        try {
+            // 1-token probe is cheap, exercises auth + routing without much cost.
+            await this.generate({
+                provider: provider,
+                ...(model && { model }),
+                input: { text: probeText },
+                maxTokens: 16,
+                disableTools: true,
+            });
+            return { provider, status: "ok", detail: "credentials valid" };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const lower = msg.toLowerCase();
+            if (err instanceof ModelAccessDeniedError) {
+                return {
+                    provider,
+                    status: "denied",
+                    detail: msg,
+                };
+            }
+            if (lower.includes("authentication") ||
+                lower.includes("401") ||
+                lower.includes("invalid api key") ||
+                lower.includes("incorrect api key") ||
+                lower.includes("api_key_invalid") ||
+                lower.includes("token has expired") ||
+                lower.includes("expired credentials")) {
+                return { provider, status: "expired", detail: msg };
+            }
+            if (lower.includes("not configured") ||
+                lower.includes("missing api") ||
+                lower.includes("api key is required") ||
+                lower.includes("no api key") ||
+                lower.includes("application default credentials") ||
+                lower.includes("google_application_credentials") ||
+                lower.includes("project_id") ||
+                lower.includes("default credentials") ||
+                lower.includes("service account")) {
+                return { provider, status: "missing", detail: msg };
+            }
+            if (lower.includes("econnrefused") ||
+                lower.includes("enotfound") ||
+                lower.includes("could not resolve") ||
+                lower.includes("timeout") ||
+                lower.includes("network") ||
+                lower.includes("cannot connect")) {
+                return { provider, status: "network", detail: msg };
+            }
+            return { provider, status: "unknown", detail: msg };
+        }
+    }
     // ========================================
     // ENHANCED: Tool Event Emission API
     // ========================================

package/dist/lib/providers/litellm.js

@@ -5,7 +5,7 @@ import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { AuthenticationError, InvalidModelError, ModelAccessDeniedError, NetworkError, ProviderError, RateLimitError, isModelAccessDeniedMessage, parseAllowedModels, } from "../types/index.js";
 import { isAbortError } from "../utils/errorHandling.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { logger } from "../utils/logger.js";
@@ -100,6 +100,17 @@ export class LiteLLMProvider extends BaseProvider {
                 return new NetworkError("LiteLLM proxy server not available. Please start the LiteLLM proxy server at " +
                     `${process.env.LITELLM_BASE_URL || "http://localhost:4000"}`, this.providerName);
             }
+            // Curator P1-1: detect "team not allowed to access model" responses
+            // and surface as ModelAccessDeniedError with the allowed_models array
+            // parsed from the body. Must run before the generic "API key" check
+            // because LiteLLM phrases this as a 403 distinct from auth.
+            if (isModelAccessDeniedMessage(errorRecord.message)) {
+                return new ModelAccessDeniedError(errorRecord.message, {
+                    provider: this.providerName,
+                    requestedModel: this.modelName,
+                    allowedModels: parseAllowedModels(errorRecord.message),
+                });
+            }
             if (errorRecord.message.includes("API_KEY_INVALID") ||
                 errorRecord.message.includes("Invalid API key")) {
                 return new AuthenticationError("Invalid LiteLLM configuration. Please check your LITELLM_API_KEY environment variable.", this.providerName);

package/dist/lib/providers/openAI.js

@@ -235,10 +235,27 @@ export class OpenAIProvider extends BaseProvider {
         const errorType = errorObj?.type && typeof errorObj.type === "string"
             ? errorObj.type
             : undefined;
+        const statusCode = typeof errorObj?.status === "number"
+            ? errorObj.status
+            : typeof errorObj?.statusCode === "number"
+                ? errorObj.statusCode
+                : undefined;
+        // Curator P1-1 / Reviewer Finding #4: only the explicit auth markers
+        // map to AuthenticationError. Earlier we treated every
+        // `invalid_request_error` as an auth failure — that's OpenAI's catch-all
+        // for any bad request (unsupported parameter, malformed JSON, etc.) and
+        // mislabelled them as "invalid API key". Use credential-specific
+        // signals only.
         if (message.includes("API_KEY_INVALID") ||
             message.includes("Invalid API key") ||
-            errorType === "invalid_api_key") {
-            return new AuthenticationError("Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.", this.providerName);
+            message.includes("Incorrect API key") ||
+            message.includes("invalid_api_key") ||
+            errorType === "invalid_api_key" ||
+            statusCode === 401) {
+            return new AuthenticationError(message.includes("Incorrect API key") ||
+                message.includes("Invalid API key")
+                ? message
+                : "Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.", this.providerName);
         }
         if (message.includes("rate limit") || errorType === "rate_limit_error") {
             return new RateLimitError("OpenAI rate limit exceeded. Please try again later.", this.providerName);

package/dist/lib/types/errors.d.ts

@@ -104,3 +104,45 @@ export declare class ModelAccessError extends BaseError {
     readonly requiredTier: string;
     constructor(model: string, tier: string, requiredTier: string);
 }
+/**
+ * Curator P1-1: thrown when a provider rejects a request because the
+ * caller's team / API key is not whitelisted for the requested model.
+ *
+ * LiteLLM's `team not allowed to access model. This team can only access
+ * models=['glm-latest', 'kimi-latest', ...]` is the canonical example —
+ * the list is parsed off the error body so callers / fallback orchestrators
+ * can choose a whitelisted alternative without scraping strings.
+ */
+export declare class ModelAccessDeniedError extends ProviderError {
+    readonly requestedModel: string | undefined;
+    readonly allowedModels: string[] | undefined;
+    readonly code: "MODEL_ACCESS_DENIED";
+    constructor(message: string, options?: {
+        provider?: string;
+        requestedModel?: string;
+        allowedModels?: string[];
+    });
+}
+/**
+ * Parse the `allowed_models` array out of a provider error message body.
+ * Currently targets the LiteLLM team-whitelist response shape:
+ *
+ *   "team not allowed to access model. This team can only access
+ *    models=['glm-latest', 'kimi-latest', 'open-large']"
+ *
+ * Implementation note: deliberately uses `indexOf`/`slice` instead of a
+ * single `/models\s*=\s*\[([^\]]*)\]/` regex. CodeQL flagged the latter
+ * as `js/polynomial-redos` because the `[^\]]*` greedy quantifier on
+ * library-supplied input can be exploited by a crafted long string. The
+ * indexOf/slice path is O(n) with no backtracking and we additionally
+ * cap the input length.
+ *
+ * Returns undefined when no list is found.
+ */
+export declare function parseAllowedModels(message: string): string[] | undefined;
+/**
+ * Returns true when `message` looks like a model-access-denied response
+ * (LiteLLM "team not allowed", generic "not allowed to access model",
+ * or "team can only access models=[...]").
+ */
+export declare function isModelAccessDeniedMessage(message: string): boolean;

package/dist/lib/types/errors.js

@@ -165,4 +165,98 @@ export class ModelAccessError extends BaseError {
         this.requiredTier = requiredTier;
     }
 }
+/**
+ * Curator P1-1: thrown when a provider rejects a request because the
+ * caller's team / API key is not whitelisted for the requested model.
+ *
+ * LiteLLM's `team not allowed to access model. This team can only access
+ * models=['glm-latest', 'kimi-latest', ...]` is the canonical example —
+ * the list is parsed off the error body so callers / fallback orchestrators
+ * can choose a whitelisted alternative without scraping strings.
+ */
+export class ModelAccessDeniedError extends ProviderError {
+    requestedModel;
+    allowedModels;
+    code = "MODEL_ACCESS_DENIED";
+    constructor(message, options = {}) {
+        super(message, options.provider);
+        this.name = "ModelAccessDeniedError";
+        this.requestedModel = options.requestedModel;
+        this.allowedModels = options.allowedModels;
+    }
+}
+/** Maximum body length we'll attempt to parse. Real provider error
+ *  bodies are well under 10 KB; longer inputs are either truncated
+ *  log output or a deliberate ReDoS attempt. */
+const MAX_ALLOWED_MODELS_INPUT = 10_000;
+/**
+ * Parse the `allowed_models` array out of a provider error message body.
+ * Currently targets the LiteLLM team-whitelist response shape:
+ *
+ *   "team not allowed to access model. This team can only access
+ *    models=['glm-latest', 'kimi-latest', 'open-large']"
+ *
+ * Implementation note: deliberately uses `indexOf`/`slice` instead of a
+ * single `/models\s*=\s*\[([^\]]*)\]/` regex. CodeQL flagged the latter
+ * as `js/polynomial-redos` because the `[^\]]*` greedy quantifier on
+ * library-supplied input can be exploited by a crafted long string. The
+ * indexOf/slice path is O(n) with no backtracking and we additionally
+ * cap the input length.
+ *
+ * Returns undefined when no list is found.
+ */
+export function parseAllowedModels(message) {
+    if (typeof message !== "string" || message.length === 0) {
+        return undefined;
+    }
+    if (message.length > MAX_ALLOWED_MODELS_INPUT) {
+        return undefined;
+    }
+    // Locate `models` keyword case-insensitively, then walk forward to
+    // confirm `=` and `[` markers — no regex backtracking.
+    const lower = message.toLowerCase();
+    let idx = lower.indexOf("models", 0);
+    while (idx !== -1) {
+        let cursor = idx + "models".length;
+        // Skip whitespace
+        while (cursor < message.length && /\s/.test(message[cursor])) {
+            cursor++;
+        }
+        if (message[cursor] !== "=") {
+            idx = lower.indexOf("models", idx + 1);
+            continue;
+        }
+        cursor++;
+        while (cursor < message.length && /\s/.test(message[cursor])) {
+            cursor++;
+        }
+        if (message[cursor] !== "[") {
+            idx = lower.indexOf("models", idx + 1);
+            continue;
+        }
+        const open = cursor;
+        const close = message.indexOf("]", open + 1);
+        if (close === -1) {
+            return undefined;
+        }
+        const inside = message.slice(open + 1, close);
+        const items = inside
+            .split(",")
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+            .filter((s) => s.length > 0);
+        return items.length > 0 ? items : undefined;
+    }
+    return undefined;
+}
+/**
+ * Returns true when `message` looks like a model-access-denied response
+ * (LiteLLM "team not allowed", generic "not allowed to access model",
+ * or "team can only access models=[...]").
+ */
+export function isModelAccessDeniedMessage(message) {
+    const lower = message.toLowerCase();
+    return ((lower.includes("team") && lower.includes("not allowed")) ||
+        lower.includes("team can only access") ||
+        /not\s+allowed\s+to\s+access\s+(this\s+)?model/i.test(message));
+}
 //# sourceMappingURL=errors.js.map

package/dist/neurolink.d.ts

@@ -968,6 +968,40 @@ export declare class NeuroLink {
      * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): TypedEventEmitter<NeuroLinkEvents>;
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    checkCredentials(input: {
+        provider: string;
+        model?: string;
+    }): Promise<{
+        provider: string;
+        status: "ok" | "missing" | "expired" | "denied" | "network" | "unknown";
+        detail: string;
+    }>;
     /**
      * Emit tool start event with execution tracking
      * @param toolName - Name of the tool being executed

package/dist/neurolink.js

@@ -52,7 +52,7 @@ import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
-import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/index.js";
+import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { TaskManager } from "./tasks/taskManager.js";
@@ -187,6 +187,13 @@ function isNonRetryableProviderError(error) {
     if (error instanceof AuthorizationError) {
         return true;
     }
+    // Curator P1-1: model-access-denied is permanent for the (provider, model)
+    // pair until the team whitelist changes. Retrying with the same config
+    // would just waste a second roundtrip. Caller / fallback-orchestrator
+    // should pick a different model.
+    if (error instanceof ModelAccessDeniedError) {
+        return true;
+    }
     // Check for HTTP status codes on error objects (e.g., from Vercel AI SDK)
     if (error && typeof error === "object") {
         const err = error;
@@ -6087,6 +6094,87 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    async checkCredentials(input) {
+        const { provider, model } = input;
+        const probeText = "ping";
+        try {
+            // 1-token probe is cheap, exercises auth + routing without much cost.
+            await this.generate({
+                provider: provider,
+                ...(model && { model }),
+                input: { text: probeText },
+                maxTokens: 16,
+                disableTools: true,
+            });
+            return { provider, status: "ok", detail: "credentials valid" };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const lower = msg.toLowerCase();
+            if (err instanceof ModelAccessDeniedError) {
+                return {
+                    provider,
+                    status: "denied",
+                    detail: msg,
+                };
+            }
+            if (lower.includes("authentication") ||
+                lower.includes("401") ||
+                lower.includes("invalid api key") ||
+                lower.includes("incorrect api key") ||
+                lower.includes("api_key_invalid") ||
+                lower.includes("token has expired") ||
+                lower.includes("expired credentials")) {
+                return { provider, status: "expired", detail: msg };
+            }
+            if (lower.includes("not configured") ||
+                lower.includes("missing api") ||
+                lower.includes("api key is required") ||
+                lower.includes("no api key") ||
+                lower.includes("application default credentials") ||
+                lower.includes("google_application_credentials") ||
+                lower.includes("project_id") ||
+                lower.includes("default credentials") ||
+                lower.includes("service account")) {
+                return { provider, status: "missing", detail: msg };
+            }
+            if (lower.includes("econnrefused") ||
+                lower.includes("enotfound") ||
+                lower.includes("could not resolve") ||
+                lower.includes("timeout") ||
+                lower.includes("network") ||
+                lower.includes("cannot connect")) {
+                return { provider, status: "network", detail: msg };
+            }
+            return { provider, status: "unknown", detail: msg };
+        }
+    }
     // ========================================
     // ENHANCED: Tool Event Emission API
     // ========================================

package/dist/providers/litellm.js

@@ -5,7 +5,7 @@ import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { AuthenticationError, InvalidModelError, ModelAccessDeniedError, NetworkError, ProviderError, RateLimitError, isModelAccessDeniedMessage, parseAllowedModels, } from "../types/index.js";
 import { isAbortError } from "../utils/errorHandling.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { logger } from "../utils/logger.js";
@@ -100,6 +100,17 @@ export class LiteLLMProvider extends BaseProvider {
                 return new NetworkError("LiteLLM proxy server not available. Please start the LiteLLM proxy server at " +
                     `${process.env.LITELLM_BASE_URL || "http://localhost:4000"}`, this.providerName);
             }
+            // Curator P1-1: detect "team not allowed to access model" responses
+            // and surface as ModelAccessDeniedError with the allowed_models array
+            // parsed from the body. Must run before the generic "API key" check
+            // because LiteLLM phrases this as a 403 distinct from auth.
+            if (isModelAccessDeniedMessage(errorRecord.message)) {
+                return new ModelAccessDeniedError(errorRecord.message, {
+                    provider: this.providerName,
+                    requestedModel: this.modelName,
+                    allowedModels: parseAllowedModels(errorRecord.message),
+                });
+            }
             if (errorRecord.message.includes("API_KEY_INVALID") ||
                 errorRecord.message.includes("Invalid API key")) {
                 return new AuthenticationError("Invalid LiteLLM configuration. Please check your LITELLM_API_KEY environment variable.", this.providerName);

package/dist/providers/openAI.js

@@ -235,10 +235,27 @@ export class OpenAIProvider extends BaseProvider {
         const errorType = errorObj?.type && typeof errorObj.type === "string"
             ? errorObj.type
             : undefined;
+        const statusCode = typeof errorObj?.status === "number"
+            ? errorObj.status
+            : typeof errorObj?.statusCode === "number"
+                ? errorObj.statusCode
+                : undefined;
+        // Curator P1-1 / Reviewer Finding #4: only the explicit auth markers
+        // map to AuthenticationError. Earlier we treated every
+        // `invalid_request_error` as an auth failure — that's OpenAI's catch-all
+        // for any bad request (unsupported parameter, malformed JSON, etc.) and
+        // mislabelled them as "invalid API key". Use credential-specific
+        // signals only.
         if (message.includes("API_KEY_INVALID") ||
             message.includes("Invalid API key") ||
-            errorType === "invalid_api_key") {
-            return new AuthenticationError("Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.", this.providerName);
+            message.includes("Incorrect API key") ||
+            message.includes("invalid_api_key") ||
+            errorType === "invalid_api_key" ||
+            statusCode === 401) {
+            return new AuthenticationError(message.includes("Incorrect API key") ||
+                message.includes("Invalid API key")
+                ? message
+                : "Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.", this.providerName);
         }
         if (message.includes("rate limit") || errorType === "rate_limit_error") {
             return new RateLimitError("OpenAI rate limit exceeded. Please try again later.", this.providerName);

package/dist/types/errors.d.ts

@@ -104,3 +104,45 @@ export declare class ModelAccessError extends BaseError {
     readonly requiredTier: string;
     constructor(model: string, tier: string, requiredTier: string);
 }
+/**
+ * Curator P1-1: thrown when a provider rejects a request because the
+ * caller's team / API key is not whitelisted for the requested model.
+ *
+ * LiteLLM's `team not allowed to access model. This team can only access
+ * models=['glm-latest', 'kimi-latest', ...]` is the canonical example —
+ * the list is parsed off the error body so callers / fallback orchestrators
+ * can choose a whitelisted alternative without scraping strings.
+ */
+export declare class ModelAccessDeniedError extends ProviderError {
+    readonly requestedModel: string | undefined;
+    readonly allowedModels: string[] | undefined;
+    readonly code: "MODEL_ACCESS_DENIED";
+    constructor(message: string, options?: {
+        provider?: string;
+        requestedModel?: string;
+        allowedModels?: string[];
+    });
+}
+/**
+ * Parse the `allowed_models` array out of a provider error message body.
+ * Currently targets the LiteLLM team-whitelist response shape:
+ *
+ *   "team not allowed to access model. This team can only access
+ *    models=['glm-latest', 'kimi-latest', 'open-large']"
+ *
+ * Implementation note: deliberately uses `indexOf`/`slice` instead of a
+ * single `/models\s*=\s*\[([^\]]*)\]/` regex. CodeQL flagged the latter
+ * as `js/polynomial-redos` because the `[^\]]*` greedy quantifier on
+ * library-supplied input can be exploited by a crafted long string. The
+ * indexOf/slice path is O(n) with no backtracking and we additionally
+ * cap the input length.
+ *
+ * Returns undefined when no list is found.
+ */
+export declare function parseAllowedModels(message: string): string[] | undefined;
+/**
+ * Returns true when `message` looks like a model-access-denied response
+ * (LiteLLM "team not allowed", generic "not allowed to access model",
+ * or "team can only access models=[...]").
+ */
+export declare function isModelAccessDeniedMessage(message: string): boolean;