@quo-systems/dock 0.1.0 → 0.2.1

package/dist/beings/look.d.ts

@@ -0,0 +1,27 @@
+import type { Blueprint, Json } from '@quo-systems/quo';
+export type Hint = {
+    title?: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    icon?: string;
+};
+export type Look = {
+    name?: string;
+    logo?: string;
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    font?: string;
+    radius?: number;
+    order?: string[];
+    asks?: Record<string, Hint>;
+};
+export declare function sanitise(v: Json | undefined): Look;
+export declare const hint: (l: Look | undefined, name: string) => Hint;
+export type Group = {
+    asks?: string[];
+    look?: Json;
+};
+export declare function groups(bp: Blueprint | null): Record<string, Group>;
+export declare function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint;

package/dist/beings/look.js

@@ -0,0 +1,71 @@
+const COLOUR = /^#[0-9a-fA-F]{3,8}$/;
+const FONT = /^[\w\s,'"-]{1,80}$/;
+const LOGO = /^data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]{1,40000}$/;
+const NAME = /^[^<>&]{1,60}$/;
+const ICON = /^[^<>&"']{1,8}$/;
+const str = (v, re) => (typeof v === 'string' && re.test(v) ? v : undefined);
+// The look as a side may use it: every token held to its shape, everything
+// else gone. A value that is not an object is no look at all.
+export function sanitise(v) {
+    if (v === null || v === undefined || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const l = {};
+    const name = str(v.name, NAME);
+    if (name !== undefined)
+        l.name = name;
+    const logo = str(v.logo, LOGO);
+    if (logo !== undefined)
+        l.logo = logo;
+    for (const k of ['accent', 'background', 'foreground']) {
+        const c = str(v[k], COLOUR);
+        if (c !== undefined)
+            l[k] = c;
+    }
+    const font = str(v.font, FONT);
+    if (font !== undefined)
+        l.font = font;
+    if (typeof v.radius === 'number' && Number.isFinite(v.radius) && v.radius >= 0 && v.radius <= 40)
+        l.radius = Math.round(v.radius);
+    if (Array.isArray(v.order))
+        l.order = v.order.filter((x) => typeof x === 'string');
+    if (v.asks !== null && typeof v.asks === 'object' && !Array.isArray(v.asks)) {
+        const asks = {};
+        for (const [ask, h] of Object.entries(v.asks)) {
+            if (h === null || typeof h !== 'object' || Array.isArray(h))
+                continue;
+            const hint = {};
+            const title = str(h.title, NAME);
+            if (title !== undefined)
+                hint.title = title;
+            const icon = str(h.icon, ICON);
+            if (icon !== undefined)
+                hint.icon = icon;
+            for (const k of ['readOnly', 'destructive', 'idempotent'])
+                if (typeof h[k] === 'boolean')
+                    hint[k] = h[k];
+            if (Object.keys(hint).length)
+                asks[ask] = hint;
+        }
+        if (Object.keys(asks).length)
+            l.asks = asks;
+    }
+    return l;
+}
+// The one hint a side reads first: whether this ask is in the look at all.
+export const hint = (l, name) => l?.asks?.[name] ?? {};
+export function groups(bp) {
+    const n = bp?.notes;
+    const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
+    return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? g : {};
+}
+// The hint for one ask, hers or a standing's: a carried ask is looked up
+// under its bare name in that standing's look.
+export function hintFor(bp, mine, name) {
+    for (const [id, g] of Object.entries(groups(bp))) {
+        if (!g.asks?.includes(name))
+            continue;
+        const prefix = `${id}-`;
+        return hint(sanitise(g.look), name.startsWith(prefix) ? name.slice(prefix.length) : name);
+    }
+    return hint(mine, name);
+}

package/dist/beings/setup.js

@@ -7,7 +7,10 @@ export async function setup(hosted, user) {
         if (out.error)
             throw new Error(`init: ${out.error}`);
     };
-    await boot({ key: 'desk', class: 'Desk', public: true });
+    await boot({ key: 'desk', class: 'Desk' });
+    const pub = (await hosted.ask('public', { key: 'desk' }));
+    if (pub.error)
+        throw new Error(`init: ${pub.error}`);
     await boot({ key: user, class: 'User' });
     const inv = (await hosted.ask('invite', { being: user, id: DESK }));
     const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello' }));

package/dist/beings/side.d.ts

@@ -1,9 +1,16 @@
-import type { Answer, Json, JsonObject, WordName } from '@quo-systems/quo';
+import type { Answer, Blueprint, Json, JsonObject, Wanted, WordName } from '@quo-systems/quo';
 import type { Avatar } from './avatar.ts';
 export type Serving = {
     close(): Promise<void>;
 };
 export type Side = (avatar: Avatar) => Promise<Serving>;
+export type Subject = {
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    ears: Set<(object: JsonObject) => void>;
+};
 export type Word = {
     word: 'object';
     value: Json;

package/dist/beings/user.d.ts

@@ -1,10 +1,11 @@
-import { Being } from '@quo-systems/quo';
 import type { Asker, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import { Carrier } from './carry.ts';
 export declare const DESK = "desk";
 declare const isDesk: (occ: OccupantRecord | undefined) => boolean;
 declare const isDevice: (occ: OccupantRecord | undefined) => boolean;
 declare const mayWake: (occ: OccupantRecord | undefined) => boolean;
-export declare class User extends Being {
+export declare class User extends Carrier {
+    static carries(occ: OccupantRecord | undefined): boolean;
     static cells: {
         name: string;
         reports: JsonObject[];
@@ -39,6 +40,9 @@ export declare class User extends Being {
                     wake: {
                         type: string;
                     };
+                    reach: {
+                        type: string;
+                    };
                 };
                 required: string[];
             };
@@ -67,6 +71,19 @@ export declare class User extends Being {
             };
             for: (occ: OccupantRecord | undefined) => boolean;
         };
+        forget: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    client: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isDesk;
+        };
         report: {
             description: string;
             input: {
@@ -98,6 +115,13 @@ export declare class User extends Being {
         error?: undefined;
         pushed: import("@quo-systems/quo").Json;
     }>;
+    forget(args: JsonObject): {
+        error: string;
+        forgot?: undefined;
+    } | {
+        error?: undefined;
+        forgot: string;
+    };
     chores(): {
         chores: string[];
     };

package/dist/beings/user.js

@@ -5,21 +5,30 @@
 // special only by the id the root chose for them: `desk`, the front desk,
 // who may ask her to invite a device; and each device, whose id is the
 // client identity the desk established.
-import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { 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;
-export class User extends Being {
+// 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.
+export class User extends Carrier {
+    static carries(occ) {
+        return isDevice(occ) && occ?.notes.reach === true;
+    }
     static cells = { name: '', reports: [] };
     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 },
-        device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+        device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' }, reach: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
         push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
         chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ) => client(occ) === 'agent' },
+        forget: { description: 'revoke a device: drop its way in and her way back to it, in one act', input: { type: 'object', properties: { client: { type: 'string' } }, required: ['client'] }, for: isDesk },
         report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
     };
     // Anyone may say hello. A device that hands her an invitation in the args
@@ -38,7 +47,8 @@ export class User extends Being {
     }
     // The front desk asks; she mints. The client identity goes into the
     // occupant's notes, and that is what every gate reads. `wake` is the
-    // human's word at the exchange that this device may wake her others.
+    // human's word at the exchange that this device may wake her others, and
+    // `reach` that it may see and ask what she holds: her standings, carried.
     async device(args) {
         const c = typeof args.client === 'string' ? args.client : null;
         if (c === null)
@@ -51,17 +61,34 @@ export class User extends Being {
             rec.notes.client = c;
             if (args.wake === true)
                 rec.notes.wake = true;
+            if (args.reach === true)
+                rec.notes.reach = true;
         }
         return inv;
     }
+    // Her way out and the device's way in are two relations, and Quo keeps
+    // them apart. She joins them herself, here, as her own rule: she does
+    // not reach a device she no longer admits. Without it a revoked device
+    // stops being able to ask her and keeps receiving everything she pushes.
     async push(args) {
         const c = typeof args.client === 'string' ? args.client : null;
-        const st = c === null ? undefined : this.standings[`to:${c}`];
+        const st = c === null || !this.cells.occupants[c] ? undefined : 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 ?? {});
         return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
     }
+    // Revocation is one act at her, because only she knows both ids. A side
+    // that had to remove two relations by hand could leave half of one
+    // standing, and every side would have to remember which half.
+    forget(args) {
+        const c = typeof args.client === 'string' ? args.client : null;
+        if (c === null)
+            return { error: 'client is a string' };
+        this.occupants.remove(c);
+        this.standings.remove(`to:${c}`);
+        return { forgot: c };
+    }
     chores() {
         return { chores: ['census', 'report'] };
     }

package/dist/cli/daemon.d.ts

@@ -50,7 +50,7 @@ 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;
 }>;

package/dist/cli/daemon.js

@@ -121,7 +121,7 @@ async function readAll(req) {
 // `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 +133,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
@@ -178,31 +178,41 @@ export async function serve(dir, options = {}) {
             mountQuo(harbor, http, server, quo);
             const routes = options.routes ?? (await readRoutes(harbor.dir));
             const password = options.password ?? (() => process.env.QUO_OWNER_PASSWORD);
-            const main = harbor.wards.get('main');
             const here = `http://${http.host}:${http.port}`;
-            // the tab page: always, on the daemon's own door when no route names a public one
-            const tab = main ? tabPages(main, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password) : null;
+            // 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);
             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;
+                // 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();
+                });
                 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 } : {};
-                        },
-                    });
-                }
+                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 tab(req, res, rest))
                     return;
                 if (ex && (await ex.handle(req, res, rest)))
                     return;
@@ -419,36 +429,76 @@ 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.
+// 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 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>`;
+    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) => {
-        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;
+        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;
         }
-        if (rest === '/tab/login' && req.method === 'POST') {
+        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 {
@@ -471,15 +521,19 @@ function tabPages(main, at, password) {
                 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')
+            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: main.record.user, client: identity });
-            return json(200, { nonce, ward: main.pk });
+            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) {
@@ -569,10 +623,10 @@ async function mountOAuth(dir, http, routes, mcp) {
         if (await oauth.handle(req, res, rest))
             return;
         if (rest === '/mcp') {
-            const identity = oauth.bearer(req);
-            if (identity === null || !mcp)
+            const grant = oauth.bearer(req);
+            if (grant === null || !mcp)
                 return oauth.challenge(res);
-            return mcp.handle(req, res, identity);
+            return mcp.handle(req, res, grant.identity, grant.ward);
         }
         res.writeHead(404, { 'content-type': 'application/json' });
         res.end(JSON.stringify({ error: 'no such route' }));

package/dist/cli/estate/Caddyfile

@@ -0,0 +1,25 @@
+# Three hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the credential exchange in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}

package/dist/cli/estate/quo.service

@@ -0,0 +1,36 @@
+# The daemon on a droplet, as one user, forever. Install with:
+#   sudo cp droplet/quo.service /etc/systemd/system/quo.service
+#   sudo systemctl enable --now quo
+# The unit runs as the `quo` user, whose home holds the estate folder and
+# the harbor folder, so the seed, the lease and the sockets are that user's
+# alone. The HTTP door is loopback only; Caddy fronts it. See Caddyfile
+# beside this file.
+[Unit]
+Description=quo: one harbor on this device
+After=network.target
+
+[Service]
+User=quo
+Group=quo
+Environment=QUO_DIR=/home/quo/.quo
+Environment=QUO_HTTP=8787
+# QUO_OWNER_PASSWORD, root-only. Without it the exchange pages are closed.
+# CLAUDE_CODE_OAUTH_TOKEN, when an agent folder runs `claude -p`: the agent
+# reads its credential from the device, never from cells.
+EnvironmentFile=-/etc/quo/env
+WorkingDirectory=/home/quo/ESTATE
+ExecStart=/usr/bin/node /home/quo/ESTATE/node_modules/@quo-systems/dock/dist/cli/quo.js serve
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=10
+NoNewPrivileges=true
+ProtectSystem=strict
+# Agents run in their folders and Claude Code keeps its own state in the
+# user's home; both must be writable for a run to happen, and a harbor
+# with no agent has neither.
+ReadWritePaths=/home/quo/.quo -/home/quo/agents -/home/quo/.claude -/home/quo/.claude.json /tmp
+PrivateTmp=false
+
+[Install]
+WantedBy=multi-user.target

package/dist/cli/estate.d.ts

@@ -0,0 +1,5 @@
+export declare function estate(dir: string, domain: string): Promise<{
+    dir: string;
+    name: string;
+    files: string[];
+}>;

package/dist/cli/estate.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// `quo estate DIR --domain D`: an estate folder, written once, of the shape
+// every estate has. One folder per harbor, here the first, `droplet/`: the
+// quo directory that device runs minus what it mints, its routes under the
+// domain, no agents, no classes of its own, and that device's unit and
+// Caddyfile. A package file that depends on this dock and nothing else, and
+// one document to fill in. An estate needs nothing the dock does not give
+// it, and this is the dock giving it.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// This package's own version, read beside the emitted or the source tree.
+async function version() {
+    for (const rel of ['../package.json', '../../package.json']) {
+        const at = fileURLToPath(new URL(rel, import.meta.url));
+        if (!existsSync(at))
+            continue;
+        const pkg = JSON.parse(await readFile(at, 'utf8'));
+        if (pkg.name === '@quo-systems/dock' && pkg.version)
+            return pkg.version;
+    }
+    return '0.1.0';
+}
+const template = (name) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+export async function estate(dir, domain) {
+    if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(domain))
+        throw new Error(`estate: ${domain} is not a domain`);
+    if (existsSync(join(dir, 'package.json')))
+        throw new Error(`estate: ${dir} already holds a package`);
+    const name = basename(dir);
+    const files = {
+        'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@quo-systems/dock': `^${await version()}` } }, null, 2) + '\n',
+        [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the quo\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
+        'droplet/routes.json': JSON.stringify({ mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}` }) + '\n',
+        'droplet/agents.json': '{}\n',
+        'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
+        'droplet/quo.service': (await template('quo.service')).replaceAll('ESTATE', name),
+        'droplet/Caddyfile': (await template('Caddyfile')).replaceAll('DOMAIN', domain),
+    };
+    for (const [rel, text] of Object.entries(files)) {
+        await mkdir(join(dir, rel, '..'), { recursive: true });
+        await writeFile(join(dir, rel), text);
+    }
+    return { dir, name, files: Object.keys(files) };
+}