@quo-systems/dock 0.2.1 → 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[];
@@ -55,3 +42,4 @@ export declare function admit(hosted: Hosted, identity: string, kind: 'local' |
     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,21 +96,6 @@ 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
@@ -175,12 +155,12 @@ 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 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 = () => [...harbor.wards]
@@ -195,7 +175,9 @@ export async function serve(dir, options = {}) {
                     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,
@@ -212,7 +194,7 @@ export async function serve(dir, options = {}) {
             }
             const ex = exchange;
             http.mount('/web', async (req, res, rest) => {
-                if (await tab(req, res, rest))
+                if (await web(req, res, rest))
                     return;
                 if (ex && (await ex.handle(req, res, rest)))
                     return;
@@ -268,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) {
@@ -417,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;
@@ -429,163 +369,6 @@ async function readRoutes(dir) {
         out.quo = r.quo.replace(/\/$/, '');
     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, at, password) {
-    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 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) => `<!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) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
-    const publicOf = (h) => h.partition.public ?? null;
-    const html = (status, res, body) => {
-        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);
-            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 === 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, 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');
@@ -607,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 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/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,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.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', 'unboot']);
@@ -114,7 +115,15 @@ 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);

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/screen.js

@@ -49,6 +49,7 @@ export async function screenSide(avatar, surface, options = {}) {
                 }
             }
         }
+        await after();
         show();
     };
     surface.onSubmit = (name, raw) => void submit(name, raw);

package/dist/human/tab.d.ts

@@ -2,8 +2,11 @@ import { USER } from '../beings/avatar.ts';
 export type Config = {
     quo: string;
     web: string;
-    ward: string;
-    pk: string;
+    wards: Record<string, {
+        pk: string;
+        public: boolean;
+    }>;
+    ward?: string;
 };
 export declare function start(cfg: Config, root?: HTMLElement): Promise<void>;
 export { USER };