@juspay/neurolink 13.8.17 → 13.8.18

package/dist/server/routes/codexProxyRoutes.js

@@ -39,6 +39,8 @@ import { logRequest, logRequestAttempt, logBodyCapture, isProxyBodyCaptureEnable
 import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { resolveProxyLogTraceContext, getProxyRequestTraceContext, } from "../../proxy/proxyTraceContext.js";
 import { isBorrowedRequest } from "../../proxy/shareContext.js";
+import { authorizeInboundRequest, inboundAuthRefusalResponse, resolveInboundToken, resolveMaxAccountsPerRequest, warnIfProxyRoutesUnauthenticated, } from "../../proxy/inboundAuth.js";
+import { MAX_COOLDOWN_MS_BY_REASON } from "../../proxy/routingEvidence.js";
 import { ProxyTracer, recordFallbackAttempt } from "../../proxy/proxyTracer.js";
 import { parseRetryAfterMs } from "../../proxy/routingPolicy.js";
 import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess, } from "../../proxy/usageStats.js";
@@ -153,20 +155,52 @@ async function refreshCodexTokenOnceWithDependencies(key, refreshToken, store, r
 async function refreshCodexTokenOnce(key, refreshToken) {
     return refreshCodexTokenOnceWithDependencies(key, refreshToken, tokenStore, refreshCodexToken);
 }
-// Headers we never forward upstream (hop-by-hop, client creds, or things we
-// re-derive). The client's own auth is replaced with the pooled account's.
-const BLOCKED_UPSTREAM_HEADERS = new Set([
-    "host",
-    "connection",
-    "content-length",
-    "transfer-encoding",
-    "cookie",
-    "proxy-authorization",
-    "authorization",
-    "x-api-key",
-    "chatgpt-account-id",
-    "accept-encoding",
+/**
+ * Protocol headers a client may influence upstream: the documented Codex
+ * client fingerprint and content negotiation. Everything else — proxy-internal
+ * `x-neurolink-*` (a borrower's share token among them), trace context, CDN and
+ * forwarding identity, cookies, hop-by-hop — is dropped. The client's own
+ * credentials are replaced with the pooled account's, never forwarded.
+ */
+const FORWARDABLE_UPSTREAM_HEADERS = new Set([
+    "accept",
+    "content-type",
+    "user-agent",
+    "originator",
+    "session_id",
+    "conversation_id",
+    "openai-beta",
 ]);
+const FORWARDABLE_UPSTREAM_HEADER_PREFIXES = ["x-codex-"];
+function isForwardableCodexHeader(lowerName) {
+    return (FORWARDABLE_UPSTREAM_HEADERS.has(lowerName) ||
+        FORWARDABLE_UPSTREAM_HEADER_PREFIXES.some((prefix) => lowerName.startsWith(prefix)));
+}
+/**
+ * Body fields that reference or create account-side state at OpenAI. A
+ * borrower may not read another caller's stored response, pin a cache key or
+ * stamp `metadata`/`user` onto the lender's account; their own `instructions`
+ * are their prompt and stay.
+ */
+const BORROWER_STRIPPED_BODY_FIELDS = [
+    "previous_response_id",
+    "prompt_cache_key",
+    "metadata",
+    "user",
+];
+function stripBorrowerAccountState(body) {
+    if (!isBorrowedRequest()) {
+        return body;
+    }
+    const stripped = { ...body };
+    for (const field of BORROWER_STRIPPED_BODY_FIELDS) {
+        delete stripped[field];
+    }
+    if ("store" in stripped) {
+        stripped.store = false;
+    }
+    return stripped;
+}
 /** Build a Codex error body as a Response with the intended status. */
 function buildCodexErrorResponse(status, message, code) {
     return new Response(JSON.stringify({
@@ -290,7 +324,7 @@ function buildCodexUpstreamHeaders(clientHeaders, account) {
     const headers = {};
     for (const [name, value] of Object.entries(clientHeaders)) {
         const lower = name.toLowerCase();
-        if (BLOCKED_UPSTREAM_HEADERS.has(lower)) {
+        if (!isForwardableCodexHeader(lower) || typeof value !== "string") {
             continue;
         }
         headers[lower] = value;
@@ -361,16 +395,20 @@ function planCodexCooldown(quota, retryAfterMs, now, errorText = "") {
     // skew. Taken literally the account is eligible again immediately and the
     // pool re-sends to something the provider just rejected.
     const floor = now + DEFAULT_TRANSIENT_COOLDOWN_MS;
+    // A reset is upstream's claim about the future. Bound it by what the window
+    // can mean, as the Claude engine does: a bogus far-future reset must not park
+    // an account until someone edits the cooldown file by hand.
+    const clamp = (untilMs, reason) => Math.min(Math.max(untilMs, floor), now + (MAX_COOLDOWN_MS_BY_REASON[reason] ?? MAX_TRANSIENT_COOLDOWN_MS));
     if (quota) {
         if (quota.weeklyStatus === "rejected" && quota.weeklyResetAt > 0) {
             return {
-                coolingUntil: Math.max(quota.weeklyResetAt * 1000, floor),
+                coolingUntil: clamp(quota.weeklyResetAt * 1000, "weekly"),
                 reason: "weekly",
             };
         }
         if (quota.sessionStatus === "rejected" && quota.sessionResetAt > 0) {
             return {
-                coolingUntil: Math.max(quota.sessionResetAt * 1000, floor),
+                coolingUntil: clamp(quota.sessionResetAt * 1000, "session"),
                 reason: "session",
             };
         }
@@ -379,7 +417,7 @@ function planCodexCooldown(quota, retryAfterMs, now, errorText = "") {
     if (bodyQuota) {
         if (bodyQuota.scope !== "unknown" && bodyQuota.resetAt > 0) {
             return {
-                coolingUntil: Math.max(bodyQuota.resetAt, floor),
+                coolingUntil: clamp(bodyQuota.resetAt, bodyQuota.scope),
                 reason: bodyQuota.scope,
             };
         }
@@ -400,8 +438,13 @@ function publishCodexHeaders(ctx, account, attempt, quota) {
     if (!ctx.responseHeaders) {
         ctx.responseHeaders = {};
     }
-    ctx.responseHeaders["x-neurolink-account"] = account.label;
-    ctx.responseHeaders["x-neurolink-account-type"] = "codex-oauth";
+    // The label is the lender's identity (an email for a ChatGPT account). A
+    // borrower gets the quota it routes on, not whose account served it — the
+    // same redaction the Claude engine applies for borrowed traffic.
+    if (!isBorrowedRequest()) {
+        ctx.responseHeaders["x-neurolink-account"] = account.label;
+        ctx.responseHeaders["x-neurolink-account-type"] = "codex-oauth";
+    }
     ctx.responseHeaders["x-neurolink-served-by"] = "codex";
     ctx.responseHeaders["x-neurolink-attempt"] = String(attempt);
     ctx.responseHeaders["x-neurolink-quota-source"] = quota ? "live" : "none";
@@ -1536,6 +1579,29 @@ async function handleCodexUpstreamFailure(rt, args) {
             lastErrorMessage: "Codex account rate-limited",
         };
     }
+    // Any other 4xx is upstream's verdict on the request itself — a malformed
+    // body, an unknown model, an over-long input. Every other account would
+    // answer the same way, so trying them only multiplies the cost: end the
+    // request here, with the upstream status.
+    if (upstream.status >= 400 &&
+        upstream.status < 500 &&
+        upstream.status !== 401 &&
+        upstream.status !== 403) {
+        const errorMessage = summarizeCodexUpstreamError(errText, "Codex error");
+        recordAttemptError(account.label, CODEX_ACCOUNT_TYPE, upstream.status);
+        writeAttempt(account, attempt, attemptStartedAt, upstream.status, {
+            errorType: "invalid_request_error",
+            errorMessage,
+            retryable: false,
+        });
+        return {
+            lastFailure: { errorType: "invalid_request_error", retryable: false },
+            lastErrorStatus: upstream.status,
+            lastErrorCode: getProxyUpstreamFailure({ responseBody: errText })?.code,
+            lastErrorMessage: errorMessage,
+            refusedRequest: true,
+        };
+    }
     // Other non-ok → record and rotate.
     if (upstream.status === 401 || upstream.status === 403) {
         // Reached when the account has no refresh token to retry with, or when
@@ -1748,7 +1814,7 @@ loopbackPort, internalDispatch) {
                 body: state.body,
             });
             state.contextPreflight = preparedContext.evidence;
-            state.body = preparedContext.body;
+            state.body = stripBorrowerAccountState(preparedContext.body);
             state.bodyStr = JSON.stringify(state.body);
         }
         catch (error) {
@@ -1774,10 +1840,12 @@ loopbackPort, internalDispatch) {
         }
         const now = Date.now();
         const ordered = orderCodexAccounts(accounts, now);
-        const eligible = ordered.filter((a) => !(a.coolingUntil !== undefined && a.coolingUntil > now));
-        if (eligible.length === 0) {
+        const notCooling = ordered.filter((a) => !(a.coolingUntil !== undefined && a.coolingUntil > now));
+        if (notCooling.length === 0) {
             return respondCodexPoolCooling(rt, ordered, now);
         }
+        // One inbound request may be tried against at most this many accounts.
+        const eligible = notCooling.slice(0, resolveMaxAccountsPerRequest());
         let attempt = 0;
         let lastErrorMessage = "All Codex accounts failed";
         let lastErrorStatus = 502;
@@ -2022,20 +2090,26 @@ async function handleCodexModelsRequest(ctx) {
     }
     const now = Date.now();
     const ordered = orderCodexAccounts(accounts, now);
-    // A cooling account is rate-limited for completions, not barred from
-    // answering what models exist. Healthy accounts go first, but a cooling one
-    // is still a candidate rather than a reason to fail discovery outright.
-    const isCooling = (a) => a.coolingUntil !== undefined && a.coolingUntil > now;
-    const candidates = [
-        ...ordered.filter((a) => !isCooling(a)),
-        ...ordered.filter(isCooling),
-    ];
-    // Forward the CLI's own query — it sends client_version, and upstream
-    // *requires* it: without it ChatGPT answers 400 with a pydantic
-    // "Field required" on ('query','client_version'). Rebuild from ctx.query,
-    // not ctx.path: path carries no query string, so reading it there silently
-    // dropped the parameter and produced exactly that 400.
-    const params = new URLSearchParams(ctx.query ?? {});
+    // Discovery used to reach every account, cooling ones included, and relay
+    // the client's whole query. Only healthy accounts answer it now, capped by
+    // the per-request account limit. Every call still reaches upstream: the
+    // limits it reports (context window, output ceiling) are recorded per model
+    // and must refresh whenever upstream changes them.
+    const candidates = ordered
+        .filter((a) => !(a.coolingUntil !== undefined && a.coolingUntil > now))
+        .slice(0, resolveMaxAccountsPerRequest());
+    if (candidates.length === 0) {
+        return buildCodexErrorResponse(503, "Every Codex account is cooling; model discovery is unavailable until one recovers.");
+    }
+    // Forward only the CLI's `client_version` — upstream *requires* it: without
+    // it ChatGPT answers 400 with a pydantic "Field required" on
+    // ('query','client_version'). Rebuild from ctx.query, not ctx.path: path
+    // carries no query string. Nothing else a client puts in the query travels.
+    const params = new URLSearchParams();
+    const clientVersion = ctx.query?.client_version;
+    if (typeof clientVersion === "string" && clientVersion !== "") {
+        params.set("client_version", clientVersion);
+    }
     const query = params.toString();
     const url = query ? `${CODEX_MODELS_URL}?${query}` : CODEX_MODELS_URL;
     let lastErrorStatus = 502;
@@ -2099,10 +2173,10 @@ async function handleCodexModelsRequest(ctx) {
             // query was not forwarded correctly, and hiding it behind a retry would
             // bury the exact regression this route was added to fix.
             const body = await upstream.text();
+            const contentType = upstream.headers.get("content-type") ?? "application/json";
             if (upstream.ok) {
                 registerCodexDiscoveredLimits(body);
             }
-            const contentType = upstream.headers.get("content-type") ?? "application/json";
             return new Response(body, {
                 status: upstream.status,
                 headers: { "content-type": contentType },
@@ -2175,8 +2249,19 @@ function warnIfAnthropicOutboundFallbackUnreachable(runtimeConfigProvider, loopb
  *   `loopbackPort` when omitted.
  * @returns RouteGroup with the Codex backend Responses endpoint.
  */
-export function createCodexProxyRoutes(basePath = "", runtimeConfigProvider, loopbackPort, internalDispatch) {
+export function createCodexProxyRoutes(basePath = "", runtimeConfigProvider, loopbackPort, internalDispatch, inboundAuth) {
     warnIfAnthropicOutboundFallbackUnreachable(runtimeConfigProvider, loopbackPort, internalDispatch);
+    const inboundToken = resolveInboundToken(inboundAuth?.token);
+    warnIfProxyRoutesUnauthenticated("Codex", inboundAuth, inboundToken);
+    const guard = (handler) => (ctx) => {
+        if (inboundToken) {
+            const verdict = authorizeInboundRequest(ctx.headers, inboundToken);
+            if (!verdict.ok) {
+                return Promise.resolve(inboundAuthRefusalResponse());
+            }
+        }
+        return handler(ctx);
+    };
     return {
         prefix: `${basePath}/backend-api/codex`,
         routes: [
@@ -2184,13 +2269,13 @@ export function createCodexProxyRoutes(basePath = "", runtimeConfigProvider, loo
                 method: "POST",
                 path: `${basePath}/backend-api/codex/responses`,
                 description: "Codex ChatGPT-backend Responses API (account pool)",
-                handler: (ctx) => handleCodexResponsesRequest(ctx, runtimeConfigProvider, loopbackPort, internalDispatch),
+                handler: guard((ctx) => handleCodexResponsesRequest(ctx, runtimeConfigProvider, loopbackPort, internalDispatch)),
             },
             {
                 method: "GET",
                 path: `${basePath}/backend-api/codex/models`,
                 description: "Codex model discovery, relayed upstream (account pool)",
-                handler: (ctx) => handleCodexModelsRequest(ctx),
+                handler: guard((ctx) => handleCodexModelsRequest(ctx)),
             },
         ],
     };

package/dist/server/routes/index.d.ts

@@ -42,4 +42,8 @@ export declare function registerAllRoutes(adapter: {
     registerRouteGroup: (group: RouteGroup) => void;
     listRoutes?: () => RouteDefinition[];
     enableMiddlewareStateCarry?: () => void;
+    hasAuthenticationMiddleware?: () => boolean;
+    noteSensitiveRoutes?: (options?: {
+        allowUnauthenticated?: boolean;
+    }) => void;
 }, basePath?: string, options?: CreateRoutesOptions): void;

package/dist/server/routes/index.js

@@ -40,13 +40,30 @@ export { createTranscribeRoutes } from "./transcribeRoutes.js";
  * and docs/features/codex-proxy-support.md.
  */
 export function createAllRoutes(basePath = "/api", options) {
+    // The tool and MCP execution routes act on the host. They refuse callers
+    // the server has not authenticated, when they can tell: registerAllRoutes()
+    // tells them through `hasAuthentication`; an explicit opt-out, by option or
+    // by NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1, opens them regardless.
+    const sensitive = {
+        allowUnauthenticated: options?.allowUnauthenticated === true || allowUnauthenticatedFromEnv(),
+        hasAuthentication: options?.hasAuthentication,
+    };
+    // The proxy doors spend pooled subscriptions; their inbound token defaults to
+    // NEUROLINK_PROXY_INBOUND_TOKEN and the factories warn loudly without one.
+    const proxyAuth = {
+        ...options?.proxyAuth,
+        allowUnauthenticated: options?.proxyAuth?.allowUnauthenticated ??
+            options?.allowUnauthenticated === true,
+    };
     const routes = [
         createAgentRoutes(basePath, {
             ...options?.agent,
             perUserAuth: options?.perUserAuth,
         }),
-        createToolRoutes(basePath),
-        createMCPRoutes(basePath),
+        ...(options?.tools === false
+            ? []
+            : [createToolRoutes(basePath, sensitive)]),
+        createMCPRoutes(basePath, sensitive),
         createMemoryRoutes(basePath),
         createHealthRoutes(basePath),
         createTranscribeRoutes(basePath, options?.transcribe),
@@ -64,13 +81,13 @@ export function createAllRoutes(basePath = "/api", options) {
     const enableCodexProxy = options?.proxy || options?.codexProxy;
     const enableGeminiProxy = options?.proxy || options?.geminiProxy;
     if (enableClaudeProxy) {
-        routes.push(createClaudeProxyRoutes(undefined, basePath));
+        routes.push(createClaudeProxyRoutes(undefined, basePath, "fill-first", false, undefined, { inboundAuth: proxyAuth }));
     }
     if (enableOpenAIProxy) {
         routes.push(createOpenAIProxyRoutes(undefined, basePath));
     }
     if (enableCodexProxy) {
-        routes.push(createCodexProxyRoutes(basePath, options?.runtimeConfigProvider));
+        routes.push(createCodexProxyRoutes(basePath, options?.runtimeConfigProvider, undefined, undefined, proxyAuth));
     }
     if (enableGeminiProxy) {
         routes.push(createGeminiProxyRoutes(undefined, basePath));
@@ -92,13 +109,27 @@ export function registerAllRoutes(adapter, basePath = "/api", options) {
     if (options?.perUserAuth) {
         adapter.enableMiddlewareStateCarry?.();
     }
+    const allowUnauthenticated = options?.allowUnauthenticated === true || allowUnauthenticatedFromEnv();
+    // The adapter knows whether authentication middleware is registered, and is
+    // asked on every request, so authentication registered after the routes
+    // counts. It also warns at start() when the routes that act on the host are
+    // mounted with no such middleware (see BaseServerAdapter).
+    adapter.noteSensitiveRoutes?.({ allowUnauthenticated });
     // If adapter has listRoutes and getRoutes not provided, use adapter's listRoutes
     const routeOptions = {
         ...options,
         getRoutes: options?.getRoutes ?? adapter.listRoutes?.bind(adapter),
+        hasAuthentication: options?.hasAuthentication ??
+            (adapter.hasAuthenticationMiddleware
+                ? () => adapter.hasAuthenticationMiddleware?.() === true
+                : undefined),
     };
     const routeGroups = createAllRoutes(basePath, routeOptions);
     for (const group of routeGroups) {
         adapter.registerRouteGroup(group);
     }
 }
+/** `NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1`: the operator's opt-out, read when routes are built. */
+function allowUnauthenticatedFromEnv() {
+    return process.env.NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED?.trim() === "1";
+}

package/dist/server/routes/mcpRoutes.d.ts

@@ -2,8 +2,12 @@
  * MCP Routes
  * Endpoints for MCP server management
  */
-import type { RouteGroup } from "../../types/index.js";
+import type { RouteGroup, ServerSensitiveRouteOptions } from "../../types/index.js";
 /**
  * Create MCP server management routes
+ *
+ * @param options - `hasAuthentication` / `allowUnauthenticated`: whether the
+ *   routes that change or use servers (reconnect, remove, execute a tool)
+ *   answer an unauthenticated caller (see `ServerSensitiveRouteOptions`).
  */
-export declare function createMCPRoutes(basePath?: string): RouteGroup;
+export declare function createMCPRoutes(basePath?: string, options?: ServerSensitiveRouteOptions): RouteGroup;

package/dist/server/routes/mcpRoutes.js

@@ -6,7 +6,14 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { z } from "zod";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+import { shapeRouteError } from "../utils/clientError.js";
+import { refuseUnauthenticatedExecution } from "./toolRoutes.js";
 import { createErrorResponse, ServerNameParamSchema, ToolArgumentsSchema, validateParams, validateRequest, } from "../utils/validation.js";
+/** The route's error response for an exception: a fixed message, the detail logged. */
+function mcpFailure(code, ctx, error, details) {
+    const shaped = shapeRouteError("mcpRoutes", ctx.requestId, error);
+    return createErrorResponse(code, shaped.message, details, ctx.requestId, shaped.status);
+}
 /**
  * Wrap a route handler with an OTel span for HTTP observability.
  */
@@ -166,7 +173,7 @@ async function handleReconnectServer(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("RECONNECT_FAILED", error instanceof Error ? error.message : String(error), undefined, ctx.requestId);
+        return mcpFailure("RECONNECT_FAILED", ctx, error);
     }
 }
 /**
@@ -198,7 +205,7 @@ async function handleRemoveServer(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("REMOVE_FAILED", error instanceof Error ? error.message : String(error), undefined, ctx.requestId);
+        return mcpFailure("REMOVE_FAILED", ctx, error);
     }
 }
 /**
@@ -278,7 +285,9 @@ async function handleExecuteTool(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("EXECUTION_FAILED", error instanceof Error ? error.message : String(error), { duration: Date.now() - startTime }, ctx.requestId);
+        return mcpFailure("EXECUTION_FAILED", ctx, error, {
+            duration: Date.now() - startTime,
+        });
     }
 }
 /**
@@ -316,8 +325,13 @@ async function handleMCPHealth(ctx) {
 }
 /**
  * Create MCP server management routes
+ *
+ * @param options - `hasAuthentication` / `allowUnauthenticated`: whether the
+ *   routes that change or use servers (reconnect, remove, execute a tool)
+ *   answer an unauthenticated caller (see `ServerSensitiveRouteOptions`).
  */
-export function createMCPRoutes(basePath = "/api") {
+export function createMCPRoutes(basePath = "/api", options) {
+    const guarded = (handler) => async (ctx) => refuseUnauthenticatedExecution(ctx, options) ?? (await handler(ctx));
     return {
         prefix: `${basePath}/mcp`,
         routes: [
@@ -338,14 +352,14 @@ export function createMCPRoutes(basePath = "/api") {
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/reconnect`,
-                handler: tracedMcpHandler("http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, handleReconnectServer),
+                handler: tracedMcpHandler("http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, guarded(handleReconnectServer)),
                 description: "Reconnect to an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: tracedMcpHandler("http.mcp.removeServer", `${basePath}/mcp/servers/:name`, handleRemoveServer),
+                handler: tracedMcpHandler("http.mcp.removeServer", `${basePath}/mcp/servers/:name`, guarded(handleRemoveServer)),
                 description: "Remove an MCP server",
                 tags: ["mcp"],
             },
@@ -359,7 +373,7 @@ export function createMCPRoutes(basePath = "/api") {
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/tools/:toolName/execute`,
-                handler: tracedMcpHandler("http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, handleExecuteTool),
+                handler: tracedMcpHandler("http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, guarded(handleExecuteTool)),
                 description: "Execute a tool from a specific MCP server",
                 tags: ["mcp", "tools"],
             },

package/dist/server/routes/memoryRoutes.js

@@ -4,6 +4,7 @@
  */
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+import { shapeRouteError } from "../utils/clientError.js";
 import { createErrorResponse, IdParamSchema, SessionIdParamSchema, validateParams, } from "../utils/validation.js";
 /**
  * Wrap a route handler with an OTel span for HTTP observability.
@@ -81,7 +82,7 @@ async function handleGetSessionMessages(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get session messages", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**
@@ -132,7 +133,7 @@ async function handleGetSession(ctx) {
         return createErrorResponse("MEMORY_ERROR", "Session retrieval not supported for this memory type", undefined, ctx.requestId);
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get session", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**
@@ -202,7 +203,7 @@ async function handleListSessions(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to list sessions", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**
@@ -226,7 +227,7 @@ async function handleGetStats(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get statistics", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**
@@ -260,7 +261,7 @@ async function handleClearSession(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to clear session", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**
@@ -284,7 +285,7 @@ async function handleClearAllSessions(ctx) {
         };
     }
     catch (error) {
-        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to clear sessions", undefined, ctx.requestId);
+        return createErrorResponse("MEMORY_ERROR", shapeRouteError("memoryRoutes", ctx.requestId, error).message, undefined, ctx.requestId);
     }
 }
 /**

package/dist/server/routes/toolRoutes.d.ts

@@ -2,8 +2,18 @@
  * Tool Routes
  * Endpoints for tool listing, discovery, and execution
  */
-import type { RouteGroup } from "../../types/index.js";
+import type { ErrorResponse, RouteGroup, ServerContext, ServerSensitiveRouteOptions } from "../../types/index.js";
+/**
+ * The 403 for an execution route on a server that authenticates nobody, or
+ * `undefined` when the request may proceed: the server authenticates, the
+ * operator opted out, or the routes were built without a way to tell.
+ */
+export declare function refuseUnauthenticatedExecution(ctx: ServerContext, options: ServerSensitiveRouteOptions | undefined): ErrorResponse | undefined;
 /**
  * Create tool routes
+ *
+ * @param options - `hasAuthentication` / `allowUnauthenticated`: whether the
+ *   execution routes answer an unauthenticated caller (see
+ *   `ServerSensitiveRouteOptions`). `createAllRoutes` supplies them.
  */
-export declare function createToolRoutes(basePath?: string): RouteGroup;
+export declare function createToolRoutes(basePath?: string, options?: ServerSensitiveRouteOptions): RouteGroup;

package/dist/server/routes/toolRoutes.js

@@ -5,11 +5,29 @@
 import { SpanStatusCode } from "@opentelemetry/api";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+import { shapeRouteError } from "../utils/clientError.js";
 import { createErrorResponse, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, validateParams, validateRequest, } from "../utils/validation.js";
+/**
+ * The 403 for an execution route on a server that authenticates nobody, or
+ * `undefined` when the request may proceed: the server authenticates, the
+ * operator opted out, or the routes were built without a way to tell.
+ */
+export function refuseUnauthenticatedExecution(ctx, options) {
+    if (!options?.hasAuthentication ||
+        options.allowUnauthenticated === true ||
+        options.hasAuthentication()) {
+        return undefined;
+    }
+    return createErrorResponse("FORBIDDEN", "This route executes tools on the server and is not served to unauthenticated callers. Register authentication middleware, or opt out with allowUnauthenticated / NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1.", undefined, ctx.requestId, 403);
+}
 /**
  * Create tool routes
+ *
+ * @param options - `hasAuthentication` / `allowUnauthenticated`: whether the
+ *   execution routes answer an unauthenticated caller (see
+ *   `ServerSensitiveRouteOptions`). `createAllRoutes` supplies them.
  */
-export function createToolRoutes(basePath = "/api") {
+export function createToolRoutes(basePath = "/api", options) {
     return {
         prefix: `${basePath}/tools`,
         // IMPORTANT: Route ordering matters for proper matching!
@@ -89,6 +107,10 @@ export function createToolRoutes(basePath = "/api") {
                 method: "POST",
                 path: `${basePath}/tools/execute`,
                 handler: async (ctx) => {
+                    const refused = refuseUnauthenticatedExecution(ctx, options);
+                    if (refused) {
+                        return refused;
+                    }
                     // Validate request body
                     const validation = validateRequest(ToolExecuteRequestSchema, ctx.body, ctx.requestId);
                     if (!validation.success) {
@@ -141,9 +163,12 @@ export function createToolRoutes(basePath = "/api") {
                                 message: errorMessage,
                             });
                             span.recordException(error instanceof Error ? error : new Error(errorMessage));
+                            // The tool's own exception text (paths, upstream bodies) stays
+                            // in the log under the request id.
                             return {
                                 success: false,
-                                error: errorMessage,
+                                error: shapeRouteError("toolRoutes", ctx.requestId, error)
+                                    .message,
                                 duration: Date.now() - startTime,
                             };
                         }
@@ -157,6 +182,10 @@ export function createToolRoutes(basePath = "/api") {
                 method: "POST",
                 path: `${basePath}/tools/:name/execute`,
                 handler: async (ctx) => {
+                    const refused = refuseUnauthenticatedExecution(ctx, options);
+                    if (refused) {
+                        return refused;
+                    }
                     // Validate params
                     const paramValidation = validateParams(ToolNameParamSchema, ctx.params, ctx.requestId);
                     if (!paramValidation.success) {
@@ -216,7 +245,8 @@ export function createToolRoutes(basePath = "/api") {
                             span.recordException(error instanceof Error ? error : new Error(errorMessage));
                             return {
                                 success: false,
-                                error: errorMessage,
+                                error: shapeRouteError("toolRoutes", ctx.requestId, error)
+                                    .message,
                                 duration: Date.now() - startTime,
                             };
                         }