@juspay/neurolink 13.8.24 → 13.8.26

package/dist/server/routes/index.js

@@ -64,7 +64,10 @@ export function createAllRoutes(basePath = "/api", options) {
             ? []
             : [createToolRoutes(basePath, sensitive)]),
         createMCPRoutes(basePath, sensitive),
-        createMemoryRoutes(basePath),
+        createMemoryRoutes(basePath, {
+            ...options?.memory,
+            perUserAuth: options?.perUserAuth,
+        }),
         createHealthRoutes(basePath),
         createTranscribeRoutes(basePath, options?.transcribe),
     ];

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

@@ -2,10 +2,43 @@
  * Memory Routes
  * Endpoints for conversation memory management
  */
-import type { RouteGroup } from "../../types/index.js";
+import type { RouteGroup, ServerMemoryRouteOptions } from "../../types/index.js";
 /**
  * Create memory management routes
  * Note: These routes provide a simplified interface to conversation memory.
  * The actual implementation depends on the memory manager type (ConversationMemoryManager or RedisConversationMemoryManager).
+ *
+ * By default the routes ignore who is calling: sessions are chosen by id (and
+ * `?userId=` on Redis), and statistics and clear-all are open to every caller
+ * that gets past your authentication. That is right for no authentication or one
+ * shared API key. Set `options.perUserAuth` (any truthy value) when the
+ * authentication middleware identifies individual people: every route but
+ * `GET /memory/health` then needs an authenticated user (401 otherwise), a
+ * caller reaches only its own sessions, and statistics and clear-all need a role
+ * in `options.adminRoles` (default `["admin"]`). A `?userId=` that is not a
+ * single value (a repeated `?userId=a&userId=b`) is refused with 400, and a user
+ * whose `roles` is not an array has no roles. A manager that can only report
+ * statistics (no `listSessions`, not Redis) shows an ordinary user an empty
+ * listing with a total of 0, never the count of everyone's sessions.
+ *
+ * `perUserAuth` needs `ctx.user` in the handler, which an adapter hands over
+ * 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, the user the authentication
+ * middleware sets does not reach the routes, so every request whose context
+ * has no `ctx.user` is answered 401, except `GET /memory/health`; a custom
+ * adapter or direct handler call that sets `ctx.user` itself is served as that
+ * user.
+ *
+ * On Redis, sessions are keyed by user, so an admin reaches another user's
+ * session only by naming that user in `?userId=`. The Redis key is
+ * `<keyPrefix><userId>:<sessionId>` with neither part escaped, so under
+ * `perUserAuth` a `:` in the authenticated user's id, an admin's `?userId=` or
+ * the session id is refused with 400 on every manager; otherwise user `a` asking
+ * for session `b:c` would reach user `a:b`'s session `c`. A session created
+ * without a `userId` is stored under the reserved user id `session-only`, which
+ * the routes refuse with 400 as the authenticated user's id or an admin's
+ * `?userId=`, so under `perUserAuth` no request reaches it.
  */
-export declare function createMemoryRoutes(basePath?: string): RouteGroup;
+export declare function createMemoryRoutes(basePath?: string, options?: ServerMemoryRouteOptions): RouteGroup;

package/dist/server/routes/memoryRoutes.js

@@ -5,6 +5,7 @@
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { shapeRouteError } from "../utils/clientError.js";
+import { SESSION_ONLY_USER_ID } from "../../utils/redis.js";
 import { createErrorResponse, IdParamSchema, SessionIdParamSchema, validateParams, } from "../utils/validation.js";
 /**
  * Wrap a route handler with an OTel span for HTTP observability.
@@ -19,16 +20,132 @@ function tracedMemoryHandler(name, route, fn) {
         },
     }, () => fn(ctx));
 }
+const DEFAULT_ADMIN_ROLES = ["admin"];
+/**
+ * Under `perUserAuth` a `:` is refused in every part of a session's key the
+ * routes take from the request: the authenticated user's id, an admin's
+ * `?userId=` and the session id. The Redis manager joins them unescaped as
+ * `<keyPrefix><userId>:<sessionId>`, so with a `:` in either part two different
+ * pairs share a key, and user `a` asking for session `b:c` would reach user
+ * `a:b`'s session `c`. The rule is the same on every manager, so whether a
+ * request is accepted does not depend on the backend.
+ */
+function refuseColon(ctx, what) {
+    return createErrorResponse("VALIDATION_ERROR", `${what} must not contain ':' when the memory routes are scoped with perUserAuth`, undefined, ctx.requestId);
+}
+/**
+ * Under `perUserAuth` the user id `session-only` is refused as well, as the
+ * authenticated user's id and as an admin's `?userId=`. It is the key a session
+ * created without a `userId` is stored under on Redis, and the Redis manager
+ * refuses it as a user id, so a request naming it could only miss; refusing it
+ * here, on every manager, says why instead of answering `404`.
+ */
+function refuseReservedUserId(ctx, what) {
+    return createErrorResponse("VALIDATION_ERROR", `${what} must not be '${SESSION_ONLY_USER_ID}', the user id reserved for sessions created without one, when the memory routes are scoped with perUserAuth`, undefined, ctx.requestId);
+}
+/**
+ * Who is calling. Without `perUserAuth` the routes do not read `ctx.user` at
+ * all: no auth and one shared API key (which sets the same `ctx.user` for every
+ * caller) both leave nothing to scope by, so the actor carries no user and every
+ * route behaves as it always has. With `perUserAuth` (any truthy value, as for
+ * the agent routes, so a JavaScript caller passing `"true"` or `1` still fails
+ * closed) the request must carry an authenticated user with a non-empty id;
+ * anything else is refused with 401, because an anonymous request is otherwise
+ * indistinguishable from the trusted unscoped one. A user whose `roles` is not
+ * an array (a malformed authentication middleware) has no roles, so it is an
+ * ordinary user, never a 500.
+ */
+function resolveMemoryActor(ctx, options) {
+    if (!options?.perUserAuth) {
+        return { user: undefined, admin: false };
+    }
+    const user = ctx.user;
+    if (!user || typeof user.id !== "string" || user.id.length === 0) {
+        return createErrorResponse("AUTH_REQUIRED", "Memory routes require an authenticated user", undefined, ctx.requestId);
+    }
+    if (user.id.includes(":")) {
+        return refuseColon(ctx, "The authenticated user id");
+    }
+    if (user.id === SESSION_ONLY_USER_ID) {
+        return refuseReservedUserId(ctx, "The authenticated user id");
+    }
+    const adminRoles = options.adminRoles ?? DEFAULT_ADMIN_ROLES;
+    return {
+        user,
+        admin: Array.isArray(user.roles) &&
+            user.roles.some((role) => adminRoles.includes(role)),
+    };
+}
+/**
+ * Whose sessions this request is about. Under `perUserAuth` the caller is always
+ * itself: `?userId=` may repeat its own id, and only an admin may name another.
+ * Taking the user from the query string is what let any authenticated caller
+ * read another user's conversations. Without it the query string is the only
+ * source, as it always was.
+ *
+ * Express, Fastify and Koa hand a repeated `?userId=a&userId=b` to the handler
+ * as an array (and an application that configures a bracket-parsing query
+ * parser gets one for `?userId[]=x` too). Under `perUserAuth` such a value is
+ * refused with 400 rather than read as "absent": reading it as absent would
+ * answer about a different user than the one the caller asked for (the caller's
+ * own sessions, or for an admin on the in-memory manager every session).
+ * Without `perUserAuth` the value is passed on untouched, as it always was.
+ */
+function resolveSubjectUserId(ctx, actor) {
+    const requested = ctx.query.userId;
+    if (!actor.user) {
+        return { userId: ctx.query.userId };
+    }
+    if (requested !== undefined && typeof requested !== "string") {
+        return createErrorResponse("VALIDATION_ERROR", "userId must be a single value", undefined, ctx.requestId);
+    }
+    if (requested?.includes(":")) {
+        return refuseColon(ctx, "userId");
+    }
+    if (requested === SESSION_ONLY_USER_ID) {
+        return refuseReservedUserId(ctx, "userId");
+    }
+    if (!requested || requested === actor.user.id) {
+        return { userId: actor.user.id };
+    }
+    if (actor.admin) {
+        return { userId: requested };
+    }
+    return createErrorResponse("FORBIDDEN", "userId does not match the authenticated user", undefined, ctx.requestId);
+}
+/**
+ * The in-memory manager keys sessions by id alone, so under `perUserAuth`
+ * ownership is the session's own `userId`. A session with none belongs to no one
+ * a caller can prove to be themselves, so only an admin sees it.
+ */
+function ownsSession(actor, session) {
+    if (!actor.user || actor.admin) {
+        return true;
+    }
+    const owner = session?.userId;
+    return typeof owner === "string" && owner === actor.user.id;
+}
 /**
  * Handler: Get messages for a session
  */
-async function handleGetSessionMessages(ctx) {
+async function handleGetSessionMessages(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
     // Validate path params
     const paramValidation = validateParams(IdParamSchema, ctx.params, ctx.requestId);
     if (!paramValidation.success) {
         return paramValidation.error;
     }
     const { id: sessionId } = paramValidation.data;
+    if (actor.user && sessionId.includes(":")) {
+        return refuseColon(ctx, "The session id");
+    }
+    const subject = resolveSubjectUserId(ctx, actor);
+    if ("error" in subject) {
+        return subject;
+    }
     // Parse query params for pagination
     const limitParam = ctx.query.limit ? parseInt(ctx.query.limit, 10) : 50;
     const offsetParam = ctx.query.offset ? parseInt(ctx.query.offset, 10) : 0;
@@ -44,7 +161,7 @@ async function handleGetSessionMessages(ctx) {
         // Handle Redis memory manager (has getUserSessionHistory)
         if ("getUserSessionHistory" in memory) {
             // For Redis, we need a userId - check query params or use a default
-            const userId = ctx.query.userId || "default";
+            const userId = subject.userId || "default";
             const sessionMessages = await memory.getUserSessionHistory(userId, sessionId);
             if (sessionMessages === null) {
                 return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
@@ -54,13 +171,17 @@ async function handleGetSessionMessages(ctx) {
         // Handle in-memory manager (has getSession)
         else if ("getSession" in memory) {
             const session = memory.getSession(sessionId);
-            if (!session) {
+            if (!session || !ownsSession(actor, session)) {
                 return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
             }
             messages = session.messages;
         }
         // Fallback: try buildContextMessages if available
         else if ("buildContextMessages" in memory) {
+            // Ownership cannot be established for this manager.
+            if (actor.user && !actor.admin) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
             messages = await memory.buildContextMessages(sessionId);
             // If no messages, session might not exist
             if (messages.length === 0) {
@@ -88,13 +209,24 @@ async function handleGetSessionMessages(ctx) {
 /**
  * Handler: Get session by ID
  */
-async function handleGetSession(ctx) {
+async function handleGetSession(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
     // Validate path params
     const paramValidation = validateParams(IdParamSchema, ctx.params, ctx.requestId);
     if (!paramValidation.success) {
         return paramValidation.error;
     }
     const { id: sessionId } = paramValidation.data;
+    if (actor.user && sessionId.includes(":")) {
+        return refuseColon(ctx, "The session id");
+    }
+    const subject = resolveSubjectUserId(ctx, actor);
+    if ("error" in subject) {
+        return subject;
+    }
     const memory = ctx.neurolink.conversationMemory;
     if (!memory) {
         return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
@@ -103,7 +235,7 @@ async function handleGetSession(ctx) {
         // Handle Redis memory manager (has getUserSessionObject or getUserSessionMetadata)
         if ("getUserSessionObject" in memory) {
             // For Redis, we need a userId - check query params or use a default
-            const userId = ctx.query.userId || "default";
+            const userId = subject.userId || "default";
             const sessionObject = await memory.getUserSessionObject(userId, sessionId);
             if (sessionObject === null) {
                 return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
@@ -119,7 +251,7 @@ async function handleGetSession(ctx) {
         // Handle in-memory manager (has getSession)
         else if ("getSession" in memory) {
             const session = memory.getSession(sessionId);
-            if (!session) {
+            if (!session || !ownsSession(actor, session)) {
                 return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
             }
             return {
@@ -139,9 +271,17 @@ async function handleGetSession(ctx) {
 /**
  * Handler: List all conversation sessions
  */
-async function handleListSessions(ctx) {
+async function handleListSessions(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
+    const subject = resolveSubjectUserId(ctx, actor);
+    if ("error" in subject) {
+        return subject;
+    }
     // Parse query params
-    const userId = ctx.query.userId;
+    const userId = subject.userId;
     const limitParam = ctx.query.limit ? parseInt(ctx.query.limit, 10) : 50;
     const offsetParam = ctx.query.offset ? parseInt(ctx.query.offset, 10) : 0;
     // Validate pagination params
@@ -171,18 +311,33 @@ async function handleListSessions(ctx) {
                 sessions = sessionIds.map((id) => ({ id }));
             }
         }
+        // In-memory manager under perUserAuth: a user sees their own sessions, an
+        // admin every session (or one user's with ?userId=), rather than the stats
+        // branch's empty list and a count of everyone's.
+        else if (actor.user && "listSessions" in memory) {
+            const scope = actor.admin ? ctx.query.userId || undefined : actor.user.id;
+            sessions = await memory.listSessions(scope);
+        }
         // Handle in-memory manager - iterate over internal sessions Map
         else if ("getStats" in memory) {
             // For in-memory, we can use getSession to check if sessions exist
             // but we need to know the session IDs first. The in-memory manager
             // doesn't expose a listSessions method, so we return stats info instead.
-            const stats = await memory.getStats?.();
+            //
+            // Under perUserAuth that total counts every user's sessions, and a manager
+            // that gets here cannot say which of them are the caller's. An ordinary
+            // user therefore gets an empty list and a total of 0, and the manager is
+            // not asked; an admin, who may read statistics anyway, gets the total.
+            const hidesTotal = Boolean(actor.user) && !actor.admin;
+            const stats = hidesTotal ? undefined : await memory.getStats?.();
             return {
                 sessions: [],
                 total: stats?.totalSessions || 0,
                 limit,
                 offset,
-                message: "Session listing not fully supported for in-memory storage. Use /stats endpoint for session counts.",
+                message: hidesTotal
+                    ? "This memory manager cannot list sessions per user."
+                    : "Session listing not fully supported for in-memory storage. Use /stats endpoint for session counts.",
                 metadata: {
                     timestamp: new Date().toISOString(),
                     requestId: ctx.requestId,
@@ -209,7 +364,14 @@ async function handleListSessions(ctx) {
 /**
  * Handler: Get memory statistics
  */
-async function handleGetStats(ctx) {
+async function handleGetStats(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
+    if (actor.user && !actor.admin) {
+        return createErrorResponse("FORBIDDEN", "Memory statistics require an admin role", undefined, ctx.requestId);
+    }
     const memory = ctx.neurolink.conversationMemory;
     if (!memory) {
         return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
@@ -233,20 +395,44 @@ async function handleGetStats(ctx) {
 /**
  * Handler: Clear a conversation session
  */
-async function handleClearSession(ctx) {
+async function handleClearSession(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
     // Validate params
     const paramValidation = validateParams(SessionIdParamSchema, ctx.params, ctx.requestId);
     if (!paramValidation.success) {
         return paramValidation.error;
     }
     const { sessionId } = paramValidation.data;
+    if (actor.user && sessionId.includes(":")) {
+        return refuseColon(ctx, "The session id");
+    }
+    const subject = resolveSubjectUserId(ctx, actor);
+    if ("error" in subject) {
+        return subject;
+    }
     const memory = ctx.neurolink.conversationMemory;
     if (!memory) {
         return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
     }
     try {
-        // Use clearSession for ConversationMemoryManager
-        const cleared = await memory.clearSession?.(sessionId);
+        const redisBacked = "getUserSessionObject" in memory;
+        if (actor.user && !actor.admin && !redisBacked) {
+            const existing = "getSession" in memory
+                ? memory.getSession(sessionId)
+                : undefined;
+            if (!existing || !ownsSession(actor, existing)) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
+        }
+        // The Redis manager derives the key from the user, so under perUserAuth hand
+        // it the one this request is scoped to; the in-memory manager ignores the
+        // argument. Without perUserAuth the call is as it always was, with no user.
+        const cleared = actor.user && redisBacked
+            ? await memory.clearSession?.(sessionId, subject.userId)
+            : await memory.clearSession?.(sessionId);
         if (cleared === false) {
             return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
         }
@@ -267,7 +453,14 @@ async function handleClearSession(ctx) {
 /**
  * Handler: Clear all conversation sessions
  */
-async function handleClearAllSessions(ctx) {
+async function handleClearAllSessions(ctx, options) {
+    const actor = resolveMemoryActor(ctx, options);
+    if ("error" in actor) {
+        return actor;
+    }
+    if (actor.user && !actor.admin) {
+        return createErrorResponse("FORBIDDEN", "Clearing every session requires an admin role", undefined, ctx.requestId);
+    }
     const memory = ctx.neurolink.conversationMemory;
     if (!memory) {
         return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
@@ -303,8 +496,41 @@ async function handleMemoryHealth(ctx) {
  * Create memory management routes
  * Note: These routes provide a simplified interface to conversation memory.
  * The actual implementation depends on the memory manager type (ConversationMemoryManager or RedisConversationMemoryManager).
+ *
+ * By default the routes ignore who is calling: sessions are chosen by id (and
+ * `?userId=` on Redis), and statistics and clear-all are open to every caller
+ * that gets past your authentication. That is right for no authentication or one
+ * shared API key. Set `options.perUserAuth` (any truthy value) when the
+ * authentication middleware identifies individual people: every route but
+ * `GET /memory/health` then needs an authenticated user (401 otherwise), a
+ * caller reaches only its own sessions, and statistics and clear-all need a role
+ * in `options.adminRoles` (default `["admin"]`). A `?userId=` that is not a
+ * single value (a repeated `?userId=a&userId=b`) is refused with 400, and a user
+ * whose `roles` is not an array has no roles. A manager that can only report
+ * statistics (no `listSessions`, not Redis) shows an ordinary user an empty
+ * listing with a total of 0, never the count of everyone's sessions.
+ *
+ * `perUserAuth` needs `ctx.user` in the handler, which an adapter hands over
+ * 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, the user the authentication
+ * middleware sets does not reach the routes, so every request whose context
+ * has no `ctx.user` is answered 401, except `GET /memory/health`; a custom
+ * adapter or direct handler call that sets `ctx.user` itself is served as that
+ * user.
+ *
+ * On Redis, sessions are keyed by user, so an admin reaches another user's
+ * session only by naming that user in `?userId=`. The Redis key is
+ * `<keyPrefix><userId>:<sessionId>` with neither part escaped, so under
+ * `perUserAuth` a `:` in the authenticated user's id, an admin's `?userId=` or
+ * the session id is refused with 400 on every manager; otherwise user `a` asking
+ * for session `b:c` would reach user `a:b`'s session `c`. A session created
+ * without a `userId` is stored under the reserved user id `session-only`, which
+ * the routes refuse with 400 as the authenticated user's id or an admin's
+ * `?userId=`, so under `perUserAuth` no request reaches it.
  */
-export function createMemoryRoutes(basePath = "/api") {
+export function createMemoryRoutes(basePath = "/api", options) {
     return {
         prefix: `${basePath}/memory`,
         routes: [
@@ -313,7 +539,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id/messages`,
-                handler: tracedMemoryHandler("http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, handleGetSessionMessages),
+                handler: tracedMemoryHandler("http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, (ctx) => handleGetSessionMessages(ctx, options)),
                 description: "Get messages for a session",
                 tags: ["memory"],
             },
@@ -321,7 +547,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id`,
-                handler: tracedMemoryHandler("http.memory.getSession", `${basePath}/memory/sessions/:id`, handleGetSession),
+                handler: tracedMemoryHandler("http.memory.getSession", `${basePath}/memory/sessions/:id`, (ctx) => handleGetSession(ctx, options)),
                 description: "Get session by ID",
                 tags: ["memory"],
             },
@@ -329,28 +555,28 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions`,
-                handler: tracedMemoryHandler("http.memory.listSessions", `${basePath}/memory/sessions`, handleListSessions),
+                handler: tracedMemoryHandler("http.memory.listSessions", `${basePath}/memory/sessions`, (ctx) => handleListSessions(ctx, options)),
                 description: "List all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/stats`,
-                handler: tracedMemoryHandler("http.memory.stats", `${basePath}/memory/stats`, handleGetStats),
+                handler: tracedMemoryHandler("http.memory.stats", `${basePath}/memory/stats`, (ctx) => handleGetStats(ctx, options)),
                 description: "Get memory statistics",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions/:sessionId`,
-                handler: tracedMemoryHandler("http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, handleClearSession),
+                handler: tracedMemoryHandler("http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, (ctx) => handleClearSession(ctx, options)),
                 description: "Clear a conversation session",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions`,
-                handler: tracedMemoryHandler("http.memory.clearAllSessions", `${basePath}/memory/sessions`, handleClearAllSessions),
+                handler: tracedMemoryHandler("http.memory.clearAllSessions", `${basePath}/memory/sessions`, (ctx) => handleClearAllSessions(ctx, options)),
                 description: "Clear all conversation sessions",
                 tags: ["memory"],
             },

package/dist/types/server.d.ts

@@ -1414,12 +1414,15 @@ export type CreateRoutesOptions = {
      * 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.
+     * authenticated user gets neither. The memory routes scope every session to
+     * that user too (see `ServerMemoryRouteOptions`). 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
+     * any authenticated caller can name another person there and act as them,
+     * and the memory routes ignore who is calling. The agent routes have one
+     * exception, 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
@@ -1445,6 +1448,70 @@ export type CreateRoutesOptions = {
      * `X-Request-ID`, and every other request runs as anonymous.
      */
     perUserAuth?: boolean;
+    /**
+     * Options for the conversation-memory routes (`<basePath>/memory/*`): which
+     * roles are admins when `perUserAuth` is on. Whether the routes are scoped is
+     * decided by the top-level `perUserAuth`, so it is not accepted here.
+     */
+    memory?: Omit<ServerMemoryRouteOptions, "perUserAuth">;
+};
+/** Options for `createMemoryRoutes()`. */
+export type ServerMemoryRouteOptions = {
+    /**
+     * Set to `true` when the authentication middleware identifies individual
+     * people (one credential per person). Every memory route but
+     * `GET <basePath>/memory/health` then needs an authenticated user (`401`
+     * without one, or with an empty id) and is scoped to it: a caller reaches
+     * only its own sessions, and statistics and clear-all need an admin role.
+     * Any truthy value turns it on.
+     *
+     * Leave it unset (default `false`) for no authentication or one shared API
+     * key, such as `neurolink serve` with `NEUROLINK_SERVER_API_KEY`. A shared key
+     * names no person, so the routes do not read `ctx.user` at all and behave as
+     * they always have: `?userId=` chooses the user on Redis, in-memory sessions
+     * are keyed by id alone, and statistics and clear-all are open to every
+     * caller that passes your authentication.
+     *
+     * The routes can only read `ctx.user` if the adapter hands it to the handler,
+     * which it does when the server carries middleware state.
+     * `registerAllRoutes` turns that on when given `perUserAuth`; a caller that
+     * registers `createMemoryRoutes` itself must create the server with
+     * `carryMiddlewareState: true`, or every request but `GET /memory/health` is
+     * answered `401`.
+     *
+     * "Only its own sessions" holds on every manager because the routes refuse a
+     * `:` (400) in the authenticated user's id, an admin's `?userId=` and the
+     * session id: the Redis manager joins user and session unescaped as
+     * `<keyPrefix><userId>:<sessionId>`, where user `a` asking for session `b:c`
+     * would otherwise reach user `a:b`'s session `c`. A deployment whose user ids
+     * contain `:` cannot use the scoped routes. On Redis a session created
+     * without a `userId` shares the key of a user whose id is `session-only`, so
+     * do not issue that id.
+     */
+    perUserAuth?: boolean;
+    /**
+     * Roles allowed to read another user's sessions, read memory statistics and
+     * clear every session. Default `["admin"]`. Only consulted with
+     * `perUserAuth`.
+     *
+     * On Redis, sessions are keyed per user, so an admin reaches another user's
+     * session by naming that user in `?userId=` (without it the admin's own
+     * sessions). A session created without a `userId` is stored under
+     * `<keyPrefix>session-only:<sessionId>`, the key of a user named
+     * `session-only`: an admin reaches it by naming `?userId=session-only` (so
+     * does an ordinary user whose own id is `session-only`), no other name
+     * reaches it, and clear-all removes it. The in-memory manager lists every
+     * session for an admin.
+     */
+    adminRoles?: string[];
+};
+/**
+ * Who is calling a memory route. `user` is the authenticated user the request
+ * is scoped to, and `undefined` when the routes are unscoped (no `perUserAuth`).
+ */
+export type ServerMemoryActor = {
+    user: AuthenticatedUser | undefined;
+    admin: boolean;
 };
 /**
  * Options of the route groups that act on the host (tool execution, MCP

package/dist/utils/redis.d.ts

@@ -3,6 +3,12 @@
  * Helper functions for Redis storage operations
  */
 import type { ChatMessage, RedisClient, RedisConversationObject, RedisStorageConfig } from "../types/index.js";
+/**
+ * The user id a session created without a `userId` is stored under. It is
+ * refused as a caller's user id (`describeRedisIdProblem`), so no user can name
+ * the sessions stored under it.
+ */
+export declare const SESSION_ONLY_USER_ID = "session-only";
 /**
  * Why an id is not usable as a key segment, or `null` when it is.
  */

package/dist/utils/redis.js

@@ -4,7 +4,13 @@
  */
 import { randomUUID } from "crypto";
 import { logger } from "./logger.js";
-const SESSION_ONLY_PREFIX = "session-only:";
+/**
+ * The user id a session created without a `userId` is stored under. It is
+ * refused as a caller's user id (`describeRedisIdProblem`), so no user can name
+ * the sessions stored under it.
+ */
+export const SESSION_ONLY_USER_ID = "session-only";
+const SESSION_ONLY_PREFIX = `${SESSION_ONLY_USER_ID}:`;
 /**
  * Longest id that may become part of a key. Redis itself allows far more, but
  * a session or user id past this length is not an id.