@juspay/neurolink 13.8.13 → 13.8.15

package/dist/server/routes/agentRoutes.js

@@ -7,6 +7,7 @@ import { ProviderFactory } from "../../factories/providerFactory.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
+import { isContextCarried } from "../utils/carriedContextMark.js";
 /**
  * Resolve `request.tools` (an array of tool NAMES shared by the execute and
  * stream endpoints) into a `toolFilter` whitelist. The field was previously
@@ -78,14 +79,144 @@ async function resolveRequestInput(ctx, requestInput, options) {
 /**
  * Create agent routes
  *
+ * `options.perUserAuth` decides where a request's identity comes from; see
+ * `ServerAgentRouteOptions`. Authentication middleware that sets `ctx.user`
+ * does not change that on its own: one shared API key sets the same user for
+ * every caller, so trusting it as a person would give every client the same
+ * userId and no conversation memory. The converse is the operator's to act on:
+ * a server whose authentication identifies individual people must set
+ * `perUserAuth`, or any authenticated caller can name another userId and
+ * sessionId in the body.
+ *
+ * Unset, identity resolves as it did before the adapters carried `ctx.user` to
+ * the handler: the body's `userId` and `sessionId`, with one exception. On
+ * Hono, a request whose client sent its own `X-Request-ID` header reached the
+ * handler with the middleware's context, so an authenticated `ctx.user` (and
+ * `ctx.session`) won over the body there, and still does. A context the
+ * built-in adapters did not hand the carry to also keeps that rule: a custom
+ * adapter that sets `ctx.user` itself, or a handler called directly with a
+ * context the caller built. Only `perUserAuth` (with the server carrying
+ * middleware state) makes these routes take the user from `ctx.user`, and
+ * ignore the body's `userId`, on every built-in adapter and for every request.
+ *
+ * `perUserAuth` needs the user in the handler, which an adapter hands over on
+ * every request only when the server carries middleware state.
+ * `registerAllRoutes()` turns that on for the server when it is given
+ * `perUserAuth`. A caller that registers these routes itself with `perUserAuth`
+ * must create the server with `carryMiddlewareState: true`. Without it, a
+ * request has a user only on Hono when the client sent its own `X-Request-ID`
+ * (Hono then hands the handler the middleware's context regardless); every
+ * other request (Hono without that header, Express, Fastify, Koa) runs as
+ * anonymous, with no `userId` and no session.
+ *
+ * Without `perUserAuth`, and when the server carries middleware state, the
+ * routes log one warning per instance the first time a request whose body names
+ * a different `userId` than its `ctx.user` is served from the body, unless that
+ * user is marked `shared: true` (an identity for every holder of one
+ * credential, which the CLI's API-key middleware sets). Such a request is
+ * served from the body; the warning only tells the operator that per-person
+ * authentication is running without the flag that makes it hold. With the
+ * carry off the handler has no `ctx.user` on those requests, so there is
+ * nothing to compare and no warning. A request where `ctx.user` already won has
+ * nothing to warn about.
+ *
  * @param options - Limits for `input.images` / `input.files`:
  *   `allowedInputRoots` (default: none, every local-path attachment is
  *   refused), `maxInputBytes` per attachment (default 50 MiB),
  *   `maxInputAttachments` per request (default 20, images and files together)
  *   and `maxInputTotalBytes` per request (default 100 MiB, one budget shared by
- *   images and files).
+ *   images and files); and `perUserAuth` (described above).
  */
 export function createAgentRoutes(basePath = "/api", options) {
+    // Truthiness, not `=== true`: a JavaScript caller passing "true" or 1 must get
+    // the strict mode, not silently the permissive one.
+    const perUser = Boolean(options?.perUserAuth);
+    // Without perUserAuth the body's userId wins (except where ctx.user already
+    // did), so an authenticated person who names someone else is acting as them.
+    // That is expected under one shared key (marked `shared`), where the body is
+    // how callers keep separate memory, and a misconfiguration under per-person
+    // authentication: say so, once, with no request values in the message.
+    // alwaysStderr, not warn: logger.warn is dropped unless debug logging is on,
+    // which would hide a security notice from the operator it is for.
+    let warnedNamingAnotherUser = false;
+    const warnIfNamingAnotherUser = (ctx, request) => {
+        if (warnedNamingAnotherUser ||
+            !ctx.user ||
+            ctx.user.shared === true ||
+            !isContextCarried(ctx) ||
+            typeof request.userId !== "string" ||
+            request.userId === ctx.user.id) {
+            return;
+        }
+        warnedNamingAnotherUser = true;
+        logger.alwaysStderr("[agentRoutes] An authenticated user named a different userId in the request body, and the body's userId was used. " +
+            "Per-person authentication without perUserAuth lets a caller name another user. " +
+            "Set perUserAuth: true, or mark an identity that stands for a shared credential with shared: true. " +
+            "This warning is logged once per server.");
+    };
+    // Who a skill mutation is attributed to. With perUserAuth the authenticated
+    // user wins and a caller-supplied name is never trusted. Otherwise the body's
+    // `requestedBy` is used, since a shared key's `ctx.user` names no person, for
+    // a context that received the adapters' carry; a context that did not (Hono
+    // with the caller's X-Request-ID, a custom adapter, a direct call) lets the
+    // authenticated user win, as it did before.
+    const skillRequester = (ctx, bodyRequestedBy) => {
+        if (perUser) {
+            return ctx.user?.id;
+        }
+        return isContextCarried(ctx)
+            ? bodyRequestedBy
+            : (ctx.user?.id ?? bodyRequestedBy);
+    };
+    // The identity generate() and stream() run under.
+    //
+    // perUserAuth: the middleware identifies individual people, so userId, email,
+    // roles and the session come only from ctx.user / ctx.session and the body's
+    // are ignored (no caller-supplied impersonation). The session is the
+    // authenticated user's: a request with no ctx.user gets none, even if a
+    // session middleware named one, because with optional authentication every
+    // anonymous caller that sends the same session id would otherwise share one
+    // conversation.
+    //
+    // Otherwise the body keeps choosing userId and sessionId, which is what every
+    // adapter did before it carried ctx.user to the handler: a context that
+    // received the adapters' carry is treated as the fresh one it used to be. The
+    // exceptions are the contexts that did not get the carry, where an
+    // authenticated ctx.user wins over the body, as it did, and so does the
+    // session: Hono with the caller's own X-Request-ID, a custom adapter that sets
+    // ctx.user itself, a handler called directly. Per-person authentication
+    // without perUserAuth therefore does not stop a caller naming someone else on
+    // the other requests.
+    const callerContext = (ctx, request) => {
+        if (perUser) {
+            return {
+                sessionId: ctx.user ? ctx.session?.id : undefined,
+                userId: ctx.user?.id,
+                userEmail: ctx.user?.email,
+                userRoles: ctx.user?.roles,
+                requestId: ctx.requestId,
+            };
+        }
+        if (!isContextCarried(ctx)) {
+            return {
+                sessionId: ctx.user
+                    ? ctx.session?.id
+                    : (ctx.session?.id ?? request.sessionId),
+                userId: ctx.user ? ctx.user.id : request.userId,
+                userEmail: ctx.user?.email,
+                userRoles: ctx.user?.roles,
+                requestId: ctx.requestId,
+            };
+        }
+        warnIfNamingAnotherUser(ctx, request);
+        return {
+            sessionId: request.sessionId,
+            userId: request.userId,
+            userEmail: undefined,
+            userRoles: undefined,
+            requestId: ctx.requestId,
+        };
+    };
     return {
         prefix: `${basePath}/agent`,
         routes: [
@@ -121,17 +252,7 @@ export function createAgentRoutes(basePath = "/api", options) {
                             temperature: request.temperature,
                             maxTokens: request.maxTokens,
                             ...(requestToolFilter ? { toolFilter: requestToolFilter } : {}),
-                            context: {
-                                // When an authenticated user context exists (set by auth middleware),
-                                // always use its IDs to prevent caller-supplied impersonation.
-                                sessionId: ctx.user
-                                    ? ctx.session?.id
-                                    : (ctx.session?.id ?? request.sessionId),
-                                userId: ctx.user ? ctx.user.id : request.userId,
-                                userEmail: ctx.user?.email,
-                                userRoles: ctx.user?.roles,
-                                requestId: ctx.requestId,
-                            },
+                            context: callerContext(ctx, request),
                         });
                         // Map tool calls from SDK format to API format
                         const toolCalls = result.toolCalls?.map((tc) => ({
@@ -174,17 +295,7 @@ export function createAgentRoutes(basePath = "/api", options) {
                         temperature: request.temperature,
                         maxTokens: request.maxTokens,
                         ...(streamToolFilter ? { toolFilter: streamToolFilter } : {}),
-                        context: {
-                            // When an authenticated user context exists (set by auth middleware),
-                            // always use its IDs to prevent caller-supplied impersonation.
-                            sessionId: ctx.user
-                                ? ctx.session?.id
-                                : (ctx.session?.id ?? request.sessionId),
-                            userId: ctx.user ? ctx.user.id : request.userId,
-                            userEmail: ctx.user?.email,
-                            userRoles: ctx.user?.roles,
-                            requestId: ctx.requestId,
-                        },
+                        context: callerContext(ctx, request),
                     });
                     // Create redactor (no-op if redaction is not enabled)
                     const redactor = createStreamRedactor(ctx.redaction);
@@ -369,14 +480,12 @@ export function createAgentRoutes(basePath = "/api", options) {
                         return validation.error;
                     }
                     const { requestedBy, ...skill } = validation.data;
+                    const requester = skillRequester(ctx, requestedBy);
                     try {
                         const result = await manager.requestMutation({
                             type: "create",
                             skill,
-                            // Authenticated identity wins over caller-supplied attribution.
-                            ...(ctx.user?.id || requestedBy
-                                ? { requestedBy: ctx.user?.id ?? requestedBy }
-                                : {}),
+                            ...(requester ? { requestedBy: requester } : {}),
                         });
                         return result;
                     }
@@ -400,14 +509,13 @@ export function createAgentRoutes(basePath = "/api", options) {
                         return validation.error;
                     }
                     const { requestedBy, ...patch } = validation.data;
+                    const requester = skillRequester(ctx, requestedBy);
                     try {
                         const result = await manager.requestMutation({
                             type: "update",
                             skillId: ctx.params.id,
                             patch,
-                            ...(ctx.user?.id || requestedBy
-                                ? { requestedBy: ctx.user?.id ?? requestedBy }
-                                : {}),
+                            ...(requester ? { requestedBy: requester } : {}),
                         });
                         return result;
                     }
@@ -427,11 +535,12 @@ export function createAgentRoutes(basePath = "/api", options) {
                     if ("error" in manager) {
                         return manager;
                     }
+                    const requester = skillRequester(ctx, undefined);
                     try {
                         const result = await manager.requestMutation({
                             type: "delete",
                             skillId: ctx.params.id,
-                            ...(ctx.user?.id ? { requestedBy: ctx.user.id } : {}),
+                            ...(requester ? { requestedBy: requester } : {}),
                         });
                         return result;
                     }

package/dist/server/routes/codexProxyRoutes.js

@@ -24,7 +24,7 @@ import { loadAccountQuotas, saveAccountQuota, } from "../../proxy/accountQuota.j
 import { createCodexUsageTap } from "../../proxy/codexUsage.js";
 import { CODEX_ACCOUNT_PREFIX, parseCodexRateLimitHeaders, } from "../../proxy/codexAccountUsage.js";
 import { buildClientAttribution } from "../../proxy/clientAttribution.js";
-import { getProxyUpstreamFailure } from "../../proxy/proxyFailureDetails.js";
+import { classifyProxyFailureCode, getProxyUpstreamFailure, } from "../../proxy/proxyFailureDetails.js";
 import { registerProxyResponseObserver, isProxyRequestFinalized, registerInternalProxyRequest, getProxyBridgeResult, releaseProxyRequestAccounting, } from "../../proxy/proxyActivity.js";
 import { parseCodexNativeRequest, translateCodexRequestToClaude, classifyCodexOutboundFailure, buildSystemBlocksFromDeveloperMessages, } from "../../proxy/codexOutboundFallback.js";
 import { createAnthropicFallbackStream } from "../../proxy/codexToAnthropicFallback.js";
@@ -77,6 +77,32 @@ function codexTransportScope(error) {
 function summarizeCodexUpstreamError(errorText, fallback) {
     return sanitizeForLog(errorText).slice(0, 200) || fallback;
 }
+/**
+ * Whether a pre-stream 401/403 refuses the REQUEST rather than the credential.
+ *
+ * Only the body can tell: a content-policy 403 and an expired-token 403 share a
+ * status. `classifyProxyFailureCode` is the verdict the outbound fallback stops
+ * on, so the pool and the fallback read one code the same way. Anything it does
+ * not call non-retryable, including a body with no code at all, stays an
+ * authentication failure.
+ */
+function readCodexRequestRefusal(status, errorText) {
+    if (status !== 401 && status !== 403) {
+        return undefined;
+    }
+    const failure = getProxyUpstreamFailure({ responseBody: errorText });
+    if (failure?.code === undefined) {
+        return undefined;
+    }
+    const known = classifyProxyFailureCode(failure.code);
+    return known.retryable === false
+        ? {
+            code: failure.code,
+            status: known.status ?? status,
+            message: failure.message,
+        }
+        : undefined;
+}
 /**
  * In-flight proactive refreshes, keyed by account.
  *
@@ -1389,6 +1415,32 @@ async function handleCodexUpstreamFailure(rt, args) {
     const { writeAttempt } = rt;
     const { account, attempt, attemptStartedAt, upstream, authRetried } = args;
     const errText = await upstream.text().catch(() => "");
+    // A refusal of the request itself says nothing about the account: a refresh
+    // would rotate its refresh token for nothing, a cooldown would park a healthy
+    // account, and every other account would be refused the same way.
+    const refusal = readCodexRequestRefusal(upstream.status, errText);
+    if (refusal) {
+        const errorMessage = refusal.message ??
+            summarizeCodexUpstreamError(errText, "Codex refused the request");
+        recordAttemptError(account.label, CODEX_ACCOUNT_TYPE, upstream.status);
+        writeAttempt(account, attempt, attemptStartedAt, upstream.status, {
+            errorType: "invalid_request_error",
+            errorCode: refusal.code,
+            errorMessage,
+            retryable: false,
+        });
+        return {
+            lastFailure: {
+                errorType: "invalid_request_error",
+                errorCode: refusal.code,
+                retryable: false,
+            },
+            lastErrorStatus: refusal.status,
+            lastErrorCode: refusal.code,
+            lastErrorMessage: errorMessage,
+            refusedRequest: true,
+        };
+    }
     // 401/403 → try a forced token refresh once, then rotate.
     if ((upstream.status === 401 || upstream.status === 403) &&
         !authRetried &&
@@ -1486,9 +1538,10 @@ async function handleCodexUpstreamFailure(rt, args) {
     }
     // Other non-ok → record and rotate.
     if (upstream.status === 401 || upstream.status === 403) {
-        // Reached only when the account has no refresh token to retry with, so
-        // it will fail identically on the next request. Park it briefly instead
-        // of letting it stay first in line with unknown quota.
+        // Reached when the account has no refresh token to retry with, or when
+        // the retry after a refresh was rejected again. Either way it will fail
+        // identically on the next request, so park it briefly instead of letting
+        // it stay first in line with unknown quota.
         await saveAccountCooldown(account.key, Date.now() + CODEX_AUTH_COOLDOWN_MS, "auth").catch(() => undefined);
     }
     const errorMessage = summarizeCodexUpstreamError(errText, "Codex error");
@@ -1733,7 +1786,8 @@ loopbackPort, internalDispatch) {
         let lastErrorCode;
         let lastFailure = { errorType: "all_accounts_failed" };
         let lastAttemptedAccount;
-        for (const account of eligible) {
+        let requestRefused = false;
+        accountLoop: for (const account of eligible) {
             try {
                 tracer?.setAccountSelection({
                     strategy: "codex-quota-order",
@@ -1859,6 +1913,11 @@ loopbackPort, internalDispatch) {
                 }
                 ({ lastFailure, lastErrorStatus, lastErrorCode, lastErrorMessage } =
                     failure);
+                if (failure.refusedRequest) {
+                    // Every other account would be refused the same way.
+                    requestRefused = true;
+                    break accountLoop;
+                }
                 break;
             }
         }
@@ -1874,7 +1933,7 @@ loopbackPort, internalDispatch) {
             ...lastFailure,
             errorMessage: lastFailure.errorMessage ?? lastErrorMessage,
         });
-        return buildCodexErrorResponse(lastErrorStatus, lastErrorMessage);
+        return buildCodexErrorResponse(lastErrorStatus, lastErrorMessage, requestRefused ? lastErrorCode : undefined);
     };
     try {
         return await dispatch();

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

@@ -29,8 +29,17 @@ export { createTranscribeRoutes } from "./transcribeRoutes.js";
 export declare function createAllRoutes(basePath?: string, options?: CreateRoutesOptions): RouteGroup[];
 /**
  * Register all routes with a server adapter
+ *
+ * With `options.perUserAuth` this also turns on the adapter's
+ * `carryMiddlewareState` (`enableMiddlewareStateCarry()`): the agent routes can
+ * only take identity from `ctx.user` if the adapter hands the handler what
+ * authentication middleware set. An adapter without that method must carry
+ * state itself; otherwise the routes see a user only where the adapter happens
+ * to share its context (Hono, when the client sent its own `X-Request-ID`), and
+ * every other request runs as anonymous.
  */
 export declare function registerAllRoutes(adapter: {
     registerRouteGroup: (group: RouteGroup) => void;
     listRoutes?: () => RouteDefinition[];
+    enableMiddlewareStateCarry?: () => void;
 }, basePath?: string, options?: CreateRoutesOptions): void;

package/dist/server/routes/index.js

@@ -41,7 +41,10 @@ export { createTranscribeRoutes } from "./transcribeRoutes.js";
  */
 export function createAllRoutes(basePath = "/api", options) {
     const routes = [
-        createAgentRoutes(basePath, options?.agent),
+        createAgentRoutes(basePath, {
+            ...options?.agent,
+            perUserAuth: options?.perUserAuth,
+        }),
         createToolRoutes(basePath),
         createMCPRoutes(basePath),
         createMemoryRoutes(basePath),
@@ -76,8 +79,19 @@ export function createAllRoutes(basePath = "/api", options) {
 }
 /**
  * Register all routes with a server adapter
+ *
+ * With `options.perUserAuth` this also turns on the adapter's
+ * `carryMiddlewareState` (`enableMiddlewareStateCarry()`): the agent routes can
+ * only take identity from `ctx.user` if the adapter hands the handler what
+ * authentication middleware set. An adapter without that method must carry
+ * state itself; otherwise the routes see a user only where the adapter happens
+ * to share its context (Hono, when the client sent its own `X-Request-ID`), and
+ * every other request runs as anonymous.
  */
 export function registerAllRoutes(adapter, basePath = "/api", options) {
+    if (options?.perUserAuth) {
+        adapter.enableMiddlewareStateCarry?.();
+    }
     // If adapter has listRoutes and getRoutes not provided, use adapter's listRoutes
     const routeOptions = {
         ...options,

package/dist/server/utils/carriedContextMark.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which route-handler contexts received the state the adapters now carry from
+ * middleware to the handler.
+ *
+ * Before the adapters carried that state, a handler normally got a fresh
+ * context with no `ctx.user` and no `ctx.session`. The one exception was Hono
+ * when the client sent its own `X-Request-ID`: Hono kept the middleware's
+ * context in a store keyed by that header, so the handler found it again, user
+ * included. The agent routes' default (`perUserAuth` unset) must not start
+ * trusting `ctx.user` on the requests that never had it, so the built-in
+ * adapters mark the contexts that received the carry, and the agent routes
+ * treat a marked context as the fresh one it used to be: identity from the body.
+ *
+ * Everything else keeps the earlier rule, an authenticated `ctx.user` wins: a
+ * Hono request with a caller-supplied `X-Request-ID` (never marked), a custom
+ * adapter that carries `ctx.user` itself, and a route handler called directly
+ * with a context the caller built.
+ *
+ * It is an internal fact about how the context was built, not part of
+ * `ServerContext`, and it is not exported from the package.
+ *
+ * @module server/utils/carriedContextMark
+ */
+import type { ServerContext } from "../../types/index.js";
+/** Record that this context received state carried from middleware. */
+export declare function markContextCarried(ctx: ServerContext): void;
+/** `true` when `markContextCarried` was called for this context. */
+export declare function isContextCarried(ctx: ServerContext): boolean;

package/dist/server/utils/carriedContextMark.js

@@ -0,0 +1,32 @@
+/**
+ * Which route-handler contexts received the state the adapters now carry from
+ * middleware to the handler.
+ *
+ * Before the adapters carried that state, a handler normally got a fresh
+ * context with no `ctx.user` and no `ctx.session`. The one exception was Hono
+ * when the client sent its own `X-Request-ID`: Hono kept the middleware's
+ * context in a store keyed by that header, so the handler found it again, user
+ * included. The agent routes' default (`perUserAuth` unset) must not start
+ * trusting `ctx.user` on the requests that never had it, so the built-in
+ * adapters mark the contexts that received the carry, and the agent routes
+ * treat a marked context as the fresh one it used to be: identity from the body.
+ *
+ * Everything else keeps the earlier rule, an authenticated `ctx.user` wins: a
+ * Hono request with a caller-supplied `X-Request-ID` (never marked), a custom
+ * adapter that carries `ctx.user` itself, and a route handler called directly
+ * with a context the caller built.
+ *
+ * It is an internal fact about how the context was built, not part of
+ * `ServerContext`, and it is not exported from the package.
+ *
+ * @module server/utils/carriedContextMark
+ */
+const receivedCarry = new WeakSet();
+/** Record that this context received state carried from middleware. */
+export function markContextCarried(ctx) {
+    receivedCarry.add(ctx);
+}
+/** `true` when `markContextCarried` was called for this context. */
+export function isContextCarried(ctx) {
+    return receivedCarry.has(ctx);
+}

package/dist/types/proxy.d.ts

@@ -1068,6 +1068,10 @@ export type CodexRotationFailure = {
     lastErrorStatus: number;
     lastErrorCode: string | undefined;
     lastErrorMessage: string;
+    /** The upstream refused the request itself (a policy or invalid-request
+     *  code), not the account: no other account would answer differently, so the
+     *  pool ends the request here instead of rotating. */
+    refusedRequest?: boolean;
 };
 /** Minimal persistence contract needed by Codex rotating-token refreshes. */
 export type CodexRefreshTokenStore = {