@juspay/neurolink 13.8.14 → 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/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/server.d.ts

@@ -40,6 +40,41 @@ export type ServerAdapterConfig = {
     redaction?: RedactionConfig;
     /** Shutdown configuration for graceful shutdown behavior */
     shutdown?: ShutdownConfig;
+    /**
+     * Carry what middleware sets on its context (`ctx.user`, `ctx.session`,
+     * `ctx.metadata`, `ctx.abortSignal` and `ctx.abortController`) to later
+     * middleware and to the route handler, on every built-in adapter (default:
+     * `false`). It does not apply to a context you build yourself: a custom
+     * adapter, or a route handler called directly, can supply a context that
+     * already has `ctx.user` set.
+     *
+     * Off, each adapter propagates context as it always did. Express, Fastify
+     * and Koa build a fresh context for every middleware step and for the
+     * handler and carry only `responseHeaders`; Hono shares one context between
+     * the steps and the handler only when the caller sent its own
+     * `X-Request-ID`. So a role guard, a permission guard or a rate-limit
+     * `keyGenerator` registered after authentication sees `ctx.user` only on
+     * that Hono request shape: on Express, Fastify and Koa, and on Hono without
+     * a caller `X-Request-ID`, the user never reaches it and the guard refuses
+     * everyone.
+     *
+     * On, the user and the rest reach later middleware and the handler on every
+     * built-in adapter. Set it when guards or key generators depend on `ctx.user`.
+     * `registerAllRoutes()` turns it on for the server by itself when called with
+     * `perUserAuth`, which needs the user in the handler. A caller that builds
+     * the agent routes with `createAgentRoutes(basePath, { perUserAuth: true })`
+     * and registers them itself must set this on the server: with it off, such a
+     * request has a user only on Hono when the client sent its own
+     * `X-Request-ID`, and every other request runs as anonymous (no `userId`, no
+     * session).
+     *
+     * The agent routes' warning about a body naming another user is raised only
+     * with this on. With it off, a handler that does receive `ctx.user` (Hono
+     * when the caller sent its own `X-Request-ID`) takes the user from it and
+     * ignores the body's `userId`, so nothing is named over it; every other
+     * request reaches the handler without a `ctx.user` to compare against.
+     */
+    carryMiddlewareState?: boolean;
 };
 /**
  * Required server adapter configuration (with defaults applied)
@@ -58,6 +93,7 @@ export type RequiredServerAdapterConfig = {
     disableBuiltInHealth: boolean;
     redaction?: RequiredRedactionConfig;
     shutdown: RequiredShutdownConfig;
+    carryMiddlewareState: boolean;
 };
 /**
  * CORS configuration
@@ -256,6 +292,12 @@ export type ServerContext = {
     /** Redaction configuration (for stream redaction support) */
     redaction?: RedactionConfig;
 };
+/**
+ * What middleware sets on its context that later middleware and the route
+ * handler must see. Adapters build a fresh context for every step, so this is
+ * what they carry between steps in the framework's per-request storage.
+ */
+export type ServerCarriedContext = Pick<ServerContext, "user" | "session" | "metadata" | "abortSignal" | "abortController">;
 /**
  * Server response object
  */
@@ -471,6 +513,50 @@ export type ServerAgentRouteOptions = {
      * file or download that would overflow it stops mid-transfer.
      */
     maxInputTotalBytes?: number;
+    /**
+     * For a caller of `createAgentRoutes()` itself; with `registerAllRoutes()` /
+     * `createAllRoutes()` use `CreateRoutesOptions.perUserAuth` instead. The
+     * routes can only take identity from `ctx.user` if the server hands it to
+     * the handler, so a caller that registers them itself with this option must
+     * create the server with `carryMiddlewareState: true`; `registerAllRoutes()`
+     * does that for the server by itself. With `carryMiddlewareState` off, such 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
+     * runs as anonymous, with no `userId` and no session.
+     *
+     * Set to `true` when the authentication middleware identifies individual
+     * people (one credential per person). The agent routes then take `userId`
+     * and the session only from the authenticated user (`ctx.user`,
+     * `ctx.session`) and ignore the request body's, on every adapter and for
+     * every request, so a caller cannot act as someone else. A request with no
+     * authenticated user gets no `userId` and no session, so with optional
+     * authentication anonymous callers never share a conversation. Any truthy
+     * value turns it on.
+     *
+     * **A server with per-person authentication must set this.** Left at the
+     * default (`false`) identity resolves as it always has: requests choose
+     * `userId` and `sessionId` in the body, so any authenticated caller can name
+     * another person there and act as them. The one exception is Hono, where a
+     * request whose client sent its own `X-Request-ID` header reaches the
+     * handler with the middleware's context, and an authenticated `ctx.user`
+     * (and `ctx.session`) wins over the body, as before, and so does it on a
+     * context the built-in adapters did not build (your own adapter, a handler
+     * called directly). Only this flag, with `carryMiddlewareState` on, makes the agent routes take
+     * the user from `ctx.user`, and ignore the body's `userId`, on every
+     * built-in adapter and every request. When the server carries middleware state
+     * the routes log one warning per instance the first time a request served
+     * from the body names a different `userId` than a `ctx.user` that is not
+     * marked `shared: true`; the body's `userId` is still used. With `carryMiddlewareState`
+     * off the handler has no `ctx.user` on such a request, so there is nothing to
+     * compare and no warning.
+     *
+     * Leave it unset for no authentication or one shared API key, such as
+     * `neurolink serve` with `NEUROLINK_SERVER_API_KEY`: a shared key names no
+     * person, so requests choose `userId` and `sessionId` in the body. Middleware
+     * for a shared key should set `shared: true` on the `AuthenticatedUser` it
+     * returns, which keeps the warning quiet (the CLI's key middleware does).
+     */
+    perUserAuth?: boolean;
 };
 /**
  * The route options plus the one thing that belongs to a single call:
@@ -762,6 +848,15 @@ export type WebSocketRequestId = string | number;
  */
 export type AuthenticatedUser = {
     id: string;
+    /**
+     * `true` when this identity stands for every holder of one credential, such
+     * as a shared API key, rather than for one person. The agent routes then do
+     * not warn when a request names a different `userId` in its body: with a
+     * shared key every caller is one trust domain and the body is how callers
+     * keep separate conversation memory. Middleware that sets one fixed user for
+     * everyone holding a key should set this; per-person middleware should not.
+     */
+    shared?: boolean;
     email?: string;
     name?: string;
     roles?: string[];
@@ -1073,6 +1168,12 @@ export type AuthResult = {
     email?: string;
     /** User roles (optional) */
     roles?: string[];
+    /**
+     * `true` when this identity stands for every holder of one credential, such
+     * as a shared API key, rather than one person. Carried to `ctx.user.shared`;
+     * see `AuthenticatedUser.shared`.
+     */
+    shared?: boolean;
     /** Additional user data */
     metadata?: Record<string, unknown>;
 };
@@ -1174,9 +1275,46 @@ export type CreateRoutesOptions = {
     /**
      * Options for the agent routes (`POST <basePath>/agent/execute` and
      * `/agent/stream`): where local-path attachments may be read from, and how
-     * large an attachment may be.
+     * large an attachment may be. Whose identity the routes trust is decided by
+     * the top-level `perUserAuth`, which is why it is not accepted here.
+     */
+    agent?: Omit<ServerAgentRouteOptions, "perUserAuth">;
+    /**
+     * Set to `true` when the authentication middleware identifies individual
+     * people (one credential per person). The agent routes then take `userId`
+     * and the session only from the authenticated user and ignore the request
+     * body's, on every adapter and for every request; a request with no
+     * authenticated user gets neither. Any truthy value turns it on.
+     *
+     * **A server with per-person authentication must set this.** Left at the
+     * default (`false`) requests choose `userId` and `sessionId` in the body, so
+     * any authenticated caller can name another person there and act as them.
+     * The one exception is Hono, where a request whose client sent its own
+     * `X-Request-ID` header reaches the handler with the middleware's context and
+     * an authenticated `ctx.user` wins over the body, as before, and so on a
+     * context the built-in adapters did not build (your own adapter, a handler
+     * called directly); only this flag, with `carryMiddlewareState` on, makes the agent routes take
+     * the user from `ctx.user` everywhere. When the server carries middleware state, the first time a
+     * request served from the body names a different `userId` than its
+     * `ctx.user`, the routes log a warning (once per instance); with `carryMiddlewareState`
+     * off the handler has no `ctx.user` to compare, and there is no warning.
+     * Leave it unset for no authentication or one shared
+     * API key, such as `neurolink serve` with `NEUROLINK_SERVER_API_KEY`:
+     * requests choose `userId` and `sessionId` in the body. Middleware for a
+     * shared key should set `shared: true` on the `AuthenticatedUser` it
+     * returns, which keeps the warning quiet.
+     *
+     * This is the one switch for a server built with `registerAllRoutes` /
+     * `createAllRoutes`: every route group that scopes by identity reads it from
+     * here, so it cannot be set for the agent routes alone. `registerAllRoutes`
+     * also turns on the server's `carryMiddlewareState` when this is set, since
+     * the routes need the user in the handler; `createAllRoutes` returns route
+     * groups only, so a caller that registers them itself must create the server
+     * with `carryMiddlewareState: true`; with `carryMiddlewareState` off, a `perUserAuth`
+     * request has a user only on Hono when the client sent its own
+     * `X-Request-ID`, and every other request runs as anonymous.
      */
-    agent?: ServerAgentRouteOptions;
+    perUserAuth?: boolean;
 };
 /** Options for `createTranscribeRoutes()`. */
 /**