@mercury-fw/channel-http 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @mercury-fw/channel-http
 
+## 0.6.0
+
+### Minor Changes
+
+- a7f2f13: A user directory decides who people are and what they may make Mercury do.
+
+  - An app can declare a `directory` in `mercury.config.ts`. Given whoever a channel says is talking, it returns the person with their roles. The person's key is `<directory name>:<id>`, so one person reached from several channels keeps one private area, one memory and one set of confirmations.
+  - With a directory the instance is closed. Someone it doesn't know gets a refusal and nothing runs, unless `access.unknown` is `"allow"`; `access.unknownMessage` sets what they're told. A directory that can't be reached, or fails to load, refuses everyone but the terminal. Answers are cached for five minutes, so a revoked role stops counting within that time.
+  - `mercury.act-as-self` (every plugin) or `mercury.act-as-self.<plugin>` (one) lets a person make Mercury act with its own identity.
+    - A plugin acting as Mercury, such as atlassian-admin, is offered only to those people, and on the terminal.
+    - A plugin acting as the person also gives them each tool a second time, as `<tool>AsMercury`.
+    - Every call made as Mercury for someone is logged with who asked.
+  - `access.plugins` restricts a plugin to some roles. Prompts, skills and the manifest follow what each person is offered.
+  - New package `@mercury-fw/directory-static`: people, their identities on each channel and their roles, listed in `DIRECTORY_STATIC_PEOPLE`.
+  - The channel contract is at version 5:
+    - `ChannelRuntimeContext.admit` says whether the core talks to a caller;
+    - the reads are per person and async, the manifest included;
+    - `DirectoryPlugin` is the directory contract;
+    - `Principal` no longer carries `roles`.
+  - `channel-http` answers `403` to a caller the directory doesn't know and `503` when it can't be reached, on every route.
+  - `auth-static` refuses `roles` in `AUTH_STATIC_TOKENS`: roles come from the directory.
+
+## 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

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. Then the core decides whether it talks to that person at all: someone the app's directory doesn't know gets `403` (unless the app lets unknown people in), and `503` when the directory can't be reached, both with `{ ok: false, error, reason }`, where `error` is what to tell them.
 
 **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,13 +72,19 @@ 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 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.
+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. `/manifest` lists what the caller is offered (a plugin acting as Mercury only for someone allowed to use it), and only `/health` is the same for everyone.
 
 | endpoint | `data` on success |
 |---|---|

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 AdmitFn, 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;
@@ -21,8 +21,17 @@ export type HttpProviderDeps = {
     reads?: ChannelHostReads;
     /** Who is calling, from the app's auth provider. */
     authenticate: Authenticate;
+    /** Whether the core talks to them, from the core. */
+    admit?: AdmitFn;
     /** 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,22 +12,28 @@
  * 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, type Principal } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission } 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, 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, principal: Principal) => Promise<ConfirmOutcome>;
+/** Whether the core talks to an authenticated caller at all, injected by the core (`ctx.admit`); everyone when absent. */
+export type AdmitFn = (principal: Principal) => Promise<Admission>;
 export type TurnRequestDeps = {
     handleTurn: HandleTurn;
     /** Who is calling, injected from the app's auth provider; `null` = refused. */
     authenticate: Authenticate;
+    admit?: AdmitFn;
     /** Bare-token interception before the model, injected by the core. */
     confirm: ConfirmFn;
     /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
@@ -56,6 +62,7 @@ export declare function openApiResponse(corsOrigin?: string): Response;
 export declare function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response>;
 export type ConfirmRequestDeps = {
     authenticate: Authenticate;
+    admit?: AdmitFn;
     resolveConfirmation: ResolveConfirmationFn;
     corsOrigin?: string;
 };
@@ -72,6 +79,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>;
@@ -88,12 +107,14 @@ type ReadRoute = {
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
  * same for a 400.
  */
-export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string): Record<string, ReadRoute>;
+export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string, admit?: AdmitFn): Record<string, ReadRoute>;
 export type HttpServerDeps = TurnRequestDeps & {
     port: number;
     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 AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
 import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
@@ -22,8 +22,13 @@ export type HttpProviderDeps = {
   reads?: ChannelHostReads;
   /** Who is calling, from the app's auth provider. */
   authenticate: Authenticate;
+  /** Whether the core talks to them, from the core. */
+  admit?: AdmitFn;
   /** 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> } {
@@ -37,8 +42,11 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         resolveConfirmation: deps.resolveConfirmation,
         reads: deps.reads,
         authenticate: deps.authenticate,
+        ...(deps.admit === undefined ? {} : { admit: deps.admit }),
         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,7 +31,9 @@ import {
   type Authenticate,
   type ChannelHostReads,
   type ConfirmOutcome,
+  type LoginOutcome,
   type Principal,
+  type Admission,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -48,10 +54,14 @@ export type ConfirmFn = (token: string, sessionKey: string, principal: Principal
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
 export type ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
 
+/** Whether the core talks to an authenticated caller at all, injected by the core (`ctx.admit`); everyone when absent. */
+export type AdmitFn = (principal: Principal) => Promise<Admission>;
+
 export type TurnRequestDeps = {
   handleTurn: HandleTurn;
   /** Who is calling, injected from the app's auth provider; `null` = refused. */
   authenticate: Authenticate;
+  admit?: AdmitFn;
   /** Bare-token interception before the model, injected by the core. */
   confirm: ConfirmFn;
   /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
@@ -90,6 +100,22 @@ function unauthorized(origin: string): Response {
   );
 }
 
+/** The core's refusal of an authenticated caller: 403 for someone it doesn't know, 503 when it couldn't tell, with what to tell them. */
+function notAdmitted(admission: Exclude<Admission, { ok: true }>, origin: string): Response {
+  return Response.json(
+    { ok: false, error: admission.message, reason: admission.reason },
+    { status: admission.reason === "unknown" ? 403 : 503, headers: corsHeaders(origin) },
+  );
+}
+
+/** The caller of `req`, authenticated and admitted, or the response refusing them. */
+async function caller(req: Request, deps: { authenticate: Authenticate; admit?: AdmitFn }, origin: string): Promise<Principal | Response> {
+  const principal = await deps.authenticate(req);
+  if (principal === null) return unauthorized(origin);
+  const admission = deps.admit ? await deps.admit(principal) : { ok: true as const };
+  return admission.ok ? principal : notAdmitted(admission, origin);
+}
+
 /** 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) });
@@ -122,8 +148,8 @@ export function openApiResponse(corsOrigin = "*"): Response {
 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);
+  const principal = await caller(req, deps, origin);
+  if (principal instanceof Response) return principal;
   let body: { text?: unknown; conversationId?: unknown };
   try {
     body = (await req.json()) as typeof body;
@@ -188,6 +214,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 }),
@@ -229,6 +257,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
 export type ConfirmRequestDeps = {
   authenticate: Authenticate;
+  admit?: AdmitFn;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
 };
@@ -248,8 +277,8 @@ export type ConfirmRequestDeps = {
 export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response> {
   const origin = deps.corsOrigin ?? "*";
   const cors = corsHeaders(origin);
-  const principal = await deps.authenticate(req);
-  if (principal === null) return unauthorized(origin);
+  const principal = await caller(req, deps, origin);
+  if (principal instanceof Response) return principal;
   let body: { token?: unknown; conversationId?: unknown };
   try {
     body = (await req.json()) as typeof body;
@@ -276,6 +305,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>;
@@ -293,7 +362,12 @@ type ReadRoute = {
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
  * same for a 400.
  */
-export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin = "*"): Record<string, ReadRoute> {
+export function readRoutes(
+  reads: ChannelHostReads,
+  authenticate: Authenticate,
+  corsOrigin = "*",
+  admit?: AdmitFn,
+): Record<string, ReadRoute> {
   const cors = corsHeaders(corsOrigin);
   const json = (payload: object, status = 200): Response =>
     Response.json(payload, { status, headers: cors });
@@ -302,14 +376,14 @@ export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate,
   const options = () => preflight(corsOrigin);
   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);
+      const principal = await caller(req, { authenticate, ...(admit === undefined ? {} : { admit }) }, corsOrigin);
+      return principal instanceof Response ? principal : GET(req, principal);
     },
     OPTIONS: options,
   });
   return {
-    "/manifest": route(() => json({ ok: true, manifest: reads.manifest() })),
-    "/confirmations": route((_req, principal) => json({ ok: true, pending: reads.pendingConfirmations(principal) })),
+    "/manifest": route(async (_req, principal) => json({ ok: true, manifest: await reads.manifest(principal) })),
+    "/confirmations": route(async (_req, principal) => json({ ok: true, pending: await reads.pendingConfirmations(principal) })),
     "/conversation": route(async (req, principal) => {
       const url = new URL(req.url);
       const id = url.searchParams.get("id");
@@ -332,7 +406,7 @@ export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate,
           .map((c) => ({ conversationId: c.sessionKey.slice(prefix.length), lastTimestamp: c.lastTimestamp, preview: c.preview })),
       });
     }),
-    "/tool-log": route((_req, principal) => json({ ok: true, entries: reads.toolLog(principal) })),
+    "/tool-log": route(async (_req, principal) => json({ ok: true, entries: await reads.toolLog(principal) })),
     "/health": route(async () => json({ ok: true, ...(await reads.health() as object) })),
     "/wiki/list": route(async (_req, principal) => json({ ok: true, files: await reads.wikiList(principal) })),
     "/wiki/read": route(async (req, principal) => {
@@ -363,6 +437,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)
@@ -384,11 +460,17 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       "/turn": { POST: (req) => handleTurnRequest(req, deps), OPTIONS: () => preflight(origin) },
       "/confirm": {
         POST: (req) =>
-          handleConfirmRequest(req, { authenticate: deps.authenticate, resolveConfirmation: deps.resolveConfirmation, corsOrigin: origin }),
+          handleConfirmRequest(req, {
+            authenticate: deps.authenticate,
+            ...(deps.admit === undefined ? {} : { admit: deps.admit }),
+            resolveConfirmation: deps.resolveConfirmation,
+            corsOrigin: origin,
+          }),
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
-      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin) : {}),
+      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit) : {}),
+      ...(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: 3,
+  apiVersion: 5,
   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,8 @@ export const httpChannel: ChannelPlugin = {
       resolveConfirmation: ctx.resolveConfirmation,
       reads: ctx.reads,
       authenticate: ctx.authenticate,
+      admit: ctx.admit,
+      ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },
 };

package/openapi.yaml

@@ -20,14 +20,20 @@ info:
     missing or refused one gets `401` with `WWW-Authenticate: Bearer`, before
     anything runs.
 
+    Then the core decides whether it talks to that person at all: someone the
+    app's directory doesn't know gets `403` (unless the app lets unknown people
+    in), and `503` when the directory can't be reached. Both carry
+    `{ ok: false, error, reason }`, `error` being what to tell them.
+
 
     ## 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.
+    Someone else's data doesn't exist as far as a caller can tell.
+    `/manifest` lists what the caller is offered, and only `/health` is the
+    same for everyone.
 
 
     ## Conversations
@@ -82,12 +88,18 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: >
             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:
@@ -115,6 +127,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: >
             `resolved: true` (with the reply `text`) when the token was a pending
@@ -156,6 +172,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: The conversation's messages in chronological order; none when it isn't one of the caller's.
           content:
@@ -181,6 +201,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: The conversation list.
           content:
@@ -193,6 +217,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Health snapshot.
           content:
@@ -201,10 +229,14 @@ paths:
                 type: object
   /manifest:
     get:
-      summary: The loaded plugins, tools and skills
+      summary: The plugins, tools and skills the caller is offered
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Plugin manifest.
           content:
@@ -217,6 +249,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Pending confirmations.
           content:
@@ -229,6 +265,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Tool log.
           content:
@@ -241,6 +281,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: File list.
           content:
@@ -260,6 +304,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: File content.
           content:
@@ -291,6 +339,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Matches.
           content:
@@ -327,6 +379,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: A page of points.
           content:
@@ -339,6 +395,30 @@ paths:
             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
@@ -370,6 +450,26 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
+    NotAdmitted:
+      description: >
+        An authenticated caller the core won't talk to: `403` when the app's
+        directory doesn't know them, `503` when it can't be reached. Nothing
+        behind the route runs.
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [ok, error, reason]
+            properties:
+              ok:
+                type: boolean
+                enum: [false]
+              error:
+                type: string
+                description: What to tell the caller.
+              reason:
+                type: string
+                enum: [unknown, unavailable]
   schemas:
     TurnRequest:
       type: object
@@ -416,6 +516,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
     "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.36.0",
-    "@mercury-fw/plugin-types": "0.36.0",
+    "@mercury-fw/channel-types": "0.42.0",
+    "@mercury-fw/plugin-types": "0.42.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"