nervur 0.21.2 → 0.21.4

package/src/edge/index.ts

@@ -4,23 +4,25 @@
 // object answers Quo over the web, a post or a held line, since a worker
 // takes no inbound TCP; and it asks over TCP and the web.
 //
-// A harbor born on another ground is carried here: its seed is the
-// worker's `NERVUR_SEED`, and its sealed package, bundled with the worker,
-// lands in the object's storage the first time the object starts. Its
-// owner holds the owner invitation minted where it was born, and pilots
-// it over the web. A harbor born here draws its seed and seals it under
-// the worker's `NERVUR_SECRET`.
+// One worker carries many harbors, each a Durable Object by its name,
+// answering at `/<name>/quo`, and one secret, `NERVUR_SECRET`, for all of
+// them. A harbor born on another ground is carried here in a pack: by
+// name, its seed sealed under that secret and its sealed places, bundled
+// with the worker and landed the first time its object starts. So a
+// harbor is added by a deploy, never by a new secret. Its owner holds the
+// owner invitation minted where it was born, and pilots it over the web.
+// A harbor born here draws its seed and seals it the same way.
 //
 //   m/<place>/<name>   one sealed entry of the harbor's memory
-//   c/seed             a drawn seed, sealed under a key from the secret
+//   c/seed             the seed, sealed under a key from the secret
 //
 // A keep is one storage transaction, whole or nothing. The storage and
 // state types name only what the kit uses, so no Cloudflare package is a
 // dependency.
 import type { AskSpec, JsonObject } from '../being/index.ts';
 import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
-import { decrypt, encrypt, hkdf, isHex, unhex, utf8 } from '../crypto/index.ts';
-import { addGround, CarrierFaculty, Harbor, landPlaces, UNDIALED, type Carried, type Dialed, type Ground, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
+import { concat, decrypt, encrypt, hex, hkdf, isHex, unhex, utf8 } from '../crypto/index.ts';
+import { addGround, CarrierFaculty, Harbor, landPlaces, readCarried, UNDIALED, type Carried, type Dialed, type Ground, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
 import { answerHeld, answerPost, askFrame, FrameReader, TCP, TCP_OPENING, WEB_OPENING, webFaculty, webPush, type WebListen, type WebListener } from '../line/index.ts';
 import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
 import { tcpAddress, tcpAt, type TcpAddress } from '../quo/index.ts';
@@ -47,10 +49,42 @@ export interface EdgeState {
   readonly storage: EdgeStorage;
   blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
 }
-export type EdgeEnv = { readonly NERVUR_SEED?: string; readonly NERVUR_SECRET?: string };
+export type EdgeEnv = { readonly NERVUR_SECRET?: string };
 // What the object hands its harbor: its state, the worker's environment,
-// and a carried package to land where the object keeps nothing yet.
-export type EdgeGiven = { readonly state: EdgeState; readonly env: EdgeEnv; readonly package?: Carried };
+// and a packed harbor to land where the object keeps no seed yet.
+export type EdgeGiven = { readonly state: EdgeState; readonly env: EdgeEnv; readonly package?: Packed };
+
+// One harbor packed for an edge: its seed sealed under the worker's
+// secret, as hex of the nonce and the sealed bytes, and its sealed places.
+// A pack is every harbor of a worker, by name.
+export type Packed = { readonly sealed: string; readonly places: Carried['places'] };
+export type Pack = Record<string, Packed>;
+
+// A harbor's name on the edge: one path segment, so it is where the
+// harbor answers, `/<name>/quo`.
+export const isHarborName = (name: unknown): name is string => typeof name === 'string' && /^[a-z0-9][a-z0-9-]{0,62}$/.test(name);
+const NONCE = 12;
+
+// A pack as JSON reads, or null for anything else.
+export const readPack = (value: unknown): Pack | null => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+  const pack: Record<string, Packed> = {};
+  for (const [name, entry] of Object.entries(value)) {
+    const { sealed, places } = (entry ?? {}) as { sealed?: unknown; places?: unknown };
+    const carried = readCarried({ places });
+    if (!isHarborName(name) || !isHex(sealed) || (sealed as string).length <= NONCE * 2 || carried === null) return null;
+    pack[name] = { sealed: sealed as string, places: carried.places };
+  }
+  return pack;
+};
+
+const sealKey = (secret: string): Promise<Uint8Array> => hkdf(utf8(secret), SEAL_INFO, 32);
+
+// A seed sealed under a worker's secret, as a pack keeps it.
+export const sealSeed = async (secret: string, seed: Uint8Array, entropy: Entropy = new CryptoEntropy()): Promise<string> => {
+  const nonce = entropy.draw(NONCE);
+  return hex(concat(nonce, await encrypt(await sealKey(secret), nonce, new Uint8Array(0), seed)));
+};
 
 const chunks = <T>(items: readonly T[]): T[][] => Array.from({ length: Math.ceil(items.length / BATCH) }, (_, i) => items.slice(i * BATCH, (i + 1) * BATCH));
 const bytesOf = (value: unknown): Uint8Array => new Uint8Array(value instanceof ArrayBuffer ? value : (value as Uint8Array));
@@ -99,33 +133,36 @@ export class EdgeMemory extends Memory {
   }
 }
 
-// The seed a harbor carried here was born with, as 64 hex, where it is
-// named. Otherwise a seed drawn once and kept sealed under a key the
-// secret gives, so the storage alone opens nothing. A harbor with neither
-// does not stand.
-export type EdgeKeys = { readonly seed?: string | undefined; readonly secret?: string | undefined };
-
+// The seed, kept sealed under a key the worker's secret gives, so the
+// storage alone opens nothing: the one a pack landed, or one drawn the
+// first time it is asked for. A worker with no secret stands no harbor.
 export class EdgeCustody extends Custody {
   readonly #storage: EdgeStorage;
-  readonly #keys: EdgeKeys;
+  readonly #secret: string | undefined;
   readonly #entropy: Entropy;
   readonly #key: string;
-  constructor(storage: EdgeStorage, keys: EdgeKeys, entropy: Entropy = new CryptoEntropy(), root = '') {
+  constructor(storage: EdgeStorage, secret: string | undefined, entropy: Entropy = new CryptoEntropy(), root = '') {
     super();
     this.#storage = storage;
-    this.#keys = keys;
+    this.#secret = secret;
     this.#entropy = entropy;
     this.#key = `${root}${SEED}`;
   }
 
+  // Whether a seed is kept, so a pack lands only where none is.
+  async kept(): Promise<boolean> {
+    return (await this.#storage.get(this.#key)) !== undefined;
+  }
+
+  // A packed seed, sealed as `sealSeed` sealed it, kept as it came.
+  async land(sealed: string, txn: EdgeStorage = this.#storage): Promise<void> {
+    const bytes = unhex(sealed);
+    await txn.put({ [this.#key]: { nonce: bytes.slice(0, NONCE), sealed: bytes.slice(NONCE) } });
+  }
+
   async seed(): Promise<Uint8Array> {
-    const { seed: named, secret } = this.#keys;
-    if (named !== undefined) {
-      if (!isHex(named.trim(), 32)) throw new Error('NERVUR_SEED is not 64 hex');
-      return unhex(named.trim());
-    }
-    if (!secret) throw new Error('the worker holds no NERVUR_SECRET');
-    const key = await hkdf(utf8(secret), SEAL_INFO, 32);
+    if (!this.#secret) throw new Error('the worker holds no NERVUR_SECRET');
+    const key = await sealKey(this.#secret);
     return this.#storage.transaction(async (txn) => {
       const kept = (await txn.get(this.#key)) as { nonce: Uint8Array; sealed: Uint8Array } | undefined;
       if (kept) {
@@ -134,7 +171,7 @@ export class EdgeCustody extends Custody {
         return seed;
       }
       const seed = this.#entropy.draw(32);
-      const nonce = this.#entropy.draw(12);
+      const nonce = this.#entropy.draw(NONCE);
       await txn.put({ [this.#key]: { nonce, sealed: await encrypt(key, nonce, new Uint8Array(0), seed) } });
       return seed.slice();
     });
@@ -303,9 +340,7 @@ export class EdgeTerrain extends PointerTerrain {
     super({
       entropy,
       loader: new HeldLoader(parts.modules ?? []),
-      // Only a harbor carried here takes the worker's NERVUR_SEED; every
-      // other object of the worker draws its own.
-      custody: new EdgeCustody(storage, { seed: parts.given.package ? parts.given.env.NERVUR_SEED : undefined, secret: parts.given.env.NERVUR_SECRET }, entropy),
+      custody: new EdgeCustody(storage, parts.given.env.NERVUR_SECRET, entropy),
       memory: new EdgeMemory(storage),
       faculties: [edgeTcp, webFaculty(edgeServe), webPush],
       opens: [TCP_OPENING, WEB_OPENING],
@@ -313,13 +348,16 @@ export class EdgeTerrain extends PointerTerrain {
     this.given = parts.given;
   }
 
-  // A carried package lands where the object keeps nothing yet, and only
-  // under the seed it was sealed with, the worker's `NERVUR_SEED`.
+  // A packed harbor lands where the object keeps no seed yet: its places
+  // first and its seed last, so a start cut short lands it whole again,
+  // and once the seed is kept the storage is the harbor and a new deploy
+  // leaves it be. A seed sealed under another secret does not open.
   override async claim(): Promise<void> {
-    const { package: carried, env } = this.given;
-    if (!carried || (await this.memory.places()).length > 0) return;
-    if (env.NERVUR_SEED === undefined) throw new Error('a carried package opens only under NERVUR_SEED');
-    await landPlaces(this.memory, carried);
+    const packed = this.given.package;
+    const custody = this.custody as EdgeCustody;
+    if (!packed || (await custody.kept())) return;
+    await landPlaces(this.memory, { places: packed.places });
+    await custody.land(packed.sealed);
   }
 
   override stand(harbor: Harbor): Promise<void> {
@@ -358,52 +396,77 @@ export const edgeGround: GroundProbe = {
   terrain: ({ given, modules }) => new EdgeTerrain({ given: given as EdgeGiven, ...(modules ? { modules } : {}) }),
 };
 
+// The harbor a request is for: the first segment of its path.
+export const harborNameOf = (request: Request): string | null => {
+  const name = new URL(request.url).pathname.split('/')[1];
+  return isHarborName(name) ? name : null;
+};
+
 // What a Durable Object class of harbors is made of:
 //
 //   modules   the code its harbors run
-//   package   a harbor carried here, from `nervur edge pack`, landed the
-//             first time an object starts; or a function of the worker's
-//             environment giving one
-//   path      where every object answers Quo, `/quo` unless named, on
-//             whatever host reaches it
-//   stood     the worker's own code, the root, run once the harbor stands
+//   pack      the harbors carried here, from `nervur edge pack`, each
+//             landed the first time its object starts; or a function of
+//             the worker's environment giving them
+//   born      the names a harbor may be born under here, with a seed of
+//             its own, where the pack holds none; none unless named, so a
+//             stranger's request mints no harbor
+//   stood     the worker's own code, the root, run once a harbor stands,
+//             with the harbor's name
 export type HarborObjectParts = {
   readonly modules: readonly Module[];
-  readonly package?: Carried | ((env: EdgeEnv) => Carried | undefined);
-  readonly path?: string;
-  readonly stood?: (harbor: Harbor) => Promise<void>;
+  readonly pack?: Pack | ((env: EdgeEnv) => Pack | undefined);
+  readonly born?: (name: string) => boolean;
+  readonly stood?: (harbor: Harbor, name: string) => Promise<void>;
 };
-export type HarborObjectClass = new (state: EdgeState, env: EdgeEnv) => { readonly harbor: Promise<Harbor>; fetch(request: Request): Promise<Response> };
-
-// A Durable Object class whose every instance is one harbor: opened once
-// per object, its web carrier opened, and every request it receives
-// answered by that carrier at `path`.
-export const harborObject = ({ modules, package: carried, path = '/quo', stood }: HarborObjectParts): HarborObjectClass =>
-  class HarborObject {
-    readonly #opening: Promise<Harbor>;
-
-    // The object's harbor, once it stands.
-    get harbor(): Promise<Harbor> {
-      return this.#opening;
-    }
+export type HarborObject = { harborFor(request: Request): Promise<Harbor | null>; fetch(request: Request): Promise<Response> };
+export type HarborObjectClass = new (state: EdgeState, env: EdgeEnv) => HarborObject;
+
+// A Durable Object class whose every instance is one harbor, by the name
+// the worker reached it under: opened at its first request, the one its
+// pack holds under that name or one `born` allows, its web carrier opened,
+// and every request it receives answered by that carrier at
+// `/<name>/quo`. An object answers the one name it opened under, and a
+// name it may not open is 404, with nothing written.
+export const harborObject = ({ modules, pack, born, stood }: HarborObjectParts): HarborObjectClass =>
+  class implements HarborObject {
+    readonly #state: EdgeState;
+    readonly #env: EdgeEnv;
+    #name: string | undefined;
+    #opening: Promise<Harbor> | undefined;
 
     constructor(state: EdgeState, env: EdgeEnv) {
       addGround(edgeGround);
-      const held = typeof carried === 'function' ? carried(env) : carried;
-      const given: EdgeGiven = { state, env, ...(held ? { package: held } : {}) };
+      this.#state = state;
+      this.#env = env;
+    }
+
+    // The harbor a request names, opened once, or null where it names
+    // another harbor or none.
+    harborFor(request: Request): Promise<Harbor | null> {
+      const name = harborNameOf(request);
+      if (name === null || (this.#name !== undefined && this.#name !== name)) return Promise.resolve(null);
+      const packed = typeof pack === 'function' ? pack(this.#env) : pack;
+      const held = packed && Object.hasOwn(packed, name) ? packed[name] : undefined;
+      if (this.#name === undefined && !held && !born?.(name)) return Promise.resolve(null);
+      this.#name = name;
       // Opened inside the object's block, so no request reaches it half
       // open and its storage answers the opening.
-      this.#opening = state.blockConcurrencyWhile(async () => {
+      this.#opening ??= this.#state.blockConcurrencyWhile(async () => {
+        const given: EdgeGiven = { state: this.#state, env: this.#env, ...(held ? { package: held } : {}) };
         const harbor = await Harbor.open({ modules, given });
         if (!harbor.box.being(WEB_OPENING.key)) await harbor.root('open', { key: WEB_OPENING.key, class: WEB_OPENING.kind });
-        await stood?.(harbor);
+        await stood?.(harbor, name);
         return harbor;
       });
+      return this.#opening;
     }
 
     async fetch(request: Request): Promise<Response> {
-      const harbor = await this.#opening;
+      const harbor = await this.harborFor(request);
+      if (!harbor) return new Response(null, { status: 404 });
       const terrain = harbor.terrain as EdgeTerrain;
+      const path = `/${this.#name!}/quo`;
       if (terrain.listening?.path !== path) {
         const url = new URL(request.url);
         await harbor.root('ask', { being: WEB_OPENING.key, method: 'listen', args: { host: url.hostname, port: url.port === '' ? 0 : Number(url.port), path } });
@@ -411,3 +474,17 @@ export const harborObject = ({ modules, package: carried, path = '/quo', stood }
       return terrain.answer(request);
     }
   };
+
+type Namespace = { idFromName(name: string): unknown; get(id: unknown): { fetch(request: Request): Promise<Response> } };
+
+// A worker of many harbors: each request goes to the object of the
+// harbor its path names, in the Durable Object namespace bound as
+// `binding`, and a path naming none is 404.
+export const harborWorker = (binding = 'HARBOR') => ({
+  fetch(request: Request, env: Record<string, unknown>): Promise<Response> {
+    const name = harborNameOf(request);
+    const objects = env[binding] as Namespace | undefined;
+    if (name === null || !objects) return Promise.resolve(new Response(null, { status: 404 }));
+    return objects.get(objects.idFromName(name)).fetch(request);
+  },
+});

package/src/harbor/catalogue.ts

@@ -29,6 +29,8 @@ export type ModuleRow = { version: string; from: string; kinds: string[] };
 // What the catalogue asks of her harbor.
 export interface Cataloguing {
   load(from: string): Promise<Loaded | null>;
+  // Why nothing loads from a name, where the loader says more.
+  missing(from: string): string | null;
   // Why these modules cannot run together, or null.
   check(modules: readonly Loaded[]): string | null;
   // The modules run from now on, or why they cannot be.
@@ -72,7 +74,7 @@ export class Catalogue extends Faculty {
         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]);
@@ -86,7 +88,7 @@ export class Catalogue extends Faculty {
     if (!text(args.from)) return { error: 'from is text' };
     const loaded = await this.#harbor.load(args.from).catch((e: Error) => e);
     if (loaded instanceof Error) return { error: loaded.message };
-    if (loaded === null) return { error: 'no such module' };
+    if (loaded === null) 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/src/harbor/dock.ts

@@ -46,6 +46,8 @@ export interface Hosting {
   keep(): Promise<boolean>;
   // What did not stand when the harbor opened.
   failures(): Failures;
+  // Whether the harbor lives only as long as a screen.
+  readonly foreground: boolean;
   // Every place of the memory the dock does not name, gone.
   sweep(): Promise<string[]>;
   // Whether a kind is a carrier this harbor's ground ships.
@@ -92,10 +94,14 @@ export class Dock extends WardBeing implements Lender {
     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.
   override describe(asker: Asker): Blueprint {
     const blueprint = super.describe(asker);
-    if (pilots(asker, this.notes(asker))) (blueprint.notes as JsonObject).failed = this.#hosting.failures();
+    if (!pilots(asker, this.notes(asker))) return blueprint;
+    const notes = blueprint.notes as JsonObject;
+    notes.failed = this.#hosting.failures();
+    if (this.#hosting.foreground) notes.foreground = true;
     return blueprint;
   }
 

package/src/harbor/harbor.ts

@@ -175,6 +175,10 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     });
   }
 
+  get foreground(): boolean {
+    return this.terrain.foreground;
+  }
+
   // Hosting: what did not stand when the harbor opened, each alone.
   failures(): Failures {
     return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
@@ -246,6 +250,10 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     return this.terrain.loader.load(from);
   }
 
+  missing(from: string): string | null {
+    return this.terrain.loader.missing(from);
+  }
+
   check(modules: readonly Loaded[]): string | null {
     return Registry.refusal(this.#kit, modules);
   }

package/src/harbor/terrain.ts

@@ -25,6 +25,12 @@ export abstract 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.
   readonly wakes: boolean = 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(): boolean {
+    return false;
+  }
 
   // Before the harbor opens: a terrain whose ground another run holds
   // refuses here. Once it stands: whatever the ground serves beside it.

package/src/pointer/bodies.ts

@@ -32,7 +32,9 @@ export class HeldCustody extends Custody {
   }
 }
 
-// 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 {
   readonly #modules = new Map<string, Module>();
   constructor(modules: readonly Module[] = []) {
@@ -43,6 +45,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);
   }
+  override missing(from: string): string {
+    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

package/src/proof/law.ts

@@ -203,7 +203,7 @@ export const lawScenes = (t: Terrain, expect: Expect): [string, () => Promise<vo
       expect.same(lost.names, ['w'], 'the rest of the harbor stands');
       expect.same(((await census(lost)) as { beings: Record<string, { absent: boolean }> }).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)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, false);