@quo-systems/dock 0.2.1 → 0.2.2

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 }>;
@@ -117,21 +110,6 @@ 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
@@ -193,12 +171,12 @@ 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 here = `http://${http.host}:${http.port}`;
       // the worlds' pages: always, on the daemon's own door when no route names a public one
-      const tab = worldPages(harbor, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password);
+      const web = webRoute(harbor, { at: { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` } });
       if (routes) {
         // the worlds a client may be allowed into: every ward with a public being, main first
         const worlds = () =>
@@ -216,7 +194,9 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
             for (const h of harbor.wards.values()) await h.save();
           },
         );
-        oauth = await mountOAuth(harbor.dir, http, routes, mcp);
+        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,
@@ -232,7 +212,7 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       }
       const ex = exchange;
       http.mount('/web', async (req, res, rest) => {
-        if (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');
@@ -277,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> {
@@ -422,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>;
@@ -432,163 +368,6 @@ async function readRoutes(dir: string): Promise<Routes | null> {
   return out;
 }
 
-// The worlds on the web route. A world is a ward with a public being, and
-// its address is `/web/<ward>`: the tab page, `human/tab.ts`, told which
-// ward and which pk, so that its guest is that ward's public being rendered
-// by the screen, whatever class she is. `/web/` lists the worlds. The bundle
-// is built once from the source beside this file, `.ts` in the tree, `.js`
-// once emitted into the package's dist. `/web/<ward>/login` is the one call
-// of the dock's own way in 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 page carries a content security policy: scripts from this origin
-// only and never inline, connections to this origin and the quo. route the
-// tab dials, images from data URIs and this origin, and nothing else. So
-// even a bug in a renderer cannot become a script, and no look can reach a
-// server. The config crosses in a JSON script, which the policy allows.
-const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
-function worldPages(harbor: DiskHarbor, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
-  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 quoOrigin = (() => {
-    try {
-      const u = new URL(at.quo);
-      return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
-    } catch {
-      return '';
-    }
-  })();
-  const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors '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>${body}</body></html>`;
-  const esc = (v: string) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
-  const publicOf = (h: Hosted) => (h.partition as { public?: string | null }).public ?? null;
-  const html = (status: number, res: ServerResponse, body: string) => {
-    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
-    res.end(shell(body));
-    return true;
-  };
-  return async (req, res, rest) => {
-    const parts = rest.split('/').filter(Boolean);
-    if (req.method === 'GET' && (rest === '' || rest === '/')) {
-      const list = [...harbor.wards]
-        .filter(([, h]) => publicOf(h) !== null)
-        .map(([n, h]) => `<li><a href="${at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
-        .join('');
-      return html(200, res, `<h1>worlds</h1>${list ? `<ul>${list}</ul>` : '<p>no ward here has a public being</p>'}`);
-    }
-    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;
-    }
-    const wardName = parts[0] ?? '';
-    if (!wardName || RESERVED_PATHS.has(wardName)) return false;
-    const hosted = harbor.wards.get(wardName);
-    if (!hosted) return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
-    if (parts.length === 1 && req.method === 'GET') {
-      if (publicOf(hosted) === null) return html(404, res, `<h1>not a world</h1><p>ward ${esc(wardName)} has no public being, so nobody is at its door.</p>`);
-      const cfg = { quo: at.quo, web: at.web, ward: wardName, pk: hosted.pk };
-      return html(200, res, `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${at.web}/tab.js"></script>`);
-    }
-    if (parts.length === 2 && parts[1] === '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 === hosted.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: hosted.record.user, client: identity, reach: true });
-      return json(200, { nonce, ward: hosted.pk });
-    }
-    return false;
-  };
-}
-
-// The tab's stylesheet: one, light and dark, honouring the variables a look
-// sets on a section. The page owns layout; a far being paints inside her
-// section and nowhere else.
-const CSS = ":root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px}body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}";
-
-// 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');
@@ -608,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 grant = oauth.bearer(req);
-      if (grant === null || !mcp) return oauth.challenge(res);
-      return mcp.handle(req, res, grant.identity, grant.ward);
-    }
-    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) };
+}

package/cli/quo.ts

@@ -8,7 +8,7 @@
 //   quo serve  [--dir D] [--http PORT] [--dial URL]  the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to URL
 //   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
 //   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
-//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }; with routes.json naming web., the answer carries the link
 //   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
 //   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
 //   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
@@ -30,8 +30,9 @@ import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { DiskHarbor } from '../harbor/disk.ts';
-import { serve } from './daemon.ts';
+import { serve, readRoutes } from './daemon.ts';
 import { ask, side, reach, type Run } from './client.ts';
+import { link, isInvitation } from '../beings/link.ts';
 import { pilotSide } from '../mcp/pilot.ts';
 import { estate } from './estate.ts';
 
@@ -116,7 +117,13 @@ async function main(argv: string[]): Promise<number> {
   if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
     const args = json ? (JSON.parse(json) as Record<string, unknown>) : {};
     const out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
-    print('error' in out ? { error: out.error } : out.result);
+    // an invitation minted here is handed on as a link when the harbor's
+    // routes name a web. origin: the world's page with the invitation in
+    // the fragment, one string to send to the person it is for
+    const minted = cmd === 'invite' && !via && 'result' in out && isInvitation(out.result) ? out.result : null;
+    const routes = minted ? await readRoutes(dir) : null;
+    if (minted && routes) print({ ...minted, link: link(`${routes.web}/${encodeURIComponent(ward)}`, minted) });
+    else print('error' in out ? { error: out.error } : out.result);
     // an error object the ward answered is an ordinary answer, and still a
     // non-zero exit, so a script can tell a boot that happened from one that did not.
     const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);

package/dist/beings/avatar.js

@@ -4,7 +4,9 @@
 // exactly one standing, `user`, and everything her side asks goes through
 // it; the user being reaches her only to push, and she hands the push to
 // every side she has. A side is in-process with her, holds the object, and
-// calls the three methods below. Nothing of a side is in her cells.
+// calls the four methods below: one of the two ways in, `enter` behind a
+// route's proof or `join` with an invitation, then `tools` and `call`.
+// Nothing of a side is in her cells.
 import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
 // Her one standing, and the id under which the user being pushes to her.
 // Two ids for one far being, because standings and occupants share one

package/dist/beings/index.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// The beings every side shares. See quo-estate.md, the trunk.
+// The beings every side shares. See quo-dock.md, the trunk.
 export { User, DESK } from './user.js';
 export { Desk } from './desk.js';
 export { Avatar, USER, PUSHER } from './avatar.js';

package/dist/beings/user.d.ts

@@ -1,4 +1,4 @@
-import type { Asker, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import type { Asker, Invitation, JsonObject, OccupantRecord } from '@quo-systems/quo';
 import { Carrier } from './carry.ts';
 export declare const DESK = "desk";
 declare const isDesk: (occ: OccupantRecord | undefined) => boolean;
@@ -9,6 +9,7 @@ export declare class User extends Carrier {
     static cells: {
         name: string;
         reports: JsonObject[];
+        ways: Record<string, Invitation>;
     };
     static asks: {
         hello: {
@@ -103,6 +104,7 @@ export declare class User extends Carrier {
         welcome: string | null;
         name: import("@quo-systems/quo").Json;
     }>;
+    wayBack(id: string, inv: Invitation): Promise<boolean>;
     whoami(_args: JsonObject, asker: Asker): {
         id: string | null;
         client: string | null;

package/dist/beings/user.js

@@ -10,18 +10,28 @@ import { Carrier } from './carry.js';
 export const DESK = 'desk';
 const isDesk = (occ) => occ?.id === DESK;
 const isDevice = (occ) => occ !== undefined && occ.id !== DESK;
-const client = (occ) => (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) => 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) => isDevice(occ) && occ?.notes.client === undefined;
+const client = (occ) => (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) => isDesk(occ) || occ?.notes.wake === true || rootMinted(occ);
 // 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.
+// 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 carries(occ) {
-        return isDevice(occ) && occ?.notes.reach === true;
+        return isDevice(occ) && (occ?.notes.reach === true || rootMinted(occ));
     }
-    static cells = { name: '', reports: [] };
+    // `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 cells = { name: '', reports: [], ways: {} };
     static 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 },
@@ -32,16 +42,30 @@ export class User extends Carrier {
         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, asker) {
         if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
-            const inv = args.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);
         }
         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, inv) {
+        const ways = this.cells.ways;
+        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, asker) {
         return { id: asker.id ?? null, client: client(this.occupant(asker)) };
     }
@@ -72,7 +96,12 @@ export class User extends Carrier {
     // stops being able to ask her and keeps receiving everything she pushes.
     async push(args) {
         const c = typeof args.client === 'string' ? args.client : null;
-        const st = c === null || !this.cells.occupants[c] ? 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[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 ?? {});
@@ -87,6 +116,7 @@ export class User extends Carrier {
             return { error: 'client is a string' };
         this.occupants.remove(c);
         this.standings.remove(`to:${c}`);
+        delete this.cells.ways[c];
         return { forgot: c };
     }
     chores() {