@mercury-fw/channel-http 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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

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.
 
@@ -84,7 +84,7 @@ Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, con
 
 ## Read-only introspection
 
-All `GET`, all JSON, all reporting state already held in-process. 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 CompleteLoginFn, 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,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:

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 } 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;
 };
@@ -103,7 +107,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;

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 CompleteLoginFn, 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,6 +22,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:
@@ -40,6 +42,7 @@ 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,
       });

package/http-server.ts

@@ -33,6 +33,7 @@ import {
   type ConfirmOutcome,
   type LoginOutcome,
   type Principal,
+  type Admission,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -53,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 `*`. */
@@ -95,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) });
@@ -127,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;
@@ -236,6 +257,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
 export type ConfirmRequestDeps = {
   authenticate: Authenticate;
+  admit?: AdmitFn;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
 };
@@ -255,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;
@@ -340,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 });
@@ -349,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");
@@ -379,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) => {
@@ -433,11 +460,16 @@ 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) =>

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,7 @@ 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,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
@@ -158,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:
@@ -183,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:
@@ -195,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:
@@ -203,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:
@@ -219,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:
@@ -231,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:
@@ -243,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:
@@ -262,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:
@@ -293,6 +339,10 @@ paths:
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
         "200":
           description: Matches.
           content:
@@ -329,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:
@@ -396,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.5.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.40.0",
-    "@mercury-fw/plugin-types": "0.40.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"