@mercury-fw/channel-http 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @mercury-fw/channel-http
 
+## 0.3.0
+
+### Minor Changes
+
+- 8d3e5af: Authentication for the HTTP surface.
+
+  - An app declares an auth provider as `auth` in `mercury.config.ts`. The core builds it and hands channels `ctx.authenticate`. A provider that fails to load leaves the channel without it, so the surface stays closed.
+  - New contract in `@mercury-fw/channel-types`: `AuthPlugin`, `AUTH_API_VERSION` and `Authenticate`. `PrincipalProvider` gains `oidc` and `static`.
+  - New package `@mercury-fw/auth-oidc` verifies an OpenID Connect bearer token against the issuer's keys and checks `iss`, `aud` and expiry. It reads `OIDC_ISSUER` and `OIDC_AUDIENCE`.
+  - New package `@mercury-fw/auth-static` maps fixed test tokens from `AUTH_STATIC_TOKENS` to users, for test apps and e2e tests.
+  - Breaking, `@mercury-fw/channel-http`: the channel doesn't start without an auth provider.
+  - `@mercury-fw/channel-http`: every route except `GET /openapi.yaml` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and a missing or refused token gets `401` before anything runs.
+  - Breaking, `@mercury-fw/channel-http`: a conversation belongs to whoever opened it. The session key is `<caller id>:<conversationId>`, so the same id from someone else is a conversation of their own. Existing HTTP conversations stay readable but can't be continued.
+  - `@mercury-fw/channel-http`: a confirmation token is checked against the caller's own session, so it can't be confirmed from someone else's.
+  - `@mercury-fw/channel-http`: authenticated callers get their own episodic memory and wiki area.
+  - `@mercury-fw/channel-http`: the read routes (`/conversations`, `/conversation`, `/wiki/*`, `/memory/scroll`, `/tool-log`, `/confirmations`) need an authenticated caller, but still show every person's data. Scoping them per person comes next, so don't give the surface to people who shouldn't see each other's conversations yet. Confirmation tokens are never listed.
+  - The HTTP `tool` event carries the name of the tool the model called. `TurnSink.onToolStart` gets it as an optional fourth argument.
+  - `mfw create` pairs the HTTP channel with an auth provider: `--auth oidc|static`, which the wizard asks for once HTTP is chosen.
+  - `mfw e2e` runs cases on the HTTP surface (`channel: "http"`) as one of the test's `users`, each a token the app accepts. A turn can name its own user, and it reports the response's status.
+  - `mfw create --local-packages <folder>` makes an app on packed tarballs, as `mfw local-packages` does on an existing one. Versions come from the tarballs, so a package that isn't published yet works too.
+
+## 0.2.0
+
+### Minor Changes
+
+- 8bed46b: - A turn carries a `Principal` (the person behind it and the provider that vouched for them) instead of the opaque `userId` and `wikiUserId`; the core derives every per-person id from it.
+  - Episodic memory follows the principal, not the channel: a session is captured whenever a provider vouched for the person. Google Chat keeps the ids it had; the terminal and the HTTP channel (until it authenticates its callers) send a principal nobody vouched for, so they stay out of episodic memory as before.
+  - The HTTP channel accepts a `conversationId` on `/turn` and `/confirm` only made of letters, digits, `-` and `_`, up to 128 characters once trimmed, and answers `400` otherwise: a client-chosen id can no longer reach another user's wiki notes, forge log lines or break the turn. An existing HTTP conversation whose id has other characters can still be read with `/conversation`, but not continued. `/conversation` keeps opening any session key `/conversations` lists, whatever channel it came from.
+  - The model's wiki read tools refuse a per-user id that isn't one path segment, as writes already did.
+  - `CHANNEL_API_VERSION` is 2: a channel written for version 1 is refused at load.
+  - The first-party channels declare their channel api version as a literal, so an older channel can't claim a newer contract it doesn't implement.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -8,10 +8,14 @@ bun add @mercury-fw/channel-http
 
 ```ts
 import { httpChannel } from "@mercury-fw/channel-http";
+import { oidcAuth } from "@mercury-fw/auth-oidc";
 
 channels: [httpChannel],
+auth: oidcAuth,
 ```
 
+It needs an auth provider next to it: [`@mercury-fw/auth-oidc`](../../auth/auth-oidc) for real users, [`@mercury-fw/auth-static`](../../auth/auth-static) for the test bed and e2e tests. Without one, or with one that fails to load, the channel doesn't start and the log says why.
+
 | Variable | |
 |---|---|
 | `HTTP_SURFACE_PORT` | The port (default `4100`). |
@@ -19,13 +23,17 @@ channels: [httpChannel],
 
 ## API
 
-It's active whenever it's declared in `mercury.config.ts`'s `channels`; remove it there to turn the surface off. It listens on `HTTP_SURFACE_PORT` (default `4100`). **No authentication** — do not publish the port outside the container network (same posture as the admin panel). Base URL `http://<host>:<port>`.
+It's active whenever it's declared in `mercury.config.ts`'s `channels` with an auth provider; remove it there to turn the surface off. It listens on `HTTP_SURFACE_PORT` (default `4100`). Base URL `http://<host>:<port>`.
+
+**Authentication.** Every route except `GET /openapi.yaml` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and the auth provider decides who the token belongs to. A missing or refused token gets `401` with `WWW-Authenticate: Bearer` before anything runs.
+
+**Conversations belong to whoever opened them.** The session key is `<caller id>:<conversationId>`, so the same `conversationId` sent by someone else is a conversation of their own, and a confirmation token staged in your conversation can't be confirmed from theirs. Each authenticated caller also gets their own episodic memory and wiki area, as on Google Chat.
 
-**CORS** is enabled on every response and every route answers an `OPTIONS` preflight, so a browser UI on another origin can call it. The allowed origin is `HTTP_SURFACE_CORS_ORIGIN` (default `*`; no credentials are used).
+**CORS** is enabled on every response and every route answers an `OPTIONS` preflight, so a browser UI on another origin can call it. The allowed origin is `HTTP_SURFACE_CORS_ORIGIN` (default `*`: the token travels in a header, never in a cookie the browser would send on its own).
 
 The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as a rendered docs page on GitHub Pages (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
 
-All responses are JSON except `POST /turn`, which streams `text/event-stream`. Every JSON response is either `{ "ok": true, ... }` or, on error, `{ "ok": false, "error": "<message>" }` with HTTP `400`/`500`.
+All responses are JSON except `POST /turn`, which streams `text/event-stream`. Every JSON response is either `{ "ok": true, ... }` or, on error, `{ "ok": false, "error": "<message>" }` with HTTP `400`/`401`/`500`.
 
 ## `POST /turn`
 
@@ -36,9 +44,9 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 | field | type | required | description |
 |---|---|---|---|
 | `text` | string | yes | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
-| `conversationId` | string | no | Opaque, client-owned id that continues a conversation. Omitted ⇒ a fresh one-off session. |
+| `conversationId` | string | no | Opaque, client-owned id that continues one of your conversations: letters, digits, `-` and `_`, up to 128 characters (a UUID fits) once surrounding whitespace is trimmed, `400` otherwise. Omitted ⇒ a fresh one-off session. |
 
-**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing or the body isn't JSON.
+**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing, the body isn't JSON, or `conversationId` has other characters than the ones above.
 
 Reasoning and answer text arrive as **incremental deltas** — never one finished block — so a UI renders them live; treat the `final` event as the authoritative text. **To cancel** a turn (e.g. a generation that's diverging), close the connection: Mercury aborts the in-flight generation.
 
@@ -48,7 +56,7 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 |---|---|---|
 | `reasoning` | `{ chunk, id }` | a model reasoning delta |
 | `reasoning_end` | `{ id, failed }` | a reasoning block ends |
-| `tool` | `{ label, detail, toolCallId }` | a tool call starts |
+| `tool` | `{ label, detail, toolCallId, name }` | a tool call starts; `name` is the tool the model called, absent when Mercury is saving something to memory |
 | `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
 | `text` | `{ chunk }` | an answer-text delta |
 | `pending` | `{ command, token }` | a confirm-required action was staged; send `token` back to confirm it — as a later `/turn` `text`, or via `POST /confirm` |
@@ -58,20 +66,21 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 ```bash
 curl -N -X POST http://localhost:4100/turn \
   -H 'content-type: application/json' \
+  -H "authorization: Bearer $TOKEN" \
   -d '{"text":"Quante issue nel progetto KAN?","conversationId":"c1"}'
 ```
 
 ## `POST /confirm`
 
-Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation, `{ ok: true, resolved: false }` otherwise. `400` if `token` or `conversationId` is missing. Never invokes the model.
+Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation, `{ ok: true, resolved: false }` otherwise. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.
 
 ## Read-only introspection
 
-All `GET`, all JSON, all reporting state already held in-process.
+All `GET`, all JSON, all reporting state already held in-process. They need an authenticated caller, but each one still shows every person's data: scoping them per person is the next step.
 
 | endpoint | `data` on success |
 |---|---|
-| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing |
+| `GET /conversation?id=<sessionKey>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing. Any session key `/conversations` lists opens here, whatever channel it came from |
 | `GET /conversations?limit=<n>` | `{ conversations: [{ sessionKey, lastTimestamp, preview }] }` — known conversations, most-recently-active first |
 | `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
 | `GET /confirmations` | `{ pending: [{ sessionKey, binary, args, expiresAt }] }` — tokens are deliberately never included |

package/dist/http-provider.d.ts

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Provider, ChannelHostReads } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, ChannelHostReads } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -19,6 +19,8 @@ export type HttpProviderDeps = {
     /** Structured resolver for the `/confirm` endpoint's `resolved` flag. */
     resolveConfirmation: ResolveConfirmationFn;
     reads?: ChannelHostReads;
+    /** Who is calling, from the app's auth provider. */
+    authenticate: Authenticate;
     /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
     corsOrigin?: string;
 };

package/dist/http-server.d.ts

@@ -12,18 +12,22 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * No auth by design — this surface is opt-in (enabled by listing this channel in
- * `mercury.config.ts`) and must not be reachable from outside the container
- * network, the same posture as the admin panel. Confirm resolution is injected
- * (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ * Every route but the OpenAPI document and the CORS preflights asks the
+ * injected `authenticate` (the auth provider the app declares) who is calling
+ * before anything runs, and answers 401 when nobody is. A conversation belongs
+ * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
+ * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
+ * package never imports the app.
  */
-import { type HandleTurn, type ChannelHostReads, type ConfirmOutcome } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome } from "@mercury-fw/channel-types";
 /** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = (token: string, sessionKey: string, userId: string) => Promise<string | null>;
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
 export type ResolveConfirmationFn = (token: string, sessionKey: string, userId: string) => Promise<ConfirmOutcome>;
 export type TurnRequestDeps = {
     handleTurn: HandleTurn;
+    /** Who is calling, injected from the app's auth provider; `null` = refused. */
+    authenticate: Authenticate;
     /** Bare-token interception before the model, injected by the core. */
     confirm: ConfirmFn;
     /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
@@ -33,31 +37,35 @@ export type TurnRequestDeps = {
 };
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
  * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
  * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
 export declare function openApiResponse(corsOrigin?: string): Response;
 /**
- * Runs one `POST /turn` request and returns an SSE stream Response. The body is
- * `{ text, conversationId? }`; `conversationId` (opaque, client-owned) becomes
- * the session key so a client can continue a conversation — Mercury already
- * keys its histories by session, so many conversations run concurrently, each
+ * Runs one `POST /turn` request and returns an SSE stream Response. The caller
+ * is authenticated first. The body is `{ text, conversationId? }`;
+ * `conversationId` (opaque, client-owned) continues one of the caller's
+ * conversations: the session key is `<principal.id>:<conversationId>`, so the
+ * same id from someone else is a session of their own. Mercury keys its
+ * histories by session, so many conversations run concurrently, each
  * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
- * session. Never throws: a bad body is a 400, a mid-turn failure is an `error`
- * event on the stream.
+ * session. Never throws: a refused caller is a 401, a bad body a 400, a
+ * mid-turn failure an `error` event on the stream.
  */
 export declare function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response>;
 export type ConfirmRequestDeps = {
+    authenticate: Authenticate;
     resolveConfirmation: ResolveConfirmationFn;
     corsOrigin?: string;
 };
 /**
  * `POST /confirm { token, conversationId }` — the explicit confirmation
  * endpoint. A nicer contract for a UI than re-POSTing the bare token as `text`
- * to `/turn`, but the exact same mechanism underneath: it resolves the token
- * through the injected `resolveConfirmation`, keyed on
- * `conversationId` as the session. `resolved: true` means the token matched a
+ * to `/turn`, but the exact same mechanism underneath: it authenticates the
+ * caller and resolves the token through the injected `resolveConfirmation`,
+ * keyed on the caller's own session (`<principal.id>:<conversationId>`), so a
+ * token staged in someone else's conversation is never found. `resolved: true` means the token matched a
  * pending confirmation and its staged action was consumed and run; the `text`
  * then reports whether that execution succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
@@ -72,10 +80,12 @@ type ReadRoute = {
 /**
  * Builds the read-only routes, each carrying CORS headers on its `GET` and a
  * shared `OPTIONS` preflight so a browser UI on `corsOrigin` (default `*`) can
- * reach them. `jsonRoute` wraps a getter into a `GET` that always JSON-encodes
- * with the CORS headers merged in; `badRequest` does the same for a 400.
+ * reach them. Every `GET` asks `authenticate` first and answers 401 without
+ * calling its getter when nobody is calling; the preflight doesn't ask.
+ * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
+ * same for a 400.
  */
-export declare function readRoutes(reads: ChannelHostReads, corsOrigin?: string): Record<string, ReadRoute>;
+export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string): Record<string, ReadRoute>;
 export type HttpServerDeps = TurnRequestDeps & {
     port: number;
     reads?: ChannelHostReads;

package/dist/index.d.ts

@@ -7,10 +7,11 @@
  * declared, it starts.
  *
  * `build` reads its port and CORS origin from `env` and takes the confirm
- * capabilities and in-process reads from the injected context (dependency
- * inversion). Those two are optional on the contract but required here, so a
- * context missing them throws — the loader isolates it fail-soft.
+ * capabilities, the in-process reads and the app's auth provider from the
+ * injected context (dependency inversion). Those are optional on the contract
+ * but required here, so a context missing them throws — the loader isolates it
+ * fail-soft, and without an auth provider the surface never opens.
  */
-import { type ChannelPlugin } from "@mercury-fw/channel-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 export declare const httpChannel: ChannelPlugin;

package/http-provider.ts

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { startHttpServer, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -20,6 +20,8 @@ export type HttpProviderDeps = {
   /** Structured resolver for the `/confirm` endpoint's `resolved` flag. */
   resolveConfirmation: ResolveConfirmationFn;
   reads?: ChannelHostReads;
+  /** Who is calling, from the app's auth provider. */
+  authenticate: Authenticate;
   /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
   corsOrigin?: string;
 };
@@ -34,6 +36,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         confirm: deps.confirm,
         resolveConfirmation: deps.resolveConfirmation,
         reads: deps.reads,
+        authenticate: deps.authenticate,
         corsOrigin: deps.corsOrigin,
       });
     },

package/http-server.ts

@@ -12,20 +12,36 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * No auth by design — this surface is opt-in (enabled by listing this channel in
- * `mercury.config.ts`) and must not be reachable from outside the container
- * network, the same posture as the admin panel. Confirm resolution is injected
- * (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ * Every route but the OpenAPI document and the CORS preflights asks the
+ * injected `authenticate` (the auth provider the app declares) who is calling
+ * before anything runs, and answers 401 when nobody is. A conversation belongs
+ * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
+ * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
+ * package never imports the app.
  */
 import {
   detectPendingConfirmation,
   PENDING_CONFIRMATION_NOTE,
   type HandleTurn,
   type TurnSink,
+  type Authenticate,
   type ChannelHostReads,
   type ConfirmOutcome,
 } from "@mercury-fw/channel-types";
 
+/**
+ * A client's conversation id becomes part of the session key and the log
+ * prefix, so only letters, digits, `-` and `_` get in: no path segments, no
+ * line breaks, nothing to encode, and no `:`, which separates it from the
+ * caller's id in the session key.
+ */
+const CONVERSATION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** `text` with every control character (line breaks included) as `?`, for a log line nobody can forge. */
+function forLog(text: string): string {
+  return text.replace(/[\u0000-\u001f\u007f]/g, "?");
+}
+
 /** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = (token: string, sessionKey: string, userId: string) => Promise<string | null>;
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -33,6 +49,8 @@ export type ResolveConfirmationFn = (token: string, sessionKey: string, userId:
 
 export type TurnRequestDeps = {
   handleTurn: HandleTurn;
+  /** Who is calling, injected from the app's auth provider; `null` = refused. */
+  authenticate: Authenticate;
   /** Bare-token interception before the model, injected by the core. */
   confirm: ConfirmFn;
   /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
@@ -50,17 +68,27 @@ const SSE_HEADERS = {
 /**
  * The CORS headers echoed on every response so a browser UI served from a
  * different origin (the separate custom-UI project) can call this surface.
- * No credentials are ever used here, so a wildcard origin is safe; a specific
- * origin can still be pinned via `HTTP_SURFACE_CORS_ORIGIN`.
+ * The caller's token travels in an explicit `Authorization` header, never in a
+ * cookie the browser would attach on its own, so a wildcard origin is safe: a
+ * page on another origin can't borrow anyone's credentials. A specific origin
+ * can still be pinned via `HTTP_SURFACE_CORS_ORIGIN`.
  */
 function corsHeaders(origin: string): Record<string, string> {
   return {
     "access-control-allow-origin": origin,
     "access-control-allow-methods": "GET, POST, OPTIONS",
-    "access-control-allow-headers": "content-type",
+    "access-control-allow-headers": "content-type, authorization",
   };
 }
 
+/** 401 for a caller the auth provider refused, with the Bearer challenge and CORS headers (so a browser UI can read it). */
+function unauthorized(origin: string): Response {
+  return Response.json(
+    { ok: false, error: "unauthorized" },
+    { status: 401, headers: { ...corsHeaders(origin), "www-authenticate": "Bearer" } },
+  );
+}
+
 /** 204 preflight response for an `OPTIONS` request, carrying only CORS headers. */
 function preflight(origin: string): Response {
   return new Response(null, { status: 204, headers: corsHeaders(origin) });
@@ -68,7 +96,7 @@ function preflight(origin: string): Response {
 
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
  * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
  * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
@@ -80,17 +108,21 @@ export function openApiResponse(corsOrigin = "*"): Response {
 }
 
 /**
- * Runs one `POST /turn` request and returns an SSE stream Response. The body is
- * `{ text, conversationId? }`; `conversationId` (opaque, client-owned) becomes
- * the session key so a client can continue a conversation — Mercury already
- * keys its histories by session, so many conversations run concurrently, each
+ * Runs one `POST /turn` request and returns an SSE stream Response. The caller
+ * is authenticated first. The body is `{ text, conversationId? }`;
+ * `conversationId` (opaque, client-owned) continues one of the caller's
+ * conversations: the session key is `<principal.id>:<conversationId>`, so the
+ * same id from someone else is a session of their own. Mercury keys its
+ * histories by session, so many conversations run concurrently, each
  * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
- * session. Never throws: a bad body is a 400, a mid-turn failure is an `error`
- * event on the stream.
+ * session. Never throws: a refused caller is a 401, a bad body a 400, a
+ * mid-turn failure an `error` event on the stream.
  */
 export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response> {
   const origin = deps.corsOrigin ?? "*";
   const cors = corsHeaders(origin);
+  const principal = await deps.authenticate(req);
+  if (principal === null) return unauthorized(origin);
   let body: { text?: unknown; conversationId?: unknown };
   try {
     body = (await req.json()) as typeof body;
@@ -101,10 +133,14 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
     return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
   }
   const text = body.text;
-  const sessionKey =
+  const conversationId =
     typeof body.conversationId === "string" && body.conversationId.trim().length > 0
       ? body.conversationId.trim()
       : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
+  if (!CONVERSATION_ID.test(conversationId)) {
+    return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
+  }
+  const sessionKey = `${principal.id}:${conversationId}`;
 
   // Aborted when the client disconnects (see the stream's `cancel` below) so
   // the in-flight turn stops instead of running to completion — the "stop"
@@ -133,7 +169,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
       // Same deterministic interception as every other channel — a
       // previously-approved mutation must never depend on the model.
-      const confirmReply = await deps.confirm(text, sessionKey, sessionKey);
+      const confirmReply = await deps.confirm(text, sessionKey, principal.id);
       if (confirmReply !== null) {
         send("final", { text: confirmReply });
         close();
@@ -141,7 +177,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
       }
 
       const sink: TurnSink = {
-        onToolStart: (label, detail, toolCallId) => send("tool", { label, detail, toolCallId }),
+        onToolStart: (label, detail, toolCallId, toolName) => send("tool", { label, detail, toolCallId, name: toolName }),
         onToolFinish: (toolCallId, outcome) => send("tool_finish", { toolCallId, outcome }),
         onTextChunk: (chunk) => {
           if (chunk !== PENDING_CONFIRMATION_NOTE) send("text", { chunk });
@@ -164,8 +200,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             multiUser: false,
             text,
             sessionKey,
-            wikiUserId: sessionKey,
-            logPrefix: `[http:${sessionKey}] `,
+            principal,
+            // The caller's id comes from the auth provider, unchecked here.
+            logPrefix: `[http:${forLog(sessionKey)}] `,
             abortSignal: abort.signal,
           },
           sink,
@@ -190,6 +227,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 }
 
 export type ConfirmRequestDeps = {
+  authenticate: Authenticate;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
 };
@@ -197,16 +235,20 @@ export type ConfirmRequestDeps = {
 /**
  * `POST /confirm { token, conversationId }` — the explicit confirmation
  * endpoint. A nicer contract for a UI than re-POSTing the bare token as `text`
- * to `/turn`, but the exact same mechanism underneath: it resolves the token
- * through the injected `resolveConfirmation`, keyed on
- * `conversationId` as the session. `resolved: true` means the token matched a
+ * to `/turn`, but the exact same mechanism underneath: it authenticates the
+ * caller and resolves the token through the injected `resolveConfirmation`,
+ * keyed on the caller's own session (`<principal.id>:<conversationId>`), so a
+ * token staged in someone else's conversation is never found. `resolved: true` means the token matched a
  * pending confirmation and its staged action was consumed and run; the `text`
  * then reports whether that execution succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
  * even token-shaped). Never touches the model.
  */
 export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response> {
-  const cors = corsHeaders(deps.corsOrigin ?? "*");
+  const origin = deps.corsOrigin ?? "*";
+  const cors = corsHeaders(origin);
+  const principal = await deps.authenticate(req);
+  if (principal === null) return unauthorized(origin);
   let body: { token?: unknown; conversationId?: unknown };
   try {
     body = (await req.json()) as typeof body;
@@ -214,11 +256,14 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
     return Response.json({ ok: false, error: "body must be JSON" }, { status: 400, headers: cors });
   }
   const token = typeof body.token === "string" ? body.token.trim() : "";
-  const sessionKey = typeof body.conversationId === "string" ? body.conversationId.trim() : "";
-  if (token.length === 0 || sessionKey.length === 0) {
+  const conversationId = typeof body.conversationId === "string" ? body.conversationId.trim() : "";
+  if (token.length === 0 || conversationId.length === 0) {
     return Response.json({ ok: false, error: "missing token or conversationId" }, { status: 400, headers: cors });
   }
-  const outcome = await deps.resolveConfirmation(token, sessionKey, sessionKey);
+  if (!CONVERSATION_ID.test(conversationId)) {
+    return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
+  }
+  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal.id);
   switch (outcome.status) {
     case "not-a-token":
     case "not-found":
@@ -239,17 +284,22 @@ type ReadRoute = {
 /**
  * Builds the read-only routes, each carrying CORS headers on its `GET` and a
  * shared `OPTIONS` preflight so a browser UI on `corsOrigin` (default `*`) can
- * reach them. `jsonRoute` wraps a getter into a `GET` that always JSON-encodes
- * with the CORS headers merged in; `badRequest` does the same for a 400.
+ * reach them. Every `GET` asks `authenticate` first and answers 401 without
+ * calling its getter when nobody is calling; the preflight doesn't ask.
+ * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
+ * same for a 400.
  */
-export function readRoutes(reads: ChannelHostReads, corsOrigin = "*"): Record<string, ReadRoute> {
+export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin = "*"): Record<string, ReadRoute> {
   const cors = corsHeaders(corsOrigin);
   const json = (payload: object, status = 200): Response =>
     Response.json(payload, { status, headers: cors });
   const badRequest = (message: string): Response => json({ ok: false, error: message }, 400);
   const requireParam = (req: Request, name: string): string | null => new URL(req.url).searchParams.get(name);
   const options = () => preflight(corsOrigin);
-  const route = (GET: ReadRoute["GET"]): ReadRoute => ({ GET, OPTIONS: options });
+  const route = (GET: ReadRoute["GET"]): ReadRoute => ({
+    GET: async (req) => ((await authenticate(req)) === null ? unauthorized(corsOrigin) : GET(req)),
+    OPTIONS: options,
+  });
   return {
     "/manifest": route(() => json({ ok: true, manifest: reads.manifest() })),
     "/confirmations": route(() => json({ ok: true, pending: reads.pendingConfirmations() })),
@@ -314,11 +364,12 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
     routes: {
       "/turn": { POST: (req) => handleTurnRequest(req, deps), OPTIONS: () => preflight(origin) },
       "/confirm": {
-        POST: (req) => handleConfirmRequest(req, { resolveConfirmation: deps.resolveConfirmation, corsOrigin: origin }),
+        POST: (req) =>
+          handleConfirmRequest(req, { authenticate: deps.authenticate, resolveConfirmation: deps.resolveConfirmation, corsOrigin: origin }),
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
-      ...(deps.reads ? readRoutes(deps.reads, origin) : {}),
+      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin) : {}),
     },
     error: (err) =>
       Response.json(

package/index.ts

@@ -7,28 +7,35 @@
  * declared, it starts.
  *
  * `build` reads its port and CORS origin from `env` and takes the confirm
- * capabilities and in-process reads from the injected context (dependency
- * inversion). Those two are optional on the contract but required here, so a
- * context missing them throws — the loader isolates it fail-soft.
+ * capabilities, the in-process reads and the app's auth provider from the
+ * injected context (dependency inversion). Those are optional on the contract
+ * but required here, so a context missing them throws — the loader isolates it
+ * fail-soft, and without an auth provider the surface never opens.
  */
-import { CHANNEL_API_VERSION, type ChannelPlugin } from "@mercury-fw/channel-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import { createHttpProvider } from "./http-provider.ts";
 
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 
 export const httpChannel: ChannelPlugin = {
-  apiVersion: CHANNEL_API_VERSION,
+  // The contract this channel is written for, as a literal: importing
+  // CHANNEL_API_VERSION would report whichever contract is installed.
+  apiVersion: 2,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {
       throw new Error("http channel requires the resolveConfirmation and reads capabilities on the runtime context");
     }
+    if (!ctx.authenticate) {
+      throw new Error("http channel requires an auth provider (auth in mercury.config.ts)");
+    }
     return createHttpProvider({
       port: Number(ctx.env.HTTP_SURFACE_PORT ?? "4100"),
       corsOrigin: ctx.env.HTTP_SURFACE_CORS_ORIGIN ?? "*",
       confirm: ctx.confirm,
       resolveConfirmation: ctx.resolveConfirmation,
       reads: ctx.reads,
+      authenticate: ctx.authenticate,
     });
   },
 };

package/openapi.yaml

@@ -5,19 +5,30 @@ info:
   description: >
     The HTTP surface of Mercury — the intended primary channel for a
     custom web UI. It is enabled by declaring the `http` channel in
-    `mercury.config.ts` and, by design,
-    carries **no authentication**: it must not be published outside the trusted
-    container network (production simply does not expose the port). CORS is
+    `mercury.config.ts`, together with an auth provider (`auth`): without one
+    the surface doesn't start. CORS is
     enabled on every response (`Access-Control-Allow-Origin`, configurable via
     `HTTP_SURFACE_CORS_ORIGIN`, default `*`) and every route answers an `OPTIONS`
     preflight, so a browser UI on another origin can call it.
 
 
+    ## Authentication
+
+    Every route except this document and the `OPTIONS` preflights needs
+    `Authorization: Bearer <token>`. The app's auth provider decides what a
+    valid token is (an OpenID Connect access token, a static test token); a
+    missing or refused one gets `401` with `WWW-Authenticate: Bearer`, before
+    anything runs.
+
+
     ## Conversations
 
-    A conversation is identified by an opaque, client-owned `conversationId`,
-    which becomes Mercury's session key. Omitting it on `POST /turn` starts a
-    fresh ephemeral conversation. The durable transcript of a conversation is
+    A conversation is identified by an opaque, client-owned `conversationId`
+    and belongs to whoever opened it: Mercury's session key is
+    `<caller id>:<conversationId>`, so the same id sent by someone else is a
+    conversation of their own, and a confirmation token staged in one person's
+    conversation is never found from another's. Omitting `conversationId` on
+    `POST /turn` starts a fresh ephemeral conversation. The durable transcript of a conversation is
     readable via `GET /conversation`, and the list of known conversations via
     `GET /conversations` (both backed by the verbatim archive; they degrade to
     empty when the vector store is unreachable).
@@ -38,6 +49,8 @@ info:
     emits a `pending` event carrying a one-time `token`. The client confirms by
     sending that token back — either as the `text` of a follow-up `POST /turn`,
     or via `POST /confirm`.
+security:
+  - bearerAuth: []
 servers:
   - url: http://localhost:4100
     description: Local/dev surface (HTTP_SURFACE_PORT, default 4100)
@@ -57,6 +70,8 @@ paths:
             schema:
               $ref: "#/components/schemas/TurnRequest"
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: >
             An SSE stream. Each event is one of the types in `TurnEvent`:
@@ -69,7 +84,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/TurnEvent"
         "400":
-          description: Missing/invalid body.
+          description: Missing/invalid body, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -79,8 +94,8 @@ paths:
       summary: Confirm a staged irreversible action
       description: >
         Runs a one-time confirmation token through the same mechanism the
-        bare-token-in-`text` path uses, keyed on `conversationId`. Never touches
-        the model.
+        bare-token-in-`text` path uses, keyed on the caller's own conversation
+        (`<caller id>:<conversationId>`). Never touches the model.
       requestBody:
         required: true
         content:
@@ -88,6 +103,8 @@ paths:
             schema:
               $ref: "#/components/schemas/ConfirmRequest"
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: >
             `resolved: true` (with the reply `text`) when the token was a pending
@@ -98,7 +115,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ConfirmResult"
         "400":
-          description: Missing token or conversationId.
+          description: Missing token or conversationId, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -110,7 +127,7 @@ paths:
         - name: id
           in: query
           required: true
-          description: The conversationId (session key) whose messages to return.
+          description: The session key whose messages to return, as `/conversations` lists it (any channel's; an HTTP one is `<caller id>:<conversationId>`).
           schema:
             type: string
         - name: limit
@@ -126,6 +143,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: The conversation's messages in chronological order.
           content:
@@ -149,6 +168,8 @@ paths:
             type: integer
             default: 50
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: The conversation list.
           content:
@@ -159,6 +180,8 @@ paths:
     get:
       summary: Liveness/health of Mercury and its dependencies
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Health snapshot.
           content:
@@ -169,6 +192,8 @@ paths:
     get:
       summary: The loaded plugins, tools and skills
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Plugin manifest.
           content:
@@ -179,6 +204,8 @@ paths:
     get:
       summary: Currently pending confirmations (tokens redacted)
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Pending confirmations.
           content:
@@ -189,6 +216,8 @@ paths:
     get:
       summary: Recent tool-call log entries
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Tool log.
           content:
@@ -199,6 +228,8 @@ paths:
     get:
       summary: List the wiki vault's files
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: File list.
           content:
@@ -215,6 +246,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: File content.
           content:
@@ -238,6 +271,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Matches.
           content:
@@ -271,6 +306,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: A page of points.
           content:
@@ -286,6 +323,7 @@ paths:
   /openapi.yaml:
     get:
       summary: This OpenAPI document
+      security: []
       responses:
         "200":
           description: The raw OpenAPI YAML.
@@ -294,6 +332,25 @@ paths:
               schema:
                 type: string
 components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: A token the app's auth provider accepts.
+  responses:
+    Unauthorized:
+      description: >
+        No `Authorization` header, or a token the auth provider refused.
+        Carries `WWW-Authenticate: Bearer`.
+      headers:
+        WWW-Authenticate:
+          schema:
+            type: string
+            enum: [Bearer]
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
   schemas:
     TurnRequest:
       type: object
@@ -304,7 +361,8 @@ components:
           description: The user's message, or a bare confirmation token.
         conversationId:
           type: string
-          description: Opaque, client-owned. Omit to start a fresh ephemeral conversation.
+          pattern: "^[A-Za-z0-9_-]{1,128}$"
+          description: Opaque, client-owned; letters, digits, `-` and `_` (a UUID fits). Omit to start a fresh ephemeral conversation.
     TurnEvent:
       type: object
       description: The shape carried by each SSE `data:` line, per event type.
@@ -324,6 +382,9 @@ components:
         detail:
           type: string
           description: On `tool` — optional detail.
+        name:
+          type: string
+          description: On `tool` — the tool the model called (e.g. `jiraCommand`); absent for Mercury's own memory notes.
         toolCallId:
           type: string
           description: On `tool`/`tool_finish`.
@@ -350,6 +411,7 @@ components:
           type: string
         conversationId:
           type: string
+          pattern: "^[A-Za-z0-9_-]{1,128}$"
     ConfirmResult:
       type: object
       required: [ok, resolved]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.35.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.31.1",
-    "@mercury-fw/plugin-types": "0.31.1",
+    "@mercury-fw/channel-types": "0.35.0",
+    "@mercury-fw/plugin-types": "0.35.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"