nervur 0.20.1 → 0.20.2

package/README.md

@@ -18,6 +18,40 @@ 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:
+
+```js
+import { harborObject } from 'nervur/edge';
+import * as greetings from './greetings.js';
+
+export const Harbor = harborObject([greetings], async (harbor) => {
+  // the worker's own code is the root: runs once the harbor stands
+});
+```
+
+Each object keeps its harbor in its storage, its seed sealed under the
+worker's `NERVUR_SECRET`, answers Quo over the web from its requests,
+and asks 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 world in one process
 
 ```js
@@ -116,13 +150,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
 
@@ -134,12 +188,23 @@ folder, Quo over TCP as its carrier. A module is a file that exports
 nervur init  --dir ./harbor
 nervur module add ./greetings.js --dir ./harbor
 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
@@ -153,12 +218,14 @@ 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 +233,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) => RootRequest[];
 export declare const via: (pilot: string, far: RootRequest) => RootRequest;
 export declare const farAnswer: (local: JsonObject) => JsonObject;
 export declare const SERVING = -1;

package/dist/cli/command.js

@@ -11,9 +11,18 @@
 //   nervur module remove <module>                   a module it runs no more
 //   nervur modules                                  what the catalogue runs
 //   nervur census [--ward W]                        the empty ask
+//   nervur sweep                                    every place of the folder this
+//                                                   harbor does not name, gone
+//   nervur export [--with-seed]                     the harbor as one JSON line, to
+//                                                   carry it to another ground; with
+//                                                   --with-seed the seed goes too
+//   nervur import <file>                            a carried harbor into an empty
+//                                                   folder, `-` being this input
 //   nervur open   <key> <kind>                      a faculty stands in the box ward
 //   nervur host   <ward> [--seed S]                 a hosted ward stands
-//   nervur route  <ward pk> <host:port | none>      where a ward is reached
+//   nervur route  <ward pk> <address... | none>     where a ward is reached, in order
+//   nervur reach  <address...>                      where this harbor is reached, as
+//                                                   every invitation it gives says
 //   nervur boot   [--ward W] <key> <kind>           a being stands
 //   nervur unboot [--ward W] <being>                a being goes
 //   nervur public [--ward W] <key | none>           the being a stranger reaches
@@ -21,8 +30,9 @@
 //   nervur ask    [--ward W] [being] [method] [args] a being, asked as the owner
 //   nervur own    [--ward W] <id>                   an invitation for an owner
 //   nervur disown [--ward W] <id>                   an owner no more
-//   nervur pilot  <name> <invitation> <host:port>   a far ward held as its owner, by a
-//                                                   pilot being of the box ward
+//   nervur pilot  <name> <invitation> [address]     a far ward held as its owner, by a
+//                                                   pilot being of the box ward, at
+//                                                   the address or the invitation's at
 //   nervur <command> --via <name> ...               the command asked of the far ward
 //                                                   that pilot holds, as its owner
 //
@@ -31,11 +41,14 @@
 // ward, and a pilot holds one ward, so --via takes no --ward. The exit is 1
 // when the answer is an error.
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { open, request, serve } from './harbor.js';
-const USAGE = 'usage: nervur <init|serve|module|modules|census|open|host|route|boot|unboot|public|invite|ask|own|disown|pilot> [args] [--dir D] [--ward W] [--via V] [--seed S] [--host H] [--port P]';
+import { harborDir } from '../node/index.js';
+import { carry, isServed, land, open, request, serve } from './harbor.js';
+const USAGE = 'usage: nervur <init|serve|module|modules|census|sweep|open|host|route|reach|boot|unboot|public|invite|ask|own|disown|pilot|export|import> [args] [--dir D] [--ward W] [--via V] [--seed S] [--with-seed] [--host H] [--port P]';
 const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
+// The one flag that stands alone, since what it names is a yes.
+const ALONE = 'with-seed';
 export const parse = (argv) => {
     const flags = {};
     const words = [];
@@ -44,6 +57,8 @@ export const parse = (argv) => {
         const name = arg.startsWith('--') ? arg.slice(2) : undefined;
         if (name === undefined)
             words.push(arg);
+        else if (name === ALONE)
+            flags[name] = 'yes';
         else if (!FLAGS.has(name) || argv[i + 1] === undefined)
             throw new Error(`--${name} is no flag with a value`);
         else
@@ -52,6 +67,13 @@ export const parse = (argv) => {
     const [command, ...rest] = words;
     return { ...(command === undefined ? {} : { command }), words: rest, flags };
 };
+// What this command was handed on its input, for `import -`.
+const standingIn = async () => {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk.toString('utf8');
+    return text;
+};
 const none = (word) => (word === 'none' ? null : word);
 const json = (word) => (word === undefined ? undefined : JSON.parse(word));
 const catalogue = (method, args = {}) => ({ method: 'ask', args: { being: 'catalogue', method, args } });
@@ -74,6 +96,8 @@ export const requestOf = (command, words, flags) => {
         }
         case 'modules':
             return (need(0), catalogue('modules'));
+        case 'sweep':
+            return (need(0), { method: 'sweep', args: {} });
         case 'census':
             return (need(0), at);
         case 'open': {
@@ -85,9 +109,15 @@ export const requestOf = (command, words, flags) => {
             return { method: 'host', args: { ward: ward, ...(flags.seed === undefined ? {} : { seed: flags.seed }) } };
         }
         case 'route': {
-            const [ward, where] = need(2);
-            return { method: 'route', args: { ward: ward, at: none(where) } };
+            const [ward, ...where] = words;
+            if (ward === undefined || where.length === 0)
+                throw new Error('route takes a ward pk and its addresses, or none');
+            return { method: 'route', args: { ward, at: where.length === 1 && where[0] === 'none' ? null : where } };
         }
+        case 'reach':
+            if (words.length === 0)
+                throw new Error('reach takes the addresses this harbor is reached at');
+            return { method: 'reach', args: { at: words } };
         case 'boot': {
             const [key, kind] = need(2);
             return { ...at, method: 'boot', args: { key: key, class: kind } };
@@ -124,7 +154,7 @@ export const main = async (argv, env, print) => {
     const { command, words, flags } = parse(argv);
     if (command === undefined)
         throw new Error(USAGE);
-    const dir = flags.dir ?? env.NERVUR_DIR ?? join(homedir(), '.nervur');
+    const dir = flags.dir ?? harborDir(env);
     const out = (answer) => {
         print(JSON.stringify(answer));
         return failed(answer) ? 1 : 0;
@@ -134,15 +164,27 @@ export const main = async (argv, env, print) => {
             throw new Error('init takes no argument');
         if (existsSync(join(dir, 'seed')))
             return out({ error: `a harbor stands at ${dir}` });
-        const { harbor, carrier } = await open(dir);
+        const harbor = await open(dir);
         try {
             const owner = await harbor.root('own', { id: 'owner' });
             return out({ pk: harbor.box.pk, owner: owner });
         }
         finally {
-            await carrier.close();
+            await harbor.close();
         }
     }
+    if (command === 'export' || command === 'import') {
+        if (words.length !== (command === 'import' ? 1 : 0))
+            throw new Error(`${command} takes ${command === 'import' ? 'one file' : 'no argument'}`);
+        if (flags.via !== undefined)
+            throw new Error(`${command} reads this folder, so it takes no --via`);
+        if (await isServed(dir))
+            throw new Error(`a harbor is served from ${dir}: stop it first`);
+        if (command === 'export')
+            return out((await carry(dir, flags[ALONE] !== undefined)));
+        const text = words[0] === '-' ? await standingIn() : await readFile(words[0], 'utf8');
+        return out({ landed: await land(dir, JSON.parse(text)) });
+    }
     if (command === 'serve') {
         if (words.length > 0)
             throw new Error('serve takes no argument');
@@ -150,12 +192,12 @@ export const main = async (argv, env, print) => {
         const stop = () => void served.close().then(() => process.exit(0));
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
-        print(JSON.stringify({ pk: served.pk, at: served.at, root: served.root }));
+        print(JSON.stringify({ pk: served.pk, at: served.at, listening: served.listening, root: served.root }));
         return SERVING;
     }
     if (command === 'pilot') {
-        if (words.length !== 3)
-            throw new Error('pilot takes 3 arguments');
+        if (words.length !== 2 && words.length !== 3)
+            throw new Error('pilot takes a name, an invitation, and an address where the invitation carries none');
         const [name, invitation, at] = words;
         const held = JSON.parse(invitation);
         for (const req of pilotRequests(name, held, at)) {
@@ -174,9 +216,10 @@ export const main = async (argv, env, print) => {
         throw new Error('--via takes no --ward');
     return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
 };
-// The root requests that hold a far ward: its route, the pilot, the take.
+// The root requests that hold a far ward: its route where one is named,
+// else the take learns it from the invitation's `at`; the pilot; the take.
 export const pilotRequests = (name, invitation, at) => [
-    { method: 'route', args: { ward: invitation.ward ?? null, at } },
+    ...(at === undefined ? [] : [{ method: 'route', args: { ward: invitation.ward ?? null, at: [at] } }]),
     { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
     { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },
 ];