nervur 0.21.2 → 0.21.4

package/dist/harbor/catalogue.js

@@ -46,7 +46,7 @@ export class Catalogue extends Faculty {
             const refused = loaded instanceof Error
                 ? loaded.message
                 : loaded === null
-                    ? `not found at ${row.from}`
+                    ? (this.#harbor.missing(row.from) ?? `not found at ${row.from}`)
                     : loaded.module !== module
                         ? `${row.from} is module ${loaded.module}`
                         : this.#harbor.check([...this.#running.values(), loaded]);
@@ -64,7 +64,7 @@ export class Catalogue extends Faculty {
         if (loaded instanceof Error)
             return { error: loaded.message };
         if (loaded === null)
-            return { error: 'no such module' };
+            return { error: this.#harbor.missing(args.from) ?? 'no such module' };
         const running = new Map(this.#running);
         running.set(loaded.module, loaded);
         const refused = this.#harbor.run([...running.values()]);

package/dist/harbor/dock.d.ts

@@ -7,6 +7,7 @@ export interface Hosting {
     route(pk: string, at: readonly string[] | null): boolean;
     keep(): Promise<boolean>;
     failures(): Failures;
+    readonly foreground: boolean;
     sweep(): Promise<string[]>;
     grounds(kind: string): boolean;
     awaken(key: string): Promise<void>;

package/dist/harbor/dock.js

@@ -54,11 +54,16 @@ export class Dock extends WardBeing {
         super(stance);
         this.#hosting = hosting;
     }
-    // The census adds what did not stand, for whoever pilots.
+    // The census adds what did not stand, for whoever pilots, and whether
+    // the harbor lives only as long as a screen.
     describe(asker) {
         const blueprint = super.describe(asker);
-        if (pilots(asker, this.notes(asker)))
-            blueprint.notes.failed = this.#hosting.failures();
+        if (!pilots(asker, this.notes(asker)))
+            return blueprint;
+        const notes = blueprint.notes;
+        notes.failed = this.#hosting.failures();
+        if (this.#hosting.foreground)
+            notes.foreground = true;
         return blueprint;
     }
     get hosted() {

package/dist/harbor/harbor.d.ts

@@ -15,6 +15,7 @@ export declare class Harbor extends Carrier implements Hosting, Cataloguing, Res
     sweep(): Promise<string[]>;
     move(name: string, seed: string, from: string | undefined, to: string | undefined): Promise<string | null>;
     release(name: string, store: string | undefined): Promise<void>;
+    get foreground(): boolean;
     failures(): Failures;
     get box(): Ward;
     get dock(): Dock;
@@ -28,6 +29,7 @@ export declare class Harbor extends Carrier implements Hosting, Cataloguing, Res
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
     classOf(kind: string): BeingClass | undefined;
     load(from: string): Promise<Loaded | null>;
+    missing(from: string): string | null;
     check(modules: readonly Loaded[]): string | null;
     run(modules: readonly Loaded[]): string | null;
     stands(kinds: readonly string[]): boolean;

package/dist/harbor/harbor.js

@@ -153,6 +153,9 @@ export class Harbor extends Carrier {
             return being instanceof Store ? [[key, being]] : [];
         });
     }
+    get foreground() {
+        return this.terrain.foreground;
+    }
     // Hosting: what did not stand when the harbor opened, each alone.
     failures() {
         return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
@@ -215,6 +218,9 @@ export class Harbor extends Carrier {
     load(from) {
         return this.terrain.loader.load(from);
     }
+    missing(from) {
+        return this.terrain.loader.missing(from);
+    }
     check(modules) {
         return Registry.refusal(this.#kit, modules);
     }

package/dist/harbor/terrain.d.ts

@@ -15,6 +15,7 @@ export declare abstract class Terrain {
     readonly faculties: readonly GroundFaculty[];
     readonly opens: readonly Opening[];
     readonly wakes: boolean;
+    get foreground(): boolean;
     claim(): Promise<void>;
     stand(_harbor: Harbor): Promise<void>;
     release(): Promise<void>;

package/dist/harbor/terrain.js

@@ -6,6 +6,12 @@ export class Terrain {
     // Whether its carriers wake and listen where their cells say. A harbor
     // opened for one ask and closed again dials and hears nothing.
     wakes = true;
+    // Whether the harbor lives only as long as a screen: a tab's, or a worker
+    // one tab owns. It is reached only while that screen is open, and hears
+    // no push, so its census says so.
+    get foreground() {
+        return false;
+    }
     // Before the harbor opens: a terrain whose ground another run holds
     // refuses here. Once it stands: whatever the ground serves beside it.
     // Once its carriers sleep: what that served, gone.

package/dist/pointer/bodies.d.ts

@@ -18,6 +18,7 @@ export declare class HeldLoader extends Loader {
     #private;
     constructor(modules?: readonly Module[]);
     load(from: string): Promise<Loaded | null>;
+    missing(from: string): string;
 }
 export declare class VolatileMemory extends Memory {
     #private;

package/dist/pointer/bodies.js

@@ -28,7 +28,9 @@ export class HeldCustody extends Custody {
         return Promise.resolve(this.#seed.slice());
     }
 }
-// Modules handed to this object, found by the name each declares.
+// Modules handed to this object, found by the name each declares: the
+// bundle a ground with no disk to load from carries, an edge's or a
+// browser's. A path, a package or any other name is no module of it.
 export class HeldLoader extends Loader {
     #modules = new Map();
     constructor(modules = []) {
@@ -40,6 +42,10 @@ export class HeldLoader extends Loader {
         const m = this.#modules.get(from);
         return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
     }
+    missing(from) {
+        const carried = [...this.#modules.keys()];
+        return `${from} is no module this bundle carries${carried.length === 0 ? ', and it carries none' : `: it carries ${carried.join(', ')}`}`;
+    }
 }
 // Entries that live as long as this object, copied in and out, which is
 // what a restart in one process finds.

package/dist/proof/law.js

@@ -194,7 +194,7 @@ export const lawScenes = (t, expect) => [
             expect.same(lost.names, ['w'], 'the rest of the harbor stands');
             expect.same((await census(lost)).beings.echo?.absent, true);
             expect.same(await lost.root('ask', { being: 'catalogue', method: 'modules' }), {
-                answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `not found at ${law.module}` } },
+                answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `${law.module} is no module this bundle carries, and it carries none` } },
             });
             const again = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([law]) });
             expect.same((await census(again)).beings.echo?.absent, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",

package/src/browser/index.ts

@@ -175,6 +175,15 @@ export class BrowserTerrain extends PointerTerrain {
     this.where = where;
   }
 
+  // A shared or a service worker outlives any one tab, and a service
+  // worker is woken for a push with none open. Anywhere else, a page or a
+  // worker a tab made, the harbor lives with that tab.
+  override get foreground(): boolean {
+    const scope = globalThis as unknown as Record<string, unknown>;
+    const is = (name: string): boolean => typeof scope[name] === 'function' && globalThis instanceof (scope[name] as new () => unknown);
+    return !is('SharedWorkerGlobalScope') && !is('ServiceWorkerGlobalScope');
+  }
+
   override async claim(): Promise<void> {
     const locks = (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks;
     if (!locks) return;

package/src/cli/command.ts

@@ -19,14 +19,14 @@
 //                                                   --with-seed the seed goes too
 //   nervur import <file>                            a carried harbor into an empty
 //                                                   folder, `-` being this input
-//   nervur edge pack <file>                         the harbor for an edge: its seed
-//                                                   printed, for the worker's
-//                                                   NERVUR_SEED, and its sealed
-//                                                   package written to the file
-//   nervur edge dev <file> [--port P]               the harbor packed to the file and
+//   nervur edge pack <file> <name>                  the harbor for an edge, under its
+//                                                   name, in the pack the file holds:
+//                                                   its seed sealed under
+//                                                   $NERVUR_SECRET, and its places
+//   nervur edge dev <file> <name> [--port P]        the harbor packed so, and the pack
 //                                                   run by the worker's own wrangler
 //                                                   dev, from this folder, at
-//                                                   http://127.0.0.1:P/quo
+//                                                   http://127.0.0.1:P/<name>/quo
 //   nervur open   <key> <kind>                      a faculty stands in the box ward
 //   nervur host   <ward> [--seed S] [--store K]     a hosted ward stands, kept by the
 //                                                   root memory or the store K
@@ -197,11 +197,11 @@ export const main = async (argv: string[], env: Record<string, string | undefine
     return out({ landed: await land(dir, JSON.parse(text)) });
   }
   if (command === 'edge') {
-    if ((words[0] !== 'pack' && words[0] !== 'dev') || words.length !== 2) throw new Error('edge takes pack or dev, and a file');
+    if ((words[0] !== 'pack' && words[0] !== 'dev') || words.length !== 3) throw new Error('edge takes pack or dev, a file, and the harbor name');
     if (flags.via !== undefined) throw new Error(`edge ${words[0]} 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 (words[0] === 'pack') return out(await pack(dir, words[1]!));
-    const dev = await edgeDev(dir, words[1]!, process.cwd(), flags.port === undefined ? EDGE_PORT : Number(flags.port));
+    if (words[0] === 'pack') return out(await pack(dir, words[1]!, words[2]!, env.NERVUR_SECRET));
+    const dev = await edgeDev(dir, words[1]!, words[2]!, process.cwd(), flags.port === undefined ? EDGE_PORT : Number(flags.port), env.NERVUR_SECRET);
     const stop = (): void => void dev.close().then(() => process.exit(0));
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
@@ -221,8 +221,9 @@ export const main = async (argv: string[], env: Record<string, string | undefine
     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 as [string, string, string | undefined];
     const held = JSON.parse(invitation) as JsonObject;
-    const census = (await request(dir, {})) as { answer?: { beings?: JsonObject } };
-    const web = census.answer?.beings !== undefined && Object.hasOwn(census.answer.beings, WEB_OPENING.key);
+    const census = (await request(dir, {})) as { answer?: { notes?: { beings?: JsonObject } } };
+    const beings = census.answer?.notes?.beings;
+    const web = beings !== undefined && Object.hasOwn(beings, WEB_OPENING.key);
     for (const req of pilotRequests(name, held, at, web)) {
       const answer = await request(dir, req);
       if (!failed(answer)) continue;

package/src/cli/edge.ts

@@ -1,16 +1,22 @@
 // SPDX-License-Identifier: Apache-2.0
 // `nervur edge dev`: an edge harbor on this machine, as it will stand on
-// Cloudflare. The harbor of a folder is packed into the file the worker
-// imports, and the worker's own `wrangler dev` runs it, in the folder the
-// command runs from, with the seed handed as `NERVUR_SEED` through the
-// environment so no listing of processes shows it. The object's storage is
-// kept under `.nervur-edge` there, so a harbor landed once stands again
-// across restarts, as it does on Cloudflare.
+// Cloudflare. The harbor of a folder is packed under its name into the
+// pack the worker imports, beside the harbors the pack holds already, and
+// the worker's own `wrangler dev` runs them all, in the folder the command
+// runs from, with the secret handed as `NERVUR_SECRET` through the
+// environment so no listing of processes shows it. The secret is the one
+// the command's environment names, or one drawn once and kept under
+// `.nervur-edge`, beside the objects' storage, so a harbor landed once
+// stands again across restarts, as it does on Cloudflare.
 //
 // wrangler is the worker's tool and never the kit's: the one who deploys
 // an edge has it already, and `edge dev` finds it where npm put it.
 import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { hex } from '../crypto/index.ts';
+import { CryptoEntropy } from '../pointer/index.ts';
 import { pack } from './harbor.ts';
 
 export const EDGE_STATE = '.nervur-edge';
@@ -38,17 +44,30 @@ const ready = async (child: ChildProcess, url: string, said: () => string): Prom
   throw new Error(`wrangler dev never answered at ${url}: ${said()}`);
 };
 
-export const edgeDev = async (dir: string, file: string, cwd: string, port: number): Promise<EdgeDev> => {
-  const { seed, places } = (await pack(dir, file)) as { seed: string; places: number };
-  const child = spawn('npx', ['--no-install', 'wrangler', 'dev', '--ip', '127.0.0.1', '--port', String(port), '--persist-to', join(cwd, EDGE_STATE), '--log-level', 'warn'], {
+// The secret `edge dev` runs under: the one named, or the one kept here.
+const devSecret = async (state: string, named: string | undefined): Promise<string> => {
+  if (named) return named;
+  const file = join(state, 'secret');
+  if (!existsSync(file)) {
+    await mkdir(state, { recursive: true, mode: 0o700 });
+    await writeFile(file, `${hex(new CryptoEntropy().draw(32))}\n`, { mode: 0o600, flag: 'wx' });
+  }
+  return (await readFile(file, 'utf8')).trim();
+};
+
+export const edgeDev = async (dir: string, file: string, name: string, cwd: string, port: number, named?: string): Promise<EdgeDev> => {
+  const state = join(cwd, EDGE_STATE);
+  const secret = await devSecret(state, named);
+  const { places } = (await pack(dir, file, name, secret)) as { places: number };
+  const child = spawn('npx', ['--no-install', 'wrangler', 'dev', '--ip', '127.0.0.1', '--port', String(port), '--persist-to', state, '--log-level', 'warn'], {
     cwd,
-    env: { ...process.env, NERVUR_SEED: seed, CLOUDFLARE_INCLUDE_PROCESS_ENV: 'true' },
+    env: { ...process.env, NERVUR_SECRET: secret, CLOUDFLARE_INCLUDE_PROCESS_ENV: 'true' },
     stdio: ['ignore', 'ignore', 'pipe'],
     detached: true,
   });
   let err = '';
   child.stderr!.on('data', (chunk: Buffer) => (err = `${err}${chunk.toString('utf8')}`.slice(-4000)));
-  const at = `http://127.0.0.1:${String(port)}/quo`;
+  const at = `http://127.0.0.1:${String(port)}/${name}/quo`;
   const close = (): Promise<void> =>
     new Promise((done) => {
       if (child.exitCode !== null) return done();

package/src/cli/harbor.ts

@@ -10,7 +10,8 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { JsonObject } from '../being/index.ts';
-import { hex } from '../crypto/index.ts';
+import { hex, unhex } from '../crypto/index.ts';
+import { isHarborName, readPack, sealSeed, type Pack } from '../edge/index.ts';
 import { FolderCustody, FolderMemory } from '../folder/index.ts';
 import { carryPlaces, Harbor, landPlaces, readCarried, rootLine, type CarrierFaculty, type Carried, type RootRequest } from '../harbor/index.ts';
 import { askServed, MODULES, NodeTerrain, socketOf } from '../node/index.ts';
@@ -49,13 +50,21 @@ export const carry = async (dir: string, seed: boolean): Promise<Carried> => {
   };
 };
 
-// What `nervur edge pack` hands a deploy: the seed, for the worker's
-// `NERVUR_SEED`, and the sealed package without it, for the bundle.
-export const pack = async (dir: string, file: string): Promise<JsonObject> => {
+// What `nervur edge pack` hands a deploy: the harbor of a folder, under
+// its name, in the pack the worker bundles, its seed sealed under the
+// worker's `NERVUR_SECRET` beside its sealed places. Every other harbor
+// the pack holds stays, so one worker carries them all, and nothing in the
+// pack opens without the secret.
+export const pack = async (dir: string, file: string, name: string, secret: string | undefined): Promise<JsonObject> => {
+  if (!isHarborName(name)) throw new Error(`${name} is no harbor name: lowercase letters, digits and -`);
+  if (!secret) throw new Error('edge pack seals the seed under NERVUR_SECRET, and none is set');
   if (!existsSync(join(dir, 'seed'))) throw new Error(`no harbor stands at ${dir}`);
   const { seed, places } = await carry(dir, true);
-  await writeFile(file, `${JSON.stringify({ places })}\n`, { mode: 0o600 });
-  return { seed: seed!, package: file, places: Object.keys(places).length };
+  const held = existsSync(file) ? readPack(JSON.parse(await readFile(file, 'utf8'))) : {};
+  if (held === null) throw new Error(`${file} is no pack`);
+  const packed: Pack = { ...held, [name]: { sealed: await sealSeed(secret, unhex(seed!)), places } };
+  await writeFile(file, `${JSON.stringify(packed)}\n`, { mode: 0o600 });
+  return { packed: name, package: file, harbors: Object.keys(packed).sort(), places: Object.keys(places).length };
 };
 
 // A carried harbor into an empty folder. A folder holding a seed or a

package/src/contract/index.ts

@@ -67,6 +67,11 @@ export type Loaded = Module & { readonly from: string };
 // one thing beside the seed a terrain hands in: a map, an import, a bundle.
 export abstract class Loader {
   abstract load(from: string): Promise<Loaded | null>;
+  // Why a name it found nothing under holds nothing, where it can say more
+  // than that: a bundle names that code comes from it alone.
+  missing(_from: string): string | null {
+    return null;
+  }
 }
 
 // Bytes to a ward pk in; bytes, or null for nothing, out. A harbor hands a