@quo-systems/dock 0.2.3 → 0.2.5

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(['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;
@@ -76,18 +98,26 @@ const CSS = [
     ':root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px;--ink:#1c1b22;--paper:#fbfaf7;--mute:#6b6a73}',
     '@media(prefers-color-scheme:dark){:root{--ink:#ecebe6;--paper:#141318;--mute:#9a99a2}}',
     'html{background:var(--paper);color:var(--ink)}',
-    'body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}',
+    // one column that is a phone first and a desk after: the same page, more air
+    'body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:1rem auto;padding:0 1rem}@media(min-width:40rem){body{margin:2rem auto}}',
+    'input:not([type=checkbox]),select,textarea{width:100%;max-width:24rem;box-sizing:border-box}',
     'nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}',
     'nav.relations{display:flex;flex-wrap:wrap;gap:.25rem;margin:.5rem 0}nav.relations button{background:transparent;color:inherit;border:1px solid color-mix(in srgb,currentColor 30%,transparent)}nav.relations button[aria-current]{border-color:var(--accent);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}',
+    // 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}',
+    // a row with a picture is a line about someone or something: the picture small and the words beside it, centred
+    '.page .row:has(>.picture){align-items:center;flex-wrap:nowrap}.page .row>.picture{max-height:2.75rem;flex:none}.page .row>.stack{gap:0;min-width:0}.page .row>.stack>p{margin:0}',
+    // a far page inside a standing's section: her title is a section's, not the page's
+    'section.standing .page{padding:.5rem 0}section.standing .page .t-title{font-size:1.3rem;margin:.25rem 0}',
     // 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 .picture{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',

package/dist/mcp/runner.js

@@ -1,13 +1,15 @@
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+import { presentation } from '../beings/look.js';
 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. `look` and `page` are
-// presentation, for a screen, and are not functions.
+// LM Studio refuses a parameters schema without one. Her look, her page and
+// every carried page are presentation, for a screen, and are not functions.
 export function tools(bp) {
+    const shown = presentation(bp);
     return bp.asks
-        .filter((a) => a.name !== 'look' && a.name !== 'page')
+        .filter((a) => !shown.has(a.name))
         .map((a) => {
         const t = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
         if (a.description !== undefined)

package/dist/mcp/server.js

@@ -11,7 +11,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
-import { hintFor, sanitise } from '../beings/look.js';
+import { hintFor, presentation, sanitise } from '../beings/look.js';
 import { isSilence, isWord, digest } from '@quo-systems/quo';
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
@@ -20,10 +20,12 @@ export const DESCRIBE = { name: 'describe', description: 'the empty ask: her des
 // Her describe, spoken as tools, the empty ask first. Name, description and
 // input are verbatim; an output schema crosses when she declared one. Her
 // look, when she has one, is the hints: a title, and the annotations a host
-// reads. The `look` ask itself is presentation, and is not a tool.
+// reads. Her look, her page and every carried page are presentation, for a
+// screen, and are not tools.
 export function tools(bp, look = {}) {
+    const shown = presentation(bp);
     const asks = bp.asks
-        .filter((a) => a.name !== 'look' && a.name !== 'page') // presentation, for a screen, and not a tool
+        .filter((a) => !shown.has(a.name))
         .map((a) => {
         const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
         if (a.description !== undefined)

package/harbor/browser.ts

@@ -1,33 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
-// The browser harbor: the core over IndexedDB, in a tab. A dialer and never
-// a listener: it holds one socket per world it is connected to, and every
-// ask to a pk it does not hold goes down a socket to the listener, which is
-// the rendezvous. The lease is a web lock on the database name, held for
-// the life of the tab: a second tab on one origin meets the lock and is a
-// screen, not a harbor. The classes are the estate's beings, handed in
-// with the bundle, plus whatever a page hands in beside them.
+// The browser harbor: the core over a store, in a webview. A dialer and
+// never a listener: it holds one socket per world it is connected to, and
+// every ask to a pk it does not hold goes down a socket to the listener,
+// which is the rendezvous. In a tab the store is IndexedDB under a name,
+// and the lease is a web lock on that name, held for the life of the tab:
+// a second tab on one origin meets the lock and is a screen, not a harbor.
+// In an app the store is handed in, and the process that holds it is the
+// lease: an app has one harbor and nothing else can open its files. The
+// classes are the estate's beings, handed in with the bundle, plus whatever
+// a page hands in beside them.
 import type { BeingClass } from '@quo-systems/quo';
 import { User, Desk, Avatar } from '../beings/index.ts';
-import { Harbor, dial, type Dialer } from '@quo-systems/quo/harbor';
+import { Harbor, dial, type Dialer, type Store } from '@quo-systems/quo/harbor';
 import { Idb } from './idb.ts';
 
 export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar };
 
 export class BrowserHarbor extends Harbor {
-  readonly db: Idb;
+  readonly name: string;
   readonly dialers: Dialer[] = [];
+  readonly #locked: boolean;
   #release: (() => void) | undefined;
 
-  constructor(name = 'quo', classes: Record<string, BeingClass> = {}) {
-    const db = new Idb(name);
-    super(db, async () => ({ ...BUILT_IN, ...classes }));
-    this.db = db;
+  constructor(store: string | Store = 'quo', classes: Record<string, BeingClass> = {}) {
+    const s = typeof store === 'string' ? new Idb(store) : store;
+    super(s, async () => ({ ...BUILT_IN, ...classes }));
+    this.name = typeof store === 'string' ? store : 'quo';
+    this.#locked = typeof store === 'string';
   }
 
   // Take the lock and boot every ward kept here. A lock already held is
   // another tab's harbor over this seed, and this one refuses to boot.
   override async boot(): Promise<void> {
-    await this.#lease();
+    if (this.#locked) await this.#lease();
     await super.boot();
   }
 
@@ -38,9 +43,15 @@ export class BrowserHarbor extends Harbor {
     return d;
   }
 
+  // The device is back: a phone out of a pocket, an app to the foreground.
+  // Every socket is told, and one that died silently is dialed again.
+  wake(): void {
+    for (const d of this.dialers) d.wake();
+  }
+
   async close(): Promise<void> {
     for (const d of this.dialers.splice(0)) d.close();
-    this.db.close();
+    (this.store as { close?(): void }).close?.();
     this.#release?.();
     this.#release = undefined;
   }
@@ -49,7 +60,7 @@ export class BrowserHarbor extends Harbor {
     const locks = (globalThis.navigator as Navigator | undefined)?.locks;
     if (!locks) return; // no web locks on this terrain: nothing vouches, as in the memory harbor
     const granted = await new Promise<boolean>((ok) => {
-      void locks.request(`quo:${this.db.name}`, { ifAvailable: true }, (lock) => {
+      void locks.request(`quo:${this.name}`, { ifAvailable: true }, (lock) => {
         if (!lock) {
           ok(false);
           return;
@@ -58,6 +69,6 @@ export class BrowserHarbor extends Harbor {
         return new Promise<void>((release) => (this.#release = release)); // held until close
       });
     });
-    if (!granted) throw new Error(`harbor ${this.db.name} is held by another tab`);
+    if (!granted) throw new Error(`harbor ${this.name} is held by another tab`);
   }
 }

package/harbor/capacitor.ts

@@ -0,0 +1,159 @@
+// 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.
+//
+// The harbor on a phone is the browser harbor over this store: the app
+// process is its lease, and the App plugin's foreground is its wake.
+import { Capacitor } from '@capacitor/core';
+import { App } from '@capacitor/app';
+import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
+import { SecureStorage, KeychainAccess } from '@aparajita/capacitor-secure-storage';
+import type { BeingClass } from '@quo-systems/quo';
+import { arithmetic } from '@quo-systems/quo/ward';
+import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+import { BrowserHarbor } from './browser.ts';
+import { sealKey, seal, open } from './seal.ts';
+
+// The app's one harbor, booted, told `wake` every time the app comes to
+// the foreground, since a phone asleep loses its sockets silently.
+export async function nativeHarbor(name = 'quo', classes: Record<string, BeingClass> = {}): Promise<BrowserHarbor> {
+  const h = new BrowserHarbor(await Native.open(name), classes);
+  await h.boot();
+  await App.addListener('appStateChange', ({ isActive }) => {
+    if (isActive) h.wake();
+  });
+  return h;
+}
+
+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');

package/harbor/edge/edge.ts

@@ -24,7 +24,8 @@ import { isSilence } from '@quo-systems/quo';
 import { User, Desk, Avatar } from '../../beings/index.ts';
 import { setup } from '../../beings/setup.ts';
 import { Harbor, Socket as Held, SUITE, type Line } from '@quo-systems/quo/harbor';
-import { DurableStorage, sealKey } from './storage.ts';
+import { DurableStorage } from './storage.ts';
+import { sealKey } from '../seal.ts';
 import type { State, Env } from './platform.d.ts';
 
 export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar };

package/harbor/edge/exercise.ts

@@ -13,7 +13,8 @@ import type { World, Handle, Census } from '@quo-systems/quo/conformance';
 import { Printer, Shop, Customer, Echo, Member } from '@quo-systems/quo/conformance';
 import type { BeingClass, Cells, Invitation, JsonObject } from '@quo-systems/quo';
 import { EdgeHarbor } from './edge.ts';
-import { DurableStorage, sealKey } from './storage.ts';
+import { DurableStorage } from './storage.ts';
+import { sealKey } from '../seal.ts';
 import type { Hosted } from '@quo-systems/quo/harbor';
 import type { State, Env } from './platform.d.ts';
 

package/harbor/edge/storage.ts

@@ -2,35 +2,16 @@
 // 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, type Kept, type Store, type WardRecord } from '@quo-systems/quo/harbor';
+import { seal, open } from '../seal.ts';
 import type { Storage } from './platform.d.ts';
 
 type Row = { seed: string; partition: Record<string, unknown>; record: WardRecord };
-// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
-const plain = (b: Uint8Array): Uint8Array<ArrayBuffer> => 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: string): Promise<CryptoKey> {
-  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: CryptoKey, seed: Uint8Array): Promise<string> {
-  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: CryptoKey, sealed: string): Promise<Uint8Array> {
-  const b = plain(unhex(sealed));
-  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
-}
 
 // `prefix` keeps more than one harbor apart in one object's storage: the
 // exercise does that, a deployment never does.

package/harbor/files.ts

@@ -1,39 +1,101 @@
 // 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 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 };
 
 export class Files implements Store {
   readonly dir: string;
+  readonly #key?: Promise<CryptoKey>;
   readonly #queues = new Map<string, Promise<void>>();
-  constructor(dir: string) {
+  constructor(dir: string, key?: string) {
     this.dir = dir;
+    if (key) this.#key = sealKey(key);
   }
   #ward(name: string) {
     return join(this.dir, 'wards', name);
   }
+  get sealed(): boolean {
+    return this.#key !== undefined;
+  }
+  // The form a folder holds, checked against the form this store speaks.
+  #form(name: string): 'plain' | 'sealed' | undefined {
+    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: string, file: string, body: string): Promise<void> {
+    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: string): Promise<Blob> {
+    const blob = (await readFile(join(this.#ward(name), 'ward.sealed'), 'utf8')).trim();
+    return JSON.parse(new TextDecoder().decode(await open(await this.#key!, blob))) 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 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(): Promise<string[]> {
     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: string): Promise<Kept | undefined> {
+    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);
-    if (!existsSync(join(wd, 'seed'))) return undefined;
     return {
       seed: unhex((await readFile(join(wd, 'seed'), 'utf8')).trim()),
       partition: JSON.parse(await readFile(join(wd, 'partition.json'), 'utf8')) as Record<string, unknown>,
@@ -42,30 +104,28 @@ export class Files implements Store {
   }
 
   async put(name: string, kept: Kept): Promise<void> {
+    if (this.#form(name)) throw new Error(`ward ${name} already exists in ${this.dir}`);
     const wd = this.#ward(name);
-    if (existsSync(join(wd, 'seed'))) throw new Error(`ward ${name} already exists in ${this.dir}`);
     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: string, partition: Record<string, unknown>): Promise<void> {
-    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: string, partition: Record<string, unknown>): Promise<void> {
+    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: string, record: WardRecord): Promise<void> {
-    if (!existsSync(join(this.#ward(name), 'seed'))) return;
-    await writeFile(join(this.#ward(name), 'ward.json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+    const form = this.#form(name);
+    if (!form) return;
+    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: string): Promise<Kept | undefined> {