nervur 0.20.0 → 0.20.1

package/src/harbor/package.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// The package: a harbor's memory, sealed under the harbor's seed. The
+// terrain keeps its bytes and reads neither a ward's name, nor a being's
+// key, nor anything a row holds.
+//
+//   key            HKDF-SHA-256 of the seed under `nervur-package`
+//   place          16 bytes under ["place", ward], as hex
+//   entry          16 bytes under ["entry", ward, row], as hex
+//   seal           32 bytes under ["seal", ward]
+//   entry bytes    nonce (12) || AES-256-GCM( JSON { row, value } ),
+//                  the entry's name as additional data
+//
+// A row is the head, under the empty name, or one being, under her key. An
+// entry that does not open refuses the whole ward, so nothing unpacks from
+// bytes the package did not seal.
+import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.ts';
+import type { Entropy, Memory, Rows } from '../contract/index.ts';
+import { HEAD_ROW } from '../ward/index.ts';
+
+const NONCE = 12;
+const LABEL = utf8('nervur-package');
+
+type Sealed = { row: string; value: unknown };
+
+class PackageRows implements Rows {
+  readonly rows: Record<string, unknown>;
+  readonly #ward: Ward;
+  readonly #told = new Set<string>();
+  #line: Promise<boolean> = Promise.resolve(true);
+
+  constructor(ward: Ward, rows: Record<string, unknown>) {
+    this.#ward = ward;
+    this.rows = rows;
+  }
+
+  told(row: string): void {
+    this.#told.add(row);
+  }
+
+  // Every row told since the last keep, sealed and written as one keep, one
+  // keep at a time.
+  kept(): Promise<boolean> {
+    const rows = [...this.#told];
+    this.#told.clear();
+    this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+    return this.#line;
+  }
+
+  async #write(told: string[]): Promise<boolean> {
+    const beings = (this.rows.beings ?? {}) as Record<string, unknown>;
+    const entries = new Map<string, Uint8Array | null>();
+    for (const row of told) {
+      const value = row === HEAD_ROW ? (this.rows.ward ?? null) : Object.hasOwn(beings, row) ? beings[row] : undefined;
+      entries.set(await this.#ward.entry(row), value === undefined ? null : await this.#ward.seal(row, value));
+    }
+    await this.#ward.write(entries);
+    return true;
+  }
+}
+
+class Ward {
+  readonly #pack: Package;
+  readonly #name: string;
+  readonly #seal: Uint8Array;
+  readonly place: string;
+
+  constructor(pack: Package, name: string, seal: Uint8Array, place: string) {
+    this.#pack = pack;
+    this.#name = name;
+    this.#seal = seal;
+    this.place = place;
+  }
+
+  entry(row: string): Promise<string> {
+    return this.#pack.derive(['entry', this.#name, row], 16).then(hex);
+  }
+
+  async seal(row: string, value: unknown): Promise<Uint8Array> {
+    const nonce = this.#pack.entropy.draw(NONCE);
+    const text = utf8(JSON.stringify({ row, value } satisfies Sealed));
+    return concat(nonce, await encrypt(this.#seal, nonce, utf8(await this.entry(row)), text));
+  }
+
+  // The name is the additional data, so an entry moved under another name
+  // does not open either.
+  async open(name: string, bytes: Uint8Array): Promise<Sealed> {
+    const text = bytes.length > NONCE ? await decrypt(this.#seal, bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE)) : null;
+    if (text === null) throw new Error('an entry the package did not seal');
+    return JSON.parse(new TextDecoder().decode(text)) as Sealed;
+  }
+
+  write(entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    return this.#pack.memory.write(this.place, entries);
+  }
+}
+
+export class Package {
+  readonly memory: Memory;
+  readonly entropy: Entropy;
+  readonly #key: Uint8Array;
+
+  private constructor(memory: Memory, entropy: Entropy, key: Uint8Array) {
+    this.memory = memory;
+    this.entropy = entropy;
+    this.#key = key;
+  }
+
+  static async open(memory: Memory, entropy: Entropy, seed: Uint8Array): Promise<Package> {
+    return new Package(memory, entropy, await hkdf(seed, LABEL, 32));
+  }
+
+  derive(info: string[], length: number): Promise<Uint8Array> {
+    return hkdf(this.#key, utf8(JSON.stringify(info)), length);
+  }
+
+  // One ward's rows, as the package kept them.
+  async rows(name: string): Promise<Rows> {
+    const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));
+    const rows: Record<string, unknown> = {};
+    const beings: Record<string, unknown> = {};
+    let any = false;
+    for (const [entry, bytes] of await this.memory.read(ward.place)) {
+      const { row, value } = await ward.open(entry, bytes);
+      any = true;
+      if (row === HEAD_ROW) rows.ward = value;
+      else beings[row] = value;
+    }
+    if (any) rows.beings = beings;
+    return new PackageRows(ward, rows);
+  }
+}

package/src/harbor/registry.ts

@@ -1,20 +1,73 @@
 // SPDX-License-Identifier: Apache-2.0
-// The catalogue a program hands its harbor, indexed by class name. It
-// resolves a name a row keeps, and decides nothing about what stands.
-import type { BeingClass } from '../being/index.ts';
+// The catalogue's index: every kind the harbor runs, from the kit's own
+// classes and the modules the catalogue loaded. It resolves a kind a row
+// keeps, and decides nothing about what stands. It refuses any set of
+// modules two readings could split:
+//
+//   a module whose name is no kind, or is the kit's, or two of one name
+//   a class with no kind of its own, or one outside its module's domain
+//   two classes of one kind, or one kind in two modules
+//   a contract with no kind of its own, or one kind for two contracts
+//   a kind that is a class and a contract
+//
+// A module's domain is its name's first two segments: `com.acme.shop`
+// stands classes under `com.acme.` alone. A contract may be any domain's,
+// so a faculty fulfils a contract another module declares. Two harbors hold
+// two registries, and nothing between them names a class.
+import { Faculty, isKind, KIT, kindOf, type BeingClass } from '../being/index.ts';
+import type { Module } from '../contract/index.ts';
 import type { Catalogue } from '../ward/index.ts';
 
+const domainOf = (name: string): string => `${name.split('.').slice(0, 2).join('.')}.`;
+
 export class Registry implements Catalogue {
   readonly #classes = new Map<string, BeingClass>();
+  readonly #modules = new Map<string, string[]>();
 
-  constructor(classes: readonly BeingClass[]) {
-    for (const C of classes) {
-      if (this.#classes.has(C.name) && this.#classes.get(C.name) !== C) throw new Error(`two classes are named ${C.name}`);
-      this.#classes.set(C.name, C);
+  // `kit` holds the kit's own classes, which alone may be of its kinds.
+  constructor(kit: readonly BeingClass[], modules: readonly Module[]) {
+    const contracts = new Map<string, unknown>();
+    const owners = new Map<string, string>();
+    const add = (C: BeingClass, kind: string): void => {
+      if (this.#classes.has(kind) && this.#classes.get(kind) !== C) throw new Error(`two classes are of kind ${kind}`);
+      this.#classes.set(kind, C);
+    };
+    for (const C of kit) add(C, kindOf(C));
+    for (const m of modules) {
+      if (!isKind(m.module) || m.module.startsWith(KIT)) throw new Error(`module ${String(m.module)} is no name a module may take`);
+      if (this.#modules.has(m.module)) throw new Error(`two modules are named ${m.module}`);
+      if (typeof m.version !== 'string' || m.version === '') throw new Error(`module ${m.module} declares no version`);
+      const kinds: string[] = [];
+      for (const C of m.classes) {
+        if (typeof C !== 'function') throw new Error(`module ${m.module} holds something that is no class`);
+        const kind = kindOf(C);
+        if (!kind.startsWith(domainOf(m.module))) throw new Error(`kind ${kind} is outside module ${m.module}`);
+        const owner = owners.get(kind);
+        if (owner !== undefined && owner !== m.module) throw new Error(`kind ${kind} is in modules ${owner} and ${m.module}`);
+        owners.set(kind, m.module);
+        add(C as BeingClass, kind);
+        kinds.push(kind);
+        if (!Faculty.fulfils(C)) continue;
+        for (let c: unknown = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
+          const contract = kindOf(c);
+          if (contract.startsWith(KIT)) throw new Error(`kind ${contract} is the kit's`);
+          if (contracts.has(contract) && contracts.get(contract) !== c) throw new Error(`two contracts are of kind ${contract}`);
+          contracts.set(contract, c);
+        }
+      }
+      this.#modules.set(m.module, kinds);
+    }
+    for (const kind of contracts.keys()) {
+      if (this.#classes.has(kind)) throw new Error(`kind ${kind} is a class and a contract`);
     }
   }
 
-  classOf(name: string): BeingClass | undefined {
-    return this.#classes.get(name);
+  classOf(kind: string): BeingClass | undefined {
+    return this.#classes.get(kind);
+  }
+
+  // The kinds a module stands, or none.
+  kindsOf(module: string): string[] {
+    return [...(this.#modules.get(module) ?? [])];
   }
 }

package/src/harbor/root-line.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// The root line: one request, one answer, both plain JSON, for whatever
+// carries the root's asks to a harbor in its own process. The command line
+// carries it over a local socket, and an edge route carries it the same way.
+//
+//   request  { ward?, method?, args? }    no ward is the box ward, no
+//                                         method the census
+//   answer   { answer }                   what the ward-being said
+//            { silence: true }            she said nothing
+//            { word }                     a kit word: unreached, late, ...
+//            { error }                    the request was not one, or the
+//                                         ward is none this harbor holds
+import { isSilence, isWord, told, type Json, type JsonObject } from '../being/index.ts';
+import type { Harbor } from './harbor.ts';
+
+export type RootRequest = { ward?: string; method?: string; args?: JsonObject };
+
+const object = (v: unknown): v is JsonObject => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export const readRootRequest = (value: unknown): RootRequest | null => {
+  if (!object(value)) return null;
+  const { ward, method, args } = value;
+  if ((ward !== undefined && typeof ward !== 'string') || (method !== undefined && typeof method !== 'string') || (args !== undefined && !object(args))) return null;
+  return { ...(ward === undefined ? {} : { ward }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) };
+};
+
+export const rootLine = async (harbor: Harbor, value: unknown): Promise<JsonObject> => {
+  const request = readRootRequest(value);
+  if (request === null) return { error: 'not a root request' };
+  const ward = request.ward === undefined ? harbor.box : harbor.ward(request.ward);
+  if (ward === undefined) return { error: 'no such ward' };
+  const out = await ward.root(request.method, request.args);
+  if (isSilence(out)) return { silence: true };
+  if (isWord(out)) return { word: told(out) as string };
+  return { answer: out as Json };
+};

package/src/harbor/terrain.ts

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // Where a harbor runs. A terrain hands the harbor one body for each
 // contract the onion cannot unpack from cells.
-import type { Carrier, Clock, Custody, Entropy, Memory } from '../contract/index.ts';
+import type { Carrier, Clock, Custody, Entropy, Loader, Memory } from '../contract/index.ts';
 
 export abstract class Terrain {
   abstract readonly entropy: Entropy;
   abstract readonly clock: Clock;
   abstract readonly custody: Custody;
   abstract readonly memory: Memory;
+  // The code the catalogue's cells name.
+  abstract readonly loader: Loader;
   // What reaches a ward pk this harbor does not hold.
   abstract readonly carrier: Carrier;
 }

package/src/index.ts

@@ -8,13 +8,13 @@ export type { Answer, Ask, Asker, AskSpec, BeingClass, BeingLike, Blueprint, Inv
 export { readInvitation } from './quo/index.ts';
 
 // What a terrain gives a harbor.
-export { Carrier, Clock, Custody, Entropy, Memory, type Rows } from './contract/index.ts';
+export { Carrier, Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module, type Rows } from './contract/index.ts';
 
 // Wards and the ward-being.
-export { CEILING, DEFAULT, DEPTH, ownerAsk, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
+export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
 
-// The onion.
-export { BOX, Dock, Harbor, Registry, Terrain } from './harbor/index.ts';
+// The onion, and the one line its root's asks cross from any front.
+export { BOX, Catalogue, Dock, Harbor, readRootRequest, Registry, rootLine, Terrain, type RootRequest } from './harbor/index.ts';
 
 // The pointer dock: a whole world in one process.
-export { CryptoEntropy, HeldCustody, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';
+export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';

package/src/pointer/bodies.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // The pointer terrain's bodies: each contract fulfilled in one process,
 // with nothing beyond JavaScript.
-import { Clock, Custody, Entropy, Memory, type Rows } from '../contract/index.ts';
+import { Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module } from '../contract/index.ts';
 
 export class CryptoEntropy extends Entropy {
   draw(length: number): Uint8Array {
@@ -20,28 +20,46 @@ export class SystemClock extends Clock {
   }
 }
 
-// Seeds drawn once per name and held by this object.
+// The harbor's seed, drawn once and held by this object.
 export class HeldCustody extends Custody {
-  readonly #entropy: Entropy;
-  readonly #seeds = new Map<string, Uint8Array>();
+  readonly #seed: Uint8Array;
   constructor(entropy: Entropy) {
     super();
-    this.#entropy = entropy;
+    this.#seed = entropy.draw(32);
   }
-  seed(name: string): Promise<Uint8Array> {
-    let seed = this.#seeds.get(name);
-    if (!seed) this.#seeds.set(name, (seed = this.#entropy.draw(32)));
-    return Promise.resolve(seed);
+  seed(): Promise<Uint8Array> {
+    return Promise.resolve(this.#seed.slice());
   }
 }
 
-// Rows that live as long as this object: opening a name again gives the
-// same rows, which is what a restart in one process finds.
+// Modules handed to this object, found by the name each declares.
+export class HeldLoader extends Loader {
+  readonly #modules = new Map<string, Module>();
+  constructor(modules: readonly Module[] = []) {
+    super();
+    for (const m of modules) this.#modules.set(m.module, m);
+  }
+  load(from: string): Promise<Loaded | null> {
+    const m = this.#modules.get(from);
+    return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
+  }
+}
+
+// Entries that live as long as this object, copied in and out, which is
+// what a restart in one process finds.
 export class VolatileMemory extends Memory {
-  readonly #wards = new Map<string, Rows>();
-  open(name: string): Promise<Rows> {
-    let rows = this.#wards.get(name);
-    if (!rows) this.#wards.set(name, (rows = { rows: {}, told: () => {}, kept: () => Promise.resolve(true) }));
-    return Promise.resolve(rows);
+  readonly #places = new Map<string, Map<string, Uint8Array>>();
+  read(place: string): Promise<Map<string, Uint8Array>> {
+    const entries = this.#places.get(place) ?? new Map<string, Uint8Array>();
+    return Promise.resolve(new Map([...entries].map(([name, bytes]) => [name, bytes.slice()])));
+  }
+  write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    let kept = this.#places.get(place);
+    if (!kept) this.#places.set(place, (kept = new Map()));
+    for (const [name, bytes] of entries) {
+      if (bytes === null) kept.delete(name);
+      else kept.set(name, bytes.slice());
+    }
+    return Promise.resolve();
   }
 }

package/src/pointer/index.ts

@@ -1,4 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
 // The pointer dock: a whole world with `nervur` alone.
-export { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+export { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
 export { NoCarrier, PointerCarrier, PointerTerrain, World, type PointerParts } from './world.ts';

package/src/pointer/world.ts

@@ -3,10 +3,9 @@
 // to harbor that stands in for the internet, and weather between them. A
 // restart drops a harbor and opens a new one on the terrain the world
 // keeps for it, so only what its memory kept comes back.
-import type { BeingClass } from '../being/index.ts';
-import { Carrier, type Clock, type Custody, type Entropy, type Memory } from '../contract/index.ts';
+import { Carrier, type Clock, type Custody, type Entropy, type Loader, type Memory, type Module } from '../contract/index.ts';
 import { Harbor, Terrain } from '../harbor/index.ts';
-import { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+import { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
 
 // A carrier that reaches no one: a harbor alone.
 export class NoCarrier extends Carrier {
@@ -27,7 +26,7 @@ export class PointerCarrier extends Carrier {
   }
 }
 
-export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier };
+export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier; loader?: Loader };
 
 export class PointerTerrain extends Terrain {
   readonly entropy: Entropy;
@@ -35,6 +34,7 @@ export class PointerTerrain extends Terrain {
   readonly custody: Custody;
   readonly memory: Memory;
   readonly carrier: Carrier;
+  readonly loader: Loader;
 
   constructor(parts: PointerParts = {}) {
     super();
@@ -43,23 +43,26 @@ export class PointerTerrain extends Terrain {
     this.custody = parts.custody ?? new HeldCustody(this.entropy);
     this.memory = parts.memory ?? new VolatileMemory();
     this.carrier = parts.carrier ?? new NoCarrier();
+    this.loader = parts.loader ?? new HeldLoader();
   }
 }
 
-type Place = { harbor: Harbor; terrain: Terrain; classes: readonly BeingClass[] };
+type Place = { harbor: Harbor; terrain: Terrain };
 
 export class World {
   readonly #places = new Map<string, Place>();
   // Harbors the world reaches no one in, nor anyone out of.
   readonly cut = new Set<string>();
 
-  // A harbor of this world. `parts` replaces the pointer bodies, a folder's
-  // memory and custody among them.
-  async harbor(name: string, classes: readonly BeingClass[], parts: Omit<PointerParts, 'carrier'> = {}): Promise<Harbor> {
+  // A harbor of this world, whose loader holds `modules` unless `parts`
+  // names a loader. `parts` replaces the pointer bodies, a folder's memory
+  // and custody among them. The harbor runs only the modules its catalogue
+  // was told to add.
+  async harbor(name: string, modules: readonly Module[] = [], parts: Omit<PointerParts, 'carrier'> = {}): Promise<Harbor> {
     if (this.#places.has(name)) throw new Error(`a harbor named ${name} stands`);
-    const terrain = new PointerTerrain({ ...parts, carrier: new PointerCarrier(this) });
-    const harbor = await Harbor.open(terrain, classes);
-    this.#places.set(name, { harbor, terrain, classes });
+    const terrain = new PointerTerrain({ loader: new HeldLoader(modules), ...parts, carrier: new PointerCarrier(this) });
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
     return harbor;
   }
 
@@ -69,16 +72,16 @@ export class World {
     return place.harbor;
   }
 
-  // The harbor opened again on its own terrain, with the classes it was
-  // made with unless others are named. `parts` replaces bodies of the
-  // terrain, as a new process would build them over the same disk.
-  async restart(name: string, classes?: readonly BeingClass[], parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor> {
+  // The harbor opened again on its own terrain. `parts` replaces bodies of
+  // the terrain, as a new process would build them over the same disk, or
+  // with other code.
+  async restart(name: string, parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor> {
     const place = this.#places.get(name);
     if (!place) throw new Error(`no harbor named ${name}`);
     const t = place.terrain;
-    const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, ...parts, carrier: t.carrier }) : t;
-    const harbor = await Harbor.open(terrain, classes ?? place.classes);
-    this.#places.set(name, { ...place, harbor, terrain });
+    const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, loader: t.loader, ...parts, carrier: t.carrier }) : t;
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
     return harbor;
   }
 

package/src/quo/door.ts

@@ -42,7 +42,7 @@ export class Door {
   }
 
   // A new heir, held fresh, and its invitation. The lock is drawn at the
-  // first invitation that names a heir, before the heir's secret.
+  // first invitation that names an heir, before the heir's secret.
   async invite(): Promise<{ heir: string; invitation: Invitation }> {
     let lock = this.relations.lock();
     if (!lock) this.relations.setLock((lock = drawLock(this.draw)));
@@ -51,7 +51,7 @@ export class Door {
     return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
   }
 
-  // The door stops holding a heir. A fresh one leaves nothing, a spent one
+  // The door stops holding an heir. A fresh one leaves nothing, a spent one
   // leaves the keys kept at removal.
   remove(heir: string): boolean {
     const record = this.relations.get(heir);

package/src/quo/keys.ts

@@ -15,7 +15,7 @@ export const LABEL = {
   wardSeal: utf8('quo-ward-seal'),
 } as const;
 
-// An Ed25519 pair: a heir, or a standing's own key.
+// An Ed25519 pair: an heir, or a standing's own key.
 export class SigningKey {
   readonly secret: Uint8Array;
   readonly pk: Uint8Array;

package/src/stand/main.ts

@@ -17,3 +17,4 @@ for await (const line of createInterface({ input: process.stdin, crlfDelay: Infi
   );
 }
 await Promise.all(pending);
+await stand.close();

package/src/stand/stand.ts

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// The stand of `quo/vectors/HARNESS.md`, part one, over `quo/` alone. Part
-// two carries bytes over TCP, which is the dock's, so its three requests
-// are `bad request`.
+// The stand of `quo/vectors/HARNESS.md`, over `quo/` and `nervur/tcp`:
+// part one judged, and part two carried, its wards answering on one
+// listener and asking through one dialer.
 import { hex, isHex, unhex } from '../crypto/index.ts';
 import { Door, freshStanding, MemoryRelations, readInvitation, Standing, WardKey, type Behind, type Choice, type Draw, type Invitation, type Payload, type Read, type Sent } from '../quo/index.ts';
+import { TcpCarrier, TcpListener } from '../tcp/index.ts';
 
 type Answer = Record<string, unknown>;
 const ERRORS = ['bad request', 'no such op', 'no such ward', 'not reached', 'ward stood', 'name held'] as const;
@@ -51,11 +52,18 @@ const OPS = new Set(['ward', 'invite', 'release', 'arrive', 'ask', 'read', 'list
 export class Stand {
   readonly #wards = new Map<string, StandWard>();
   readonly #draw: Draw;
+  readonly #carrier = new TcpCarrier();
+  #listener: Promise<TcpListener> | undefined;
 
   constructor(draw: Draw) {
     this.#draw = draw;
   }
 
+  async close(): Promise<void> {
+    await this.#carrier.close();
+    await (await this.#listener)?.close();
+  }
+
   async handle(line: string): Promise<Answer> {
     let request: unknown;
     try {
@@ -90,11 +98,45 @@ export class Stand {
         return this.#ask(r);
       case 'read':
         return this.#read(r);
+      case 'listen':
+        return this.#listen();
+      case 'route':
+        return this.#route(r);
       default:
-        return refuse('bad request');
+        return this.#send(r);
     }
   }
 
+  // One listener, answering for every ward this program stands.
+  async #listen(): Promise<Answer> {
+    this.#listener ??= TcpListener.listen({
+      arrive: async (pk, bytes) => {
+        const ward = this.#wards.get(pk);
+        return ward ? (await ward.door.arrive(bytes)).bytes : null;
+      },
+    });
+    return { at: (await this.#listener).at };
+  }
+
+  #route(r: Record<string, unknown>): Answer {
+    const far = r.far;
+    if (!isHex(far, 64) || !this.#carrier.route(far, text(r.at))) return refuse('bad request');
+    return { routed: far };
+  }
+
+  async #send(r: Record<string, unknown>): Promise<Answer> {
+    const invitation = inviteOf(r.invitation);
+    const method = r.method === undefined ? undefined : text(r.method);
+    const args = r.args === undefined ? undefined : objectText(r.args);
+    const ward = this.#ward_(r.ward);
+    const held = this.#standing(ward, invitation);
+    const sent = await held.standing.ask(method, args);
+    if (sent === null) return refuse('bad request');
+    held.last = sent;
+    const reply = await this.#carrier.carry(invitation.ward, sent.bytes);
+    return { read: readOf(await held.standing.read(sent, reply)) };
+  }
+
   async #ward(seed: string, reach: string | undefined): Promise<Answer> {
     reached(reach);
     const key = await WardKey.from(seed);

package/src/tcp/frame.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// The frames of Quo over TCP, `quo/CARRIER-TCP.md`:
+//
+//   frame = length (4, big-endian) || kind (1) || id (4, big-endian) || rest
+//   00 ask      rest = ward pk (64) || box
+//   01 reply    rest = box
+//   02 nothing  rest = empty
+//
+// A reader says a stream is not a frame as soon as its bytes say so, and
+// reads nothing after it.
+import { concat } from '../crypto/index.ts';
+
+export const ASK = 0;
+export const REPLY = 1;
+export const NOTHING = 2;
+export const MAX_BODY = 1_048_645;
+const PK = 64;
+
+export type Frame = { kind: 'ask'; id: number; pk: Uint8Array; box: Uint8Array } | { kind: 'reply'; id: number; box: Uint8Array } | { kind: 'nothing'; id: number };
+
+const frame = (kind: number, id: number, ...rest: Uint8Array[]): Uint8Array => {
+  const head = new Uint8Array(9);
+  const view = new DataView(head.buffer);
+  view.setUint32(0, 5 + rest.reduce((n, r) => n + r.length, 0));
+  head[4] = kind;
+  view.setUint32(5, id >>> 0);
+  return concat(head, ...rest);
+};
+
+export const askFrame = (id: number, pk: Uint8Array, box: Uint8Array): Uint8Array => frame(ASK, id, pk, box);
+export const replyFrame = (id: number, box: Uint8Array): Uint8Array => frame(REPLY, id, box);
+export const nothingFrame = (id: number): Uint8Array => frame(NOTHING, id);
+
+// Whether a body of this length, and this first byte when known, is no frame.
+const notAFrame = (length: number, kind: number | undefined): boolean =>
+  length > MAX_BODY || length < 5 || (kind !== undefined && (kind > NOTHING || (kind === ASK && length < 5 + PK) || (kind === NOTHING && length !== 5)));
+
+export class FrameReader {
+  #buffer: Uint8Array = new Uint8Array(0);
+  #bad = false;
+
+  // True once bytes that are not a frame arrived; nothing is read after.
+  get bad(): boolean {
+    return this.#bad;
+  }
+
+  push(chunk: Uint8Array): Frame[] {
+    if (this.#bad) return [];
+    this.#buffer = this.#buffer.length === 0 ? chunk.slice() : concat(this.#buffer, chunk);
+    const out: Frame[] = [];
+    while (this.#buffer.length >= 4) {
+      const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset);
+      const length = view.getUint32(0);
+      if (notAFrame(length, this.#buffer.length > 4 ? this.#buffer[4] : undefined)) {
+        this.#bad = true;
+        this.#buffer = new Uint8Array(0);
+        return out;
+      }
+      if (this.#buffer.length < 4 + length) break;
+      const body = this.#buffer.subarray(4, 4 + length);
+      this.#buffer = this.#buffer.slice(4 + length);
+      const id = new DataView(body.buffer, body.byteOffset).getUint32(1);
+      if (body[0] === ASK) out.push({ kind: 'ask', id, pk: body.slice(5, 5 + PK), box: body.slice(5 + PK) });
+      else if (body[0] === REPLY) out.push({ kind: 'reply', id, box: body.slice(5) });
+      else out.push({ kind: 'nothing', id });
+    }
+    return out;
+  }
+}
+
+// "host:port" to its parts, or null. A host in brackets is an IPv6 address.
+export const parseAt = (at: unknown): { host: string; port: number } | null => {
+  if (typeof at !== 'string') return null;
+  const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):(\d{1,5})$/.exec(at);
+  if (!m) return null;
+  const port = Number(m[3]);
+  return port > 0 && port < 65_536 ? { host: m[1] ?? m[2]!, port } : null;
+};