@quo-systems/dock 0.2.2 → 0.2.4

package/dist/human/tree.js

@@ -0,0 +1,89 @@
+import { escape } from './html.js';
+const ROLES = new Set(['title', 'lead', 'body', 'quiet', 'label']);
+const AS = new Set(['auto', 'text', 'table', 'cards', 'list']);
+const TEXT = 4000; // characters a text node may carry
+const DEPTH = 12; // how deep a tree may nest
+const WIDE = 200; // children a container may have
+const NAME = /^[\w.-]{1,80}$/;
+// A value held to the grammar, or null. Children that fail are dropped and
+// the container kept; a container with nothing left is kept empty, since an
+// empty region is a design and not a fault.
+export function sanitiseTree(v, depth = 0) {
+    if (depth > DEPTH || v === null || typeof v !== 'object' || Array.isArray(v))
+        return null;
+    const o = v;
+    switch (o.kind) {
+        case 'stack':
+        case 'row': {
+            const of = Array.isArray(o.of) ? o.of.slice(0, WIDE).map((c) => sanitiseTree(c, depth + 1)).filter((c) => c !== null) : [];
+            return { kind: o.kind, of };
+        }
+        case 'text': {
+            if (typeof o.text !== 'string')
+                return null;
+            const n = { kind: 'text', text: o.text.slice(0, TEXT) };
+            if (typeof o.role === 'string' && ROLES.has(o.role))
+                n.role = o.role;
+            return n;
+        }
+        case 'image': {
+            if (typeof o.src !== 'string' || !/^data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+$/i.test(o.src))
+                return null;
+            const n = { kind: 'image', src: o.src };
+            if (typeof o.alt === 'string')
+                n.alt = o.alt.slice(0, 200);
+            return n;
+        }
+        case 'form':
+            return typeof o.ask === 'string' && NAME.test(o.ask) ? { kind: 'form', ask: o.ask } : null;
+        case 'answer': {
+            if (typeof o.ask !== 'string' || !NAME.test(o.ask))
+                return null;
+            const n = { kind: 'answer', ask: o.ask };
+            if (typeof o.as === 'string' && AS.has(o.as))
+                n.as = o.as;
+            return n;
+        }
+        case 'standing':
+            return typeof o.id === 'string' && NAME.test(o.id) ? { kind: 'standing', id: o.id } : null;
+        case 'standings':
+            return { kind: 'standings' };
+        default:
+            return null;
+    }
+}
+// The names a tree asks the answers of: what a side runs on her behalf so
+// the page opens with what it shows, when the ask needs nothing typed.
+export function answersIn(n, out = []) {
+    if (n.kind === 'answer')
+        out.push(n.ask);
+    if (n.kind === 'stack' || n.kind === 'row')
+        for (const c of n.of)
+            answersIn(c, out);
+    return out;
+}
+const ROLE_TAG = { title: 'h1', lead: 'p', body: 'p', quiet: 'p', label: 'p' };
+export function paint(n, p) {
+    switch (n.kind) {
+        case 'stack':
+        case 'row':
+            return `<div class="${n.kind}">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+        case 'text': {
+            const role = n.role ?? 'body';
+            return `<${ROLE_TAG[role]} class="t-${role}">${escape(n.text)}</${ROLE_TAG[role]}>`;
+        }
+        case 'image':
+            return `<img class="picture" alt="${escape(n.alt ?? '')}" src="${n.src}">`;
+        case 'form':
+            return p.form(n.ask);
+        case 'answer':
+            return p.answer(n.ask, n.as ?? 'auto');
+        case 'standing':
+            return p.standing(n.id);
+        case 'standings':
+            return p.standings();
+    }
+}
+// A painter with nothing behind it: for a page that names no ask, the door
+// page and any page painted before anyone is in.
+export const nobody = { form: () => '', answer: () => '', standing: () => '', standings: () => '' };

package/dist/human/web.d.ts

@@ -6,4 +6,5 @@ export type WebOptions = {
         web: string;
     };
 };
+export declare const TAB_CODE = "tab/index.ts";
 export declare function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean>;

package/dist/human/web.js

@@ -1,16 +1,30 @@
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import process from 'node:process';
 import { build } from 'esbuild';
 import { door } from './door.js';
 // The paths under `/web` that are the exchange's, never a ward's name.
-const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+const RESERVED_PATHS = new Set(['allow', 'tab.js', 'beings.js']);
+// The world's code for the tab: a module in the harbor folder, the twin of
+// `classes/index.ts`, exporting by name the classes the tab boots into its
+// local ward for a world of this harbor. Served bundled as `beings.js` on
+// this origin, and one origin is one world's code.
+export const TAB_CODE = 'tab/index.ts';
 export function webRoute(harbor, o) {
     const tabEntry = () => {
         const js = fileURLToPath(new URL('./tab.js', import.meta.url));
         return existsSync(js) ? js : fileURLToPath(new URL('./tab.ts', import.meta.url));
     };
+    const beingsEntry = join(harbor.dir, TAB_CODE);
+    const bundled = (entry) => 
+    // the entry may sit in a harbor folder with no node_modules of its own, as on a droplet whose
+    // estate folder is the working directory: what it imports is resolved from there too
+    build({ entryPoints: [entry], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false, nodePaths: [join(process.cwd(), 'node_modules')] }).then((out) => out.outputFiles[0].text);
     let bundle;
-    const built = () => (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((out) => out.outputFiles[0].text));
+    const built = () => (bundle ??= bundled(tabEntry()));
+    let beings;
+    const builtBeings = () => (beings ??= bundled(beingsEntry));
     const quoOrigin = (() => {
         try {
             const u = new URL(o.at.quo);
@@ -41,7 +55,7 @@ export function webRoute(harbor, o) {
     };
     const wards = () => Object.fromEntries([...harbor.wards].map(([n, h]) => [n, { pk: h.pk, public: publicOf(h) !== null }]));
     const tab = (ward) => {
-        const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), ...(ward ? { ward } : {}) };
+        const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), beings: existsSync(beingsEntry), ...(ward ? { ward } : {}) };
         return `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
     };
     return async (req, res, rest) => {
@@ -58,6 +72,14 @@ export function webRoute(harbor, o) {
             res.end(await built());
             return true;
         }
+        // the world's code for the tab, when the harbor folder holds any; a harbor with none has no such path
+        if (rest === '/beings.js' && req.method === 'GET') {
+            if (!existsSync(beingsEntry))
+                return false;
+            res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+            res.end(await builtBeings());
+            return true;
+        }
         const wardName = parts[0] ?? '';
         if (!wardName || RESERVED_PATHS.has(wardName))
             return false;
@@ -82,14 +104,20 @@ const CSS = [
     '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}',
+    // a being of the world running in the tab: her own section under the far page
+    'section.local{border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);margin:1.5rem 0;padding-top:.5rem}section.local header:empty{display:none}',
     '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}',
+    // a page in the grammar: regions, roles, cards
+    '.page .stack{display:flex;flex-direction:column;gap:.5rem}.page .row{display:flex;flex-wrap:wrap;gap:.5rem 1rem;align-items:baseline}',
+    '.page .t-title{font-size:2rem;font-weight:600;letter-spacing:-.02em;margin:.5rem 0}.page .t-lead{font-size:1.25rem;margin:.25rem 0}.page .t-label{font-size:.8rem;letter-spacing:.06em;text-transform:uppercase;color:var(--mute);margin:0}.page .t-quiet{color:var(--mute);font-size:.9rem}.page .t-body{margin:.25rem 0}',
+    '.page .picture{max-height:6rem}.cards{display:flex;flex-wrap:wrap;gap:.75rem}.card{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);padding:.5rem .75rem}',
     // the door page: one column, generous air, the mark, a word, a sentence
     'main.door{min-height:70vh;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;max-width:32rem;margin:0 auto;padding:3rem 0;font-family:ui-serif,Georgia,"Times New Roman",serif}',
-    'main.door .mark{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
-    'main.door h1{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
-    'main.door .where{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .where span{text-transform:none;letter-spacing:0}',
-    'main.door .lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
+    'main.door .picture{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
+    'main.door .t-title{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
+    'main.door .t-label{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .t-label span{text-transform:none;letter-spacing:0}',
+    'main.door .t-lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
     'main.door p{font-size:1.05rem;line-height:1.6;margin:0 0 1rem;max-width:30rem}',
-    'main.door .quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
+    'main.door .t-quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
 ].join('');

package/dist/mcp/oauth.js

@@ -14,8 +14,8 @@
 //   POST /token                                       code or refresh for an access token
 //
 // The web route finishes a request by calling `complete(request, identity)`
-// after its own login and allow pages; that returns the redirect that
-// carries the code back to the client. Step 8 builds those pages.
+// after its allow page, where the human hands the invitation the root minted;
+// that returns the redirect that carries the code back to the client.
 import { randomBytes, createHash } from 'node:crypto';
 // A token, a code, a client id: every key here is a string the far side chose,
 // and a bare lookup would find `__proto__` and hand back an object with no

package/dist/mcp/route.js

@@ -17,7 +17,7 @@ export async function mcpRoute(dir, routes, mcp) {
         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 });
+    const oauth = new OAuth({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/allow?request=${id}`, store, persist });
     const handler = async (req, res, rest) => {
         if (await oauth.handle(req, res, rest))
             return;

package/dist/mcp/runner.js

@@ -3,9 +3,12 @@ export const TURNS = 10;
 // Her describe, spoken as a tools array. Name, description and input are
 // verbatim, with the one narrowing an endpoint has asked for: an ask that
 // declares no properties is sent with an empty `properties`, because
-// LM Studio refuses a parameters schema without one.
+// LM Studio refuses a parameters schema without one. `look` and `page` are
+// presentation, for a screen, and are not functions.
 export function tools(bp) {
-    return bp.asks.map((a) => {
+    return bp.asks
+        .filter((a) => a.name !== 'look' && a.name !== 'page')
+        .map((a) => {
         const t = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
         if (a.description !== undefined)
             t.function.description = a.description;

package/dist/mcp/server.js

@@ -23,7 +23,7 @@ export const DESCRIBE = { name: 'describe', description: 'the empty ask: her des
 // reads. The `look` ask itself is presentation, and is not a tool.
 export function tools(bp, look = {}) {
     const asks = bp.asks
-        .filter((a) => a.name !== 'look')
+        .filter((a) => a.name !== 'look' && a.name !== 'page') // presentation, for a screen, and not a tool
         .map((a) => {
         const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
         if (a.description !== undefined)

package/dist/mcp/web/exchange.d.ts

@@ -1,26 +1,22 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Invitation } from '@quo-systems/quo';
 import type { OAuth } from '../oauth.ts';
-export declare const SESSION_TTL: number;
-export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{
+export type Join = (identity: string, invitation: Invitation, ward: string) => Promise<{
     error?: string;
 }>;
 export type Options = {
     oauth: OAuth;
-    password: () => string | undefined;
-    admit: Admit;
+    join: Join;
     worlds: () => {
         ward: string;
+        pk: string;
         user: string;
     }[];
-    now?: () => number;
 };
 export declare const suggest: (name: string) => string;
+export declare function invitationOf(text: string): Invitation | null;
 export declare class Exchange {
     readonly o: Options;
-    readonly secret: NonSharedBuffer;
     constructor(o: Options);
-    now(): number;
-    mint(): string;
-    valid(req: IncomingMessage): boolean;
     handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean>;
 }

package/dist/mcp/web/exchange.js

@@ -1,21 +1,5 @@
-// SPDX-License-Identifier: Apache-2.0
-// The exchange pages on the web route. Two static pages, hand-written, and
-// explicitly not the human side: they render no blueprint. They end the
-// credential exchange the way the trunk says every route does: a proof is
-// made, the front desk trades it for an invitation, the avatar knocks, and
-// the OAuth request completes with the client identity the human chose.
-//
-//   GET  /login?request=ID     the owner password, from QUO_OWNER_PASSWORD
-//   POST /login                sets a short session cookie, goes to /allow
-//   GET  /allow?request=ID     who is asking, and the identity they will be
-//   POST /allow                allow as that identity, or deny
-//
-// The password is the device's, read from the environment the way an envoy
-// reads a secret, never through cells. With none set, the exchange is closed.
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { readForm } from '../oauth.js';
-export const SESSION_TTL = 10 * 60 * 1000; // a login lives as long as a request: ten minutes
-const COOKIE = 'quo_exchange';
+import { parse } from '../../beings/link.js';
 const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
 const word = (s) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
 // A client's name as an identity: lowercase words joined by dashes.
@@ -24,127 +8,92 @@ export const suggest = (name) => name
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-|-$/g, '')
     .slice(0, 40) || 'client';
+// The invitation as typed: the link's compact form, `ward.heir.secret`, or
+// the whole link it came in, or the JSON value `quo invite` printed.
+export function invitationOf(text) {
+    const t = text.trim();
+    const hash = t.indexOf('#');
+    const linked = parse(hash === -1 ? `#quo=${t}` : t.slice(hash));
+    if (linked?.heir)
+        return linked;
+    try {
+        const v = JSON.parse(t);
+        if (v && typeof v === 'object' && typeof v.ward === 'string' && typeof v.heir === 'string' && typeof v.secret === 'string')
+            return { ward: v.ward, heir: v.heir, secret: v.secret };
+    }
+    catch {
+        /* not JSON either */
+    }
+    return null;
+}
 export class Exchange {
     o;
-    secret = randomBytes(32); // sessions die with the daemon, and that is fine: they live ten minutes
     constructor(o) {
         this.o = o;
     }
-    now() {
-        return this.o.now?.() ?? Date.now();
-    }
-    // ---- the session cookie: an expiry, signed
-    mint() {
-        const exp = String(this.now() + SESSION_TTL);
-        return `${exp}.${createHmac('sha256', this.secret).update(exp).digest('base64url')}`;
-    }
-    valid(req) {
-        const m = /(?:^|;\s*)quo_exchange=([^;]+)/.exec(req.headers.cookie ?? '');
-        const [exp, sig] = (m?.[1] ?? '').split('.');
-        if (!exp || !sig)
-            return false;
-        const want = createHmac('sha256', this.secret).update(exp).digest('base64url');
-        return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)) && Number(exp) > this.now();
-    }
     async handle(req, res, rest) {
         const url = new URL(req.url ?? '/', 'http://localhost');
-        const page = (status, body, headers = {}) => {
-            res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...headers });
+        const page = (status, body) => {
+            res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
             res.end(shell(body));
+            return true;
         };
-        const go = (to, headers = {}) => {
-            res.writeHead(302, { location: to, 'cache-control': 'no-store', ...headers });
+        const go = (to) => {
+            res.writeHead(302, { location: to, 'cache-control': 'no-store' });
             res.end();
+            return true;
         };
-        if (rest === '/login' && req.method === 'GET') {
-            const request = url.searchParams.get('request') ?? '';
-            const p = this.o.oauth.pending(request);
-            if (!p)
-                return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`), true;
-            if (this.o.password() === undefined)
-                return page(503, `<h1>Closed</h1><p>This world takes no logins: no owner password is set.</p>`), true;
-            if (this.valid(req))
-                return go(`/allow?request=${encodeURIComponent(request)}`), true;
-            return page(200, loginForm(request, p.client.client_name)), true;
-        }
-        if (rest === '/login' && req.method === 'POST') {
-            const f = await readForm(req);
-            const request = f.get('request') ?? '';
-            const p = this.o.oauth.pending(request);
-            if (!p)
-                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-            const want = this.o.password();
-            const got = f.get('password') ?? '';
-            if (want === undefined)
-                return page(503, `<h1>Closed</h1>`), true;
-            if (got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
-                await new Promise((ok) => setTimeout(ok, 300));
-                return page(401, loginForm(request, p.client.client_name, 'That is not the password.')), true;
-            }
-            return go(`/allow?request=${encodeURIComponent(request)}`, { 'set-cookie': `${COOKIE}=${this.mint()}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${SESSION_TTL / 1000}` }), true;
-        }
         if (rest === '/allow' && req.method === 'GET') {
             const request = url.searchParams.get('request') ?? '';
             const p = this.o.oauth.pending(request);
             if (!p)
-                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-            if (!this.valid(req))
-                return go(`/login?request=${encodeURIComponent(request)}`), true;
-            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`);
+            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds()));
         }
         if (rest === '/allow' && req.method === 'POST') {
             const f = await readForm(req);
             const request = f.get('request') ?? '';
             const p = this.o.oauth.pending(request);
             if (!p)
-                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-            if (!this.valid(req))
-                return go(`/login?request=${encodeURIComponent(request)}`), true;
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`);
             if (f.get('decision') !== 'allow') {
                 const out = await this.o.oauth.deny(request);
-                return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
+                return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
             }
             const worlds = this.o.worlds();
-            const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
+            const again = (err) => page(400, allowForm(request, p.client.client_name, p.redirect_uri, word(f.get('identity')) ?? suggest(p.client.client_name), worlds, err));
+            const inv = invitationOf(f.get('invitation') ?? '');
+            if (!inv)
+                return again('That is not an invitation.');
+            const world = worlds.find((w) => w.pk === inv.ward);
             if (!world)
-                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
+                return again('That invitation is for a world that does not live here.');
             const identity = word(f.get('identity'));
             if (identity === null || identity === world.user || identity === 'desk')
-                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
-            const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
-            if (admitted.error)
-                return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
+                return again('An identity is one word, and not the user or the desk.');
+            const joined = await this.o.join(identity, inv, world.ward);
+            if (joined.error)
+                return again(`Not in: ${joined.error}.`);
             const out = await this.o.oauth.complete(request, identity, world.ward);
-            return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
+            return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
         }
         return false;
     }
 }
 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>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input,textarea{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}textarea{font-family:ui-monospace,monospace;min-height:5rem}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
 </head><body>${body}</body></html>`;
-const loginForm = (request, client, err = '') => `<h1>${esc(client)} wants in</h1>
-<p>Log in as the owner of this world to decide.</p>
-${err ? `<p class="err">${esc(err)}</p>` : ''}
-<form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
-<label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
-<button type="submit">Log in</button></form>`;
-// The world is a choice when the harbor has more than one; the user named
-// is the first world's, and the page says which world each identity lands in.
+// The one page. The world is the invitation's, so the page only says which
+// worlds live here and whose they are.
 const allowForm = (request, client, redirect, identity, worlds, err = '') => {
-    const user = worlds[0]?.user ?? '';
-    const pick = worlds.length > 1
-        ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
-        : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+    const whose = worlds.map((w) => `<strong>${esc(w.user)}</strong> in ${esc(w.ward)}`).join(', ');
     return `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
-<p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of ${whose || 'a world here'}.</p>
+<p>It will see exactly what the user being shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
-${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
-<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
-<label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
+<label for="v">Invitation</label><textarea id="v" name="invitation" autofocus required placeholder="the invitation the owner minted for this client, as the link or as printed"></textarea>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
 };

package/harbor/capacitor.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store on a phone: the wrapped form over Capacitor's Filesystem and
+// a secure-storage plugin. One key per harbor in the Keychain, this device
+// only, so it never travels in a backup; one sealed file per ward, seed,
+// partition and record as one blob, in the folder iCloud does not copy.
+//
+//   <Library/NoCloud>/quo/<harbor>/wards/<name>.sealed
+//   <Library/NoCloud>/quo/<harbor>/reach.json
+//   Keychain: quo-<harbor>                32 bytes as hex
+//
+// Custody is the backup question, and opening the store answers it: a key
+// with no folder is a reinstall, and the stale key is deleted; a folder
+// with no key is a restore to another device, and the unreadable files are
+// deleted. Either way the harbor starts fresh and there is never a twin.
+import { Capacitor } from '@capacitor/core';
+import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
+import { SecureStorage, KeychainAccess } from '@aparajita/capacitor-secure-storage';
+import { arithmetic } from '@quo-systems/quo/ward';
+import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+import { sealKey, seal, open } from './seal.ts';
+
+const { hex, unhex } = arithmetic;
+type Blob = { seed: string; partition: Record<string, unknown>; record: WardRecord };
+
+// Where the files live: the folder iCloud does not copy on iOS, the app's
+// own files on Android, whose manifest says no backup.
+const directory = Capacitor.getPlatform() === 'ios' ? Directory.LibraryNoCloud : Directory.Data;
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Filesystem.stat({ path, directory });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class Native implements Store {
+  readonly harbor: string;
+  readonly #key: CryptoKey;
+  readonly #queues = new Map<string, Promise<void>>();
+  private constructor(harbor: string, key: CryptoKey) {
+    this.harbor = harbor;
+    this.#key = key;
+  }
+
+  // Open one harbor's store, applying the custody rule, minting the key and
+  // the folder when this is a fresh install.
+  static async open(harbor: string): Promise<Native> {
+    const item = `quo-${harbor}`;
+    const root = `quo/${harbor}`;
+    // `set` keeps JSON, so `get` parses it back; `getItem` would hand back the quotes.
+    const got = await SecureStorage.get(item, false, false);
+    let secret = typeof got === 'string' ? got : undefined;
+    const folder = await exists(root);
+    if (secret && !folder) {
+      await SecureStorage.remove(item);
+      secret = undefined;
+    }
+    if (!secret && folder) await Filesystem.rmdir({ path: root, directory, recursive: true });
+    if (!secret) {
+      secret = hex(crypto.getRandomValues(new Uint8Array(32)));
+      await SecureStorage.set(item, secret, false, false, KeychainAccess.afterFirstUnlockThisDeviceOnly);
+    }
+    // mkdir refuses a folder that exists, recursive or not.
+    if (!(await exists(`${root}/wards`))) await Filesystem.mkdir({ path: `${root}/wards`, directory, recursive: true });
+    return new Native(harbor, await sealKey(secret));
+  }
+
+  // Everything this harbor has, key and files: what a person does by hand
+  // to leave a device, and what a test does between two openings.
+  static async wipe(harbor: string): Promise<void> {
+    await SecureStorage.remove(`quo-${harbor}`);
+    if (await exists(`quo/${harbor}`)) await Filesystem.rmdir({ path: `quo/${harbor}`, directory, recursive: true });
+  }
+
+  #path(name: string) {
+    return `quo/${this.harbor}/wards/${name}.sealed`;
+  }
+  async #read(name: string): Promise<Blob> {
+    const { data } = await Filesystem.readFile({ path: this.#path(name), directory, encoding: Encoding.UTF8 });
+    return JSON.parse(new TextDecoder().decode(await open(this.#key, (data as string).trim()))) as Blob;
+  }
+  // A sealed ward is rewritten whole, so the read sits inside the queue
+  // with the write: two changes to one ward never lose each other's part.
+  #keep(name: string, change: (b: Blob | undefined) => Blob): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const blob = change((await exists(this.#path(name))) ? await this.#read(name) : undefined);
+      const sealed = await seal(this.#key, new TextEncoder().encode(JSON.stringify(blob)));
+      await Filesystem.writeFile({ path: this.#path(name), directory, data: sealed + '\n', encoding: Encoding.UTF8 });
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+
+  async list(): Promise<string[]> {
+    const { files } = await Filesystem.readdir({ path: `quo/${this.harbor}/wards`, directory });
+    return files.filter((f) => f.name.endsWith('.sealed')).map((f) => f.name.slice(0, -'.sealed'.length));
+  }
+
+  async load(name: string): Promise<Kept | undefined> {
+    if (!(await exists(this.#path(name)))) return undefined;
+    const b = await this.#read(name);
+    return { seed: unhex(b.seed), partition: b.partition, record: b.record };
+  }
+
+  async put(name: string, kept: Kept): Promise<void> {
+    if (await exists(this.#path(name))) throw new Error(`ward ${name} already exists on this device`);
+    return this.#keep(name, () => ({ seed: hex(kept.seed), partition: kept.partition, record: kept.record }));
+  }
+
+  async save(name: string, partition: Record<string, unknown>): Promise<void> {
+    if (!(await exists(this.#path(name)))) return; // a name not kept is nothing
+    return this.#keep(name, (b) => ({ ...b!, partition }));
+  }
+
+  async record(name: string, record: WardRecord): Promise<void> {
+    if (!(await exists(this.#path(name)))) return;
+    return this.#keep(name, (b) => ({ ...b!, record }));
+  }
+
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (!kept) return undefined;
+    await this.#queues.get(name);
+    await Filesystem.deleteFile({ path: this.#path(name), directory });
+    return kept;
+  }
+
+  async hints(): Promise<Record<string, string>> {
+    const p = `quo/${this.harbor}/reach.json`;
+    if (!(await exists(p))) return {};
+    const { data } = await Filesystem.readFile({ path: p, directory, encoding: Encoding.UTF8 });
+    return JSON.parse(data as string) as Record<string, string>;
+  }
+
+  async hint(pk: string, url: string): Promise<void> {
+    const all = await this.hints();
+    all[pk] = url;
+    await Filesystem.writeFile({ path: `quo/${this.harbor}/reach.json`, directory, data: JSON.stringify(all) + '\n', encoding: Encoding.UTF8 });
+  }
+}

package/harbor/disk.ts

@@ -9,7 +9,9 @@
 //   <dir>/
 //     lease                 pid of the one process that holds this harbor
 //     classes/index.ts      the default class source, a module exporting classes
-//     wards/<name>/         seed, partition.json, ward.json: see files.ts
+//     tab/index.ts          the classes for the tab, served bundled by the web route: human/web.ts
+//     wards/<name>/         seed, partition.json, ward.json, or one sealed
+//                           blob when the daemon holds QUO_SEED_KEY: see files.ts
 //     reach.json            the directory's hints
 import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -51,7 +53,10 @@ export class DiskHarbor extends Harbor {
 
   constructor(dir: string) {
     const abs = resolve(dir);
-    super(new Files(abs), async (rec) => ({ ...BUILT_IN, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }));
+    // The key the environment gives, the edge's name for it: from the
+    // Keychain through the app that spawned this daemon, or nothing on a
+    // droplet, whose folder stays plain under its file modes.
+    super(new Files(abs, process.env.QUO_SEED_KEY), async (rec) => ({ ...BUILT_IN, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }));
     this.dir = abs;
   }
 
@@ -62,7 +67,7 @@ export class DiskHarbor extends Harbor {
   // has one.
   static async init(dir: string, name = 'main', user = 'me'): Promise<{ dir: string; name: string; pk: string; user: string }> {
     const h = new DiskHarbor(dir);
-    if (existsSync(join(h.dir, 'wards', name, 'seed'))) throw new Error(`ward ${name} already exists in ${h.dir}`);
+    if ((await h.store.list()).includes(name)) throw new Error(`ward ${name} already exists in ${h.dir}`);
     await mkdir(join(h.dir, 'classes'), { recursive: true });
     const classes = join(h.dir, DEFAULT_CODE);
     if (!existsSync(classes)) await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');