@quo-systems/dock 0.2.3 → 0.2.5

package/beings/carry.ts

@@ -58,16 +58,20 @@ export class Carrier extends Being {
       if (!st) continue;
       if (!rec.blueprint || rec.seen !== rec.digest) await st.ask(); // her ward writes the record
       if (!rec.blueprint) continue;
+      // her look is kept here once per digest and never carried as an ask;
+      // her page follows every call, so it is carried as one and named in
+      // the notes, where every side finds it and none takes it for a form
       const names: string[] = [];
+      const group: { asks: string[]; look?: Look; page?: string } = { asks: names };
       for (const a of rec.blueprint.asks) {
-        if (a.name === 'look' || a.name === 'page') continue; // presentation is hers, never carried as an ask
+        if (a.name === 'look') continue;
         const name = `${id}-${a.name}`;
         if (own.has(name)) continue;
         carried[name] = { id, ask: a.name };
-        names.push(name);
         bp.asks.push({ ...a, name });
+        if (a.name === 'page') group.page = name;
+        else names.push(name);
       }
-      const group: { asks: string[]; look?: Look } = { asks: names };
       if (rec.blueprint.asks.some((a) => a.name === 'look')) {
         const kept = this.looks[id];
         if (!kept || kept.digest !== rec.digest) {

package/beings/desk.ts

@@ -25,8 +25,12 @@ export class Desk extends Being {
     device: { description: 'trade a proof for a device invitation', input: { type: 'object', properties: { proof: { type: 'object' } }, required: ['proof'] } },
   };
 
+  // A stranger learns the proof kinds and nothing else. Who lives on this
+  // world is not the caller's to know: the verifier names the user, so
+  // nobody at the door ever has to, and a world with a thousand of them
+  // would otherwise hand the whole list to anyone who knocked.
   hello(_args: JsonObject, asker: Asker) {
-    return { desk: true, asker: asker.id ?? null, kinds: Object.keys(Desk.verifiers), users: Object.keys(this.cells.standings).filter((k) => k.startsWith('user:')).map((k) => k.slice(5)) };
+    return { desk: true, asker: asker.id ?? null, kinds: Object.keys(Desk.verifiers) };
   }
 
   async device(args: JsonObject) {

package/beings/look.ts

@@ -75,15 +75,24 @@ export function sanitise(v: Json | undefined): Look {
 // The one hint a side reads first: whether this ask is in the look at all.
 export const hint = (l: Look | undefined, name: string): Hint => l?.asks?.[name] ?? {};
 
-// A carrier's notes say which asks are a standing's, and how she looks:
-// `standings: { id: { asks: [name], look? } }`. Every side reads them here.
-export type Group = { asks?: string[]; look?: Json };
+// A carrier's notes say which asks are a standing's, how she looks, and
+// which carried ask is her page: `standings: { id: { asks: [name], look?,
+// page? } }`. Every side reads them here.
+export type Group = { asks?: string[]; look?: Json; page?: string };
 export function groups(bp: Blueprint | null): Record<string, Group> {
   const n = bp?.notes;
   const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
   return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? (g as Record<string, Group>) : {};
 }
 
+// The asks that are presentation and never a form nor a tool: her look, her
+// page, and the page of every standing she carries, named in her notes.
+export function presentation(bp: Blueprint | null): Set<string> {
+  const p = new Set(['look', 'page']);
+  for (const g of Object.values(groups(bp))) if (typeof g.page === 'string') p.add(g.page);
+  return p;
+}
+
 // The hint for one ask, hers or a standing's: a carried ask is looked up
 // under its bare name in that standing's look.
 export function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint {

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.
@@ -272,14 +278,15 @@ Carrying is a base, `beings/carry.ts`, and nothing in it knows what a user
 is: a house being could carry its rooms, a company its suppliers. A subclass
 says who may see what she carries, and the user being says a device with the
 `reach` note, written when the human ticked the box at the exchange. The
-notes of a carrier's describe say which asks are whose,
-`standings: { id: { asks, look? } }`, so a screen draws one section per
-standing and a model side keeps the flat list it needs; the mapping back
-from a carried name to the standing is in her cells and never parsed from
-the name. Her own asks come first and are never shadowed. She asks a
-standing's describe again when its digest moved and its `look` once per
-digest, so a describe of hers may cost one ask per stale standing, the price
-of a page that is never more than one ask behind.
+notes of a carrier's describe say which asks are whose, how each standing
+looks and which carried ask is her page, `standings: { id: { asks, look?,
+page? } }`, so a screen draws one section per standing, paints her page in
+it when she has one, and a model side keeps the flat list it needs with no
+page in it; the mapping back from a carried name to the standing is in her
+cells and never parsed from the name. Her own asks come first and are never
+shadowed. She asks a standing's describe again when its digest moved and its
+`look` once per digest, so a describe of hers may cost one ask per stale
+standing, the price of a page that is never more than one ask behind.
 
 ## The look
 
@@ -307,11 +314,13 @@ A look is not capability: it is never in a blueprint or a digest, Quo never
 sees it, and a being without one renders and lists exactly as before. The
 `look` ask itself is presentation and is neither a form nor a tool, and so
 is `page`, the one other presentation ask, which a screen alone reads and
-`packages/dock/human/quo-human.md` defines; a carrier carries neither. A
-carrier keeps each standing's look beside her asks in the notes, so acme's
-section on the human's page is painted as acme asked, inside that section
-and nowhere else. No token can carry a URL, a stylesheet or code, so a far
-being cannot paint over the page or reach a server through it. A being who
+`packages/dock/human/quo-human.md` defines. A carrier keeps each standing's
+look beside her asks in the notes, since a look moves with the digest, and
+carries her page as an ask named there, since a page moves with every call;
+so acme's section on the human's page is painted as acme asked, her look
+and her page, inside that section and nowhere else. No token can carry a
+URL, a stylesheet or code, so a far being cannot paint over the page or
+reach a server through it. A being who
 marks an ask read-only and then writes has lied to her own page, and nothing
 enforces it, the way nothing enforces that her empty ask is safe to repeat.
 

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

@@ -56,18 +56,24 @@ export class Carrier extends Being {
                 await st.ask(); // her ward writes the record
             if (!rec.blueprint)
                 continue;
+            // her look is kept here once per digest and never carried as an ask;
+            // her page follows every call, so it is carried as one and named in
+            // the notes, where every side finds it and none takes it for a form
             const names = [];
+            const group = { asks: names };
             for (const a of rec.blueprint.asks) {
-                if (a.name === 'look' || a.name === 'page')
-                    continue; // presentation is hers, never carried as an ask
+                if (a.name === 'look')
+                    continue;
                 const name = `${id}-${a.name}`;
                 if (own.has(name))
                     continue;
                 carried[name] = { id, ask: a.name };
-                names.push(name);
                 bp.asks.push({ ...a, name });
+                if (a.name === 'page')
+                    group.page = name;
+                else
+                    names.push(name);
             }
-            const group = { asks: names };
             if (rec.blueprint.asks.some((a) => a.name === 'look')) {
                 const kept = this.looks[id];
                 if (!kept || kept.digest !== rec.digest) {

package/dist/beings/desk.d.ts

@@ -37,7 +37,6 @@ export declare class Desk extends Being {
         desk: boolean;
         asker: string | null;
         kinds: string[];
-        users: string[];
     };
     device(args: JsonObject): Promise<Json>;
 }

package/dist/beings/desk.js

@@ -17,8 +17,12 @@ export class Desk extends Being {
         hello: { description: 'how to get in', input: { type: 'object' } },
         device: { description: 'trade a proof for a device invitation', input: { type: 'object', properties: { proof: { type: 'object' } }, required: ['proof'] } },
     };
+    // A stranger learns the proof kinds and nothing else. Who lives on this
+    // world is not the caller's to know: the verifier names the user, so
+    // nobody at the door ever has to, and a world with a thousand of them
+    // would otherwise hand the whole list to anyone who knocked.
     hello(_args, asker) {
-        return { desk: true, asker: asker.id ?? null, kinds: Object.keys(Desk.verifiers), users: Object.keys(this.cells.standings).filter((k) => k.startsWith('user:')).map((k) => k.slice(5)) };
+        return { desk: true, asker: asker.id ?? null, kinds: Object.keys(Desk.verifiers) };
     }
     async device(args) {
         const proof = args.proof;

package/dist/beings/look.d.ts

@@ -22,6 +22,8 @@ export declare const hint: (l: Look | undefined, name: string) => Hint;
 export type Group = {
     asks?: string[];
     look?: Json;
+    page?: string;
 };
 export declare function groups(bp: Blueprint | null): Record<string, Group>;
+export declare function presentation(bp: Blueprint | null): Set<string>;
 export declare function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint;

package/dist/beings/look.js

@@ -58,6 +58,15 @@ export function groups(bp) {
     const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
     return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? g : {};
 }
+// The asks that are presentation and never a form nor a tool: her look, her
+// page, and the page of every standing she carries, named in her notes.
+export function presentation(bp) {
+    const p = new Set(['look', 'page']);
+    for (const g of Object.values(groups(bp)))
+        if (typeof g.page === 'string')
+            p.add(g.page);
+    return p;
+}
 // The hint for one ask, hers or a standing's: a carried ask is looked up
 // under its bare name in that standing's look.
 export function hintFor(bp, mine, name) {

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/browser.d.ts

@@ -1,13 +1,13 @@
 import type { BeingClass } from '@quo-systems/quo';
-import { Harbor, type Dialer } from '@quo-systems/quo/harbor';
-import { Idb } from './idb.ts';
+import { Harbor, type Dialer, type Store } from '@quo-systems/quo/harbor';
 export declare const BUILT_IN: Record<string, BeingClass>;
 export declare class BrowserHarbor extends Harbor {
     #private;
-    readonly db: Idb;
+    readonly name: string;
     readonly dialers: Dialer[];
-    constructor(name?: string, classes?: Record<string, BeingClass>);
+    constructor(store?: string | Store, classes?: Record<string, BeingClass>);
     boot(): Promise<void>;
     dial(url: string): Dialer;
+    wake(): void;
     close(): Promise<void>;
 }

package/dist/harbor/browser.js

@@ -3,18 +3,21 @@ import { Harbor, dial } from '@quo-systems/quo/harbor';
 import { Idb } from './idb.js';
 export const BUILT_IN = { User, Desk, Avatar };
 export class BrowserHarbor extends Harbor {
-    db;
+    name;
     dialers = [];
+    #locked;
     #release;
-    constructor(name = 'quo', classes = {}) {
-        const db = new Idb(name);
-        super(db, async () => ({ ...BUILT_IN, ...classes }));
-        this.db = db;
+    constructor(store = 'quo', classes = {}) {
+        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.
     async boot() {
-        await this.#lease();
+        if (this.#locked)
+            await this.#lease();
         await super.boot();
     }
     // Hold one socket to a world's quo. route.
@@ -23,10 +26,16 @@ export class BrowserHarbor extends Harbor {
         this.dialers.push(d);
         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() {
+        for (const d of this.dialers)
+            d.wake();
+    }
     async close() {
         for (const d of this.dialers.splice(0))
             d.close();
-        this.db.close();
+        this.store.close?.();
         this.#release?.();
         this.#release = undefined;
     }
@@ -35,7 +44,7 @@ export class BrowserHarbor extends Harbor {
         if (!locks)
             return; // no web locks on this terrain: nothing vouches, as in the memory harbor
         const granted = await new Promise((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;
@@ -45,6 +54,6 @@ export class BrowserHarbor extends Harbor {
             });
         });
         if (!granted)
-            throw new Error(`harbor ${this.db.name} is held by another tab`);
+            throw new Error(`harbor ${this.name} is held by another tab`);
     }
 }

package/dist/harbor/capacitor.d.ts

@@ -0,0 +1,19 @@
+import type { BeingClass } from '@quo-systems/quo';
+import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+import { BrowserHarbor } from './browser.ts';
+export declare function nativeHarbor(name?: string, classes?: Record<string, BeingClass>): Promise<BrowserHarbor>;
+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,151 @@
+// 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 { arithmetic } from '@quo-systems/quo/ward';
+import { BrowserHarbor } from './browser.js';
+import { sealKey, seal, open } from './seal.js';
+// 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 = {}) {
+    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;
+// 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 });
+    }
+}