@quo-systems/dock 0.2.0 → 0.2.2

package/dist/cli/daemon.d.ts

@@ -1,21 +1,13 @@
-import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { Socket as Held, type Dialer } from '@quo-systems/quo/harbor';
 import { DiskHarbor, type Hosted } from '../harbor/disk.ts';
 import { type Avatar } from '../beings/index.ts';
 import { type Agent } from '../mcp/agent.ts';
-import { OAuth } from '../mcp/oauth.ts';
+import type { OAuth } 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[];
-};
+import { type Routes } from '../mcp/route.ts';
+import { type Http, type Quo } from './http.ts';
+export type { Handler, Http, Quo } from './http.ts';
+export type { Routes } from '../mcp/route.ts';
 export type Serving = {
     harbor: DiskHarbor;
     sock: string;
@@ -28,11 +20,6 @@ export type Serving = {
     quo: Quo;
     close(): Promise<void>;
 };
-export type Routes = {
-    mcp: string;
-    web: string;
-    quo?: string;
-};
 export type Agents = Record<string, {
     command: string;
     args?: string[];
@@ -50,8 +37,9 @@ export type Options = {
 };
 export declare const sockPath: (dir: string) => string;
 export declare const sidePath: (dir: string) => string;
-export declare function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake?: boolean): Promise<{
+export declare function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake?: boolean, reach?: boolean): Promise<{
     avatar?: Avatar;
     error?: string;
 }>;
 export declare function serve(dir: string, options?: Options): Promise<Serving>;
+export declare function readRoutes(dir: string): Promise<Routes | null>;

package/dist/cli/daemon.js

@@ -37,28 +37,20 @@
 // 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 } from 'node:net';
-import { createServer as createHttp } from 'node:http';
-import { WebSocketServer } from 'ws';
-import { build } from 'esbuild';
-import { fileURLToPath } from 'node:url';
-import { Socket as Held, dial, SUITE } from '@quo-systems/quo/harbor';
-import { unlink, chmod, readFile, writeFile, rename } from 'node:fs/promises';
+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';
@@ -68,9 +60,12 @@ import { Desk } from '../beings/index.js';
 import { mcpSide } from '../mcp/server.js';
 import { runnerSide } from '../mcp/runner.js';
 import { agentSide, processRun } from '../mcp/agent.js';
-import { OAuth, emptyStore } from '../mcp/oauth.js';
 import { Exchange } from '../mcp/web/exchange.js';
 import { McpHttp } from '../mcp/http.js';
+import { mcpRoute } from '../mcp/route.js';
+import { webRoute } from '../human/web.js';
+import { quoRoute } from '../harbor/quo.js';
+import { listenHttp } from './http.js';
 // 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
@@ -101,27 +96,12 @@ const honour = (kind) => (proof) => {
 };
 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) {
-    const chunks = [];
-    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, identity, kind, wake = false) {
+export async function admit(hosted, identity, kind, wake = false, reach = false) {
     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}`;
@@ -133,7 +113,7 @@ export async function admit(hosted, identity, kind, wake = false) {
         avatar = hosted.being(key);
     }
     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
@@ -175,34 +155,46 @@ export async function serve(dir, options = {}) {
             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, 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.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)))
+                if (await web(req, res, rest))
                     return;
                 if (ex && (await ex.handle(req, res, rest)))
                     return;
@@ -258,48 +250,6 @@ export async function serve(dir, options = {}) {
         },
     };
 }
-// 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, host, port, quo) {
-    const mounts = new Map();
-    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((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, c) {
@@ -407,7 +357,7 @@ async function handle(harbor, line) {
     }
 }
 // `<dir>/routes.json`: { mcp, web, quo? }, the public origins the proxy serves.
-async function readRoutes(dir) {
+export async function readRoutes(dir) {
     const p = join(dir, 'routes.json');
     if (!existsSync(p))
         return null;
@@ -419,119 +369,6 @@ async function readRoutes(dir) {
         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, at, password) {
-    // 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;
-    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);
-            let body = {};
-            try {
-                body = JSON.parse(raw?.toString() || '{}');
-            }
-            catch {
-                /* nothing to read */
-            }
-            const json = (status, v) => {
-                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, http, server, quo) {
-    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);
-        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 = new Held(ws, (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) {
     const p = join(dir, 'dial.json');
@@ -553,29 +390,3 @@ async function readAgents(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, http, routes, mcp) {
-    const file = join(dir, 'oauth.json');
-    const store = existsSync(file) ? { ...emptyStore(), ...JSON.parse(await readFile(file, 'utf8')) } : emptyStore();
-    let queue = Promise.resolve();
-    const persist = (s) => (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/dist/cli/http.d.ts

@@ -0,0 +1,17 @@
+import { 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;
+};
+export type Quo = {
+    sockets: Set<Held>;
+    dialers: Dialer[];
+};
+export declare function readAll(req: AsyncIterable<Buffer>): Promise<Buffer | undefined>;
+export declare function listenHttp(harbor: DiskHarbor, host: string, port: number, quo: Quo): Promise<Http & {
+    server: HttpServer;
+}>;

package/dist/cli/http.js

@@ -0,0 +1,60 @@
+// 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 } from 'node:http';
+// 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) {
+    const chunks = [];
+    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, host, port, quo) {
+    const mounts = new Map();
+    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((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/dist/cli/quo.js

@@ -8,9 +8,10 @@
 //   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
 //   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
@@ -29,11 +30,12 @@ import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { DiskHarbor } from '../harbor/disk.js';
-import { serve } from './daemon.js';
+import { serve, readRoutes } from './daemon.js';
 import { ask, side, reach } from './client.js';
+import { link, isInvitation } from '../beings/link.js';
 import { pilotSide } from '../mcp/pilot.js';
 import { estate } from './estate.js';
-const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove']);
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
 function parse(argv) {
     const flags = {};
     const rest = [];
@@ -113,13 +115,21 @@ async function main(argv) {
     if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
         const args = json ? JSON.parse(json) : {};
         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);
         return failed ? 1 : 0;
     }
-    console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+    console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|unboot|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
     return 2;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/harbor/quo.d.ts

@@ -0,0 +1,4 @@
+import type { Server as HttpServer } from 'node:http';
+import type { DiskHarbor } from './disk.ts';
+import { type Handler, type Quo } from '../cli/http.ts';
+export declare function quoRoute(harbor: DiskHarbor, server: HttpServer, quo: Quo): Handler;

package/dist/harbor/quo.js

@@ -0,0 +1,53 @@
+import { WebSocketServer } from 'ws';
+import { Socket as Held, SUITE } from '@quo-systems/quo/harbor';
+import { readAll } from '../cli/http.js';
+export function quoRoute(harbor, server, quo) {
+    const pks = () => [...harbor.doors.keys()];
+    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 = new Held(ws, (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());
+        });
+    });
+    // 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' };
+    return 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);
+        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));
+    };
+}

package/dist/human/door.d.ts

@@ -0,0 +1,5 @@
+export type Door = {
+    world?: string;
+    host: string;
+};
+export declare function door(at: Door): string;

package/dist/human/door.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// The door page: what a stranger sees where nothing lets them in. No
+// invitation in the fragment, no relation in this tab's harbor, and nobody
+// at the ward's door; or a harbor's root with no world to list. It is
+// Quo's page and not the estate's: it says what this is and that a world
+// here is entered by a link someone sends you, and it asks for nothing,
+// since there is nothing a stranger could type that would let them in. A
+// world that wants a face of its own has a public being with a look, or
+// its own page on its own origin; this is the default and nothing more.
+// Pure, strings in and strings out, under the tab's policy: no script, no
+// image that is not a data URI, styles from the one stylesheet.
+import { escape } from './html.js';
+// The mark: a ring with a gap, one being's voice reaching another's door.
+const MARK = 'data:image/svg+xml;base64,' +
+    btoa(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round"><circle cx="32" cy="32" r="22" stroke-dasharray="110 30" transform="rotate(-60 32 32)"/><circle cx="32" cy="32" r="5" fill="currentColor" stroke="none"/></svg>`);
+export function door(at) {
+    const where = at.world ? `<p class="where">${escape(at.world)} <span>at ${escape(at.host)}</span></p>` : `<p class="where">${escape(at.host)}</p>`;
+    return `<main class="door"><img class="mark" alt="" src="${MARK}"><h1>quo</h1>${where}<p class="lead">${at.world ? 'This world is entered by invitation.' : 'The worlds here are entered by invitation.'}</p><p>An invitation is a link someone sends you. Open it here, and you are in: no account, no password, nothing to type. What you can do inside is what the world shows you, and it is yours to keep on this device.</p><p class="quiet">Nothing on this page asks anything of you. If you were sent here without a link, ask the person who sent you for one.</p></main>`;
+}

package/dist/human/guest.d.ts

@@ -0,0 +1,3 @@
+import type { Avatar } from '../beings/avatar.ts';
+import type { Subject } from '../beings/side.ts';
+export declare function guest(avatar: Avatar, ward: string): Subject;