@m6d/cortex-server 2.5.0 → 2.6.0

package/README.md

@@ -62,7 +62,17 @@ export default {
 
 Only `database`, `model`, and `agents` are required for a minimal setup. `storage` enables attachment uploads/downloads, `embedding` is only required when `neo4j` graph features are configured, and agent `systemPrompt` defaults to an empty prompt when omitted. An optional `redis: { url, streamTtlSeconds? }` backs resumable streams with Redis so runs survive reconnects, reloads, and multiple server instances; without it an in-memory, single-process fallback is used.
 
-Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, `resolveRequestContext`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
+Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, `resolveRequestContext`, `auth`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
+
+## Authentication
+
+The top-level `auth` verifies end-user JWTs for the whole server: tokens are checked against the IdP's remote JWKS (`jwksUri`) and pinned `issuer`, and the verified `sub` becomes the user id. Without it, every request shares one anonymous identity — fine for local development, wrong for anything multi-user.
+
+An agent can carry its own `auth: { jwksUri, issuer, audience? }`, either in its `agents` entry or configured on the agent in the Control Center (the code entry wins; the cc value reaches the server through the same config sync as the rest of the agent). On such an agent, identity comes only from tokens that issuer signed — the server-level default and the anonymous fallback no longer apply, and requests without a verifiable token get a 401. cc playground tokens remain valid so the Control Center can test auth-enabled agents.
+
+Set the optional `audience` when the issuer mints tokens for more than one application: the token's `aud` claim must then contain it, so a token issued for a different audience under the same issuer is rejected. The owner-supplied `jwksUri` is fetched under an SSRF policy that refuses loopback, private, link-local, and cloud-metadata destinations, pins DNS against rebinding, and rejects redirects; a self-hosted IdP on a private network is reached by setting `EGRESS_ALLOW_PRIVATE_NETWORK=true` (development only).
+
+Requirements for the token minter: asymmetric signing (RS256/ES256/EdDSA) with the public keys published at the JWKS URL, a `kid` header, and exact `iss` and `exp` claims. Tokens travel as `Authorization: Bearer <jwt>`; WebSocket upgrades use `?token=<jwt>` since browsers cannot set headers there.
 
 ## Client tools
 

package/contracts/src/runtime/index.ts

@@ -130,6 +130,22 @@ export const serviceCardSchema = z.object({
 
 export const runtimeAgentConfigSchema = z.object({
     agentId: agentSlugSchema,
+    /**
+     * End-user JWT verification for this agent, managed by the agent's owner.
+     * Tokens must be asymmetrically signed (the JWKS URI serves the public
+     * keys) with a matching `iss` claim. Absent = the server's own auth
+     * default applies.
+     */
+    auth: z
+        .object({
+            jwksUri: z.url(),
+            issuer: z.string().trim().min(1).max(2048),
+            // Optional: when set, the token's `aud` must contain it. Guards
+            // against a token minted for another audience under the same
+            // issuer being replayed here.
+            audience: z.string().trim().min(1).max(2048).optional(),
+        })
+        .optional(),
     systemPrompt: z.string(),
     promptVariables: z.array(z.enum(PROMPT_VARIABLES)),
     defaultLocale: localeSchema,

package/dist/contracts/src/runtime/index.d.ts

@@ -101,6 +101,11 @@ export declare const serviceCardSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const runtimeAgentConfigSchema: z.ZodObject<{
     agentId: z.ZodString;
+    auth: z.ZodOptional<z.ZodObject<{
+        jwksUri: z.ZodURL;
+        issuer: z.ZodString;
+        audience: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     systemPrompt: z.ZodString;
     promptVariables: z.ZodArray<z.ZodEnum<{
         userName: "userName";

package/dist/src/lib/adapters/database/index.d.ts

@@ -46,8 +46,10 @@ export type DatabaseAdapter = {
             output: string | null;
             tokenUsage: TokenUsage | null;
         }[]): Promise<void>;
+        /** `threadId` is for the caller's ownership check, not the wire. */
         listByMessageId(messageId: string): Promise<{
             id: string;
+            threadId: string;
             prompt: string;
             output: string | null;
             tokenUsage: TokenUsage | null;

package/dist/src/lib/adapters/database/mssql/index.d.ts

@@ -95,6 +95,7 @@ export declare function createMssqlAdapter(connectionString: string, storage?: S
         }[]): Promise<void>;
         listByMessageId(messageId: string): Promise<{
             id: string;
+            threadId: string;
             prompt: string;
             output: string | null;
             tokenUsage: import("../../..").TokenUsage | null;

package/dist/src/lib/adapters/database/mssql/llm-requests.d.ts

@@ -11,6 +11,7 @@ export declare function createLlmRequestsRepository(db: MssqlDb, enqueue?: typeo
     /** Ordered by step so the inspector replays a turn in the order it ran. */
     listByMessageId(messageId: string): Promise<{
         id: string;
+        threadId: string;
         prompt: string;
         output: string | null;
         tokenUsage: import("../../..").TokenUsage | null;

package/dist/src/lib/adapters/database/postgres/index.d.ts

@@ -95,6 +95,7 @@ export declare function createPostgresAdapter(connectionString: string, storage?
         }[]): Promise<void>;
         listByMessageId(messageId: string): Promise<{
             id: string;
+            threadId: string;
             prompt: string;
             output: string | null;
             tokenUsage: import("../../..").TokenUsage | null;

package/dist/src/lib/adapters/database/postgres/llm-requests.d.ts

@@ -11,6 +11,7 @@ export declare function createLlmRequestsRepository(db: PostgresDb, enqueue?: ty
     /** Ordered by step so the inspector replays a turn in the order it ran. */
     listByMessageId(messageId: string): Promise<{
         id: string;
+        threadId: string;
         prompt: string;
         output: string | null;
         tokenUsage: import("../../..").TokenUsage | null;

package/dist/src/lib/ai/cc-runtime.d.ts

@@ -45,6 +45,11 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
         };
         catalogVersion: string;
         publishedAt: string;
+        auth?: {
+            jwksUri: string;
+            issuer: string;
+            audience?: string | undefined;
+        } | undefined;
     };
     registry: CcToolRegistry;
     clientTools: Map<string, CcClientTool>;

package/dist/src/lib/auth/jwks-cache.d.ts

@@ -0,0 +1,10 @@
+export declare function remoteJwks(url: string, options?: {
+    guarded?: boolean;
+}): {
+    (protectedHeader?: import("jose").JWSHeaderParameters, token?: import("jose").FlattenedJWSInput): Promise<import("jose").CryptoKey>;
+    coolingDown: boolean;
+    fresh: boolean;
+    reloading: boolean;
+    reload: () => Promise<void>;
+    jwks: () => import("jose").JSONWebKeySet | undefined;
+};

package/dist/src/lib/auth/middleware.d.ts

@@ -1,4 +1,15 @@
 import type { AppEnv, AuthedAppEnv } from "../types";
-import type { ControlCenterConfig, CortexConfig } from "../config";
+import type { ControlCenterConfig, CortexConfig, ResolvedCortexAgentConfig } from "../config";
 export declare function createUserLoaderMiddleware(authConfig: CortexConfig["auth"], controlCenter?: ControlCenterConfig): import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+/**
+ * Identity for an agent that carries its own JWKS + issuer: the caller is
+ * whoever that issuer vouches for, or nobody — the server-level result
+ * (including the anonymous fallback) does not apply on that agent's routes.
+ * cc playground tokens stay valid so the Control Center can test
+ * auth-enabled agents. `undefined` means `requireAuth` will answer 401.
+ */
+export declare function resolveAgentUser(request: Request, auth: NonNullable<ResolvedCortexAgentConfig["auth"]>, controlCenter?: ControlCenterConfig): Promise<{
+    id: string;
+    token: string;
+} | undefined>;
 export declare const requireAuth: import("hono").MiddlewareHandler<AuthedAppEnv, string, {}, Response>;

package/dist/src/lib/auth/safe-jwks-fetch.d.ts

@@ -0,0 +1,10 @@
+import type { FetchImplementation } from "jose";
+/**
+ * A jose `customFetch`: the global `fetch` signature jose would otherwise call,
+ * but pinned to the SSRF policy above and refusing redirects. Passed to
+ * `createRemoteJWKSet` for the per-agent path only. The undici call is cast
+ * once at the boundary: undici's Request/Response types diverge from the
+ * global ones jose is typed against, and only its `dispatcher` option carries
+ * the pinned lookup.
+ */
+export declare const guardedJwksFetch: FetchImplementation;

package/dist/src/lib/cc/client.d.ts

@@ -47,6 +47,11 @@ export declare class ControlCenterClient {
             };
             catalogVersion: string;
             publishedAt: string;
+            auth?: {
+                jwksUri: string;
+                issuer: string;
+                audience?: string | undefined;
+            } | undefined;
         };
         readonly etag: string | null;
     } | null>;

package/dist/src/lib/cc/config-cache.d.ts

@@ -16,4 +16,9 @@ export declare function getControlCenterConfig(cc: ControlCenterClient, agentId:
     };
     catalogVersion: string;
     publishedAt: string;
+    auth?: {
+        jwksUri: string;
+        issuer: string;
+        audience?: string | undefined;
+    } | undefined;
 } | null>;

package/dist/src/lib/config.d.ts

@@ -133,6 +133,17 @@ type AgentBehavior<TSession extends Record<string, unknown>, TRequestContext ext
         isAborted: boolean;
     }) => void;
 };
+/**
+ * Agent-level end-user JWT verification. When set, identity on that agent's
+ * routes comes only from tokens this issuer signed (or cc playground tokens);
+ * the server-level `auth`/anonymous fallback no longer applies there.
+ */
+type AgentAuthConfig = {
+    jwksUri: string;
+    issuer: string;
+    /** When set, the token's `aud` must contain it. */
+    audience?: string;
+};
 /**
  * An agent as authored. Providers are optional because an unset one inherits
  * from server level; `null` on knowledge means "opt out entirely" rather than
@@ -140,6 +151,7 @@ type AgentBehavior<TSession extends Record<string, unknown>, TRequestContext ext
  * decided by publishing them there, not per entry here.
  */
 export type CortexAgentDefinition<TSession extends Record<string, unknown> = Record<string, unknown>, TRequestContext extends Record<string, unknown> = Record<string, unknown>> = AgentBehavior<TSession, TRequestContext> & Partial<ProviderConfig> & {
+    auth?: AgentAuthConfig;
     knowledge?: KnowledgeConfig | null;
     context?: Partial<ContextConfig>;
 };
@@ -150,6 +162,7 @@ export type CortexAgentDefinition<TSession extends Record<string, unknown> = Rec
  */
 export type ResolvedCortexAgentConfig = AgentBehavior<Record<string, unknown>, Record<string, unknown>> & ProviderConfig & {
     agentId: string;
+    auth?: AgentAuthConfig;
     db: DatabaseAdapter;
     storage?: StorageAdapter;
     controlCenter?: ControlCenterConfig;

package/dist/src/lib/routes/ws.d.ts

@@ -1,7 +1,3 @@
 import { Hono } from "hono";
 import type { AppEnv } from "../types";
-type WsRouteOptions = {
-    useAgentParam?: boolean;
-};
-export declare function createWsRoute(options?: WsRouteOptions): Hono<AppEnv, import("hono/types").BlankSchema, "/">;
-export {};
+export declare function createWsRoute(): Hono<AppEnv, import("hono/types").BlankSchema, "/">;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",
@@ -44,7 +44,8 @@
         "minio": "^8.0.7",
         "mssql": "^12.2.0",
         "pg": "^8.16.3",
-        "quickjs-emscripten": "^0.32.0"
+        "quickjs-emscripten": "^0.32.0",
+        "undici": "7.28.0"
     },
     "devDependencies": {
         "@tanstack/ai": "^0.43.1",

package/src/lib/adapters/database/index.ts

@@ -55,9 +55,11 @@ export type DatabaseAdapter = {
                 tokenUsage: TokenUsage | null;
             }[],
         ): Promise<void>;
+        /** `threadId` is for the caller's ownership check, not the wire. */
         listByMessageId(messageId: string): Promise<
             {
                 id: string;
+                threadId: string;
                 prompt: string;
                 output: string | null;
                 tokenUsage: TokenUsage | null;

package/src/lib/adapters/database/mssql/llm-requests.ts

@@ -1,5 +1,5 @@
 import { asc, eq, type InferInsertModel } from "drizzle-orm";
-import { llmRequests } from "@/db/schema.mssql";
+import { llmRequests, messages } from "@/db/schema.mssql";
 import { usageRecordEvent } from "@/cc/sync-events";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import type { MssqlDb } from "./client";
@@ -50,11 +50,15 @@ export function createLlmRequestsRepository(
             return await db
                 .select({
                     id: llmRequests.id,
+                    // Requests key on the message; the owning thread comes
+                    // through it for the route's ownership check.
+                    threadId: messages.threadId,
                     prompt: llmRequests.prompt,
                     output: llmRequests.output,
                     tokenUsage: llmRequests.tokenUsage,
                 })
                 .from(llmRequests)
+                .innerJoin(messages, eq(messages.id, llmRequests.messageId))
                 .where(eq(llmRequests.messageId, messageId))
                 .orderBy(asc(llmRequests.stepNumber))
                 .execute();

package/src/lib/adapters/database/postgres/llm-requests.ts

@@ -1,7 +1,7 @@
 // fallow-ignore-file code-duplication -- mirrors ../mssql/llm-requests.ts by design;
 // Drizzle types query builders per dialect. See DatabaseAdapter in ../index.ts.
 import { asc, eq, type InferInsertModel } from "drizzle-orm";
-import { llmRequests } from "@/db/schema.pg";
+import { llmRequests, messages } from "@/db/schema.pg";
 import { usageRecordEvent } from "@/cc/sync-events";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import type { PostgresDb } from "./client";
@@ -52,11 +52,15 @@ export function createLlmRequestsRepository(
             return await db
                 .select({
                     id: llmRequests.id,
+                    // Requests key on the message; the owning thread comes
+                    // through it for the route's ownership check.
+                    threadId: messages.threadId,
                     prompt: llmRequests.prompt,
                     output: llmRequests.output,
                     tokenUsage: llmRequests.tokenUsage,
                 })
                 .from(llmRequests)
+                .innerJoin(messages, eq(messages.id, llmRequests.messageId))
                 .where(eq(llmRequests.messageId, messageId))
                 .orderBy(asc(llmRequests.stepNumber))
                 .execute();

package/src/lib/ai/commit-gate.ts

@@ -1,5 +1,6 @@
 import {
     EventType,
+    generateMessageId,
     StreamProcessor,
     type MessagePart,
     type StreamChunk,
@@ -15,6 +16,77 @@ type CommitGateOptions = {
 
 const ABORTED_TOOL_RESULT = "Generation was aborted";
 
+/**
+ * Chunk types whose processor handler opens an assistant message when none is
+ * active, minting a local `msg-…` fallback id if the chunk names none.
+ */
+const MESSAGE_OPENERS = new Set<StreamChunk["type"]>([
+    EventType.TEXT_MESSAGE_CONTENT,
+    EventType.TOOL_CALL_START,
+    EventType.STEP_FINISHED,
+    EventType.REASONING_MESSAGE_CONTENT,
+    EventType.RUN_ERROR,
+]);
+
+/** The message id a chunk names, for the types that can name one. */
+function namedMessageId(chunk: StreamChunk) {
+    switch (chunk.type) {
+        case EventType.TEXT_MESSAGE_START:
+        case EventType.TEXT_MESSAGE_CONTENT:
+            return chunk.messageId;
+        case EventType.TOOL_CALL_START:
+            return chunk.parentMessageId;
+        default:
+            return undefined;
+    }
+}
+
+/**
+ * The id half of the read-back guarantee. The model adapters' chunks name no
+ * message id, so the StreamProcessor rebuilding messages here and the one in
+ * every client each mint their own `msg-…` fallback id for the same message —
+ * and the client's post-turn refetch then remounts those messages under the
+ * stored ids (re-running entrance animations). Opening each such message here,
+ * with an explicit TEXT_MESSAGE_START carrying an id minted once, puts the
+ * same id on both sides. Mirrors the processor's activation rules: an opened
+ * message stays active until the iteration's RUN_FINISHED (or RUN_ERROR)
+ * finalizes it.
+ */
+async function* withStampedMessageIds(stream: AsyncIterable<StreamChunk>) {
+    let activeId: string | undefined;
+    let openRuns = 0;
+
+    for await (const chunk of stream) {
+        const named = namedMessageId(chunk);
+        if (named) activeId = named;
+
+        if (!activeId && MESSAGE_OPENERS.has(chunk.type)) {
+            activeId = generateMessageId();
+            yield {
+                type: EventType.TEXT_MESSAGE_START,
+                messageId: activeId,
+                role: "assistant",
+                timestamp: Date.now(),
+            } satisfies Extract<StreamChunk, { type: EventType.TEXT_MESSAGE_START }>;
+        }
+
+        switch (chunk.type) {
+            case EventType.RUN_STARTED:
+                openRuns += 1;
+                break;
+            case EventType.RUN_FINISHED:
+                openRuns -= 1;
+                if (openRuns <= 0) activeId = undefined;
+                break;
+            case EventType.RUN_ERROR:
+                activeId = undefined;
+                break;
+        }
+
+        yield chunk;
+    }
+}
+
 /**
  * Rebuilds the run's messages from its own chunks and holds the run's terminal
  * event back until they are committed, so a client that refetches when the
@@ -33,7 +105,7 @@ export async function* commitBeforeTerminal(
     let commitError: unknown;
 
     try {
-        for await (const chunk of stream) {
+        for await (const chunk of withStampedMessageIds(stream)) {
             // A snapshot replaces the processor's whole message list with the
             // context window under synthetic ids. The client wants it; persistence
             // must not see it, or a turn would rewrite the thread it replied to.

package/src/lib/auth/jwks-cache.ts

@@ -0,0 +1,27 @@
+import { createRemoteJWKSet, customFetch } from "jose";
+import { guardedJwksFetch } from "./safe-jwks-fetch";
+
+/*
+ * One remote key set per JWKS URL, shared by every issuer this server trusts
+ * (the cc playground, per-agent IdPs). jose already caches the fetched keys
+ * and refetches on unknown-kid, so one set per URL is all the state needed.
+ *
+ * `guarded` routes the fetch through the SSRF policy in `safe-jwks-fetch`, for
+ * owner-supplied per-agent URLs. Operator-configured issuers stay unguarded: a
+ * self-hosted cc or IdP may legitimately sit on a private network.
+ */
+
+const jwksByUrl = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+export function remoteJwks(url: string, options: { guarded?: boolean } = {}) {
+    const key = options.guarded ? `guarded:${url}` : url;
+    let jwks = jwksByUrl.get(key);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(
+            new URL(url),
+            options.guarded ? { [customFetch]: guardedJwksFetch } : undefined,
+        );
+        jwksByUrl.set(key, jwks);
+    }
+    return jwks;
+}

package/src/lib/auth/middleware.ts

@@ -1,11 +1,20 @@
 import { createMiddleware } from "hono/factory";
 import { getCookie } from "hono/cookie";
 import { HTTPException } from "hono/http-exception";
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { jwtVerify } from "jose";
 import type { AppEnv, AuthedAppEnv } from "@/types";
-import type { ControlCenterConfig, CortexConfig } from "@/config";
+import type { ControlCenterConfig, CortexConfig, ResolvedCortexAgentConfig } from "@/config";
+import { remoteJwks } from "./jwks-cache";
 import { isPlaygroundToken, verifyPlaygroundToken } from "./playground";
 
+/** Bearer header first, then `?token=` — the query form exists for WebSocket
+ * upgrades, where browsers cannot set headers. */
+function tokenFromRequest(request: Request) {
+    const header = request.headers.get("Authorization");
+    if (header?.startsWith("Bearer ")) return header.slice(7);
+    return new URL(request.url).searchParams.get("token");
+}
+
 export function createUserLoaderMiddleware(
     authConfig: CortexConfig["auth"],
     controlCenter?: ControlCenterConfig,
@@ -35,7 +44,7 @@ export function createUserLoaderMiddleware(
         });
     }
 
-    const jwks = createRemoteJWKSet(new URL(authConfig.jwksUri));
+    const jwks = remoteJwks(authConfig.jwksUri);
 
     return createMiddleware<AppEnv>(async (c, next) => {
         let token: string | null = null;
@@ -43,19 +52,7 @@ export function createUserLoaderMiddleware(
         if (authConfig.tokenExtractor) {
             token = authConfig.tokenExtractor(c.req.raw);
         } else {
-            // 1. Authorization header
-            const authHeader = c.req.header("Authorization");
-            if (authHeader?.startsWith("Bearer ")) {
-                token = authHeader.slice(7);
-            }
-
-            // 2. Query parameter
-            if (!token) {
-                const url = new URL(c.req.url);
-                token = url.searchParams.get("token");
-            }
-
-            // 3. Cookie
+            token = tokenFromRequest(c.req.raw);
             if (!token && authConfig.cookieName) {
                 token = getCookie(c, authConfig.cookieName) ?? null;
             }
@@ -88,6 +85,37 @@ export function createUserLoaderMiddleware(
     });
 }
 
+/**
+ * Identity for an agent that carries its own JWKS + issuer: the caller is
+ * whoever that issuer vouches for, or nobody — the server-level result
+ * (including the anonymous fallback) does not apply on that agent's routes.
+ * cc playground tokens stay valid so the Control Center can test
+ * auth-enabled agents. `undefined` means `requireAuth` will answer 401.
+ */
+export async function resolveAgentUser(
+    request: Request,
+    auth: NonNullable<ResolvedCortexAgentConfig["auth"]>,
+    controlCenter?: ControlCenterConfig,
+) {
+    const token = tokenFromRequest(request);
+    if (!token) return undefined;
+
+    try {
+        const payload = isPlaygroundToken(controlCenter, token)
+            ? await verifyPlaygroundToken(controlCenter!, token)
+            : (
+                  await jwtVerify(token, remoteJwks(auth.jwksUri, { guarded: true }), {
+                      issuer: auth.issuer,
+                      audience: auth.audience,
+                      clockTolerance: 60,
+                  })
+              ).payload;
+        return payload.sub ? { id: payload.sub, token } : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
 export const requireAuth = createMiddleware<AuthedAppEnv>(async (c, next) => {
     const user = c.get("user");
     if (!user) {

package/src/lib/auth/playground.ts

@@ -1,24 +1,15 @@
-import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+import { decodeJwt, jwtVerify } from "jose";
 import type { ControlCenterConfig } from "@/config";
+import { remoteJwks } from "./jwks-cache";
 
 /*
  * cc as a secondary issuer (opt-in via `controlCenter.playground`): its
  * short-lived end-user JWTs verify against `{url}/api/auth/jwks`, and its
- * signed `X-Cortex-Playground` header marks threads as test data. The remote
- * JWKS set is cached per cc URL — jose already caches the fetched keys and
- * refetches on unknown-kid, so one set per URL is all the state needed.
+ * signed `X-Cortex-Playground` header marks threads as test data.
  */
 
-const jwksByUrl = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
-
 function ccJwks(config: ControlCenterConfig) {
-    const url = `${config.url.replace(/\/+$/, "")}/api/auth/jwks`;
-    let jwks = jwksByUrl.get(url);
-    if (!jwks) {
-        jwks = createRemoteJWKSet(new URL(url));
-        jwksByUrl.set(url, jwks);
-    }
-    return jwks;
+    return remoteJwks(`${config.url.replace(/\/+$/, "")}/api/auth/jwks`);
 }
 
 export function ccIssuer(config: ControlCenterConfig) {

package/src/lib/auth/safe-jwks-fetch.ts

@@ -0,0 +1,129 @@
+// fallow-ignore-file complexity -- SSRF classification keeps each prohibited address range explicit
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import type { LookupFunction } from "node:net";
+import { Agent, fetch as undiciFetch } from "undici";
+import type { FetchImplementation } from "jose";
+
+/*
+ * A per-agent JWKS URL is supplied by the agent's owner, so the fetch the
+ * runtime makes for its signing keys is an SSRF vector. This mirrors the
+ * outbound policy the Control Center already applies to tool endpoints
+ * (apps/cortex-cc/src/lib/safe-fetch.ts): plaintext blocked off loopback,
+ * private/link-local/metadata ranges refused, DNS pinned so a rebind cannot
+ * slip a private address past the check, redirects rejected. cortex-server is
+ * a separately published package and cannot import cc app code, so the address
+ * policy is duplicated here rather than shared.
+ *
+ * Operator-configured issuers (server-level `auth`, the cc playground) do not
+ * pass through here: only the per-agent path is attacker-influenced.
+ */
+
+function isBlockedAddress(address: string): boolean {
+    // Development-only opt-out so a self-hosted IdP on localhost/a private
+    // network works. Never set in production: it disables every range below.
+    if (process.env.EGRESS_ALLOW_PRIVATE_NETWORK === "true") return false;
+    if (isIP(address) === 6) {
+        const normalized = address.toLowerCase();
+        if (normalized.startsWith("::ffff:")) {
+            const mapped = normalized.slice("::ffff:".length);
+            return isIP(mapped) === 4 ? isBlockedAddress(mapped) : true;
+        }
+        return (
+            normalized === "::" ||
+            normalized === "::1" ||
+            normalized.startsWith("fc") ||
+            normalized.startsWith("fd") ||
+            /^fe[89ab]/.test(normalized)
+        );
+    }
+
+    const [a = 0, b = 0] = address.split(".").map(Number);
+    return (
+        a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224
+    );
+}
+
+function egressError() {
+    const error: NodeJS.ErrnoException = new Error("egress blocked");
+    error.code = "EGRESS_BLOCKED";
+    return error;
+}
+
+/**
+ * Re-resolves the hostname and re-validates every candidate on every connection
+ * attempt, handing the socket only vetted public addresses. The address dialed
+ * is the exact one just checked, so a nameserver cannot return a public IP to
+ * the check and a private one to the connect.
+ */
+const pinnedLookup: LookupFunction = (hostname, options, callback) => {
+    lookup(hostname, { all: true, verbatim: true }).then(
+        (addresses) => {
+            const first = addresses[0];
+            if (!first || addresses.some((address) => isBlockedAddress(address.address))) {
+                callback(egressError(), "", 0);
+                return;
+            }
+            if (options.all) {
+                callback(
+                    null,
+                    addresses.map((address) => ({
+                        address: address.address,
+                        family: address.family,
+                    })),
+                );
+                return;
+            }
+            callback(null, first.address, first.family);
+        },
+        (error: unknown) =>
+            callback(error instanceof Error ? error : new Error("lookup failed"), "", 0),
+    );
+};
+
+/**
+ * A jose `customFetch`: the global `fetch` signature jose would otherwise call,
+ * but pinned to the SSRF policy above and refusing redirects. Passed to
+ * `createRemoteJWKSet` for the per-agent path only. The undici call is cast
+ * once at the boundary: undici's Request/Response types diverge from the
+ * global ones jose is typed against, and only its `dispatcher` option carries
+ * the pinned lookup.
+ */
+export const guardedJwksFetch: FetchImplementation = async (url, options) => {
+    const target = new URL(url);
+    const hostname = target.hostname.replace(/^\[(.*)]$/, "$1");
+
+    if (!["http:", "https:"].includes(target.protocol) || target.username || target.password) {
+        throw egressError();
+    }
+
+    // Fail fast before opening a socket; pinnedLookup re-checks at connect time.
+    const preflight = await lookup(hostname, { all: true, verbatim: true });
+    if (!preflight.length || preflight.some((address) => isBlockedAddress(address.address))) {
+        throw egressError();
+    }
+
+    const dispatcher = new Agent({ connect: { lookup: pinnedLookup } });
+    try {
+        const response = await undiciFetch(target, {
+            method: options?.method,
+            // Flattened to entries: jose's `Headers` is a nominally different
+            // type from undici's, but both accept `[name, value][]`.
+            headers: options?.headers ? [...options.headers] : undefined,
+            signal: options?.signal ?? undefined,
+            redirect: "error",
+            dispatcher,
+        });
+        return response as unknown as Response;
+    } finally {
+        if (typeof dispatcher.close === "function") void dispatcher.close().catch(() => undefined);
+    }
+};

package/src/lib/config.ts

@@ -160,6 +160,18 @@ type AgentBehavior<
     onStreamFinish?: (result: { messages: ChatMessage[]; isAborted: boolean }) => void;
 };
 
+/**
+ * Agent-level end-user JWT verification. When set, identity on that agent's
+ * routes comes only from tokens this issuer signed (or cc playground tokens);
+ * the server-level `auth`/anonymous fallback no longer applies there.
+ */
+type AgentAuthConfig = {
+    jwksUri: string;
+    issuer: string;
+    /** When set, the token's `aud` must contain it. */
+    audience?: string;
+};
+
 /**
  * An agent as authored. Providers are optional because an unset one inherits
  * from server level; `null` on knowledge means "opt out entirely" rather than
@@ -171,6 +183,7 @@ export type CortexAgentDefinition<
     TRequestContext extends Record<string, unknown> = Record<string, unknown>,
 > = AgentBehavior<TSession, TRequestContext> &
     Partial<ProviderConfig> & {
+        auth?: AgentAuthConfig;
         knowledge?: KnowledgeConfig | null;
         context?: Partial<ContextConfig>;
     };
@@ -186,6 +199,7 @@ export type ResolvedCortexAgentConfig = AgentBehavior<
 > &
     ProviderConfig & {
         agentId: string;
+        auth?: AgentAuthConfig;
         db: DatabaseAdapter;
         storage?: StorageAdapter;
         controlCenter?: ControlCenterConfig;

package/src/lib/factory.ts

@@ -4,7 +4,7 @@ import type { CortexConfig, ResolvedCortexAgentConfig } from "./config";
 import { DEFAULT_CONTEXT_CONFIG } from "./ai/context/types";
 import type { ContextConfig } from "./ai/context/types";
 import type { AppEnv, CortexAppEnv } from "./types";
-import { createUserLoaderMiddleware } from "./auth/middleware";
+import { createUserLoaderMiddleware, resolveAgentUser } from "./auth/middleware";
 import { createThreadRoutes } from "./routes/threads";
 import { createChatRoutes } from "./routes/chat";
 import { createFileRoutes } from "./routes/files";
@@ -63,9 +63,6 @@ export function createCortex(config: CortexConfig) {
             const userLoader = createUserLoaderMiddleware(config.auth, config.controlCenter);
             app.use("*", userLoader);
 
-            // Compatibility WebSocket route
-            app.route("/", createWsRoute());
-
             // Agent-scoped routes
             const agentApp = new Hono<CortexAppEnv>();
 
@@ -75,9 +72,13 @@ export function createCortex(config: CortexConfig) {
                 // Control Center: existence is checked against it (ETag-cached, so
                 // usually a 304), which makes publishing there the only allowlist.
                 let agentDef = config.agents?.[agentId];
+                let ccAuth: ResolvedCortexAgentConfig["auth"];
                 if (!agentDef && ccClient && AGENT_SLUG_PATTERN.test(agentId)) {
                     const ccConfig = await getControlCenterConfig(ccClient, agentId);
-                    if (ccConfig) agentDef = {};
+                    if (ccConfig) {
+                        agentDef = {};
+                        ccAuth = ccConfig.auth;
+                    }
                 }
                 if (!agentDef) return c.json({ error: "Agent not found" }, 404);
 
@@ -89,6 +90,7 @@ export function createCortex(config: CortexConfig) {
 
                 const resolvedConfig: ResolvedCortexAgentConfig = {
                     agentId,
+                    auth: agentDef.auth ?? ccAuth,
                     db,
                     storage,
                     model: agentDef.model ?? config.model,
@@ -114,13 +116,26 @@ export function createCortex(config: CortexConfig) {
 
                 c.set("agentConfig", resolvedConfig);
                 c.set("agentId", agentId);
+
+                if (resolvedConfig.auth) {
+                    const user = await resolveAgentUser(
+                        c.req.raw,
+                        resolvedConfig.auth,
+                        config.controlCenter,
+                    );
+                    // CortexAppEnv only promises a user past requireAuth; an
+                    // unverifiable caller must also clear whatever identity the
+                    // server-level loader derived.
+                    c.set("user", user as { id: string; token: string });
+                }
+
                 await next();
             });
 
             agentApp.route("/", createThreadRoutes());
             agentApp.route("/", createChatRoutes());
             agentApp.route("/", createFileRoutes());
-            agentApp.route("/", createWsRoute({ useAgentParam: true }));
+            agentApp.route("/", createWsRoute());
 
             app.route("/agents/:agentId", agentApp);
 

package/src/lib/routes/threads.ts

@@ -77,7 +77,14 @@ export function createThreadRoutes() {
         const config = c.get("agentConfig");
         const messageId = c.req.param("messageId");
         const requests = await config.db.llmRequests.listByMessageId(messageId);
-        return c.json(requests);
+
+        // Message ids are caller-supplied: the rows only leave through the
+        // caller's own thread on the agent in the path.
+        if (requests[0]) {
+            await requireOwnedThread(c, requests[0].threadId);
+        }
+
+        return c.json(requests.map(({ threadId: _, ...request }) => request));
     });
 
     app.post(

package/src/lib/routes/ws.ts

@@ -3,18 +3,13 @@ import { upgradeWebSocket } from "hono/bun";
 import type { AppEnv } from "@/types";
 import { addConnection, removeConnection } from "@/ws/connections";
 
-type WsRouteOptions = {
-    useAgentParam?: boolean;
-};
-
-export function createWsRoute(options?: WsRouteOptions) {
+export function createWsRoute() {
     const app = new Hono<AppEnv>();
     const handleUpgrade = upgradeWebSocket(function (c) {
         // upgradeWebSocket erases the app's env generic, so the context reads as any.
         const user = c.get("user") as AppEnv["Variables"]["user"];
         const userId = user?.id;
-        const agentId =
-            options?.useAgentParam === true ? c.req.param("agentId") : c.req.query("agentId");
+        const agentId = c.req.param("agentId");
 
         return {
             onOpen(_, ws) {
@@ -36,8 +31,7 @@ export function createWsRoute(options?: WsRouteOptions) {
             return c.json({ error: "Unauthorized" }, 401);
         }
 
-        const agentId =
-            options?.useAgentParam === true ? c.req.param("agentId") : c.req.query("agentId");
+        const agentId = c.req.param("agentId");
         if (!agentId) {
             return c.json({ error: "agentId is required" }, 400);
         }