@quo-systems/dock 0.1.0

package/cli/daemon.ts

@@ -0,0 +1,582 @@
+// SPDX-License-Identifier: Apache-2.0
+// The daemon: `quo serve`. One process holds the harbor and the ask pointer
+// of every ward in it. Two local doors, never mixed, each a unix socket only
+// the device's user can read:
+//
+//   quo.sock    the root. One line of JSON in, one line out.
+//               -> { id, ward?, method?, args?, via? }
+//               <- { id, result } | { id, error }
+//               A result of silence crosses as { silence: true }, because the
+//               wire has no symbol. With `via`, the line is an owner ask on
+//               another ward: `via` names a standing the user being holds
+//               at that ward, and the daemon asks on it in-process, as it
+//               drives an avatar for a side. The answer is what the far
+//               ward says to an owner at its door.
+//   side.sock   local sides. The first line names the client identity, and
+//               every line after is MCP, JSON-RPC, one message per line. The
+//               daemon runs the model side in-process with the avatar; the
+//               process on the other end of the socket is a pipe to stdio.
+//               -> { as, ward? }
+//               <- { ok: as } | { error }
+//               With `run`, the side is the runner instead: a model at a
+//               completions endpoint, driven from here. Every line after the
+//               hello is one line from the human and starts a turn; every
+//               final text the model says comes back as one line, whoever
+//               started the turn. The bearer, if any, is read from the
+//               device by the client and crosses only this socket.
+//               -> { as, ward?, run: { url, model, key?, turns? } }
+//               <- { ok: as } | { error }, then one line per final text
+//
+// The proof for a local side is that it reached side.sock: the daemon mints
+// a nonce for the connection and the desk's `local` verifier honours it
+// once. A `local` proof arriving any other way names no nonce and is refused.
+//
+// Agents have no door: `<dir>/agents.json` names each agent's identity, its
+// command and its folder, and the daemon admits her on the local proof and
+// runs the agent side beside her avatar for as long as it serves. A push to
+// 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
+// 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 { existsSync } from 'node:fs';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isSilence, isWord, wordOf, type JsonObject } from '@quo-systems/quo';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { DiskHarbor, type Hosted } from '../harbor/disk.ts';
+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 { Exchange } from '../mcp/web/exchange.ts';
+import { McpHttp } from '../mcp/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 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 }>;
+export type Options = { http?: { port: number; host?: string }; routes?: Routes; agents?: Agents; dial?: string[]; password?: () => string | undefined };
+
+// The sockets live in the harbor's folder, where the folder's own permissions
+// guard them. A unix socket path is short by law, about a hundred bytes on
+// macOS, so a deep folder gets its sockets in the temp dir under a name only
+// its path produces. Client and daemon compute the same answer.
+const socketPath = (dir: string, name: string): string => {
+  const inside = join(resolve(dir), `${name}.sock`);
+  if (inside.length < 100) return inside;
+  return join(tmpdir(), `quo-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 16)}-${name}.sock`);
+};
+export const sockPath = (dir: string) => socketPath(dir, 'quo');
+export const sidePath = (dir: string) => socketPath(dir, 'side');
+
+// The nonces this daemon minted, honoured once each. Two proof kinds share
+// 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 }>();
+// 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.
+const honour =
+  (kind: string): Verifier =>
+  (proof) => {
+    const who = typeof proof.nonce === 'string' ? NONCES.get(proof.nonce) : undefined;
+    if (!who || who.kind !== kind) return null;
+    NONCES.delete(proof.nonce as string);
+    const { kind: _, ...rest } = who;
+    return rest;
+  };
+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 }> {
+  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;
+  if (!avatar) {
+    const out = (await hosted.ask('boot', { key, class: 'Avatar' })) as { error?: string };
+    if (out.error) return { error: out.error };
+    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 });
+  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
+  if ('error' in entered && !('asks' in entered)) return { error: entered.error };
+  return { avatar };
+}
+
+async function listen(path: string, onConnection: (c: Socket) => void): Promise<Server> {
+  await unlink(path).catch(() => {}); // a socket left by a process that died holds nobody
+  const server = createServer(onConnection);
+  await new Promise<void>((ok, no) => {
+    server.once('error', no);
+    server.listen(path, () => ok());
+  });
+  await chmod(path, 0o600);
+  return server;
+}
+
+export async function serve(dir: string, options: Options = {}): Promise<Serving> {
+  const harbor = new DiskHarbor(dir);
+  await harbor.boot();
+  const sock = sockPath(harbor.dir);
+  const side = sidePath(harbor.dir);
+  const servers: (Server | HttpServer)[] = [];
+  let http: Http | null = null;
+  let oauth: OAuth | null = null;
+  let exchange: Exchange | null = null;
+  let mcp: McpHttp | null = null;
+  const agents = new Map<string, Agent>();
+  const quo: Quo = { sockets: new Set(), dialers: [] };
+  try {
+    servers.push(
+      await listen(sock, (c) => {
+        createInterface({ input: c }).on('line', (line) => {
+          void handle(harbor, line).then((reply) => c.write(reply + '\n'));
+        });
+        c.on('error', () => {});
+      }),
+    );
+    servers.push(await listen(side, (c) => void sideConnection(harbor, c)));
+    if (options.http) {
+      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);
+      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;
+      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 } : {};
+            },
+          });
+        }
+      }
+      const ex = exchange;
+      http.mount('/web', async (req, res, rest) => {
+        if (tab && (await tab(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');
+      });
+    }
+    for (const url of options.dial ?? (await readDial(harbor.dir))) quo.dialers.push(dial(harbor, url));
+    const main = harbor.wards.get('main');
+    if (main) {
+      for (const [identity, a] of Object.entries(options.agents ?? (await readAgents(harbor.dir)))) {
+        const admitted = await admit(main, identity, 'local');
+        if (!admitted.avatar) throw new Error(`agent ${identity}: ${admitted.error}`);
+        agents.set(identity, agentSide(admitted.avatar, processRun(a.command, a.args ?? [], a.dir), () => main.save()));
+      }
+    }
+  } catch (e) {
+    for (const s of servers) s.close();
+    for (const a of agents.values()) await a.close();
+    for (const d of quo.dialers) d.close();
+    await harbor.close(); // no daemon, no lease
+    throw e;
+  }
+  return {
+    harbor,
+    sock,
+    side,
+    http,
+    oauth,
+    exchange,
+    mcp,
+    agents,
+    quo,
+    close: async () => {
+      await mcp?.close();
+      for (const a of agents.values()) await a.close();
+      for (const d of quo.dialers) d.close();
+      for (const s of quo.sockets) s.close();
+      for (const s of servers) await new Promise<void>((ok) => s.close(() => ok()));
+      await unlink(sock).catch(() => {});
+      await unlink(side).catch(() => {});
+      await harbor.close();
+    },
+  };
+}
+
+// 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> {
+  c.on('error', () => {});
+  const lines = createInterface({ input: c });
+  const hello = await new Promise<string>((ok) => lines.once('line', ok));
+  let as: string, hosted, run: Model | undefined;
+  try {
+    const req = JSON.parse(hello) as { as?: string; ward?: string; run?: unknown };
+    hosted = harbor.wards.get(req.ward ?? 'main');
+    if (!hosted) throw new Error('no such ward');
+    if (typeof req.as !== 'string' || !/^[\w.-]+$/.test(req.as) || req.as === hosted.record.user || req.as === 'desk') throw new Error('as is a word, and not a being of the ward');
+    as = req.as;
+    if (req.run !== undefined) {
+      const r = req.run as Partial<Model>;
+      if (typeof r.url !== 'string' || typeof r.model !== 'string') throw new Error('run names a model: { url, model }');
+      run = { url: r.url, model: r.model, ...(typeof r.key === 'string' ? { key: r.key } : {}), ...(typeof r.turns === 'number' ? { turns: r.turns } : {}) };
+    }
+  } catch (e) {
+    c.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) + '\n');
+    return;
+  }
+  const admitted = await admit(hosted, as, 'local');
+  if (!admitted.avatar) return void c.end(JSON.stringify({ error: admitted.error }) + '\n');
+  const avatar = admitted.avatar;
+  c.write(JSON.stringify({ ok: as }) + '\n');
+
+  if (run) {
+    const runner = runnerSide(avatar, run, (text) => c.write(text + '\n'), () => hosted.save());
+    lines.on('line', (line) => {
+      runner.say(line).then(
+        (text) => {
+          if (text === null) c.write('\n'); // the ceiling: a turn with no final text is an empty line
+        },
+        (e: unknown) => c.write(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) + '\n'),
+      );
+    });
+    c.once('close', () => void runner.close().catch(() => {}));
+    return;
+  }
+
+  const transport: Transport = {
+    start: async () => {},
+    send: async (m: JSONRPCMessage) => {
+      c.write(JSON.stringify(m) + '\n');
+    },
+    close: async () => {
+      c.end();
+    },
+  };
+  lines.on('line', (line) => {
+    try {
+      transport.onmessage?.(JSON.parse(line) as JSONRPCMessage);
+    } catch (e) {
+      transport.onerror?.(e instanceof Error ? e : new Error(String(e)));
+    }
+  });
+  const serving = await mcpSide(avatar, transport, () => hosted.save());
+  c.once('close', () => {
+    transport.onclose?.();
+    void serving.close().catch(() => {});
+  });
+}
+
+async function handle(harbor: DiskHarbor, line: string): Promise<string> {
+  let id: unknown = null;
+  try {
+    const req = JSON.parse(line) as { id?: unknown; ward?: string; method?: string; args?: Record<string, unknown>; via?: unknown; reach?: { pk?: unknown; url?: unknown } };
+    id = req.id ?? null;
+    if (req.reach) {
+      // the directory is the harbor's, not a ward's: a hint from a link
+      if (typeof req.reach.pk !== 'string' || !/^[0-9a-f]{128}$/.test(req.reach.pk) || typeof req.reach.url !== 'string') return JSON.stringify({ id, error: 'a reach is a ward pk and a URL' });
+      await harbor.remember(req.reach.pk, req.reach.url);
+      return JSON.stringify({ id, result: { reach: req.reach.pk, url: req.reach.url } });
+    }
+    const hosted = harbor.wards.get(req.ward ?? 'main');
+    if (!hosted) return JSON.stringify({ id, error: 'no such ward' });
+    if (req.via !== undefined) {
+      // owning another ward is one of the human's standings, so her user
+      // being holds it, and the root asks on it. The keys rotate in the
+      // partition with every ask, and no door was passed, so the harbor
+      // saves here.
+      if (typeof req.via !== 'string') return JSON.stringify({ id, error: 'via is a standing of the user being' });
+      const user = hosted.being(hosted.record.user) as User | undefined;
+      const st = user?.standings[req.via];
+      if (!st) return JSON.stringify({ id, error: `no standing ${req.via} at the user being` });
+      try {
+        const out = await st.ask(req.method, (req.args ?? {}) as JsonObject);
+        return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : isWord(out) ? { word: wordOf(out) } : out });
+      } finally {
+        await hosted.save();
+      }
+    }
+    const out = await hosted.ask(req.method, req.args ?? {});
+    return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : out });
+  } catch (e) {
+    return JSON.stringify({ id, error: e instanceof Error ? e.message : String(e) });
+  }
+}
+
+// `<dir>/routes.json`: { mcp, web, quo? }, the public origins the proxy serves.
+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>;
+  if (typeof r.mcp !== 'string' || typeof r.web !== 'string') return null;
+  const out: Routes = { mcp: r.mcp.replace(/\/$/, ''), web: r.web.replace(/\/$/, '') };
+  if (typeof r.quo === 'string') out.quo = r.quo.replace(/\/$/, '');
+  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');
+  if (!existsSync(p)) return [];
+  const v = JSON.parse(await readFile(p, 'utf8')) as unknown;
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [];
+}
+
+// `<dir>/agents.json`: { <identity>: { command, args?, dir } }, one per agent.
+async function readAgents(dir: string): Promise<Agents> {
+  const p = join(dir, 'agents.json');
+  if (!existsSync(p)) return {};
+  const out: Agents = {};
+  for (const [identity, a] of Object.entries(JSON.parse(await readFile(p, 'utf8')) as Record<string, Partial<Agents[string]>>)) {
+    if (typeof a.command !== 'string' || typeof a.dir !== 'string') throw new Error(`agents.json: ${identity} needs a command and a dir`);
+    out[identity] = { command: a.command, args: Array.isArray(a.args) ? a.args.filter((x): x is string => typeof x === 'string') : [], dir: a.dir };
+  }
+  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;
+}