nervur 0.20.1 → 0.20.3

package/README.md

@@ -18,6 +18,76 @@ Node 22.18 or later. The main entry imports no platform, so it runs in a
 browser, Deno, Bun and workerd as well. `nervur/folder` keeps a harbor on
 a disk and needs Node's file system.
 
+## A harbor where you run
+
+```js
+import { Harbor } from 'nervur';
+import * as greetings from './greetings.js';
+
+const harbor = await Harbor.open({ modules: [greetings] });
+```
+
+With no terrain, the harbor picks its ground's bodies itself. In Node it
+keeps itself in a folder, `where` if you name one, else `$NERVUR_DIR`,
+else `~/.nervur`, speaks TCP and, where you open them, the web and Web
+Push, and serves its root line, so the `nervur` command below asks it
+while it stands. A folder opens in one run at a time. Bundled for a
+browser, in a page or a worker, it keeps itself in the IndexedDB
+database `where` names, else `nervur`, its seed sealed under a key the
+browser never hands out, speaks the web, and opens in one run at a time.
+On Cloudflare Workers it is one Durable Object, answering Quo at `/quo`
+on whatever host reaches it, and asking over TCP and the web. Anywhere
+else it lives as long as its process and speaks the web. Hand in a
+terrain, as below, and that one is used.
+
+## A harbor on the edge
+
+An edge harbor is born on your machine and carried there, so you pilot it
+from your own harbor, as you pilot one on a server. Make it and set it
+up with the command below, naming where the edge will reach it:
+
+```sh
+nervur init --dir ./edge
+nervur reach https://harbor.example.workers.dev/quo --dir ./edge
+nervur own pilot --dir ./edge
+nervur edge pack ./package.json --dir ./edge
+```
+
+`own` prints the owner invitation, which never leaves your machine.
+`edge pack` prints the harbor's seed and writes its sealed package. Keep
+the seed as the worker's secret, `wrangler secret put NERVUR_SEED`, and
+bundle the package with the worker:
+
+```js
+import { harborObject } from 'nervur/edge';
+import carried from './package.json';
+import * as greetings from './greetings.js';
+
+export const Harbor = harborObject({ modules: [greetings], package: carried });
+```
+
+The first time the object starts, the package lands in its storage and
+the harbor opens under that seed; after that the storage is the harbor,
+and a new deploy leaves it be. Then, from your own harbor:
+
+```sh
+nervur pilot edge '<the owner invitation>' --dir ./mine
+nervur host shop --via edge --dir ./mine
+```
+
+`pilot` opens the web carrier where the invitation names a web address.
+An object with no package draws its own seed, sealed under the worker's
+`NERVUR_SECRET`, and `stood` runs the worker's own code on it as root:
+
+```js
+export const Shop = harborObject({
+  modules: [greetings],
+  stood: async (harbor) => {
+    // runs once the harbor stands
+  },
+});
+```
+
 ## A world in one process
 
 ```js
@@ -116,13 +186,33 @@ stands a ward under a seed you name, or a drawn one.
 - **Harbor, Terrain, Dock, Catalogue, Registry, WardBeing.** The onion.
 - **World, PointerTerrain** and the pointer bodies, `HeldLoader` among
   them. A whole world with this package alone.
+- **addGround, grounds**: the grounds `Harbor.open()` tries, and a way to
+  add your own.
+- **NodeTerrain**, from `nervur/node`: the Node ground's terrain, for a
+  folder you name in code.
+- **BrowserTerrain, IdbMemory, IdbCustody**, from `nervur/browser`: the
+  browser ground's terrain and bodies. `serveWorker(Harbor.open())` at
+  the top of a shared or service worker holds one harbor for every tab,
+  each tab asks it with `rootOf(worker)`, and a push the service worker
+  hears makes every relay client `ring`.
 - **FolderMemory, FolderCustody**, from `nervur/folder`.
 - **TcpCarrier, TcpListener**, from `nervur/tcp`: Quo over TCP. Route a
-  ward pk to `host:port` on the carrier, hand the listener your harbor,
-  and harbors in two processes, or a harbor and another kit, speak.
-
-Other carriers, storage beyond a folder, key custody, and every screen
-are `@nervur-org/dock`'s, as classes fulfilling these contracts.
+  ward pk to its `tcp://host:port` addresses on the carrier, hand the
+  listener your harbor, and harbors in two processes, or a harbor and
+  another kit, speak. `tcpFaculty` is the same carrier as a faculty of a
+  harbor.
+- **WebDialer, webFaculty**: Quo over the web, a post to `https://` or a
+  held line to `wss://`, in any engine with `fetch` and WebSocket.
+  `webServe` and `webGround`, from `nervur/http`, listen for it on Node.
+
+- **The relay**, `org.nervur.relay` and `org.nervur.relay-client`, in
+  every harbor: a harbor nobody can dial is reached through one that
+  can, by relations alone. See "A harbor nobody dials" below.
+- **Push, webPush**: a ring with no content, as Web Push sends it,
+  signed with VAPID, on fetch and Web Crypto.
+
+Carriers such as MCP, and every screen, are `@nervur-org/*`'s, as
+classes fulfilling these contracts.
 
 ## The command
 
@@ -132,33 +222,50 @@ folder, Quo over TCP as its carrier. A module is a file that exports
 
 ```sh
 nervur init  --dir ./harbor
-nervur module add ./greetings.js --dir ./harbor
+nervur module add ./greetings.js --dir ./harbor   # or @acme/greetings, or its id
 nervur serve --dir ./harbor --port 7000
+nervur reach tcp://harbor.example:7000 --dir ./harbor
+nervur open web org.nervur.web --dir ./harbor
+nervur ask web listen '{"port":8080,"path":"/quo"}' --dir ./harbor
 nervur host alice --dir ./harbor
 nervur boot --ward alice greeter org.example.greeter --dir ./harbor
-nervur route <ward pk> host:port --dir ./harbor
 nervur ask --ward alice greeter hello --dir ./harbor
 ```
 
+`reach` names where the harbor is reached, and every invitation it gives
+carries those addresses in `at`. With no `reach`, an invitation carries
+where the harbor listens, which serves a harbor callers reach directly;
+behind a router or a proxy, name the public address with `reach`. A
+harbor that takes such an invitation keeps them as that ward's route,
+so nobody routes it by hand. Where an invitation carries no `at`,
+`nervur route <ward pk> tcp://host:port` names the route, and a route
+named this way is trusted first.
+
 `init` makes the harbor and prints its pk and an owner invitation. `serve`
 listens for Quo on TCP and for the root's asks on a local socket, open to
 you alone. Every other command is one root ask, sent to the served
 harbor, or answered from the folder when none is served. Each prints one
-JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`. The
-catalogue keeps a module by its file's absolute path, and routes live in
-the harbor like everything else, so a restart finds both. `nervur
+JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`.
+`module add` takes a file, an installed package, or a module's id, and
+the catalogue keeps the id the module declares, so the same harbor finds
+its code on any ground: on this machine through `modules.json` beside
+the harbor, which remembers where each id was found, and on an edge or
+in a browser in the bundle. Routes live in the harbor like everything
+else, so a restart finds both. `nervur
 modules` shows what runs, and `nervur module remove <module>` stops one.
 
 A harbor elsewhere is piloted with the owner invitation its `init`
 printed, from a harbor of your own:
 
 ```sh
-nervur pilot far '<owner invitation>' host:port --dir ./mine
+nervur pilot far '<owner invitation>' --dir ./mine
 nervur host shop --via far --dir ./mine
 ```
 
 `pilot` boots an `org.nervur.pilot` being in your harbor that holds the
-invitation as an ordinary Quo relation, kept in your harbor's memory. With
+invitation as an ordinary Quo relation, kept in your harbor's memory, and
+reaches the far harbor where its invitation's `at` says; where it says
+nothing, name the address after the invitation. With
 `--via far`, any command is asked of the far harbor as its owner, sealed
 over TCP, except `own` and `disown`, which stay the far root's.
 `nervur unboot far` lets it go.
@@ -166,6 +273,61 @@ over TCP, except `own` and `disown`, which stay the far root's.
 `rootLine(harbor, request)` is the same request in code, for any other
 front: `{ ward?, method?, args? }` in, one JSON answer out.
 
+## A harbor nobody dials
+
+A device behind a home router listens nowhere a caller can reach. A
+served harbor that can be reached relays for it. On the relay's harbor:
+
+```sh
+nervur open relay org.nervur.relay --dir ./relay
+nervur ask relay invite '{"id":"house","wards":["<camera ward pk>"]}' --dir ./relay
+```
+
+On the device, with the relay's address as its own reach:
+
+```sh
+nervur open client org.nervur.relay-client --dir ./house
+nervur ask client hold '{"invitation":<the invitation>,"line":true}' --dir ./house
+nervur reach tcp://relay.example:7000 --dir ./house
+nervur serve --dir ./house
+```
+
+Every invitation the device gives now sends callers to the relay. The
+relay holds each sealed box, the client collects it by an ordinary ask,
+hands it to the device's door, and returns the sealed reply in its next
+ask. Nothing is opened on the way. `line` keeps collecting, for a
+camera. Without it the client is a doorbell: `ring` collects what waits,
+and `"every": 60000` rings on a schedule, for a garage door.
+
+A doorbell can also be rung by a push with nothing in it. The relay's
+harbor opens Web Push and names who it is:
+
+```sh
+nervur open push org.nervur.web-push --dir ./relay
+nervur ask push subject '{"subject":"mailto:ops@example.org"}' --dir ./relay
+```
+
+The device asks its client for the key (`nervur ask client key`),
+subscribes to pushes with it, and hands the subscription's endpoint to
+`nervur ask client bell '{"endpoint":"https://..."}'`. When a box waits
+and no line collects, the relay rings that endpoint once. Whatever hears
+the push on the device asks the client's `ring`.
+
+## Moving a harbor
+
+A harbor moves to another machine by its bytes, with no harbor open:
+
+```sh
+nervur export --with-seed --dir ./harbor > harbor.json
+nervur import harbor.json --dir ./elsewhere
+```
+
+`export` reads the folder's sealed places, and carries the seed only
+where you ask for it. `import` writes them into a folder that holds none.
+A package with no seed lands where custody already holds the one it was
+sealed under. In code, `copyPackage(from, to)` carries every place of one
+memory into another.
+
 ## License
 
 Apache-2.0.

package/dist/browser/index.d.ts

@@ -0,0 +1,35 @@
+import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
+import type { GroundProbe } from '../harbor/index.ts';
+import { PointerTerrain } from '../pointer/index.ts';
+export { ringAll, rootOf, serveWorker, type Reaching } from './worker.ts';
+export declare const BROWSER = "browser";
+export declare const BROWSER_HARBOR = "nervur";
+export declare class IdbMemory extends Memory {
+    #private;
+    constructor(name?: string);
+    get name(): string;
+    read(place: string): Promise<Map<string, Uint8Array>>;
+    write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+    protected put(store: IDBObjectStore, key: [string, string], bytes: ArrayBuffer | null): void;
+    places(): Promise<string[]>;
+    forget(place: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class IdbCustody extends Custody {
+    #private;
+    constructor(name?: string, entropy?: Entropy);
+    seed(): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+export type BrowserParts = {
+    readonly where?: string;
+    readonly modules?: readonly Module[];
+};
+export declare class BrowserTerrain extends PointerTerrain {
+    #private;
+    readonly where: string;
+    constructor(parts?: BrowserParts);
+    claim(): Promise<void>;
+    release(): Promise<void>;
+}
+export declare const browserGround: GroundProbe;

package/dist/browser/index.js

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/browser`: the browser ground, in a page or a worker. A harbor
+// keeps its sealed memory and its seed in one IndexedDB database, named
+// by `where`, speaks the web, and holds its database to one run with a
+// Web Lock of the same name.
+//
+//   entries   one sealed entry per key [place, name]
+//   custody   the seed, sealed under an AES-GCM key the engine never
+//             hands out, itself kept as the engine keeps a CryptoKey
+//
+// A keep is one transaction, so it is whole or nothing by IndexedDB's own
+// rule.
+import { Custody, Memory } from '../contract/index.js';
+import { webFaculty, WEB_OPENING, webPush } from '../line/index.js';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.js';
+export { ringAll, rootOf, serveWorker } from './worker.js';
+export const BROWSER = 'browser';
+// The database a harbor keeps itself in unless named.
+export const BROWSER_HARBOR = 'nervur';
+const ENTRIES = 'entries';
+const CUSTODY = 'custody';
+const SEED = 'seed';
+// Past every lowercase hex name, so [place, END] bounds a place's keys.
+const END = '￿';
+const done = (request) => new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB refused'));
+});
+// A transaction's end. A request that fails aborts it, and the abort
+// carries that request's error.
+const finished = (tx) => new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onabort = () => reject(tx.error ?? new Error('the keep was aborted'));
+});
+// One database, opened once per body and made on first open.
+class Database {
+    name;
+    #open;
+    constructor(name) {
+        this.name = name;
+    }
+    get() {
+        this.#open ??= new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.name, 1);
+            request.onupgradeneeded = () => {
+                request.result.createObjectStore(ENTRIES);
+                request.result.createObjectStore(CUSTODY);
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error ?? new Error(`${this.name} did not open`));
+        });
+        return this.#open;
+    }
+    async close() {
+        const open = this.#open;
+        this.#open = undefined;
+        if (open)
+            (await open).close();
+    }
+}
+export class IdbMemory extends Memory {
+    #db;
+    constructor(name = BROWSER_HARBOR) {
+        super();
+        this.#db = new Database(name);
+    }
+    // The database it keeps in.
+    get name() {
+        return this.#db.name;
+    }
+    async read(place) {
+        const store = (await this.#db.get()).transaction(ENTRIES).objectStore(ENTRIES);
+        const range = IDBKeyRange.bound([place, ''], [place, END]);
+        const [keys, values] = await Promise.all([done(store.getAllKeys(range)), done(store.getAll(range))]);
+        return new Map(keys.map((key, i) => [key[1], new Uint8Array(values[i])]));
+    }
+    async write(place, entries) {
+        const tx = (await this.#db.get()).transaction(ENTRIES, 'readwrite');
+        const kept = finished(tx);
+        const store = tx.objectStore(ENTRIES);
+        try {
+            for (const [name, bytes] of entries)
+                this.put(store, [place, name], bytes === null ? null : bytes.slice().buffer);
+        }
+        catch (e) {
+            tx.abort();
+            await kept.catch(() => undefined);
+            throw e;
+        }
+        await kept;
+    }
+    // One entry of a keep: its bytes, or null where it goes.
+    put(store, key, bytes) {
+        if (bytes === null)
+            store.delete(key);
+        else
+            store.put(bytes, key);
+    }
+    async places() {
+        const keys = await done((await this.#db.get()).transaction(ENTRIES).objectStore(ENTRIES).getAllKeys());
+        return [...new Set(keys.map((key) => key[0]))];
+    }
+    async forget(place) {
+        const tx = (await this.#db.get()).transaction(ENTRIES, 'readwrite');
+        tx.objectStore(ENTRIES).delete(IDBKeyRange.bound([place, ''], [place, END]));
+        await finished(tx);
+    }
+    close() {
+        return this.#db.close();
+    }
+}
+export class IdbCustody extends Custody {
+    #db;
+    #entropy;
+    constructor(name = BROWSER_HARBOR, entropy = new CryptoEntropy()) {
+        super();
+        this.#db = new Database(name);
+        this.#entropy = entropy;
+    }
+    // The seed the database holds, or a drawn one sealed there the first
+    // time. Two first asks at once keep the one added first.
+    async seed() {
+        const db = await this.#db.get();
+        const kept = (await done(db.transaction(CUSTODY).objectStore(CUSTODY).get(SEED)));
+        if (kept)
+            return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: kept.iv }, kept.key, kept.sealed));
+        const seed = this.#entropy.draw(32);
+        const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+        const iv = new Uint8Array(this.#entropy.draw(12));
+        const sealed = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, new Uint8Array(seed));
+        const tx = db.transaction(CUSTODY, 'readwrite');
+        tx.objectStore(CUSTODY).add({ key, iv, sealed }, SEED);
+        try {
+            await finished(tx);
+        }
+        catch (e) {
+            if (e.name === 'ConstraintError')
+                return this.seed();
+            throw e;
+        }
+        return seed;
+    }
+    close() {
+        return this.#db.close();
+    }
+}
+// A harbor of the browser: its database, the web opened at genesis, Web
+// Push beside it, and one run to a database, held by a Web Lock where the
+// engine has them.
+export class BrowserTerrain extends PointerTerrain {
+    where;
+    #release;
+    constructor(parts = {}) {
+        const where = parts.where ?? BROWSER_HARBOR;
+        const entropy = new CryptoEntropy();
+        super({ entropy, loader: new HeldLoader(parts.modules ?? []), custody: new IdbCustody(where, entropy), memory: new IdbMemory(where), faculties: [webFaculty(), webPush], opens: [WEB_OPENING] });
+        this.where = where;
+    }
+    async claim() {
+        const locks = globalThis.navigator?.locks;
+        if (!locks)
+            return;
+        const held = await new Promise((granted) => {
+            void locks.request(`nervur:${this.where}`, { ifAvailable: true }, (lock) => {
+                if (lock === null) {
+                    granted(false);
+                    return undefined;
+                }
+                granted(true);
+                return new Promise((release) => (this.#release = release));
+            });
+        });
+        if (!held)
+            throw new Error(`a harbor is already open on ${this.where}`);
+    }
+    async release() {
+        this.#release?.();
+        this.#release = undefined;
+        await this.memory.close();
+        await this.custody.close();
+    }
+}
+// A page or a worker with IndexedDB and Web Crypto.
+export const browserGround = {
+    name: BROWSER,
+    fits: () => typeof indexedDB !== 'undefined' && typeof crypto?.subtle !== 'undefined',
+    terrain: ({ modules, where }) => new BrowserTerrain({ ...(where ? { where } : {}), ...(modules ? { modules } : {}) }),
+};

package/dist/browser/worker.d.ts

@@ -0,0 +1,12 @@
+import type { JsonObject } from '../being/index.ts';
+import { type Harbor } from '../harbor/index.ts';
+type Scope = {
+    addEventListener(type: string, listener: (event: never) => void): void;
+};
+export declare const ringAll: (harbor: Harbor) => Promise<JsonObject[]>;
+export declare const serveWorker: (harbor: Promise<Harbor>, scope?: Scope) => void;
+export type Reaching = {
+    postMessage(message: unknown, transfer: Transferable[]): void;
+};
+export declare const rootOf: (worker: Reaching) => (request: JsonObject) => Promise<JsonObject>;
+export {};

package/dist/browser/worker.js

@@ -0,0 +1,40 @@
+import { RELAY_CLIENT, rootLine } from '../harbor/index.js';
+const answer = async (harbor, data, reply) => {
+    if (!reply)
+        return;
+    let out;
+    try {
+        out = await rootLine(await harbor, data?.request);
+    }
+    catch {
+        out = { error: 'the harbor threw' };
+    }
+    reply.postMessage(out);
+};
+// Every relay client of the harbor asked to collect what waits.
+export const ringAll = async (harbor) => {
+    const keys = Object.entries(harbor.box.partition.beings)
+        .filter(([, row]) => row.class === RELAY_CLIENT)
+        .map(([key]) => key);
+    return Promise.all(keys.map(async (being) => (await harbor.root('ask', { being, method: 'ring' }))));
+};
+// Called as the worker's script starts, so no tab's first message is
+// lost while the harbor opens.
+export const serveWorker = (harbor, scope = globalThis) => {
+    scope.addEventListener('connect', (event) => {
+        const port = event.ports[0];
+        port.onmessage = (message) => void answer(harbor, message.data, message.ports[0]);
+        port.start();
+    });
+    scope.addEventListener('message', (event) => void answer(harbor, event.data, event.ports[0]));
+    scope.addEventListener('push', (event) => event.waitUntil(harbor.then(ringAll)));
+};
+// A tab's root line to the worker's harbor.
+export const rootOf = (worker) => (request) => new Promise((resolve) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = (message) => {
+        channel.port1.close();
+        resolve(message.data);
+    };
+    worker.postMessage({ request }, [channel.port2]);
+});

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export * from './index.ts';

package/dist/browser.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur` as a browser bundle reads it: the main entry, with the browser
+// ground added, so `Harbor.open()` keeps a harbor in IndexedDB.
+import { browserGround } from './browser/index.js';
+import { addGround } from './harbor/index.js';
+export * from './index.js';
+addGround(browserGround);

package/dist/cli/command.d.ts

@@ -7,7 +7,7 @@ export declare const parse: (argv: string[]) => {
 };
 export declare const requestOf: (command: string, words: string[], flags: Record<string, string>) => RootRequest;
 export declare const main: (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void) => Promise<number>;
-export declare const pilotRequests: (name: string, invitation: JsonObject, at: string) => RootRequest[];
+export declare const pilotRequests: (name: string, invitation: JsonObject, at?: string, web?: boolean) => RootRequest[];
 export declare const via: (pilot: string, far: RootRequest) => RootRequest;
 export declare const farAnswer: (local: JsonObject) => JsonObject;
 export declare const SERVING = -1;