@quo-systems/dock 0.2.0 → 0.2.2

package/beings/user.ts

@@ -5,45 +5,79 @@
 // special only by the id the root chose for them: `desk`, the front desk,
 // who may ask her to invite a device; and each device, whose id is the
 // client identity the desk established.
-import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
 import type { Asker, Invitation, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import { Carrier } from './carry.ts';
 
 export const DESK = 'desk';
 const isDesk = (occ: OccupantRecord | undefined) => occ?.id === DESK;
 const isDevice = (occ: OccupantRecord | undefined) => occ !== undefined && occ.id !== DESK;
-const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client === 'string' ? occ.notes.client : null);
-// A device the human allowed to wake her other devices: the note says so.
-const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true;
+// A device is known by its client identity. The desk writes it as a note
+// when it asks her to mint; the root, minting on her directly, writes
+// nothing, and then the id the root chose is the identity.
+const rootMinted = (occ: OccupantRecord | undefined) => isDevice(occ) && occ?.notes.client === undefined;
+const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client === 'string' ? occ.notes.client : rootMinted(occ) ? occ!.id : null);
+// A device the human allowed to wake her other devices: the note says so,
+// or the root minted it, and the root's word needs no note.
+const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true || rootMinted(occ);
 
-export class User extends Being {
-  static override cells = { name: '', reports: [] as JsonObject[] };
+// She carries her standings, acme, the calendar, the house, for a device the
+// human allowed to reach them at the exchange: the note says so. A device
+// without the note sees her own asks alone, and a model sees acme only
+// because the human said it may. A device the root minted reaches: the root
+// is the owner of everything she holds and chose to mint it.
+export class User extends Carrier {
+  static override carries(occ: OccupantRecord | undefined): boolean {
+    return isDevice(occ) && (occ?.notes.reach === true || rootMinted(occ));
+  }
+  // `ways` holds a device's way back that could not be taken when it was
+  // handed over: the knock was unreached, a tab whose pk the far harbor had
+  // not bound yet, a phone in a tunnel. Nothing delivered spends nothing,
+  // so the invitation is tried again at the next push.
+  static override cells = { name: '', reports: [] as JsonObject[], ways: {} as Record<string, Invitation> };
   static override asks = {
     hello: { description: 'say hello, and hand back an invitation so she can reach you', input: { type: 'object', properties: { invitation: { type: 'object' } } } },
     whoami: { description: 'who she thinks you are', input: { type: 'object' }, for: isDevice },
-    device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+    device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' }, reach: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
     push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
     chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ: OccupantRecord | undefined) => client(occ) === 'agent' },
+    forget: { description: 'revoke a device: drop its way in and her way back to it, in one act', input: { type: 'object', properties: { client: { type: 'string' } }, required: ['client'] }, for: isDesk },
     report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
   };
 
   // Anyone may say hello. A device that hands her an invitation in the args
-  // is taken as a standing under its own id, so she can push to it later.
+  // is taken as a standing under its own id, so she can push to it later;
+  // if it cannot be taken now, it is kept and tried at the next push.
   async hello(args: JsonObject, asker: Asker) {
     if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
-      const inv = args.invitation as Invitation;
-      const back = await this.knock(inv);
-      if (!isSilence(back) && !isWord(back)) await this.take(`to:${asker.id}`, inv);
+      await this.wayBack(asker.id, args.invitation as Invitation);
     }
     return { welcome: asker.id ?? null, name: this.cells.name };
   }
 
+  // Take a device's way back, or keep it for later when the knock did not
+  // reach. A refusal spends the heir and is final; the way is dropped.
+  async wayBack(id: string, inv: Invitation): Promise<boolean> {
+    const ways = this.cells.ways as Record<string, Invitation>;
+    const back = await this.knock(inv);
+    if (!isSilence(back) && !isWord(back)) {
+      await this.take(`to:${id}`, inv);
+      delete ways[id];
+      return true;
+    }
+    if (isWord(back) && wordOf(back) !== 'unreached') delete ways[id];
+    else ways[id] = inv;
+    return false;
+  }
+
   whoami(_args: JsonObject, asker: Asker) {
     return { id: asker.id ?? null, client: client(this.occupant(asker)) };
   }
 
   // The front desk asks; she mints. The client identity goes into the
   // occupant's notes, and that is what every gate reads. `wake` is the
-  // human's word at the exchange that this device may wake her others.
+  // human's word at the exchange that this device may wake her others, and
+  // `reach` that it may see and ask what she holds: her standings, carried.
   async device(args: JsonObject) {
     const c = typeof args.client === 'string' ? args.client : null;
     if (c === null) return { error: 'client is a string' };
@@ -53,18 +87,38 @@ export class User extends Being {
     if (rec) {
       rec.notes.client = c;
       if (args.wake === true) rec.notes.wake = true;
+      if (args.reach === true) rec.notes.reach = true;
     }
     return inv as unknown as JsonObject;
   }
 
+  // Her way out and the device's way in are two relations, and Quo keeps
+  // them apart. She joins them herself, here, as her own rule: she does
+  // not reach a device she no longer admits. Without it a revoked device
+  // stops being able to ask her and keeps receiving everything she pushes.
   async push(args: JsonObject) {
     const c = typeof args.client === 'string' ? args.client : null;
-    const st = c === null ? undefined : this.standings[`to:${c}`];
+    if (c === null || !this.cells.occupants[c]) return { error: 'no such device, or it gave no way back' };
+    const kept = (this.cells.ways as Record<string, Invitation>)[c];
+    if (!this.standings[`to:${c}`] && kept) await this.wayBack(c, kept);
+    const st = this.standings[`to:${c}`];
     if (!st) return { error: 'no such device, or it gave no way back' };
     const out = await st.ask('notify', (args.object as JsonObject) ?? {});
     return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
   }
 
+  // Revocation is one act at her, because only she knows both ids. A side
+  // that had to remove two relations by hand could leave half of one
+  // standing, and every side would have to remember which half.
+  forget(args: JsonObject) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    if (c === null) return { error: 'client is a string' };
+    this.occupants.remove(c);
+    this.standings.remove(`to:${c}`);
+    delete (this.cells.ways as Record<string, Invitation>)[c];
+    return { forgot: c };
+  }
+
   chores() {
     return { chores: ['census', 'report'] };
   }

package/cli/daemon.ts

@@ -37,28 +37,21 @@
 // her from the user being runs the command in the folder with the event.
 //
 // A third door, for occupants from elsewhere, is one HTTP listener on
-// localhost that a reverse proxy fronts. Routes mount on it by path: `/mcp`
-// for the model side, `/web` for the exchange pages, `/quo` for other
-// harbors. It listens only when asked, and only on loopback: the proxy is
-// what faces the world, and the daemon never does.
-//
-// `/quo` is the socket door, the quo. route, and the proxy maps the quo.
-// hostname onto it, so a URL of that route is the base of every reach:
-// POST `/quo/<pk>` carries one ask to a pk this harbor holds or holds a
-// socket for, and an upgrade at `/quo` is a dialer's held socket,
-// announcing its pks to be bound. With
-// `--dial URL`, or `<dir>/dial.json`, this daemon is itself a dialer: it
-// holds one socket to each URL, announces its wards, and reconnects with
+// localhost that a reverse proxy fronts, `http.ts`. Routes mount on it by
+// path, and each lives in the folder whose truth it is: `/web`, the worlds'
+// pages and the exchange, in `human/web.ts` and `mcp/web/`; `/mcp`, the
+// model side behind its credential exchange, in `mcp/route.ts`; `/quo`, the
+// socket door, in `harbor/quo.ts`. It listens only when asked, and only on
+// loopback: the proxy is what faces the world, and the daemon never does.
+// With `--dial URL`, or `<dir>/dial.json`, this daemon is itself a dialer:
+// it holds one socket to each URL, announces its wards, and reconnects with
 // backoff, so a Mac behind NAT is reached through the droplet it dialed.
 import { createServer, type Server, type Socket } from 'node:net';
-import { createServer as createHttp, type IncomingMessage, type ServerResponse, type Server as HttpServer } from 'node:http';
-import { WebSocketServer } from 'ws';
-import { build } from 'esbuild';
-import { fileURLToPath } from 'node:url';
-import { Socket as Held, dial, SUITE, type Line, type Dialer } from '@quo-systems/quo/harbor';
-import { unlink, chmod, readFile, writeFile, rename } from 'node:fs/promises';
+import type { Server as HttpServer } from 'node:http';
+import { dial } from '@quo-systems/quo/harbor';
+import { unlink, chmod, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
@@ -70,17 +63,17 @@ import { Desk, type Avatar, type User, type Verifier } from '../beings/index.ts'
 import { mcpSide } from '../mcp/server.ts';
 import { runnerSide, type Model } from '../mcp/runner.ts';
 import { agentSide, processRun, type Agent } from '../mcp/agent.ts';
-import { OAuth, emptyStore, type Store } from '../mcp/oauth.ts';
+import type { OAuth } from '../mcp/oauth.ts';
 import { Exchange } from '../mcp/web/exchange.ts';
 import { McpHttp } from '../mcp/http.ts';
+import { mcpRoute, type Routes } from '../mcp/route.ts';
+import { webRoute } from '../human/web.ts';
+import { quoRoute } from '../harbor/quo.ts';
+import { listenHttp, type Http, type Quo } from './http.ts';
 
-export type Handler = (req: IncomingMessage, res: ServerResponse, rest: string) => void | Promise<void>;
-export type Http = { port: number; host: string; mount(prefix: string, handler: Handler): void };
-export type Quo = { sockets: Set<Held>; dialers: Dialer[] };
+export type { Handler, Http, Quo } from './http.ts';
+export type { Routes } from '../mcp/route.ts';
 export type Serving = { harbor: DiskHarbor; sock: string; side: string; http: Http | null; oauth: OAuth | null; exchange: Exchange | null; mcp: McpHttp | null; agents: Map<string, Agent>; quo: Quo; close(): Promise<void> };
-// The routes' public faces. From `<dir>/routes.json` on a device, or given.
-// `quo` is what a tab dials; without it the tab dials the daemon itself.
-export type Routes = { mcp: string; web: string; quo?: string };
 // The agents this daemon runs, by client identity. From `<dir>/agents.json`
 // on a device, or given.
 export type Agents = Record<string, { command: string; args?: string[]; dir: string }>;
@@ -102,7 +95,7 @@ export const sidePath = (dir: string) => socketPath(dir, 'side');
 // them: `local`, for a side that reached side.sock, and `web`, for a human
 // who passed the exchange pages. Both are the daemon vouching for someone it
 // saw itself; a proof of either kind arriving any other way names no nonce.
-const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean }>();
+const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean; reach?: boolean }>();
 // A nonce is minted for one kind and honoured under that kind alone: a tab's
 // nonce offered as a `local` proof names no nonce, so a proof of a kind still
 // arrives only the one way that kind is made.
@@ -117,28 +110,13 @@ const honour =
   };
 Desk.verifiers.local = honour('local');
 Desk.verifiers.web = honour('web');
-Desk.verifiers.tab = honour('tab'); // a tab that gave the owner password at the web route
-
-// What a request may carry, on the doors that read a body: enough for any ask
-// a ward seals, and not a body chosen by whoever is on the other end.
-const BODY = 1 << 20;
-async function readAll(req: AsyncIterable<Buffer>): Promise<Buffer | undefined> {
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const c of req) {
-    size += c.length;
-    if (size > BODY) return undefined;
-    chunks.push(c);
-  }
-  return Buffer.concat(chunks);
-}
 
 // Admit a client identity into a ward: find or boot her avatar, and enter
 // her with a nonce the desk honours once. On a reconnect she already holds
 // `user` and nothing is minted, so `wake`, the human's word that this
 // device may wake her others, is read the first time only; to change it,
 // remove the occupant and allow again. The one path for every side.
-export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false): Promise<{ avatar?: Avatar; error?: string }> {
+export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false, reach = false): Promise<{ avatar?: Avatar; error?: string }> {
   if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk') return { error: 'an identity is a word, and not a being of the ward' };
   const key = `avatar:${identity}`;
   let avatar = hosted.being(key) as Avatar | undefined;
@@ -148,7 +126,7 @@ export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'w
     avatar = hosted.being(key) as Avatar;
   }
   const nonce = randomBytes(16).toString('hex');
-  NONCES.set(nonce, wake ? { kind, user: hosted.record.user, client: identity, wake: true } : { kind, user: hosted.record.user, client: identity });
+  NONCES.set(nonce, { kind, user: hosted.record.user, client: identity, ...(wake ? { wake: true } : {}), ...(reach ? { reach: true } : {}) });
   const entered = await avatar.enter({ ward: hosted.pk }, { kind, nonce });
   NONCES.delete(nonce);
   await hosted.save(); // the knock went through the ward's own door, which the harbor never sees
@@ -193,33 +171,48 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       const { server, ...door } = await listenHttp(harbor, options.http.host ?? '127.0.0.1', options.http.port, quo);
       servers.push(server);
       http = door;
-      mountQuo(harbor, http, server, quo);
+      http.mount('/quo', quoRoute(harbor, server as HttpServer, quo));
       const routes = options.routes ?? (await readRoutes(harbor.dir));
       const password = options.password ?? (() => process.env.QUO_OWNER_PASSWORD);
-      const main = harbor.wards.get('main');
       const here = `http://${http.host}:${http.port}`;
-      // the tab page: always, on the daemon's own door when no route names a public one
-      const tab = main ? tabPages(main, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password) : null;
+      // the worlds' pages: always, on the daemon's own door when no route names a public one
+      const web = webRoute(harbor, { at: { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` } });
       if (routes) {
-        // the MCP endpoint: a bearer names an identity, the identity names her avatar, the side runs beside her
-        mcp = main ? new McpHttp((identity) => admit(main, identity, 'web'), () => main.save()) : null;
-        oauth = await mountOAuth(harbor.dir, http, routes, mcp);
-        if (mcp) mcp.gone = (identity) => oauth!.revoke(identity); // removal at the ward ends the grant at the route
-        if (main) {
-          exchange = new Exchange({
-            oauth,
-            password,
-            user: main.record.user,
-            admit: async (identity, wake) => {
-              const r = await admit(main, identity, 'web', wake);
-              return r.error ? { error: r.error } : {};
-            },
-          });
-        }
+        // the worlds a client may be allowed into: every ward with a public being, main first
+        const worlds = () =>
+          [...harbor.wards]
+            .filter(([, h]) => (h.partition as { public?: string | null }).public !== null)
+            .sort(([a], [b]) => (a === 'main' ? -1 : b === 'main' ? 1 : a.localeCompare(b)))
+            .map(([ward, h]) => ({ ward, user: h.record.user }));
+        // the MCP endpoint: a bearer names an identity in a world, the identity names her avatar there, the side runs beside her
+        mcp = new McpHttp(
+          async (identity, ward) => {
+            const hosted = harbor.wards.get(ward);
+            return hosted ? admit(hosted, identity, 'web') : { error: 'no such world' };
+          },
+          async () => {
+            for (const h of harbor.wards.values()) await h.save();
+          },
+        );
+        const route = await mcpRoute(harbor.dir, routes, mcp);
+        oauth = route.oauth;
+        http.mount('/mcp', route.handler);
+        mcp.gone = (identity, ward) => oauth!.revoke(identity, ward); // removal at the ward ends the grant at the route
+        exchange = new Exchange({
+          oauth,
+          password,
+          worlds,
+          admit: async (identity, wake, reach, ward) => {
+            const hosted = harbor.wards.get(ward);
+            if (!hosted) return { error: 'no such world' };
+            const r = await admit(hosted, identity, 'web', wake, reach);
+            return r.error ? { error: r.error } : {};
+          },
+        });
       }
       const ex = exchange;
       http.mount('/web', async (req, res, rest) => {
-        if (tab && (await tab(req, res, rest))) return;
+        if (await web(req, res, rest)) return;
         if (ex && (await ex.handle(req, res, rest))) return;
         res.writeHead(404, { 'content-type': 'text/plain' });
         res.end('no such page');
@@ -264,50 +257,6 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
   };
 }
 
-// The HTTP door. Loopback only; the proxy faces the world. A route mounts
-// under a prefix and gets the rest of the path. `/health` is the daemon's
-// own: the wards it hosts, by name and pk, and nothing a stranger can use.
-async function listenHttp(harbor: DiskHarbor, host: string, port: number, quo: Quo): Promise<Http & { server: HttpServer }> {
-  const mounts = new Map<string, Handler>();
-  const server = createHttp((req, res) => {
-    const url = new URL(req.url ?? '/', 'http://localhost');
-    if (url.pathname === '/health') {
-      // the wards it hosts, and the directory: pks and whether each is a
-      // socket held here, which is what an operator needs to see a dialer.
-      // Open to any origin: a tab reads it, and it holds nothing a stranger can use.
-      res.writeHead(200, { 'content-type': 'application/json', 'access-control-allow-origin': '*' });
-      res.end(
-        JSON.stringify({
-          ok: true,
-          wards: Object.fromEntries([...harbor.wards].map(([n, h]) => [n, h.pk])),
-          reaches: Object.fromEntries([...harbor.reaches].map(([pk, b]) => [pk, b.held ? 'held' : 'reach'])),
-          sockets: quo.sockets.size,
-          dialers: quo.dialers.map((d) => ({ url: d.url, open: d.socket !== null })),
-        }),
-      );
-      return;
-    }
-    for (const [prefix, handler] of mounts) {
-      if (url.pathname === prefix || url.pathname.startsWith(prefix + '/')) {
-        void Promise.resolve(handler(req, res, url.pathname.slice(prefix.length))).catch(() => {
-          if (!res.headersSent) res.writeHead(500);
-          res.end();
-        });
-        return;
-      }
-    }
-    res.writeHead(404, { 'content-type': 'application/json' });
-    res.end(JSON.stringify({ error: 'no such route' }));
-  });
-  await new Promise<void>((ok, no) => {
-    server.once('error', no);
-    server.listen(port, host, () => ok());
-  });
-  const address = server.address();
-  const bound = typeof address === 'object' && address !== null ? address.port : port;
-  return { server, host, port: bound, mount: (prefix, handler) => mounts.set(prefix.replace(/\/$/, ''), handler) };
-}
-
 // A side connection: hello, then MCP over the same lines, or, with `run`,
 // the human's lines in and the model's final texts out.
 async function sideConnection(harbor: DiskHarbor, c: Socket): Promise<void> {
@@ -409,7 +358,7 @@ async function handle(harbor: DiskHarbor, line: string): Promise<string> {
 }
 
 // `<dir>/routes.json`: { mcp, web, quo? }, the public origins the proxy serves.
-async function readRoutes(dir: string): Promise<Routes | null> {
+export async function readRoutes(dir: string): Promise<Routes | null> {
   const p = join(dir, 'routes.json');
   if (!existsSync(p)) return null;
   const r = JSON.parse(await readFile(p, 'utf8')) as Partial<Routes>;
@@ -419,122 +368,6 @@ async function readRoutes(dir: string): Promise<Routes | null> {
   return out;
 }
 
-// The tab page, `estate/human/tab.ts`, on the web route: the page, its
-// bundle built once from the source, and the one call of the exchange a tab
-// makes: the owner password for a nonce the desk honours under `tab`. The
-// avatar that knocks with it lives in the tab, not here, so nothing is
-// admitted on this side; the tab's harbor announces its ward and the user
-// being knocks back down that socket.
-function tabPages(main: Hosted, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
-  // The tab's source sits beside this file: `.ts` in the tree, `.js` once
-  // emitted into the package's dist. The bundler takes whichever is there.
-  const tabEntry = () => {
-    const js = fileURLToPath(new URL('../human/tab.js', import.meta.url));
-    return existsSync(js) ? js : fileURLToPath(new URL('../human/tab.ts', import.meta.url));
-  };
-  let bundle: Promise<string> | undefined;
-  const built = () =>
-    (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((o) => o.outputFiles[0]!.text));
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem;color:#222}input,button{font:inherit;padding:.4rem;margin:.2rem}pre{background:#f4f4f4;padding:.75rem;overflow:auto}</style>
-</head><body><script type="module">import { start } from './tab.js'; start(${JSON.stringify(at)});</script></body></html>`;
-  return async (req, res, rest) => {
-    if (rest === '/tab' && req.method === 'GET') {
-      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(html);
-      return true;
-    }
-    if (rest === '/tab.js' && req.method === 'GET') {
-      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(await built());
-      return true;
-    }
-    if (rest === '/tab/login' && req.method === 'POST') {
-      const raw = await readAll(req as AsyncIterable<Buffer>);
-      let body: { password?: unknown; identity?: unknown } = {};
-      try {
-        body = JSON.parse(raw?.toString() || '{}') as typeof body;
-      } catch {
-        /* nothing to read */
-      }
-      const json = (status: number, v: unknown) => {
-        res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
-        res.end(JSON.stringify(v));
-        return true;
-      };
-      const want = password();
-      if (want === undefined) return json(503, { error: 'closed: no owner password is set' });
-      const got = typeof body.password === 'string' ? body.password : '';
-      if (got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
-        await new Promise((ok) => setTimeout(ok, 300));
-        return json(401, { error: 'that is not the password' });
-      }
-      const identity = typeof body.identity === 'string' ? body.identity : '';
-      if (!/^[\w.-]{1,40}$/.test(identity) || identity === main.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
-      const nonce = randomBytes(16).toString('hex');
-      NONCES.set(nonce, { kind: 'tab', user: main.record.user, client: identity });
-      return json(200, { nonce, ward: main.pk });
-    }
-    return false;
-  };
-}
-
-// The quo. route. A request carries one ask to a pk; an upgrade is a held
-// socket. Bytes from here go to an own door or a held socket, never onward.
-function mountQuo(harbor: DiskHarbor, http: Http, server: HttpServer, quo: Quo): void {
-  const pks = () => [...harbor.doors.keys()];
-  // The route is public and carries sealed bytes, so any origin may POST
-  // to it: a tab on a world's web. reaching another world's quo. is the
-  // ordinary case, and a binary POST needs the preflight answered.
-  const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-headers': 'content-type, quo-suite' };
-  http.mount('/quo', async (req, res, rest) => {
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204, open);
-      return void res.end();
-    }
-    // The wire suite the caller speaks. Absent is this one, because a caller
-    // older than the header is this one. Anything else this door cannot open
-    // and says so as nothing delivered, rather than taking bytes that will
-    // never open and answering a silence that names no reason.
-    const suite = req.headers['quo-suite'];
-    if (suite !== undefined && suite !== String(SUITE)) {
-      res.writeHead(404, { 'content-type': 'application/json', ...open });
-      return void res.end(JSON.stringify({ error: `this door speaks wire suite ${SUITE}` }));
-    }
-    const pk = rest.slice(1);
-    if (req.method !== 'POST' || !/^[0-9a-f]{128}$/.test(pk)) {
-      res.writeHead(404, { 'content-type': 'application/json', ...open });
-      return void res.end(JSON.stringify({ error: 'POST /quo/<pk>' }));
-    }
-    const raw = await readAll(req as AsyncIterable<Buffer>);
-    const back = raw === undefined ? undefined : await harbor.deliver(pk, new Uint8Array(raw));
-    if (back === undefined) {
-      res.writeHead(404, { 'content-type': 'application/json', ...open });
-      return void res.end(JSON.stringify({ error: 'no reach for that pk' }));
-    }
-    res.writeHead(200, { 'content-type': 'application/octet-stream', ...open });
-    res.end(Buffer.from(back));
-  });
-  const wss = new WebSocketServer({ noServer: true });
-  server.on('upgrade', (req, socket, head) => {
-    const url = new URL(req.url ?? '/', 'http://localhost');
-    if (url.pathname.replace(/\/$/, '') !== '/quo') return void socket.destroy(); // the proxy rewrites the route root to /quo/
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      const s: Held = new Held(
-        ws as unknown as Line,
-        (pk, bytes) => harbor.deliver(pk, bytes),
-        (far) => void harbor.bind(far, s, true), // a dialer's claims, each proven at its door: held here, reachable through this socket
-        () => {
-          harbor.unbind(s);
-          quo.sockets.delete(s);
-        },
-      );
-      quo.sockets.add(s);
-      s.announce(pks());
-    });
-  });
-}
-
 // `<dir>/dial.json`: [url, ...], the quo. routes this daemon holds a socket to.
 async function readDial(dir: string): Promise<string[]> {
   const p = join(dir, 'dial.json');
@@ -554,29 +387,3 @@ async function readAgents(dir: string): Promise<Agents> {
   }
   return out;
 }
-
-// The mcp route: OAuth today, the MCP endpoint at step 9. Its store is
-// `<dir>/oauth.json`, the route's own and never a ward's: clients, pending
-// requests, codes and tokens, each mapping to a client identity at most.
-async function mountOAuth(dir: string, http: Http, routes: Routes, mcp: McpHttp | null): Promise<OAuth> {
-  const file = join(dir, 'oauth.json');
-  const store: Store = existsSync(file) ? { ...emptyStore(), ...(JSON.parse(await readFile(file, 'utf8')) as Partial<Store>) } : emptyStore();
-  let queue = Promise.resolve();
-  const persist = (s: Store) =>
-    (queue = queue.then(async () => {
-      await writeFile(file + '.tmp', JSON.stringify(s), { mode: 0o600 });
-      await rename(file + '.tmp', file);
-    }));
-  const oauth = new OAuth({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/login?request=${id}`, store, persist });
-  http.mount('/mcp', async (req, res, rest) => {
-    if (await oauth.handle(req, res, rest)) return;
-    if (rest === '/mcp') {
-      const identity = oauth.bearer(req);
-      if (identity === null || !mcp) return oauth.challenge(res);
-      return mcp.handle(req, res, identity);
-    }
-    res.writeHead(404, { 'content-type': 'application/json' });
-    res.end(JSON.stringify({ error: 'no such route' }));
-  });
-  return oauth;
-}

package/cli/http.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// The HTTP door: one listener on loopback that a reverse proxy fronts, and
+// the routes mount on it by path prefix. `/health` is the daemon's own: the
+// wards it hosts, by name and pk, and nothing a stranger can use. Each route
+// lives in its own folder, `human/web.ts`, `harbor/quo.ts`, `mcp/route.ts`,
+// and this file knows none of them: a route is a handler under a prefix.
+import { createServer as createHttp, type IncomingMessage, type ServerResponse, type Server as HttpServer } from 'node:http';
+import type { Socket as Held, Dialer } from '@quo-systems/quo/harbor';
+import type { DiskHarbor } from '../harbor/disk.ts';
+
+export type Handler = (req: IncomingMessage, res: ServerResponse, rest: string) => void | Promise<void>;
+export type Http = { port: number; host: string; mount(prefix: string, handler: Handler): void };
+// What the quo. route holds: the sockets held here and the dialers this
+// daemon runs. `/health` reports them.
+export type Quo = { sockets: Set<Held>; dialers: Dialer[] };
+
+// What a request may carry, on the doors that read a body: enough for any ask
+// a ward seals, and not a body chosen by whoever is on the other end.
+const BODY = 1 << 20;
+export async function readAll(req: AsyncIterable<Buffer>): Promise<Buffer | undefined> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > BODY) return undefined;
+    chunks.push(c);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function listenHttp(harbor: DiskHarbor, host: string, port: number, quo: Quo): Promise<Http & { server: HttpServer }> {
+  const mounts = new Map<string, Handler>();
+  const server = createHttp((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname === '/health') {
+      // the wards it hosts, and the directory: pks and whether each is a
+      // socket held here, which is what an operator needs to see a dialer.
+      // Open to any origin: a tab reads it, and it holds nothing a stranger can use.
+      res.writeHead(200, { 'content-type': 'application/json', 'access-control-allow-origin': '*' });
+      res.end(
+        JSON.stringify({
+          ok: true,
+          wards: Object.fromEntries([...harbor.wards].map(([n, h]) => [n, h.pk])),
+          reaches: Object.fromEntries([...harbor.reaches].map(([pk, b]) => [pk, b.held ? 'held' : 'reach'])),
+          sockets: quo.sockets.size,
+          dialers: quo.dialers.map((d) => ({ url: d.url, open: d.socket !== null })),
+        }),
+      );
+      return;
+    }
+    for (const [prefix, handler] of mounts) {
+      if (url.pathname === prefix || url.pathname.startsWith(prefix + '/')) {
+        void Promise.resolve(handler(req, res, url.pathname.slice(prefix.length))).catch(() => {
+          if (!res.headersSent) res.writeHead(500);
+          res.end();
+        });
+        return;
+      }
+    }
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'no such route' }));
+  });
+  await new Promise<void>((ok, no) => {
+    server.once('error', no);
+    server.listen(port, host, () => ok());
+  });
+  const address = server.address();
+  const bound = typeof address === 'object' && address !== null ? address.port : port;
+  return { server, host, port: bound, mount: (prefix, handler) => mounts.set(prefix.replace(/\/$/, ''), handler) };
+}