@mercury-fw/channel-http 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mercury-fw/channel-http
 
+## 0.7.0
+
+### Minor Changes
+
+- 2c63bbf: One person across accounts: linking them by a code.
+
+  - `POST /link` on the HTTP surface hands the caller a one-time code (`xxxx-xxxx-xxxx`, ten minutes, single use). They send it from the other account, on any channel, twice. The first time Mercury says whom the account would be linked to, the second time it links it.
+  - From then on the account is the person it's linked to: one private area, one memory, the same roles. Its earlier area stays where it was, and undoing the link gives it back.
+  - A link never touches the terminal, never chains, and is refused for an account the directory already knows as someone else.
+  - The links live on the vault's volume, out of the vault's git and out of reach of the model and the HTTP reads.
+  - `mfw identity links | link | unlink` lets the operator manage them, for instances where nobody can be shown a code.
+  - Channels get the code through the confirmation hook they already call (`ctx.confirm`), and the HTTP surface gets `ctx.linking`.
+  - Fixed: `ctx.confirm` refused someone the core doesn't admit before checking that their text was a token at all. On Google Chat, every message from an unknown sender came back as the refusal.
+
+## 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

package/README.md

@@ -26,7 +26,7 @@ It needs an auth provider next to it: [`@mercury-fw/auth-oidc`](../../auth/auth-
 
 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`, `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.
+**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.
 
@@ -78,13 +78,17 @@ Where a person comes back after logging in to a service a plugin acts on as them
 
 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 /link`
+
+A code for linking another of the caller's accounts to them, for the UI to show: `{ ok: true, code, expiresAt }`, or `400` with the reason when there's none. The person sends the code from the other account, on any channel, twice: the first time Mercury says whom the account would be linked to, the second time it links it, and from then on both accounts are one person (one private area, the same roles). The code lasts ten minutes, works once, and only the caller sees it; the model never does. It belongs to the first account that sends it, so it should be sent in a one-to-one conversation, never in a shared space where someone else could send it first. Over HTTP only an account the instance already admits can send it (anyone else is refused before the turn), so an account a closed instance doesn't know links from a chat.
+
 ## `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,8 +10,8 @@
  * (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 CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, ChannelHostReads } from "@mercury-fw/channel-types";
+import { type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import type { Authenticate, Provider, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -21,6 +21,8 @@ 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:
@@ -30,6 +32,8 @@ export type HttpProviderDeps = {
         accept: (callbackUrl: string) => void;
         complete: CompleteLoginFn;
     };
+    /** Linking another account to the caller (`POST /link`). */
+    linking?: ChannelLinking;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -22,15 +22,18 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission, type ChannelLinking } 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 `*`. */
@@ -59,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;
 };
@@ -75,6 +79,20 @@ export type ConfirmRequestDeps = {
  * even token-shaped). Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+export type LinkRequestDeps = {
+    authenticate: Authenticate;
+    admit?: AdmitFn;
+    /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+    start: ChannelLinking["start"];
+    corsOrigin?: string;
+};
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export declare function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response>;
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 /**
@@ -103,7 +121,7 @@ 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;
@@ -111,6 +129,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     resolveConfirmation: ResolveConfirmationFn;
     /** Finishes people's logins; `/login/callback` is mounted only with it. */
     completeLogin?: CompleteLoginFn;
+    /** Linking another account to the caller; `/link` is mounted only with it. */
+    linking?: ChannelLinking;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/http-provider.ts

@@ -10,8 +10,8 @@
  * (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 CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
+import { startHttpServer, type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import type { Authenticate, Provider, HandleTurn, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -22,11 +22,15 @@ 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 };
+  /** Linking another account to the caller (`POST /link`). */
+  linking?: ChannelLinking;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -40,8 +44,10 @@ 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.linking === undefined ? {} : { linking: deps.linking }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -33,6 +33,8 @@ import {
   type ConfirmOutcome,
   type LoginOutcome,
   type Principal,
+  type Admission,
+  type ChannelLinking,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -53,10 +55,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 `*`. */
@@ -95,6 +101,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) });
@@ -127,8 +149,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;
@@ -236,6 +258,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
 export type ConfirmRequestDeps = {
   authenticate: Authenticate;
+  admit?: AdmitFn;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
 };
@@ -255,8 +278,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;
@@ -283,6 +306,33 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   }
 }
 
+export type LinkRequestDeps = {
+  authenticate: Authenticate;
+  admit?: AdmitFn;
+  /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+  start: ChannelLinking["start"];
+  corsOrigin?: string;
+};
+
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export async function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response> {
+  const origin = deps.corsOrigin ?? "*";
+  const principal = await caller(req, deps, origin);
+  if (principal instanceof Response) return principal;
+  const started = await deps.start(principal);
+  return Response.json(started, { status: started.ok ? 200 : 400, headers: { ...corsHeaders(origin), "cache-control": "no-store" } });
+}
+
+/** `POST /link` and its preflight, mounted when the core offers linking. */
+function linkRoutes(deps: LinkRequestDeps): Record<string, { POST: (req: Request) => Promise<Response>; OPTIONS: () => Response }> {
+  return { "/link": { POST: (req) => handleLinkRequest(req, deps), OPTIONS: () => preflight(deps.corsOrigin ?? "*") } };
+}
+
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 
@@ -340,7 +390,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 });
@@ -349,14 +404,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");
@@ -379,7 +434,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) => {
@@ -412,6 +467,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   resolveConfirmation: ResolveConfirmationFn;
   /** Finishes people's logins; `/login/callback` is mounted only with it. */
   completeLogin?: CompleteLoginFn;
+  /** Linking another account to the caller; `/link` is mounted only with it. */
+  linking?: ChannelLinking;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -433,12 +490,18 @@ 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) : {}),
+      ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },
     error: (err) =>
       Response.json(

package/index.ts

@@ -22,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: 4,
+  apiVersion: 5,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {
@@ -42,6 +42,8 @@ export const httpChannel: ChannelPlugin = {
       resolveConfirmation: ctx.resolveConfirmation,
       reads: ctx.reads,
       authenticate: ctx.authenticate,
+      admit: ctx.admit,
+      ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
       ...(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,6 +88,10 @@ 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`:
@@ -117,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
@@ -132,6 +146,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /link:
+    post:
+      summary: A code for linking another account to the caller
+      description: >
+        A one-time code (`xxxx-xxxx-xxxx`, valid for ten minutes) the person
+        sends from another account, on any channel, twice: the first time
+        Mercury says whom the account would be linked to, the second time it
+        links it. From then on both accounts are one person. Only the caller
+        sees the code; the model never does.
+      responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "400":
+          description: No code for this caller, with the reason.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "200":
+          description: The code and when it expires.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, code, expiresAt]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+                  code:
+                    type: string
+                    pattern: "^[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$"
+                  expiresAt:
+                    type: string
+                    format: date-time
   /conversation:
     get:
       summary: A conversation's durable transcript
@@ -158,6 +211,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:
@@ -183,6 +240,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: The conversation list.
           content:
@@ -195,6 +256,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Health snapshot.
           content:
@@ -203,10 +268,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:
@@ -219,6 +288,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Pending confirmations.
           content:
@@ -231,6 +304,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Tool log.
           content:
@@ -243,6 +320,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: File list.
           content:
@@ -262,6 +343,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: File content.
           content:
@@ -293,6 +378,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Matches.
           content:
@@ -329,6 +418,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:
@@ -396,6 +489,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.5.0",
+  "version": "0.7.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.40.0",
-    "@mercury-fw/plugin-types": "0.40.0",
+    "@mercury-fw/channel-types": "0.44.0",
+    "@mercury-fw/plugin-types": "0.44.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"