@mercury-fw/channel-http 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @mercury-fw/channel-http
 
+## 0.4.0
+
+### Minor Changes
+
+- 521db42: Isolation between the people an agent talks to.
+
+  - The core keeps one identity per person, `<provider>:<id>`, so two providers issuing the same id are two people. Memory, the conversation archive, the tool log and pending confirmations are keyed on it.
+  - The wiki has a common area (`curated/`) everyone reads and an area per person (`users/<key>/`), which the model sees as `personal/`. Listing, reading and grepping reach the common area and the caller's own area, nothing else.
+  - Breaking: the model's `write_file` writes only under `personal/notes/`. The new `promote_note` tool copies one of the person's notes into `curated/`, and only once they confirm it with the token.
+  - A confirmation can only be confirmed by whoever staged it, in the same session. Its note is written once, in the person's area: a staged note no longer stays "pending" after it's resolved, for ids such as Google Chat's `users/<n>`.
+  - Breaking, `@mercury-fw/channel-types`: channel contract 3. `confirm` and `resolveConfirmation` take the caller's `Principal`, and so does every read getter except `manifest` and `health`. Channels written for contract 2 are refused.
+  - `@mercury-fw/confirm-engine`: the store's `stage`, `take` and `pending` take the owner's key.
+  - Breaking, `@mercury-fw/channel-http`: every read route returns only the caller's data. `/conversation?id=` takes one of the caller's `conversationId`s and `/conversations` lists them by `conversationId`. `/wiki/read` answers `404` outside what the caller can see, and `/memory/scroll` answers `400` for a collection that isn't kept per person.
+  - `@mercury-fw/channel-google-chat`: on channel contract 3.
+  - At startup, an instance's existing data moves to the new layout. Google Chat and terminal notes go into their areas, and Qdrant's ids go onto the new keys. Ids that don't say which provider they came from are left in place and logged.
+  - `mfw vault read` refuses a path outside the vault.
+  - The admin panel's wiki box edits the common area with the operator's tools (list, read, grep, `write_curated`), the same the nightly review uses.
+
+## 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

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,7 +44,7 @@ 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: letters, digits, `-` and `_`, up to 128 characters (a UUID fits) once surrounding whitespace is trimmed, `400` otherwise. 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, the body isn't JSON, or `conversationId` has other characters than the ones above.
 
@@ -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,6 +66,7 @@ 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"}'
 ```
 
@@ -67,20 +76,20 @@ Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, con
 
 ## 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 and show only what belongs to them: their conversations, confirmations, tool calls and memory, and the wiki as they see it (the team's `curated/` plus their own notes as `personal/`). Someone else's data doesn't exist as far as a caller can tell; only `/manifest` and `/health` are the same for everyone.
 
 | 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. 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 /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — one of your conversations, its durable transcript in order (empty for an id that isn't yours); `400` if `id` is missing or has other characters than `/turn` accepts |
+| `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview }] }` — your 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 |
-| `GET /tool-log` | `{ entries: [...] }` |
+| `GET /confirmations` | `{ pending: [{ sessionKey, summary, expiresAt }] }` — your pending confirmations; tokens are deliberately never included |
+| `GET /tool-log` | `{ entries: [...] }` — the tool calls of your recent turns |
 | `GET /health` | `{ uptimeSeconds, memory, qdrantReachable, ollamaReachable }` |
-| `GET /wiki/list` | `{ files: [...] }` |
-| `GET /wiki/read?path=<vault-path>` | `{ content }` — `400` if `path` is missing |
+| `GET /wiki/list` | `{ files: [...] }` — `curated/...` and `personal/...` paths |
+| `GET /wiki/read?path=<path>` | `{ content }` — a path as `/wiki/list` gives it; `400` if `path` is missing, `404` if it isn't among yours |
 | `GET /wiki/grep?pattern=<regex>` | `{ matches: [...] }` — `400` if `pattern` is missing |
-| `GET /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of the named episodic/semantic collection |
+| `GET /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of your points in a collection kept per person (verbatim archive, episodic memory, semantic facts); `400` for any other collection |
 | `GET /openapi.yaml` | the OpenAPI document for this surface (`text/yaml`) |
 
 Conversation history and the conversation list are backed by the durable verbatim archive; they degrade to empty when the vector store is unreachable.

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, type Principal } 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>;
+export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => 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 ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => 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 `*`. */
@@ -39,25 +43,29 @@ export type TurnRequestDeps = {
  */
 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,15 @@ 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. The
+ * caller's principal goes to every per-person getter, so the core answers with
+ * their data only; a conversation is named by its conversationId, as on
+ * `/turn`, and its session key is built from the caller.
+ * `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,9 +7,10 @@
  * 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";
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";

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,34 +12,46 @@
  * 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,
+  type Principal,
 } from "@mercury-fw/channel-types";
 
 /**
- * A client's conversation id becomes the session key, a log prefix and (until
- * the channel authenticates) the per-person wiki id, so only letters, digits,
- * `-` and `_` get in: no path segments, no line breaks, nothing to encode.
+ * 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>;
+export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => 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 ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => 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 `*`. */
@@ -57,17 +69,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) });
@@ -87,17 +109,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;
@@ -108,13 +134,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(sessionKey)) {
+  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"
@@ -143,7 +170,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);
       if (confirmReply !== null) {
         send("final", { text: confirmReply });
         close();
@@ -151,7 +178,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 });
@@ -174,10 +201,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             multiUser: false,
             text,
             sessionKey,
-            // Unauthenticated: the conversation id stands in for the caller,
-            // and nobody vouches for it.
-            principal: { id: sessionKey, provider: "none" },
-            logPrefix: `[http:${sessionKey}] `,
+            principal,
+            // The caller's id comes from the auth provider, unchecked here.
+            logPrefix: `[http:${forLog(sessionKey)}] `,
             abortSignal: abort.signal,
           },
           sink,
@@ -202,6 +228,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 }
 
 export type ConfirmRequestDeps = {
+  authenticate: Authenticate;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
 };
@@ -209,16 +236,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;
@@ -226,14 +257,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 });
   }
-  if (!CONVERSATION_ID.test(sessionKey)) {
+  if (!CONVERSATION_ID.test(conversationId)) {
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
   }
-  const outcome = await deps.resolveConfirmation(token, sessionKey, sessionKey);
+  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal);
   switch (outcome.status) {
     case "not-a-token":
     case "not-found":
@@ -254,52 +285,75 @@ 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. The
+ * caller's principal goes to every per-person getter, so the core answers with
+ * their data only; a conversation is named by its conversationId, as on
+ * `/turn`, and its session key is built from the caller.
+ * `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: (req: Request, principal: Principal) => Response | Promise<Response>): ReadRoute => ({
+    GET: async (req) => {
+      const principal = await authenticate(req);
+      return principal === null ? unauthorized(corsOrigin) : GET(req, principal);
+    },
+    OPTIONS: options,
+  });
   return {
     "/manifest": route(() => json({ ok: true, manifest: reads.manifest() })),
-    "/confirmations": route(() => json({ ok: true, pending: reads.pendingConfirmations() })),
-    "/conversation": route(async (req) => {
+    "/confirmations": route((_req, principal) => json({ ok: true, pending: reads.pendingConfirmations(principal) })),
+    "/conversation": route(async (req, principal) => {
       const url = new URL(req.url);
       const id = url.searchParams.get("id");
       if (!id) return badRequest("missing ?id");
+      if (!CONVERSATION_ID.test(id)) return badRequest("invalid conversationId");
       const limit = Number(url.searchParams.get("limit") ?? "200");
       const offset = url.searchParams.get("offset") ?? undefined;
-      return json({ ok: true, ...(await reads.conversation(id, limit, offset) as object) });
+      return json({ ok: true, ...(await reads.conversation(principal, `${principal.id}:${id}`, limit, offset) as object) });
     }),
-    "/conversations": route(async (req) => {
+    "/conversations": route(async (req, principal) => {
       const limit = Number(new URL(req.url).searchParams.get("limit") ?? "50");
-      return json({ ok: true, ...(await reads.conversations(limit) as object) });
+      const { conversations } = (await reads.conversations(principal, limit)) as {
+        conversations: Array<{ sessionKey: string; lastTimestamp: string; preview: string }>;
+      };
+      const prefix = `${principal.id}:`;
+      return json({
+        ok: true,
+        conversations: conversations
+          .filter((c) => c.sessionKey.startsWith(prefix))
+          .map((c) => ({ conversationId: c.sessionKey.slice(prefix.length), lastTimestamp: c.lastTimestamp, preview: c.preview })),
+      });
     }),
-    "/tool-log": route(() => json({ ok: true, entries: reads.toolLog() })),
+    "/tool-log": route((_req, principal) => json({ ok: true, entries: reads.toolLog(principal) })),
     "/health": route(async () => json({ ok: true, ...(await reads.health() as object) })),
-    "/wiki/list": route(async () => json({ ok: true, files: await reads.wikiList() })),
-    "/wiki/read": route(async (req) => {
+    "/wiki/list": route(async (_req, principal) => json({ ok: true, files: await reads.wikiList(principal) })),
+    "/wiki/read": route(async (req, principal) => {
       const path = requireParam(req, "path");
       if (!path) return badRequest("missing ?path");
-      return json({ ok: true, content: await reads.wikiRead(path) });
+      const content = await reads.wikiRead(principal, path);
+      return content === null ? json({ ok: false, error: "not found" }, 404) : json({ ok: true, content });
     }),
-    "/wiki/grep": route(async (req) => {
+    "/wiki/grep": route(async (req, principal) => {
       const pattern = requireParam(req, "pattern");
       if (!pattern) return badRequest("missing ?pattern");
-      return json({ ok: true, matches: await reads.wikiGrep(pattern) });
+      return json({ ok: true, matches: await reads.wikiGrep(principal, pattern) });
     }),
-    "/memory/scroll": route(async (req) => {
+    "/memory/scroll": route(async (req, principal) => {
       const url = new URL(req.url);
       const collection = url.searchParams.get("collection");
       if (!collection) return badRequest("missing ?collection");
       const limit = Number(url.searchParams.get("limit") ?? "50");
       const offset = url.searchParams.get("offset") ?? undefined;
-      return json({ ok: true, ...(await reads.memoryScroll(collection, limit, offset) as object) });
+      const page = await reads.memoryScroll(principal, collection, limit, offset);
+      return page === null ? badRequest(`unknown collection: ${collection}`) : json({ ok: true, ...(page as object) });
     }),
   };
 }
@@ -329,11 +383,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,9 +7,10 @@
  * 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 { createHttpProvider } from "./http-provider.ts";
@@ -19,18 +20,22 @@ export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 export const httpChannel: ChannelPlugin = {
   // The contract this channel is written for, as a literal: importing
   // CHANNEL_API_VERSION would report whichever contract is installed.
-  apiVersion: 2,
+  apiVersion: 3,
   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,22 +5,43 @@ 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.
+
+
+    ## What a caller sees
+
+    Every read is scoped to the caller: their own conversations, pending
+    confirmations, tool calls and memory, and the wiki as they see it, the
+    team's common area (`curated/`) plus their own notes (`personal/`).
+    Someone else's data doesn't exist as far as a caller can tell. Only
+    `/manifest` and `/health` are the same for everyone.
+
+
     ## 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
-    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).
+    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 one of the caller's conversations is readable via `GET /conversation`,
+    and the list of their conversations via `GET /conversations` (both backed
+    by the verbatim archive; they degrade to empty when the vector store is
+    unreachable).
 
 
     ## Streaming and cancellation
@@ -38,6 +59,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 +80,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`:
@@ -79,8 +104,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 +113,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
@@ -110,9 +137,10 @@ paths:
         - name: id
           in: query
           required: true
-          description: The session key whose messages to return, as `/conversations` lists it (any channel's).
+          description: The caller's `conversationId`, as `/conversations` lists it.
           schema:
             type: string
+            pattern: "^[A-Za-z0-9_-]{1,128}$"
         - name: limit
           in: query
           required: false
@@ -126,21 +154,23 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
-          description: The conversation's messages in chronological order.
+          description: The conversation's messages in chronological order; none when it isn't one of the caller's.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ConversationPage"
         "400":
-          description: Missing `?id`.
+          description: Missing or malformed `?id`.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /conversations:
     get:
-      summary: List known conversations (most-recently-active first)
+      summary: List the caller's conversations (most-recently-active first)
       parameters:
         - name: limit
           in: query
@@ -149,6 +179,8 @@ paths:
             type: integer
             default: 50
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: The conversation list.
           content:
@@ -159,6 +191,8 @@ paths:
     get:
       summary: Liveness/health of Mercury and its dependencies
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Health snapshot.
           content:
@@ -169,6 +203,8 @@ paths:
     get:
       summary: The loaded plugins, tools and skills
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Plugin manifest.
           content:
@@ -177,8 +213,10 @@ paths:
                 type: object
   /confirmations:
     get:
-      summary: Currently pending confirmations (tokens redacted)
+      summary: The caller's pending confirmations (tokens redacted)
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Pending confirmations.
           content:
@@ -187,8 +225,10 @@ paths:
                 type: object
   /tool-log:
     get:
-      summary: Recent tool-call log entries
+      summary: The tool calls made in the caller's recent turns
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Tool log.
           content:
@@ -197,8 +237,10 @@ paths:
                 type: object
   /wiki/list:
     get:
-      summary: List the wiki vault's files
+      summary: List the wiki files the caller can see (`curated/` and `personal/`)
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: File list.
           content:
@@ -207,14 +249,17 @@ paths:
                 type: object
   /wiki/read:
     get:
-      summary: Read one wiki vault file
+      summary: Read one wiki file the caller can see
       parameters:
         - name: path
           in: query
           required: true
+          description: A path as `/wiki/list` gives it, e.g. `curated/team.md` or `personal/notes/plan.md`.
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: File content.
           content:
@@ -227,9 +272,15 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "404":
+          description: No such file among those the caller can see.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
   /wiki/grep:
     get:
-      summary: Grep the wiki vault
+      summary: Grep the wiki files the caller can see
       parameters:
         - name: pattern
           in: query
@@ -238,6 +289,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: Matches.
           content:
@@ -252,11 +305,12 @@ paths:
                 $ref: "#/components/schemas/Error"
   /memory/scroll:
     get:
-      summary: Scroll a Qdrant memory collection
+      summary: Scroll the caller's points in a memory collection
       parameters:
         - name: collection
           in: query
           required: true
+          description: One of the collections kept per person (the verbatim archive, episodic memory, semantic facts), by its configured name.
           schema:
             type: string
         - name: limit
@@ -271,6 +325,8 @@ paths:
           schema:
             type: string
       responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
         "200":
           description: A page of points.
           content:
@@ -278,7 +334,7 @@ paths:
               schema:
                 type: object
         "400":
-          description: Missing `?collection`.
+          description: Missing `?collection`, or one that isn't kept per person.
           content:
             application/json:
               schema:
@@ -286,6 +342,7 @@ paths:
   /openapi.yaml:
     get:
       summary: This OpenAPI document
+      security: []
       responses:
         "200":
           description: The raw OpenAPI YAML.
@@ -294,6 +351,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
@@ -325,6 +401,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`.
@@ -392,9 +471,9 @@ components:
             - type: "null"
     ConversationSummary:
       type: object
-      required: [sessionKey, lastTimestamp, preview]
+      required: [conversationId, lastTimestamp, preview]
       properties:
-        sessionKey:
+        conversationId:
           type: string
         lastTimestamp:
           type: string

package/package.json

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