@mercury-fw/channel-http 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @mercury-fw/channel-http
 
+## 0.5.0
+
+### Minor Changes
+
+- 0739f77: A plugin acts as the person Mercury is talking to, who logs in to the service through Mercury.
+
+  - Plugin contract version 4: a plugin declares `actsAs: "person" | "mercury"`, and one acting as the person contributes a `login`; its tools get the turn's `person` and `requireLogin` in their context.
+  - A person is offered only the plugins acting as the person: their prompt fragments, skills and tools. A plugin acting as Mercury, or declaring nothing, is offered on the terminal only until people can be allowed to make Mercury act as itself; the startup log names it.
+  - `createCliTool` adds `--user` with the person's id to every command, staged confirmations included, and when the CLI exits with code 3 (not logged in) returns their login instead. `createCliPersonLogin` builds a plugin's `login` on a CLI's two-step remote login. A failed `runCli` carries `exitCode`.
+  - Channel contract version 4: channels get `logins` (`accept` a callback URL, `complete` a login) and `detectLoginRequired`.
+  - The HTTP channel, with `HTTP_SURFACE_PUBLIC_URL` set, streams a `login` event with the link to open and takes the person back at `GET /login/callback`, public and protected by the single-use state.
+  - `mercury.cliCredentials` can declare `userSetup`, run by `mfw credentials setup <plugin> --user-app`: the app people log in through, set up without logging anyone in.
+  - plugin-jira and plugin-bitbucket act as the person, on CLIs 2.3.0: set up their people's app with `--user-app` and register `<HTTP_SURFACE_PUBLIC_URL>/login/callback` on it. Jira's skill now says `currentUser()` is the person.
+  - plugin-atlassian-admin acts as Mercury, on CLI 0.2.0, whose `init` asks for the key without echoing it: until permissions exist it's available on the terminal only.
+  - A third-party plugin needs `apiVersion: 4` to load, and `actsAs: "person"` with a `login` to be offered to people.
+
+## 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

package/README.md

@@ -20,12 +20,13 @@ It needs an auth provider next to it: [`@mercury-fw/auth-oidc`](../../auth/auth-
 |---|---|
 | `HTTP_SURFACE_PORT` | The port (default `4100`). |
 | `HTTP_SURFACE_CORS_ORIGIN` | The origin a browser UI calls from (default `*`). |
+| `HTTP_SURFACE_PUBLIC_URL` | The address people's browsers reach the surface at (e.g. `https://mercury.example.com`). With it, people log in here to the services plugins act on as them (see [`GET /login/callback`](#get-logincallback)); without it, nobody can. |
 
 ## API
 
 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.
+**Authentication.** Every route except `GET /openapi.yaml`, `GET /login/callback` 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.
 
@@ -60,6 +61,7 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 | `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` |
+| `login` | `{ service, url }` | the caller isn't logged in to `service` yet, which a plugin acts on as them: show them `url` to open (the model never gets it) |
 | `final` | `{ text }` | the complete answer (also emitted for a token confirmation, with no model turn) |
 | `error` | `{ message }` | the turn failed mid-stream |
 
@@ -70,26 +72,32 @@ curl -N -X POST http://localhost:4100/turn \
   -d '{"text":"Quante issue nel progetto KAN?","conversationId":"c1"}'
 ```
 
+## `GET /login/callback`
+
+Where a person comes back after logging in to a service a plugin acts on as them (Jira, Bitbucket): the `login` event's `url` sends them to the service, and the service sends their browser here with `code` and `state`. Mounted only with `HTTP_SURFACE_PUBLIC_URL`, at `<HTTP_SURFACE_PUBLIC_URL>/login/callback`, which is the URL to register as a callback on the service's app (the Atlassian 3LO app, the Bitbucket consumer people log in through). No bearer token: the browser has none here, and the `state` Mercury issued for that person, single-use and valid for ten minutes, is what ties the request to their login. Answers with a plain-text page saying how it went.
+
+Whoever opens the link and accepts decides which account gets linked: a link belongs to the person it was shown to, and someone else accepting it would link their own account to that person's Mercury identity. A UI should say so next to the link. Checking the linked account against the person is [#179](https://github.com/lucabro81/mercury-fw/issues/179).
+
 ## `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, 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. They need an authenticated caller, but each one still shows every person's data: scoping them per person is the next step.
+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=<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 /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

@@ -10,7 +10,7 @@
  * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
-import { type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import { type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
 import type { Authenticate, Provider, ChannelHostReads } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
@@ -23,6 +23,13 @@ export type HttpProviderDeps = {
     authenticate: Authenticate;
     /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
     corsOrigin?: string;
+    /** People's logins, when the surface has a public URL to be sent back to:
+     * the callback is offered (`accept`) once the server listens. */
+    logins?: {
+        callbackUrl: string;
+        accept: (callbackUrl: string) => void;
+        complete: CompleteLoginFn;
+    };
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -12,18 +12,21 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * Every route but the OpenAPI document and the CORS preflights asks the
- * injected `authenticate` (the auth provider the app declares) who is calling
+ * `/login/callback` is where a person's browser comes back after logging in to
+ * a service a plugin acts on as them; the single-use state is its credential.
+ *
+ * Every route but the OpenAPI document, the login callback 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 Authenticate, type ChannelHostReads, type ConfirmOutcome } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, 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. */
@@ -72,6 +75,18 @@ export type ConfirmRequestDeps = {
  * even token-shaped). Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+/** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
+export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
+/**
+ * `GET /login/callback`: where the provider sends a person back after they log
+ * in, with `code` and `state` (or `error`, when they refused). Public: the
+ * person's browser carries no token here, and the single-use `state` the core
+ * issued for them is what ties the request to their login. Answers with a
+ * plain page telling them how it went.
+ */
+export declare function handleLoginCallback(req: Request, deps: {
+    complete: CompleteLoginFn;
+}): Promise<Response>;
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
 type ReadRoute = {
     GET: (req: Request) => Response | Promise<Response>;
@@ -81,7 +96,10 @@ 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. Every `GET` asks `authenticate` first and answers 401 without
- * calling its getter when nobody is calling; the preflight doesn't ask.
+ * 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.
  */
@@ -91,6 +109,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     reads?: ChannelHostReads;
     /** The `/confirm` endpoint's structured resolver, injected by the core. */
     resolveConfirmation: ResolveConfirmationFn;
+    /** Finishes people's logins; `/login/callback` is mounted only with it. */
+    completeLogin?: CompleteLoginFn;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/dist/index.d.ts

@@ -6,11 +6,13 @@
  * is no runtime inert condition (unlike Google Chat's subscription): if it's
  * declared, it starts.
  *
- * `build` reads its port and CORS origin from `env` and takes the confirm
+ * `build` reads its port, CORS origin and public URL from `env` and takes the confirm
  * 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.
+ * fail-soft, and without an auth provider the surface never opens. With a
+ * public URL (`HTTP_SURFACE_PUBLIC_URL`) it also takes people's logins: it
+ * mounts `<url>/login/callback` and, once it's listening, offers it to the core.
  */
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";

package/http-provider.ts

@@ -10,7 +10,7 @@
  * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
-import { startHttpServer, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import { startHttpServer, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
 import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
@@ -24,6 +24,9 @@ export type HttpProviderDeps = {
   authenticate: Authenticate;
   /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
   corsOrigin?: string;
+  /** People's logins, when the surface has a public URL to be sent back to:
+   * the callback is offered (`accept`) once the server listens. */
+  logins?: { callbackUrl: string; accept: (callbackUrl: string) => void; complete: CompleteLoginFn };
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -38,7 +41,9 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         reads: deps.reads,
         authenticate: deps.authenticate,
         corsOrigin: deps.corsOrigin,
+        completeLogin: deps.logins?.complete,
       });
+      deps.logins?.accept(deps.logins.callbackUrl);
     },
     async notify(): Promise<{ sessionKey: string }> {
       // No proactive push channel over HTTP (request/response only).

package/http-server.ts

@@ -12,14 +12,18 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * Every route but the OpenAPI document and the CORS preflights asks the
- * injected `authenticate` (the auth provider the app declares) who is calling
+ * `/login/callback` is where a person's browser comes back after logging in to
+ * a service a plugin acts on as them; the single-use state is its credential.
+ *
+ * Every route but the OpenAPI document, the login callback 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 {
+  detectLoginRequired,
   detectPendingConfirmation,
   PENDING_CONFIRMATION_NOTE,
   type HandleTurn,
@@ -27,6 +31,8 @@ import {
   type Authenticate,
   type ChannelHostReads,
   type ConfirmOutcome,
+  type LoginOutcome,
+  type Principal,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -43,9 +49,9 @@ function forLog(text: string): string {
 }
 
 /** 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;
@@ -169,7 +175,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, principal.id);
+      const confirmReply = await deps.confirm(text, sessionKey, principal);
       if (confirmReply !== null) {
         send("final", { text: confirmReply });
         close();
@@ -187,6 +193,8 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
         onStep: (step) => {
           const pending = detectPendingConfirmation(step);
           if (pending) send("pending", { command: pending.summary, token: pending.token });
+          const login = detectLoginRequired(step);
+          if (login) send("login", { service: login.service, url: login.url });
         },
         onUsage: () => {},
         finalize: async (finalText) => send("final", { text: finalText }),
@@ -263,7 +271,7 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   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);
+  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal);
   switch (outcome.status) {
     case "not-a-token":
     case "not-found":
@@ -275,6 +283,46 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   }
 }
 
+/** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
+export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
+
+/** A plain-text page for the person's browser, at the end of their login. */
+function loginPage(text: string, status: number): Response {
+  // The URL carried the code and the state: neither kept nor passed on.
+  return new Response(text, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer" },
+  });
+}
+
+/**
+ * `GET /login/callback`: where the provider sends a person back after they log
+ * in, with `code` and `state` (or `error`, when they refused). Public: the
+ * person's browser carries no token here, and the single-use `state` the core
+ * issued for them is what ties the request to their login. Answers with a
+ * plain page telling them how it went.
+ */
+export async function handleLoginCallback(req: Request, deps: { complete: CompleteLoginFn }): Promise<Response> {
+  const params = new URL(req.url).searchParams;
+  const error = params.get("error");
+  if (error !== null) {
+    const reason = error.replace(/[^A-Za-z0-9_.-]/g, "").slice(0, 64);
+    return loginPage(`The login didn't happen (${reason}). Ask Mercury again for a new link.`, 400);
+  }
+  const code = params.get("code");
+  const state = params.get("state");
+  if (!code || !state) return loginPage("The login link came back without a code or a state. Ask Mercury again for a new link.", 400);
+  const outcome = await deps.complete(state, code);
+  return outcome.ok
+    ? loginPage(`You're logged in to ${outcome.service}. Go back to the conversation and ask again.`, 200)
+    : loginPage(outcome.error, 400);
+}
+
+/** The login callback route, mounted when the server can complete logins. */
+function loginRoutes(complete: CompleteLoginFn): Record<string, { GET: (req: Request) => Promise<Response> }> {
+  return { "/login/callback": { GET: (req) => handleLoginCallback(req, { complete }) } };
+}
+
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
 type ReadRoute = {
   GET: (req: Request) => Response | Promise<Response>;
@@ -285,7 +333,10 @@ 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. Every `GET` asks `authenticate` first and answers 401 without
- * calling its getter when nobody is calling; the preflight doesn't ask.
+ * 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.
  */
@@ -296,45 +347,60 @@ export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate,
   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: async (req) => ((await authenticate(req)) === null ? unauthorized(corsOrigin) : GET(req)),
+  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) });
     }),
   };
 }
@@ -344,6 +410,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   reads?: ChannelHostReads;
   /** The `/confirm` endpoint's structured resolver, injected by the core. */
   resolveConfirmation: ResolveConfirmationFn;
+  /** Finishes people's logins; `/login/callback` is mounted only with it. */
+  completeLogin?: CompleteLoginFn;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -370,6 +438,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin) : {}),
+      ...(deps.completeLogin ? loginRoutes(deps.completeLogin) : {}),
     },
     error: (err) =>
       Response.json(

package/index.ts

@@ -6,11 +6,13 @@
  * is no runtime inert condition (unlike Google Chat's subscription): if it's
  * declared, it starts.
  *
- * `build` reads its port and CORS origin from `env` and takes the confirm
+ * `build` reads its port, CORS origin and public URL from `env` and takes the confirm
  * 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.
+ * fail-soft, and without an auth provider the surface never opens. With a
+ * public URL (`HTTP_SURFACE_PUBLIC_URL`) it also takes people's logins: it
+ * mounts `<url>/login/callback` and, once it's listening, offers it to the core.
  */
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import { createHttpProvider } from "./http-provider.ts";
@@ -20,7 +22,7 @@ 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: 4,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {
@@ -29,6 +31,10 @@ export const httpChannel: ChannelPlugin = {
     if (!ctx.authenticate) {
       throw new Error("http channel requires an auth provider (auth in mercury.config.ts)");
     }
+    // The provider sends a person back here after they log in, so it needs
+    // the address their browser reaches the surface at.
+    const publicUrl = ctx.env.HTTP_SURFACE_PUBLIC_URL?.trim().replace(/\/+$/, "");
+    const logins = publicUrl ? ctx.logins : undefined;
     return createHttpProvider({
       port: Number(ctx.env.HTTP_SURFACE_PORT ?? "4100"),
       corsOrigin: ctx.env.HTTP_SURFACE_CORS_ORIGIN ?? "*",
@@ -36,6 +42,7 @@ export const httpChannel: ChannelPlugin = {
       resolveConfirmation: ctx.resolveConfirmation,
       reads: ctx.reads,
       authenticate: ctx.authenticate,
+      ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },
 };

package/openapi.yaml

@@ -21,6 +21,15 @@ info:
     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`
@@ -28,10 +37,11 @@ info:
     `<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).
+    `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
@@ -77,7 +87,9 @@ paths:
             An SSE stream. Each event is one of the types in `TurnEvent`:
             `reasoning`/`reasoning_end`, `text` (incremental deltas), `tool`/
             `tool_finish` (status of a tool call), `pending` (a staged
-            confirm-required action, with its command and token), `final` (the
+            confirm-required action, with its command and token), `login` (a
+            service the caller has to log in to first, with the link to open),
+            `final` (the
             authoritative complete answer), and `error`.
           content:
             text/event-stream:
@@ -127,9 +139,10 @@ paths:
         - name: id
           in: query
           required: true
-          description: The session key whose messages to return, as `/conversations` lists it (any channel's; an HTTP one is `<caller id>:<conversationId>`).
+          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
@@ -146,20 +159,20 @@ paths:
         "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
@@ -202,7 +215,7 @@ 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"
@@ -214,7 +227,7 @@ 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"
@@ -226,7 +239,7 @@ 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"
@@ -238,11 +251,12 @@ 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:
@@ -260,9 +274,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
@@ -287,11 +307,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
@@ -315,11 +336,35 @@ paths:
               schema:
                 type: object
         "400":
-          description: Missing `?collection`.
+          description: Missing `?collection`, or one that isn't kept per person.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /login/callback:
+    get:
+      summary: Where a person comes back after logging in to a service
+      description: >
+        Mounted when `HTTP_SURFACE_PUBLIC_URL` is set. The service sends the
+        person's browser here with `code` and `state` (or `error`); the
+        single-use state is the credential, so no bearer token is needed.
+        Answers with a plain-text page.
+      security: []
+      parameters:
+        - { name: code, in: query, schema: { type: string } }
+        - { name: state, in: query, schema: { type: string } }
+        - { name: error, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: Logged in.
+          content:
+            text/plain:
+              schema: { type: string }
+        "400":
+          description: Refused, expired, already used, or missing code/state.
+          content:
+            text/plain:
+              schema: { type: string }
   /openapi.yaml:
     get:
       summary: This OpenAPI document
@@ -397,6 +442,12 @@ components:
         token:
           type: string
           description: On `pending` — the one-time confirmation token.
+        service:
+          type: string
+          description: On `login` — the service the caller has to log in to.
+        url:
+          type: string
+          description: On `login` — the link the caller opens to log in; it comes back to `/login/callback`.
         text:
           type: string
           description: On `final` — the authoritative complete answer.
@@ -452,9 +503,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.3.0",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.35.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.35.0",
-    "@mercury-fw/plugin-types": "0.35.0",
+    "@mercury-fw/channel-types": "0.40.0",
+    "@mercury-fw/plugin-types": "0.40.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"