@nervur-org/dock 0.3.0

package/human/worker.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// The tab's ear while the tab is closed. A ring from a world's doorbell
+// arrives here, at the service worker on that world's origin, and this is
+// the one piece of a tab that runs when nothing of the tab is open.
+//
+// A device is one harbor, and the lock says who holds it. A page that is
+// open holds it, so this worker asks that page to wake and drain and tells
+// the human what came back; with no page open the worker is the device's
+// harbor for the length of the wake, boots over the same database, dials
+// the world, drains and closes.
+//
+// The line is the world's own. A Web Push body is encrypted under RFC 8291
+// to keys only this browser holds, so the ring arrives here already opened
+// and the push service that carried it saw an endpoint, a signature and
+// ciphertext. A ring that carried no line leaves the line to what was
+// drained, which is objects that crossed sealed over Quo.
+//
+// Its config is the world's, written above the bundle by the route that
+// serves it: the quo. route to dial and the wards of this world by pk.
+import type { JsonObject } from '@nervur-org/nervur';
+import { BrowserHarbor } from '../harbor/browser.ts';
+import { drained, notice } from './wake.ts';
+import type { Config } from './tab.ts';
+
+// What a service worker is, in the little of it this file uses. The DOM's
+// own `self` is a window, and a worker's is not, so it is asked for by the
+// shape it has here rather than by pulling a second global library in.
+type Client = { postMessage(message: unknown, transfer?: unknown[]): void };
+type Worker = {
+  quo?: Config;
+  clients: { matchAll(o?: { type?: string; includeUncontrolled?: boolean }): Promise<Client[]>; claim(): Promise<void> };
+  registration: { showNotification(title: string, options?: { body?: string; tag?: string }): Promise<void> };
+  skipWaiting(): Promise<void>;
+  addEventListener(type: string, fn: (event: { waitUntil(p: Promise<unknown>): void; data?: { json(): unknown } | null }) => void): void;
+};
+
+// The line the ring carried, when it carried one. A Web Push body is
+// encrypted to this subscription's own keys and the browser has already
+// opened it by the time it arrives here, so this is the world's own line
+// and not a guess at one. A ring that carried nothing, and a body that is
+// not a line, are the same thing: nothing to show yet.
+const carried = (event: { data?: { json(): unknown } | null }): { title: string; body: string } | null => {
+  try {
+    const said = event.data?.json() as { title?: unknown; body?: unknown } | null;
+    if (!said || typeof said.title !== 'string') return null;
+    return { title: said.title, body: typeof said.body === 'string' ? said.body : '' };
+  } catch {
+    return null;
+  }
+};
+
+const sw = globalThis as unknown as Worker;
+
+// Every step of a wake is bounded: a push event lives for as long as the
+// platform gives it, and a wake that found nothing shows nothing.
+const within = <T>(ms: number, work: Promise<T>, floor: T): Promise<T> => Promise.race([work, new Promise<T>((ok) => setTimeout(() => ok(floor), ms))]);
+
+// A page that is open holds the harbor. It is handed a port, it drains on
+// its own harbor and answers what it found; the first page to answer is the
+// one that held it, and no page answering means none did.
+async function fromPage(): Promise<JsonObject[] | null> {
+  const pages = await sw.clients.matchAll({ type: 'window', includeUncontrolled: true });
+  if (pages.length === 0) return null;
+  return within(
+    5000,
+    new Promise<JsonObject[] | null>((ok) => {
+      for (const page of pages) {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = (e: MessageEvent) => {
+          const said = (e.data ?? {}) as { missed?: unknown };
+          if (Array.isArray(said.missed)) ok(said.missed as JsonObject[]);
+        };
+        page.postMessage({ quo: 'wake' }, [channel.port2]);
+      }
+    }),
+    null,
+  );
+}
+
+// No page open: this worker is the device's harbor for the length of the
+// wake. A boot that meets the lock is a page that holds it and did not
+// answer, and this worker leaves it alone rather than opening a second
+// harbor over one seed.
+async function here(cfg: Config): Promise<JsonObject[]> {
+  const harbor = new BrowserHarbor('quo');
+  try {
+    await harbor.boot();
+  } catch {
+    return [];
+  }
+  try {
+    harbor.dial(cfg.quo);
+    return await within(
+      20000,
+      drained(
+        harbor,
+        Object.values(cfg.wards).map((w) => w.pk),
+      ),
+      [],
+    );
+  } finally {
+    await harbor.close();
+  }
+}
+
+async function woken(cfg: Config, said: { title: string; body: string } | null): Promise<void> {
+  const objects = (await fromPage()) ?? (await here(cfg));
+  // What the world sent is what the human reads, since the world knows what
+  // it rang about and this worker knows only what it managed to drain. What
+  // was drained composes the line when the ring carried none, and a ring
+  // with neither is a device that was already told: a notification saying
+  // so would be the doorbell inventing news.
+  if (!said && objects.length === 0) return;
+  const { title, body } = said ?? notice(objects);
+  // Bounded like every other step, because a browser build with no
+  // notification platform under it answers this call neither way, and a
+  // wake that waits on it is a worker the browser keeps alive for nothing.
+  await within(5000, sw.registration.showNotification(title, { body, tag: 'quo' }), undefined);
+}
+
+const cfg = sw.quo;
+sw.addEventListener('install', () => void sw.skipWaiting());
+sw.addEventListener('activate', (e) => e.waitUntil(sw.clients.claim()));
+if (cfg) sw.addEventListener('push', (e) => e.waitUntil(woken(cfg, carried(e))));

package/human/worlds.ts

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worlds in a tab, and the relations in each. A tab is a device with a
+// harbor of its own, and it keeps one local ward per far world, named by
+// the far ward's pk; inside it, one avatar per relation, since an avatar is
+// one standing and nothing more. An invitation names its ward by pk, so an
+// invitation is self-addressing: the local ward is chosen by the invitation
+// and never by the page it was opened on, and a fresh invitation is always a
+// fresh avatar, never a join on one that already holds her standing. Two
+// humans on one family tablet are two relations in one world; a shop and a
+// friend in one far ward are two as well. Nothing here touches a document:
+// `tab.ts` is the shell over this, and this is what the memory harbor proves.
+import type { Harbor, Hosted } from '@nervur-org/nervur/harbor';
+import { Avatar, USER } from '../beings/avatar.ts';
+import { settled } from '../dock/faculty.ts';
+
+// Which worlds a device has joined, and where each one lives. A tab learns
+// this from the page it is on, one world per origin, and needs it only to
+// list the others; an app is one origin and every world is somewhere else,
+// so the list is the only way back to any of them. It is addresses and
+// pks, nothing secret: what lets a device into a world is the standing in
+// its ward, and that is in the harbor.
+//
+// The pk is the key, because that is what an invitation names. A world met
+// again at a new address is the same world and keeps its ward. `home` is
+// whether the being reached there is her user being, which the user being
+// says in her describe, so a switcher can put home first.
+export type World = { pk: string; at: string; name: string; home?: boolean };
+export type Joined = { read(): World[]; write(worlds: World[]): void };
+
+// The list as a browser keeps it, the tab's and the app's alike: one item,
+// under the key the tab has always used. A device with no storage still
+// works and forgets, which is why every read has a floor.
+export const KEY = 'quo-worlds';
+export function inStorage(storage: Pick<Storage, 'getItem' | 'setItem'>): Joined {
+  return {
+    read: () => {
+      try {
+        const raw: unknown = JSON.parse(storage.getItem(KEY) ?? 'null');
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [];
+        return Object.entries(raw as Record<string, unknown>).flatMap(([pk, v]) => {
+          const w = (v ?? {}) as { at?: unknown; url?: unknown; name?: unknown; home?: unknown };
+          const at = typeof w.at === 'string' ? w.at : typeof w.url === 'string' ? w.url : '';
+          return at ? [{ pk, at, name: typeof w.name === 'string' ? w.name : '', ...(w.home === true ? { home: true } : {}) }] : [];
+        });
+      } catch {
+        return [];
+      }
+    },
+    write: (worlds) => {
+      try {
+        storage.setItem(KEY, JSON.stringify(Object.fromEntries(worlds.map((w) => [w.pk, { at: w.at, url: w.at, name: w.name, ...(w.home ? { home: true } : {}) }]))));
+      } catch {
+        /* forgets */
+      }
+    },
+  };
+}
+
+// One world joined, or met again: the same pk keeps its place in the list
+// and takes the newer address, any name it has gained and whether it is a
+// home, and a world not seen before goes to the end. The list is in the
+// order they were joined; `ordered` is how a switcher shows them.
+export function joined(list: World[], met: World): World[] {
+  const at = list.findIndex((w) => w.pk === met.pk);
+  if (at === -1) return [...list, met];
+  const out = [...list];
+  out[at] = { ...out[at], at: met.at, ...(met.name ? { name: met.name } : {}), ...(met.home !== undefined ? { home: met.home } : {}) };
+  return out;
+}
+
+// Home first, memberships behind it, each in the order joined: what a
+// person thinks of as "me" before the worlds that know an id of hers. A
+// membership with no home stands where it is.
+export function ordered(list: World[]): World[] {
+  return [...list.filter((w) => w.home), ...list.filter((w) => !w.home)];
+}
+
+// The local ward for a far world, by its pk: created on first sight, on
+// the tab's own seed, empty.
+export const localName = (pk: string): string => `w-${pk.slice(0, 16)}`;
+export async function world(harbor: Harbor, pk: string): Promise<Hosted> {
+  const name = localName(pk);
+  return harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+}
+
+// The relations held in a local ward: every avatar there who holds her
+// standing, by key, in the order they were born.
+export type Relation = { key: string; avatar: Avatar };
+export function relations(ward: Hosted): Relation[] {
+  const out: Relation[] = [];
+  for (const key of ward.keys()) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && a.standings[USER]) out.push({ key, avatar: a });
+  }
+  return out;
+}
+
+// A presence being for a relation not yet made: one who holds no standing
+// at a world, whether left by a guest who never came in or booted now under
+// the next free key. She is the one who knocks, as a guest or with an
+// invitation, and she becomes a relation the moment she takes her standing.
+// She is the being of that world who lives on this device, holding what the
+// box lends from her birth, and a bare tab lends her nothing.
+export async function fresh(ward: Hosted): Promise<Relation> {
+  for (const key of ward.keys()) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && !a.standings[USER]) return { key, avatar: a };
+  }
+  // The next free key, found by asking rather than by reading a table: boot
+  // refuses a key that has a row, so the ward is the one that knows, and a
+  // row whose class did not construct this run is a taken key the harbor
+  // has no object for. The bound is there because a loop that asks forever
+  // is a tab that hangs.
+  for (let n = 1; n <= 64; n++) {
+    const key = `r${n}`;
+    const out = (await ward.ask('boot', { key, class: 'Presence' })) as { error?: string };
+    if (out.error) continue;
+    // She takes what the box lends at her birth, and birth is synchronous
+    // while taking a standing is not. She is handed back when they have
+    // landed, not before: a screen painted from her describe a moment early
+    // is a page missing every faculty of the box, and nothing paints it
+    // again until the person navigates.
+    await settled();
+    return { key, avatar: ward.being(key) as Avatar };
+  }
+  throw new Error('the tab could not boot an avatar: every key it tries is taken');
+}

package/mcp/agent.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// The model side as an event-driven agent: the world is the loop. The user
+// being holds a standing to the agent's avatar and asks her when something
+// happens; that ask is a push, and her `notify` answers at once, so the ask
+// is never held open. The push lands in her inbox, which is the queue, in
+// her cells. This side drains the inbox one event at a time: it starts a
+// run with the event, and when the run ends she asks the user being back on
+// her own standing with the result. One run at a time, in the order the
+// events came, across a restart too, because the queue is in the partition
+// and not in this process. What a run may do is the gate; how it behaves
+// is its constitution, the folder it runs in.
+import { spawn } from 'node:child_process';
+import type { Json, JsonObject } from '@nervur-org/nervur';
+import type { Avatar } from '../beings/avatar.ts';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
+
+// A run: the event in, a result out. Two exist here: any function, and a
+// process in a folder. The runner of runner.ts is a third when handed as a
+// function.
+export type Run = (event: JsonObject) => Promise<Json>;
+
+// The ask on the user being that takes the result. Gated to devices; the
+// agent's client identity is what the gate reads.
+export const REPORT = 'report';
+
+// `claude -p` or any CLI agent: the command runs in the agent's folder with
+// the event, as JSON, as its last argument. The result is what it printed.
+// A non-zero exit is an error object with what it said on stderr.
+export function processRun(command: string, args: string[], dir: string): Run {
+  return (event) =>
+    new Promise((ok) => {
+      const child = spawn(command, [...args, JSON.stringify(event)], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      let err = '';
+      child.stdout.on('data', (c: Buffer) => (out += c.toString()));
+      child.stderr.on('data', (c: Buffer) => (err += c.toString()));
+      child.on('error', (e) => ok({ error: e.message }));
+      child.on('close', (code) => ok(code === 0 ? { output: out.trim() } : { error: `exit ${code}`, stderr: err.trim() }));
+    });
+}
+
+export type Agent = Serving & {
+  // Resolves when the queue is empty and no run is in flight.
+  idle(): Promise<void>;
+};
+
+// `after` runs when her cells changed and when an ask is done, as in the
+// other sides: a harbor that must write what the ward changed hooks it.
+export function agentSide(avatar: Avatar, run: Run, after: () => Promise<void> = async () => {}): Agent {
+  let draining: Promise<void> = Promise.resolve();
+  let open = true;
+  const inbox = () => avatar.cells.inbox as JsonObject[];
+
+  async function one(event: JsonObject): Promise<void> {
+    let result: Json;
+    try {
+      result = await run(event);
+    } catch (e) {
+      result = { error: e instanceof Error ? e.message : String(e) };
+    }
+    // The report is an ask like any other. Silence and unreached are told
+    // apart and dropped: a report is never retried, and never held.
+    const w = word(await avatar.call(REPORT, { event, result }));
+    if (w.word === 'silence' || w.word === 'unreached' || w.word === 'quo') say({ dropped: w.word === 'silence' ? SILENCE_TEXT : w.word === 'quo' ? wordText(w.name) : UNREACHED_TEXT });
+    await after();
+  }
+
+  // One at a time, first in first out, until the inbox is empty.
+  function drain(): Promise<void> {
+    draining = draining.then(async () => {
+      while (open && inbox().length > 0) {
+        const event = inbox().shift()!;
+        await after(); // the event left the queue before the run starts: a crash mid-run loses it, and never runs it twice
+        await one(event);
+      }
+    });
+    return draining;
+  }
+
+  // A dropped report is told to her other sides, if any: the agent itself has no ear for it.
+  const say = (object: JsonObject) => { for (const ear of avatar.ears) if (ear !== ear0) ear(object); };
+  const ear0 = () => void drain();
+  avatar.ears.add(ear0);
+  void drain(); // whatever waited while no side was up
+
+  return {
+    idle: () => draining,
+    close: async () => {
+      open = false;
+      avatar.ears.delete(ear0);
+      await draining;
+    },
+  };
+}

package/mcp/allow.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// The allow page, the one page of the model side's credential exchange,
+// mounted on the web route. It ends the credential exchange the way every
+// way in ends: with a knock. Nothing is typed to get in but an invitation,
+// the one the root minted for this client on the user being with `quo
+// invite` and sent as a link or a line; the avatar the identity boots
+// knocks with it, and the OAuth request completes with the identity the
+// human chose. No password, no cookie, no session: the invitation is the
+// credential, it is used once, and from the knock on there is no token
+// anywhere but the route's own grant.
+//
+// It is hand-written, and that is forced rather than chosen. The screen
+// paints a being's describe through a standing, and here there is neither:
+// a human at this page is a stranger, holding nothing, and the world she is
+// about to let something into is named by an invitation she has not typed
+// yet. The page grammar cannot say this page either, since its `form` node
+// is one of a being's asks by name and this form is nobody's ask. So it is
+// written out, like the door page and for the same reason: the claim that
+// no world writes a page is about worlds, and this page is Quo's.
+//
+// What it does not do is dress itself. It wears the one stylesheet every
+// screen wears, so a design that swaps the face swaps this page with it,
+// and there is no second look here to drift from the first.
+//
+//   GET  /allow?request=ID     who is asking, the identity it will be, and
+//                              the field for the invitation
+//   POST /allow                allow as that identity with that invitation,
+//                              or deny
+//
+// The invitation names its ward, so the world the client lands in is the
+// one the invitation was minted on, and there is nothing to choose.
+import type { Invitation } from '@nervur-org/nervur';
+import type { OAuth } from './oauth.ts';
+import { readForm } from './oauth.ts';
+import { invitationOf } from '../beings/link.ts';
+import { CSS } from '../human/style.ts';
+import { POLICY } from '../human/door.ts';
+import { MARK_SVG } from '../human/mark.ts';
+
+export type Join = (identity: string, invitation: Invitation, ward: string) => Promise<{ error?: string }>;
+export type Options = {
+  oauth: OAuth;
+  join: Join; // the daemon: boot or find the avatar for this identity in that world, and knock
+  worlds: () => { ward: string; pk: string; user: string }[]; // the worlds of this harbor, by name and pk
+};
+
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+const word = (s: unknown) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
+// A client's name as an identity: lowercase words joined by dashes.
+export const suggest = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'client';
+
+
+export class Exchange {
+  readonly o: Options;
+  constructor(o: Options) {
+    this.o = o;
+  }
+
+  // A page in, a page out: this side answers as the endpoint beside it does,
+  // and a path that is not one of its two is nothing it declines by
+  // answering nothing.
+  async handle(req: Request, rest: string): Promise<Response | undefined> {
+    const url = new URL(req.url);
+    const page = (status: number, body: string): Response =>
+      new Response(shell(body), { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': POLICY, 'referrer-policy': 'no-referrer' } });
+    const go = (to: string): Response => new Response(null, { status: 302, headers: { location: to, 'cache-control': 'no-store' } });
+
+    if (rest === '/allow' && req.method === 'GET') {
+      const request = url.searchParams.get('request') ?? '';
+      const p = this.o.oauth.pending(request);
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`);
+      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds()));
+    }
+    if (rest === '/allow' && req.method === 'POST') {
+      const f = await readForm(req);
+      const request = f.get('request') ?? '';
+      const p = this.o.oauth.pending(request);
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`);
+      if (f.get('decision') !== 'allow') {
+        const out = await this.o.oauth.deny(request);
+        return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
+      }
+      const worlds = this.o.worlds();
+      const again = (err: string) => page(400, allowForm(request, p.client.client_name, p.redirect_uri, word(f.get('identity')) ?? suggest(p.client.client_name), worlds, err));
+      const inv = invitationOf(f.get('invitation') ?? '');
+      if (!inv) return again('That is not an invitation.');
+      const world = worlds.find((w) => w.pk === inv.ward);
+      if (!world) return again('That invitation is for a world that does not live here.');
+      const identity = word(f.get('identity'));
+      if (identity === null || identity === world.user || identity === 'desk') return again('An identity is one word, and not the user or the desk.');
+      const joined = await this.o.join(identity, inv, world.ward);
+      if (joined.error) return again(`Not in: ${joined.error}.`);
+      const out = await this.o.oauth.complete(request, identity, world.ward);
+      return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
+    }
+    return undefined;
+  }
+}
+
+// The one stylesheet, and no colour of this page's own. The policy is the
+// one every page Quo writes itself is served under, `human/door.ts`, since
+// this is one of them: it runs no script of its own and wants none.
+const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body><main class="door">${body}</main></body></html>`;
+
+// The one page, and every sentence on it is something a human needs in
+// order to decide. Who is asking, what it will be able to see, that it is
+// bounded by a gate rather than by a promise, that she can end it, and
+// where it goes when she is done. The world is the invitation's, so the
+// page says which worlds live here and whose they are, and asks her to
+// choose none of them.
+const allowForm = (request: string, client: string, redirect: string, identity: string, worlds: { ward: string; user: string }[], err = '') => {
+  const whose = worlds.map((w) => `<strong>${esc(w.user)}</strong> in ${esc(w.ward)}`).join(', ');
+  return `${MARK_SVG}
+<h1 class="t-title">Allow ${esc(client)}?</h1>
+<p class="t-lead"><strong>${esc(client)}</strong> asks to be let into ${whose || 'a world here'}, as an occupant under a name you give it.</p>
+<p>It will see exactly what that world shows that name, decided by her gate and by nothing it can ask for. It cannot become anything else later, and it can be taken out of the world at any time.</p>
+<p class="t-quiet">The invitation below is the whole credential. It is spent once, here, and nothing is stored afterwards: no password, no cookie, no session. If you did not mint it for ${esc(client)} yourself, close this page.</p>
+<p class="t-quiet">When you are done it returns to <code>${esc(redirect)}</code>.</p>
+${err ? `<p class="answer error">${esc(err)}</p>` : ''}
+<form method="post" action=""><input type="hidden" name="request" value="${esc(request)}">
+<p><label for="i">The name it will be known by</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required></p>
+<p><label for="v">The invitation you minted for it</label><textarea id="v" name="invitation" autofocus required placeholder="as the link, or as printed"></textarea></p>
+<p><button type="submit" name="decision" value="allow">Allow</button> <button type="submit" name="decision" value="deny">Deny</button></p></form>`;
+};

package/mcp/http.ts

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+// The MCP endpoint on the mcp route: streamable HTTP, one session per
+// client connection, one avatar per client identity. A bearer names the
+// identity, the identity names the avatar, and the side from `server.ts`
+// runs beside her exactly as it does over stdio. A session belongs to the
+// identity that opened it; a bearer of another identity on the same session
+// is refused. Sessions live in memory and die with the daemon, which is
+// what a reconnect is for: the standing is the state, and it is on disk. A
+// client that goes away without a DELETE leaves a session behind; one idle
+// for an hour is dropped, since HTTP tells the server nothing else.
+import { WebStandardStreamableHTTPServerTransport as StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import type { Avatar } from '../beings/avatar.ts';
+import type { Serving } from '../beings/side.ts';
+import { mcpSide } from './server.ts';
+
+export type Session = { identity: string; ward: string; transport: StreamableHTTPServerTransport; serving: Serving; touched: number };
+export const SESSION_IDLE = 60 * 60 * 1000;
+// An identity in a world: one harbor holds many, and the grant names which.
+export type Resolve = (identity: string, ward: string) => Promise<{ avatar?: Avatar; error?: string }>;
+
+export class McpHttp {
+  readonly sessions = new Map<string, Session>();
+  readonly resolve: Resolve;
+  readonly after: () => Promise<void>;
+  now: () => number = () => Date.now();
+  // What to do with an identity the user being has removed: the route's
+  // revoke, so the client's tokens go with the occupant. Set by whoever
+  // mounts the route beside the credential exchange.
+  gone: (identity: string, ward: string) => Promise<void> = async () => {};
+  constructor(resolve: Resolve, after: () => Promise<void> = async () => {}) {
+    this.resolve = resolve;
+    this.after = after;
+  }
+
+  // `identity` is what the bearer named; the caller has already turned a
+  // stranger away. A request on a known session goes to it. A request with
+  // no session opens one, if it is an initialize; anything else is 400.
+  async handle(req: Request, identity: string, ward: string): Promise<Response> {
+    const sid = req.headers.get('mcp-session-id') ?? undefined;
+    const json = (status: number, body: unknown) => Response.json(body, { status });
+    this.sweep();
+    if (sid !== undefined) {
+      const s = this.sessions.get(sid);
+      if (!s) return json(404, { jsonrpc: '2.0', error: { code: -32001, message: 'no such session' }, id: null });
+      if (s.identity !== identity || s.ward !== ward) return json(403, { jsonrpc: '2.0', error: { code: -32003, message: 'not your session' }, id: null });
+      s.touched = this.now();
+      const out = await s.transport.handleRequest(req);
+      if (req.method === 'DELETE') this.drop(sid);
+      return out;
+    }
+    if (req.method !== 'POST') return json(400, { jsonrpc: '2.0', error: { code: -32000, message: 'no session' }, id: null });
+    const found = await this.resolve(identity, ward);
+    // A session opens on her describe, and admit already asked it. The one
+    // word the door says for an identity the user being removed is
+    // `removed`, under the key it bound for her avatar: in MCP's vocabulary
+    // that is 401, the client drops its token and starts the exchange again,
+    // and the route forgets the grant.
+    if (found.error === 'removed') {
+      await this.gone(identity, ward);
+      for (const [key, s] of this.sessions) if (s.identity === identity && s.ward === ward) this.drop(key);
+      return json(401, { jsonrpc: '2.0', error: { code: -32001, message: 'removed: the user being removed this identity' }, id: null });
+    }
+    if (!found.avatar) return json(500, { jsonrpc: '2.0', error: { code: -32002, message: found.error ?? 'no avatar' }, id: null });
+    const transport = new StreamableHTTPServerTransport({
+      // the web crypto's, not node's: a session id is a fresh uuid on every
+      // runtime and this endpoint names no terrain
+      sessionIdGenerator: () => globalThis.crypto.randomUUID(),
+      onsessioninitialized: (s) => {
+        this.sessions.set(s, { identity, ward, transport, serving, touched: this.now() });
+      },
+      onsessionclosed: (s) => this.drop(s),
+    });
+    const serving = await mcpSide(found.avatar, transport, this.after);
+    return transport.handleRequest(req);
+  }
+
+  sweep() {
+    const now = this.now();
+    for (const [sid, s] of this.sessions) if (now - s.touched > SESSION_IDLE) this.drop(sid);
+  }
+
+  drop(sid: string) {
+    const s = this.sessions.get(sid);
+    if (!s) return;
+    this.sessions.delete(sid);
+    void s.serving.close().catch(() => {});
+  }
+
+  async close() {
+    for (const sid of [...this.sessions.keys()]) this.drop(sid);
+  }
+}