@quo-systems/dock 0.2.3 → 0.2.4

package/beings/quo-dock.md

@@ -151,6 +151,12 @@ taken when it can be: a knock back that is unreached, a tab whose pk the
 far harbor has not bound yet or a phone in a tunnel, spends nothing, so she
 keeps the invitation and takes it at the next push. A refusal is final.
 
+A device the root minted may also call her: her `name` ask, gated to
+root-minted devices alone, since the root already trusts that device with
+its id and its reach. A being does not know her own key, so a name is
+always given, by the desk's first hello at setup or by such a device, and
+she keeps the last one. A name is a word, held to the same shape as a key.
+
 ## Architecture
 
 One droplet, one harbor, three routes. Every other placement is a subset.

package/beings/user.ts

@@ -43,6 +43,7 @@ export class User extends Carrier {
     chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ: OccupantRecord | undefined) => client(occ) === 'agent' },
     look: { description: 'how she is shown', input: { type: 'object' }, for: isDevice },
     page: { description: 'her page, as a tree of values', input: { type: 'object' }, for: isDevice },
+    name: { description: 'what she is called', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, for: rootMinted },
     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 },
   };
@@ -134,16 +135,18 @@ export class User extends Carrier {
   look() {
     return {
       name: (this.cells.name as string) || 'you',
-      order: ['whoami', 'push'],
-      asks: { whoami: { title: 'who am I', readOnly: true }, push: { title: 'wake a device' } },
+      order: ['whoami', 'push', 'name'],
+      asks: { whoami: { title: 'who am I', readOnly: true }, push: { title: 'wake a device' }, name: { title: 'call her' } },
     };
   }
 
   // Her page for a device: her name, who this device is, the worlds she
-  // holds as sections, and the one thing a human does here by hand, waking
-  // another device. `hello` and `report` are wiring, a device's first word
-  // and an agent's callback; they stay in her describe under the gate and
-  // off her page, since a page is presentation and the gate is permission.
+  // holds as sections, and the two things a human does here by hand, waking
+  // another device and naming her. `hello` and `report` are wiring, a
+  // device's first word and an agent's callback; they stay in her describe
+  // under the gate and off her page, since a page is presentation and the
+  // gate is permission. A device that may not do a thing sees no form for
+  // it, however the page names it.
   page() {
     return {
       kind: 'stack',
@@ -152,10 +155,21 @@ export class User extends Carrier {
         { kind: 'row', of: [{ kind: 'text', text: 'this device', role: 'label' }, { kind: 'answer', ask: 'whoami' }] },
         { kind: 'standings' },
         { kind: 'form', ask: 'push' },
+        { kind: 'form', ask: 'name' },
       ],
     };
   }
 
+  // A device the root minted may say what she is called: the root trusts
+  // it with its id and its reach already, and a being does not know her own
+  // key. A name is a word; she keeps the last one given.
+  name(args: JsonObject) {
+    const name = typeof args.name === 'string' ? args.name.trim() : '';
+    if (!/^[\w.-]{1,80}$/.test(name)) return { error: 'a name is a word' };
+    this.cells.name = name;
+    return { named: name };
+  }
+
   // A device that ran something for her says what it found. Kept, so that
   // whoever renders her can show it; the ask itself is the callback.
   report(args: JsonObject, asker: Asker) {

package/dist/beings/user.d.ts

@@ -3,6 +3,7 @@ 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 rootMinted: (occ: OccupantRecord | undefined) => boolean;
 declare const mayWake: (occ: OccupantRecord | undefined) => boolean;
 export declare class User extends Carrier {
     static carries(occ: OccupantRecord | undefined): boolean;
@@ -86,6 +87,19 @@ export declare class User extends Carrier {
             };
             for: typeof isDevice;
         };
+        name: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof rootMinted;
+        };
         forget: {
             description: string;
             input: {
@@ -152,6 +166,9 @@ export declare class User extends Carrier {
             push: {
                 title: string;
             };
+            name: {
+                title: string;
+            };
         };
     };
     page(): {
@@ -192,6 +209,13 @@ export declare class User extends Carrier {
             ask: string;
         })[];
     };
+    name(args: JsonObject): {
+        error: string;
+        named?: undefined;
+    } | {
+        error?: undefined;
+        named: string;
+    };
     report(args: JsonObject, asker: Asker): {
         reported: boolean;
     };

package/dist/beings/user.js

@@ -40,6 +40,7 @@ export class User extends Carrier {
         chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ) => client(occ) === 'agent' },
         look: { description: 'how she is shown', input: { type: 'object' }, for: isDevice },
         page: { description: 'her page, as a tree of values', input: { type: 'object' }, for: isDevice },
+        name: { description: 'what she is called', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, for: rootMinted },
         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 },
     };
@@ -134,15 +135,17 @@ export class User extends Carrier {
     look() {
         return {
             name: this.cells.name || 'you',
-            order: ['whoami', 'push'],
-            asks: { whoami: { title: 'who am I', readOnly: true }, push: { title: 'wake a device' } },
+            order: ['whoami', 'push', 'name'],
+            asks: { whoami: { title: 'who am I', readOnly: true }, push: { title: 'wake a device' }, name: { title: 'call her' } },
         };
     }
     // Her page for a device: her name, who this device is, the worlds she
-    // holds as sections, and the one thing a human does here by hand, waking
-    // another device. `hello` and `report` are wiring, a device's first word
-    // and an agent's callback; they stay in her describe under the gate and
-    // off her page, since a page is presentation and the gate is permission.
+    // holds as sections, and the two things a human does here by hand, waking
+    // another device and naming her. `hello` and `report` are wiring, a
+    // device's first word and an agent's callback; they stay in her describe
+    // under the gate and off her page, since a page is presentation and the
+    // gate is permission. A device that may not do a thing sees no form for
+    // it, however the page names it.
     page() {
         return {
             kind: 'stack',
@@ -151,9 +154,20 @@ export class User extends Carrier {
                 { kind: 'row', of: [{ kind: 'text', text: 'this device', role: 'label' }, { kind: 'answer', ask: 'whoami' }] },
                 { kind: 'standings' },
                 { kind: 'form', ask: 'push' },
+                { kind: 'form', ask: 'name' },
             ],
         };
     }
+    // A device the root minted may say what she is called: the root trusts
+    // it with its id and its reach already, and a being does not know her own
+    // key. A name is a word; she keeps the last one given.
+    name(args) {
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!/^[\w.-]{1,80}$/.test(name))
+            return { error: 'a name is a word' };
+        this.cells.name = name;
+        return { named: name };
+    }
     // A device that ran something for her says what it found. Kept, so that
     // whoever renders her can show it; the ask itself is the callback.
     report(args, asker) {

package/dist/harbor/capacitor.d.ts

@@ -0,0 +1,16 @@
+import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+export declare class Native implements Store {
+    #private;
+    readonly harbor: string;
+    private constructor();
+    static open(harbor: string): Promise<Native>;
+    static wipe(harbor: string): Promise<void>;
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}

package/dist/harbor/capacitor.js

@@ -0,0 +1,135 @@
+// 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 { sealKey, seal, open } from './seal.js';
+const { hex, unhex } = arithmetic;
+// 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) {
+    try {
+        await Filesystem.stat({ path, directory });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class Native {
+    harbor;
+    #key;
+    #queues = new Map();
+    constructor(harbor, key) {
+        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) {
+        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) {
+        await SecureStorage.remove(`quo-${harbor}`);
+        if (await exists(`quo/${harbor}`))
+            await Filesystem.rmdir({ path: `quo/${harbor}`, directory, recursive: true });
+    }
+    #path(name) {
+        return `quo/${this.harbor}/wards/${name}.sealed`;
+    }
+    async #read(name) {
+        const { data } = await Filesystem.readFile({ path: this.#path(name), directory, encoding: Encoding.UTF8 });
+        return JSON.parse(new TextDecoder().decode(await open(this.#key, data.trim())));
+    }
+    // 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, change) {
+        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() {
+        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) {
+        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, kept) {
+        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, partition) {
+        if (!(await exists(this.#path(name))))
+            return; // a name not kept is nothing
+        return this.#keep(name, (b) => ({ ...b, partition }));
+    }
+    async record(name, record) {
+        if (!(await exists(this.#path(name))))
+            return;
+        return this.#keep(name, (b) => ({ ...b, record }));
+    }
+    async take(name) {
+        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() {
+        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);
+    }
+    async hint(pk, url) {
+        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/dist/harbor/disk.js

@@ -17,7 +17,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //   <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';
@@ -54,7 +56,10 @@ export class DiskHarbor extends Harbor {
     #held = false;
     constructor(dir) {
         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;
     }
     // Create a harbor folder with one ward, and the root's setup in it: the
@@ -64,7 +69,7 @@ export class DiskHarbor extends Harbor {
     // has one.
     static async init(dir, name = 'main', user = 'me') {
         const h = new DiskHarbor(dir);
-        if (existsSync(join(h.dir, 'wards', name, 'seed')))
+        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);

package/dist/harbor/edge/edge.js

@@ -2,7 +2,8 @@ import { isSilence } from '@quo-systems/quo';
 import { User, Desk, Avatar } from '../../beings/index.js';
 import { setup } from '../../beings/setup.js';
 import { Harbor, Socket as Held, SUITE } from '@quo-systems/quo/harbor';
-import { DurableStorage, sealKey } from './storage.js';
+import { DurableStorage } from './storage.js';
+import { sealKey } from '../seal.js';
 export const BUILT_IN = { User, Desk, Avatar };
 const json = (status, v, headers = {}) => new Response(JSON.stringify(v), { status, headers: { 'content-type': 'application/json', ...headers } });
 const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-headers': 'content-type, quo-suite' };

package/dist/harbor/edge/exercise.js

@@ -11,7 +11,8 @@ import { conform, conformStore, conformReach } from '@quo-systems/quo/conformanc
 import { request as byRequest } from '@quo-systems/quo/harbor';
 import { Printer, Shop, Customer, Echo, Member } from '@quo-systems/quo/conformance';
 import { EdgeHarbor } from './edge.js';
-import { DurableStorage, sealKey } from './storage.js';
+import { DurableStorage } from './storage.js';
+import { sealKey } from '../seal.js';
 const assert = {
     equal(a, b, m) {
         if (a !== b)

package/dist/harbor/edge/storage.d.ts

@@ -1,8 +1,5 @@
 import { type Kept, type Store, type WardRecord } from '@quo-systems/quo/harbor';
 import type { Storage } from './platform.d.ts';
-export declare function sealKey(secret: string): Promise<CryptoKey>;
-export declare function seal(key: CryptoKey, seed: Uint8Array): Promise<string>;
-export declare function open(key: CryptoKey, sealed: string): Promise<Uint8Array>;
 export declare class DurableStorage implements Store {
     #private;
     readonly storage: Storage;

package/dist/harbor/edge/storage.js

@@ -2,32 +2,13 @@
 // The store as Durable Object storage: one object per harbor, its storage
 // holding one row per ward under `ward:<name>`, seed, partition and record,
 // and one row per hint under `hint:<pk>`. The seed is kept sealed under a
-// key from the platform's secrets, `QUO_SEED_KEY`, so the storage holds
-// ciphertext and the secret store holds the one key, which is what the
-// harbor document's table says the edge does. Values cross as JSON, as
-// they do into a file, because the ward hands the partition out through a
-// guard that structured clone refuses.
-import { arithmetic } from '@quo-systems/quo/ward';
+// key from the platform's secrets, `QUO_SEED_KEY`, with the seal in
+// `../seal.ts`, so the storage holds ciphertext and the secret store holds
+// the one key, which is what the harbor document's table says the edge
+// does. Values cross as JSON, as they do into a file, because the ward
+// hands the partition out through a guard that structured clone refuses.
 import { values } from '@quo-systems/quo/harbor';
-// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
-const plain = (b) => new Uint8Array(b);
-const { hex, unhex } = arithmetic;
-// The seal on a seed: AES-GCM under the platform key, a fresh nonce each
-// time, nonce and ciphertext together as hex.
-export async function sealKey(secret) {
-    if (!/^[0-9a-f]{64}$/.test(secret))
-        throw new Error('QUO_SEED_KEY is 32 bytes as hex');
-    return crypto.subtle.importKey('raw', plain(unhex(secret)), 'AES-GCM', false, ['encrypt', 'decrypt']);
-}
-export async function seal(key, seed) {
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(seed)));
-    return hex(iv) + hex(ct);
-}
-export async function open(key, sealed) {
-    const b = plain(unhex(sealed));
-    return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
-}
+import { seal, open } from '../seal.js';
 // `prefix` keeps more than one harbor apart in one object's storage: the
 // exercise does that, a deployment never does.
 export class DurableStorage {

package/dist/harbor/files.d.ts

@@ -2,7 +2,8 @@ import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
 export declare class Files implements Store {
     #private;
     readonly dir: string;
-    constructor(dir: string);
+    constructor(dir: string, key?: string);
+    get sealed(): boolean;
     list(): Promise<string[]>;
     load(name: string): Promise<Kept | undefined>;
     put(name: string, kept: Kept): Promise<void>;

package/dist/harbor/files.js

@@ -1,35 +1,99 @@
 // SPDX-License-Identifier: Apache-2.0
-// The store as a folder on disk, one folder per ward:
+// The store as a folder on disk, one folder per ward, in one of two forms.
+//
+// Plain, when the store has no key, what the droplets run:
 //
 //   <dir>/wards/<name>/seed             32 bytes, hex, mode 0600
 //   <dir>/wards/<name>/partition.json
 //   <dir>/wards/<name>/ward.json        the ward record
+//
+// Sealed, when the store holds a key, what a device's daemon runs with the
+// key from its Keychain:
+//
+//   <dir>/wards/<name>/ward.sealed      seed, partition and record as one
+//                                       JSON, sealed under the key, hex
+//
+// and in both:
+//
 //   <dir>/reach.json                    the directory's hints
 //
-// Every write of the partition goes through a temp file and a rename, and
-// writes are queued per ward so two calls never race on one file.
+// A ward is whole in either form, and a store that meets the other form
+// refuses it by name: a daemon started without its key, or with one against
+// a plain folder, fails loudly instead of booting on what it cannot read.
+// Sealing a plain folder is a deliberate command, never a boot's doing.
+// Every write of a ward goes through a temp file and a rename, and writes
+// are queued per ward so two calls never race on one file.
 import { mkdir, readFile, writeFile, rename, readdir, rm, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { arithmetic } from '@quo-systems/quo/ward';
+import { sealKey, seal, open } from './seal.js';
 const { hex, unhex } = arithmetic;
 export class Files {
     dir;
+    #key;
     #queues = new Map();
-    constructor(dir) {
+    constructor(dir, key) {
         this.dir = dir;
+        if (key)
+            this.#key = sealKey(key);
     }
     #ward(name) {
         return join(this.dir, 'wards', name);
     }
+    get sealed() {
+        return this.#key !== undefined;
+    }
+    // The form a folder holds, checked against the form this store speaks.
+    #form(name) {
+        const wd = this.#ward(name);
+        const form = existsSync(join(wd, 'ward.sealed')) ? 'sealed' : existsSync(join(wd, 'seed')) ? 'plain' : undefined;
+        if (form === 'sealed' && !this.sealed)
+            throw new Error(`ward ${name} in ${this.dir} is sealed and this harbor has no key`);
+        if (form === 'plain' && this.sealed)
+            throw new Error(`ward ${name} in ${this.dir} is plain and this harbor holds a key`);
+        return form;
+    }
+    // One write at a time per ward, through a temp file and a rename.
+    #write(name, file, body) {
+        const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+            const tmp = join(this.#ward(name), `${file}.tmp`);
+            await writeFile(tmp, body, { mode: 0o600 });
+            await rename(tmp, join(this.#ward(name), file));
+        });
+        this.#queues.set(name, next.catch(() => { }));
+        return next;
+    }
+    async #read(name) {
+        const blob = (await readFile(join(this.#ward(name), 'ward.sealed'), 'utf8')).trim();
+        return JSON.parse(new TextDecoder().decode(await open(await this.#key, 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, change) {
+        const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+            const wd = this.#ward(name);
+            const blob = change(existsSync(join(wd, 'ward.sealed')) ? await this.#read(name) : undefined);
+            const sealed = await seal(await this.#key, new TextEncoder().encode(JSON.stringify(blob)));
+            await writeFile(join(wd, 'ward.sealed.tmp'), sealed + '\n', { mode: 0o600 });
+            await rename(join(wd, 'ward.sealed.tmp'), join(wd, 'ward.sealed'));
+        });
+        this.#queues.set(name, next.catch(() => { }));
+        return next;
+    }
     async list() {
         const wards = join(this.dir, 'wards');
-        return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed'))) : [];
+        return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed')) || existsSync(join(wards, n, 'ward.sealed'))) : [];
     }
     async load(name) {
-        const wd = this.#ward(name);
-        if (!existsSync(join(wd, 'seed')))
+        const form = this.#form(name);
+        if (!form)
             return undefined;
+        if (form === 'sealed') {
+            const b = await this.#read(name);
+            return { seed: unhex(b.seed), partition: b.partition, record: b.record };
+        }
+        const wd = this.#ward(name);
         return {
             seed: unhex((await readFile(join(wd, 'seed'), 'utf8')).trim()),
             partition: JSON.parse(await readFile(join(wd, 'partition.json'), 'utf8')),
@@ -37,31 +101,32 @@ export class Files {
         };
     }
     async put(name, kept) {
-        const wd = this.#ward(name);
-        if (existsSync(join(wd, 'seed')))
+        if (this.#form(name))
             throw new Error(`ward ${name} already exists in ${this.dir}`);
+        const wd = this.#ward(name);
         await mkdir(wd, { recursive: true, mode: 0o700 });
+        if (this.sealed)
+            return this.#keep(name, () => ({ seed: hex(kept.seed), partition: kept.partition, record: kept.record }));
         await writeFile(join(wd, 'seed'), hex(kept.seed), { mode: 0o600 });
         await chmod(join(wd, 'seed'), 0o600);
         await writeFile(join(wd, 'partition.json'), JSON.stringify(kept.partition) + '\n', { mode: 0o600 });
         await writeFile(join(wd, 'ward.json'), JSON.stringify(kept.record, null, 2) + '\n', { mode: 0o600 });
     }
-    save(name, partition) {
-        const wd = this.#ward(name);
-        if (!existsSync(join(wd, 'seed')))
-            return Promise.resolve(); // a name not kept is nothing
-        const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
-            const tmp = join(wd, 'partition.json.tmp');
-            await writeFile(tmp, JSON.stringify(partition) + '\n', { mode: 0o600 });
-            await rename(tmp, join(wd, 'partition.json'));
-        });
-        this.#queues.set(name, next.catch(() => { }));
-        return next;
+    async save(name, partition) {
+        const form = this.#form(name);
+        if (!form)
+            return; // a name not kept is nothing
+        if (form === 'sealed')
+            return this.#keep(name, (b) => ({ ...b, partition }));
+        return this.#write(name, 'partition.json', JSON.stringify(partition) + '\n');
     }
     async record(name, record) {
-        if (!existsSync(join(this.#ward(name), 'seed')))
+        const form = this.#form(name);
+        if (!form)
             return;
-        await writeFile(join(this.#ward(name), 'ward.json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+        if (form === 'sealed')
+            return this.#keep(name, (b) => ({ ...b, record }));
+        return this.#write(name, 'ward.json', JSON.stringify(record, null, 2) + '\n');
     }
     async take(name) {
         const kept = await this.load(name);

package/dist/harbor/seal.d.ts

@@ -0,0 +1,3 @@
+export declare function sealKey(secret: string): Promise<CryptoKey>;
+export declare function seal(key: CryptoKey, bytes: Uint8Array): Promise<string>;
+export declare function open(key: CryptoKey, sealed: string): Promise<Uint8Array>;

package/dist/harbor/seal.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// The seal: what a store does to a ward's bytes before they rest on a data
+// store, under one key the secret store holds. One piece with three users,
+// the edge under the platform's secret, the daemon under a key from its
+// environment, the phone under a key from the Keychain. AES-GCM under a
+// 32-byte key, a fresh nonce each time, nonce and ciphertext together as
+// hex. WebCrypto only, so it runs wherever a store does.
+import { arithmetic } from '@quo-systems/quo/ward';
+const { hex, unhex } = arithmetic;
+// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
+const plain = (b) => new Uint8Array(b);
+export async function sealKey(secret) {
+    if (!/^[0-9a-f]{64}$/.test(secret))
+        throw new Error('a seal key is 32 bytes as hex');
+    return crypto.subtle.importKey('raw', plain(unhex(secret)), 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+export async function seal(key, bytes) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(bytes)));
+    return hex(iv) + hex(ct);
+}
+export async function open(key, sealed) {
+    const b = plain(unhex(sealed));
+    return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
+}

package/dist/human/html.js

@@ -207,5 +207,7 @@ export function page(m) {
     const notes = bp && shown !== null && shown !== undefined && !(typeof shown === 'object' && !Array.isArray(shown) && !Object.keys(shown).length) ? `<aside class="notes">${view(shown)}</aside>` : '';
     const pushes = m.pushes.length ? `<section class="pushes"><h2>pushes</h2><ol>${m.pushes.map((p) => `<li>${view(p)}</li>`).join('')}</ol></section>` : '';
     const mine = look(m.look);
-    return `<header${mine.style}>${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1><p class="notice">${escape(m.notice)}</p></header>${notes}<main${mine.style}>${asks}</main>${pushes}`;
+    // a page carries its own title, so the header keeps only the notice; a being painted as forms is headed by her name
+    const head = m.tree ? '' : `${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1>`;
+    return `<header${mine.style}>${head}<p class="notice">${escape(m.notice)}</p></header>${notes}<main${mine.style}>${asks}</main>${pushes}`;
 }