nervur 0.19.2 → 0.20.1

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

@@ -0,0 +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, 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

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: what a stranger writes a world with. It imports no platform, so
+// it runs wherever JavaScript runs. A disk is `nervur/folder`.
+
+// Beings, faculties, and what they are told.
+export { Being, canonical, digest, Faculty, isSilence, isWord, OWNER, silence, told, WARD, word } from './being/index.ts';
+export type { Answer, Ask, Asker, AskSpec, BeingClass, BeingLike, Blueprint, Invitation, Json, JsonObject, Occupants, Reply, Schema, Silence, Stance, Standing, Standings, Wanted, Word, WordName } from './being/index.ts';
+export { readInvitation } from './quo/index.ts';
+
+// What a terrain gives a harbor.
+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, Pilot, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/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, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';

package/src/pointer/bodies.ts

@@ -0,0 +1,65 @@
+// 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, Loader, Memory, type Loaded, type Module } from '../contract/index.ts';
+
+export class CryptoEntropy extends Entropy {
+  draw(length: number): Uint8Array {
+    return globalThis.crypto.getRandomValues(new Uint8Array(length));
+  }
+}
+
+export class SystemClock extends Clock {
+  now(): number {
+    return Date.now();
+  }
+  wait(ms: number): { done: Promise<void>; cancel(): void } {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const done = new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)));
+    return { done, cancel: () => clearTimeout(timer) };
+  }
+}
+
+// The harbor's seed, drawn once and held by this object.
+export class HeldCustody extends Custody {
+  readonly #seed: Uint8Array;
+  constructor(entropy: Entropy) {
+    super();
+    this.#seed = entropy.draw(32);
+  }
+  seed(): Promise<Uint8Array> {
+    return Promise.resolve(this.#seed.slice());
+  }
+}
+
+// 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 #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

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

package/src/pointer/world.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer world: harbors in one process, an address book from ward pk
+// 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 { 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, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
+
+// A carrier that reaches no one: a harbor alone.
+export class NoCarrier extends Carrier {
+  carry(): Promise<Uint8Array | null> {
+    return Promise.resolve(null);
+  }
+}
+
+// Bytes to whichever harbor of a world holds the ward pk.
+export class PointerCarrier extends Carrier {
+  readonly #world: World;
+  constructor(world: World) {
+    super();
+    this.#world = world;
+  }
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return this.#world.carry(pk, bytes);
+  }
+}
+
+export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier; loader?: Loader };
+
+export class PointerTerrain extends Terrain {
+  readonly entropy: Entropy;
+  readonly clock: Clock;
+  readonly custody: Custody;
+  readonly memory: Memory;
+  readonly carrier: Carrier;
+  readonly loader: Loader;
+
+  constructor(parts: PointerParts = {}) {
+    super();
+    this.entropy = parts.entropy ?? new CryptoEntropy();
+    this.clock = parts.clock ?? new SystemClock();
+    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 };
+
+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, 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({ loader: new HeldLoader(modules), ...parts, carrier: new PointerCarrier(this) });
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
+    return harbor;
+  }
+
+  get(name: string): Harbor {
+    const place = this.#places.get(name);
+    if (!place) throw new Error(`no harbor named ${name}`);
+    return place.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, loader: t.loader, ...parts, carrier: t.carrier }) : t;
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
+    return harbor;
+  }
+
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    for (const [name, { harbor }] of this.#places) {
+      if (harbor.holds(pk)) return this.cut.has(name) ? Promise.resolve(null) : harbor.arrive(pk, bytes);
+    }
+    return Promise.resolve(null);
+  }
+}

package/src/quo/door.ts

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+// The door: an ask's box in, a reply's box out, judged by the thirteen cases
+// of the spec in their order. A stranger hears one silence whatever the
+// case. The case is handed back beside the bytes, for the kit's own eyes,
+// with `heard`: whether a key the door holds or keeps spoke.
+import { decapsulate, hex, unhex, utf8, x25519Public, zero } from '../crypto/index.ts';
+import { drawLock, SigningKey, type Draw, type WardKey } from './keys.ts';
+import type { Invitation } from './invitation.ts';
+import { readPayload, type Payload } from './payload.ts';
+import type { HeirRecord, Keys, Relations } from './relations.ts';
+import { writeReply, type Reply } from './reply.ts';
+import { checkBody, follow, HEAD, knockEdge, openBody, openHead, replyKey, sealReply, signBody, SIZE, splitBody, splitKnock, ZERO_EDGE, type OpenedHead, type ReplyKey } from './seal.ts';
+
+// The count numbers below the highest a door still honours: those within
+// this span that it has not seen.
+export const SPAN = 64;
+
+export type Choice = { readonly object: string; readonly seen: string | null } | { readonly silence: true };
+
+// What stands behind the door. `zero` says whether anything answers the
+// zero head.
+export interface Behind {
+  readonly zero: boolean;
+  answer(heir: string | null, payload: Payload): Promise<Choice>;
+}
+
+export type Judged = { bytes: Uint8Array; case: number; heard: boolean };
+
+type Body = { edge: Uint8Array; text: Uint8Array; signature: Uint8Array };
+
+export class Door {
+  readonly key: WardKey;
+  readonly relations: Relations;
+  readonly behind: Behind;
+  readonly draw: Draw;
+
+  constructor(key: WardKey, relations: Relations, behind: Behind, draw: Draw) {
+    this.key = key;
+    this.relations = relations;
+    this.behind = behind;
+    this.draw = draw;
+  }
+
+  // A new heir, held fresh, and its invitation. The lock is drawn at the
+  // 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)));
+    const heir = await SigningKey.draw(this.draw);
+    this.relations.set(heir.id, { state: 'fresh' });
+    return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
+  }
+
+  // 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);
+    if (record === undefined || record.state === 'kept') return false;
+    if (record.state === 'fresh') this.relations.delete(heir);
+    else this.relations.set(heir, { state: 'kept', held: record.held, vouched: record.vouched, open: record.open, offered: record.offered });
+    return true;
+  }
+
+  async arrive(bytes: Uint8Array): Promise<Judged> {
+    const stranger = async (n: number): Promise<Judged> => ({ bytes: await this.#silence(bytes), case: n, heard: false });
+    if (bytes.length > SIZE || bytes.length < HEAD) return stranger(1);
+    const agreement = await this.key.open(bytes.subarray(0, HEAD));
+    const opened = agreement && (await openHead(bytes, agreement));
+    if (!opened) return stranger(1);
+    const isZero = zero(opened.head);
+    const heir = hex(opened.head);
+    const record = isZero ? undefined : this.relations.get(heir);
+    const body = await this.#body(opened, record);
+    if (!body) return stranger(1);
+    const read = readPayload(body.text);
+    if ('fault' in read) return stranger(read.fault === 'not an object' ? 2 : 3);
+    const p = read.payload;
+    if (isZero ? p.to !== null : p.to !== heir) return stranger(3);
+
+    if (isZero) {
+      if (!this.behind.zero) return stranger(4);
+      if (!(await checkBody(unhex(p.by), body))) return stranger(5);
+      const choice = await this.#choose(null, p);
+      return { bytes: await this.#sealed(opened, choice), case: 'object' in choice ? 12 : 13, heard: false };
+    }
+
+    if (record === undefined) return stranger(6);
+    if (!admits(record, heir, p.by)) return stranger(7);
+    if (!(await checkBody(unhex(p.by), body))) return stranger(8);
+    const reply = await replyKey(this.draw, opened.lid);
+    if (!reply) return stranger(1);
+    const offered = await follow(body.edge, reply.agreement);
+
+    // Checked again, since another arrival may have moved the keys while
+    // this one was checking its signature.
+    const now = this.relations.get(heir);
+    if (now === undefined || !admits(now, heir, p.by) || !opensUnder(now, body.edge)) return stranger(7);
+    if (now.state === 'kept') return this.#heard(reply, { quo: 'removed' }, 9);
+    if (now.state === 'fresh' && (p.next === null || p.next === heir)) return this.#heard(reply, { quo: 'unannounced' }, 10);
+    if (now.state === 'spent' && !honours(now, p.seq)) return this.#heard(reply, { quo: 'repeated' }, 11);
+
+    this.relations.set(heir, move(now, heir, p, hex(body.edge), hex(offered)));
+    const choice = await this.#choose(heir, p);
+    const kept = await this.relations.kept().catch(() => false);
+    return this.#heard(reply, kept ? choice : { silence: true }, kept && 'object' in choice ? 12 : 13);
+  }
+
+  async #heard(key: ReplyKey, reply: Reply, n: number): Promise<Judged> {
+    return { bytes: await sealReply(key, await this.#signed(reply)), case: n, heard: true };
+  }
+
+  #signed(reply: Reply): Promise<Uint8Array> {
+    return signBody(utf8(writeReply(reply)), this.key.signing);
+  }
+
+  async #choose(heir: string | null, p: Payload): Promise<Choice> {
+    try {
+      return await this.behind.answer(heir, p);
+    } catch {
+      return { silence: true };
+    }
+  }
+
+  async #sealed(opened: OpenedHead, reply: Reply): Promise<Uint8Array> {
+    const key = await replyKey(this.draw, opened.lid);
+    return key ? sealReply(key, await this.#signed(reply)) : this.#silence(opened.lid);
+  }
+
+  // The body, opened under the edge keys the door takes for this head.
+  async #body(opened: OpenedHead, record: HeirRecord | undefined): Promise<Body | null> {
+    const tries: { edge: Uint8Array; sealed: Uint8Array }[] = [];
+    if (record?.state === 'fresh') {
+      const knock = splitKnock(opened.rest);
+      const lock = this.relations.lock();
+      const shared = knock && lock ? decapsulate(lock.dk, knock.ciphertext) : null;
+      if (!knock || !shared) return null;
+      tries.push({ edge: await knockEdge(shared), sealed: knock.sealedBody });
+    } else if (record === undefined) tries.push({ edge: ZERO_EDGE, sealed: opened.rest });
+    else for (const edge of [record.open, record.offered]) tries.push({ edge: unhex(edge), sealed: opened.rest });
+    for (const { edge, sealed } of tries) {
+      const plain = await openBody(opened, edge, sealed);
+      if (plain === null) continue;
+      const body = splitBody(plain);
+      return body && { edge, ...body };
+    }
+    return null;
+  }
+
+  // A stranger's silence: sealed to the first thirty-two bytes that arrived
+  // when they take a seal, and otherwise to a lid nobody holds.
+  async #silence(arrived: Uint8Array): Promise<Uint8Array> {
+    const text = await this.#signed({ silence: true });
+    const candidates = [arrived.length >= HEAD ? arrived.subarray(0, HEAD) : null, this.draw(HEAD)];
+    for (const lid of candidates) {
+      const key = lid && (await replyKey(this.draw, lid));
+      if (key) return sealReply(key, text);
+    }
+    return sealReply((await replyKey(this.draw, await x25519Public(this.draw(HEAD))))!, text);
+  }
+}
+
+const admits = (record: HeirRecord, heir: string, by: string): boolean => (record.state === 'fresh' ? by === heir : by === record.held || by === record.vouched);
+
+const opensUnder = (record: HeirRecord, edge: Uint8Array): boolean => record.state === 'fresh' || hex(edge) === record.open || hex(edge) === record.offered;
+
+const honours = (record: { highest: number; honoured: readonly number[] }, seq: number): boolean =>
+  seq > record.highest || (seq > record.highest - SPAN && seq !== record.highest && !record.honoured.includes(seq));
+
+// The move tables: the keys and edge keys after a choice, and the count.
+const move = (record: HeirRecord, heir: string, p: Payload, edge: string, offered: string): HeirRecord => {
+  const announced = p.next !== null && p.next !== heir && p.next !== p.by ? p.next : null;
+  if (record.state === 'fresh') return { state: 'spent', held: announced!, vouched: null, open: edge, offered, highest: p.seq, honoured: [] };
+  if (record.state !== 'spent') return record;
+  if (p.seq < record.highest) return { ...record, honoured: [...record.honoured, p.seq] };
+  const keys: Keys = p.by === record.held ? { held: record.held, vouched: announced ?? record.vouched, open: edge, offered } : { held: p.by, vouched: announced, open: edge, offered };
+  const honoured = [...record.honoured, record.highest].filter((n) => n > p.seq - SPAN);
+  return { state: 'spent', ...keys, highest: p.seq, honoured };
+};

package/src/quo/index.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo's wire: keys, the invitation, the payload, the reply, the boxes, the
+// door and the standing. It knows no being, no ward and no terrain.
+export { Door, SPAN, type Behind, type Choice, type Judged } from './door.ts';
+export { readInvitation, type Invitation } from './invitation.ts';
+export { Ephemeral, SigningKey, WardKey, type Draw } from './keys.ts';
+export { readPayload, writePayload, type Payload } from './payload.ts';
+export { GONE, keptLock, lockOf, MemoryRelations, type HeirRecord, type KeptLock, type Relations } from './relations.ts';
+export { readReply, SILENCE, WORDS, writeReply, type Reply, type Word } from './reply.ts';
+export { SIZE } from './seal.ts';
+export { freshStanding, Standing, type Read, type Sent, type StandingState } from './standing.ts';

package/src/quo/invitation.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// The invitation: `{ ward, heir, secret, lock }`, a value with no route.
+import { EK, encapsulate, isHex, unhex } from '../crypto/index.ts';
+
+export type Invitation = { readonly ward: string; readonly heir: string; readonly secret: string; readonly lock: string };
+
+// An invitation, or null for any other shape. A field beside the four is
+// ignored, and the lock is held to the modulus check.
+export const readInvitation = (value: unknown): Invitation | null => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+  const { ward, heir, secret, lock } = value as Record<string, unknown>;
+  if (!isHex(ward, 64) || !isHex(heir, 32) || !isHex(secret, 32) || !isHex(lock, EK)) return null;
+  if (encapsulate(unhex(lock), new Uint8Array(32)) === null) return null;
+  return { ward, heir, secret, lock };
+};

package/src/quo/keys.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// The keys of Quo: the ward key derived from a seed, and every other key
+// drawn. A draw is the caller's, so this layer names no source of bytes.
+import { agree, ed25519Public, hex, hkdf, lockFrom, sha256, utf8, x25519Public, type Lock } from '../crypto/index.ts';
+
+// Drawn bytes, from whatever the caller's terrain gives.
+export type Draw = (length: number) => Uint8Array;
+
+export const LABEL = {
+  seal: utf8('quo-seal'),
+  edgeSeal: utf8('quo-edge-seal'),
+  lock: utf8('quo-lock'),
+  edge: utf8('quo-edge'),
+  wardSign: utf8('quo-ward-sign'),
+  wardSeal: utf8('quo-ward-seal'),
+} as const;
+
+// An Ed25519 pair: an heir, or a standing's own key.
+export class SigningKey {
+  readonly secret: Uint8Array;
+  readonly pk: Uint8Array;
+  private constructor(secret: Uint8Array, pk: Uint8Array) {
+    this.secret = secret;
+    this.pk = pk;
+  }
+  static async from(secret: Uint8Array): Promise<SigningKey> {
+    return new SigningKey(secret, await ed25519Public(secret));
+  }
+  static draw(draw: Draw): Promise<SigningKey> {
+    return SigningKey.from(draw(32));
+  }
+  get id(): string {
+    return hex(this.pk);
+  }
+}
+
+// An X25519 pair used for one box.
+export class Ephemeral {
+  readonly secret: Uint8Array;
+  readonly pk: Uint8Array;
+  private constructor(secret: Uint8Array, pk: Uint8Array) {
+    this.secret = secret;
+    this.pk = pk;
+  }
+  static async from(secret: Uint8Array): Promise<Ephemeral> {
+    return new Ephemeral(secret, await x25519Public(secret));
+  }
+  static draw(draw: Draw): Promise<Ephemeral> {
+    return Ephemeral.from(draw(32));
+  }
+  agree(pk: Uint8Array): Promise<Uint8Array | null> {
+    return agree(this.secret, pk);
+  }
+}
+
+// The ward key: a signing pair and a padlock, both from the seed.
+export class WardKey {
+  readonly signing: SigningKey;
+  readonly sealSecret: Uint8Array;
+  readonly padlock: Uint8Array;
+  private constructor(signing: SigningKey, sealSecret: Uint8Array, padlock: Uint8Array) {
+    this.signing = signing;
+    this.sealSecret = sealSecret;
+    this.padlock = padlock;
+  }
+
+  // Thirty-two bytes are the seed. Text, and bytes of any other length, are
+  // hashed to it first.
+  static async from(seed: Uint8Array | string): Promise<WardKey> {
+    const bytes = typeof seed === 'string' ? await sha256(utf8(seed)) : seed.length === 32 ? seed : await sha256(seed);
+    const sealSecret = await hkdf(bytes, LABEL.wardSeal, 32);
+    return new WardKey(await SigningKey.from(await hkdf(bytes, LABEL.wardSign, 32)), sealSecret, await x25519Public(sealSecret));
+  }
+
+  get pk(): string {
+    return hex(this.signing.pk) + hex(this.padlock);
+  }
+
+  open(lid: Uint8Array): Promise<Uint8Array | null> {
+    return agree(this.sealSecret, lid);
+  }
+}
+
+// A ward pk's two halves.
+export const wardHalves = (pk: string): { signing: string; padlock: string } => ({ signing: pk.slice(0, 64), padlock: pk.slice(64) });
+
+// A lock from sixty-four drawn bytes.
+export const drawLock = (draw: Draw): Lock => {
+  const bytes = draw(64);
+  return lockFrom(bytes.subarray(0, 32), bytes.subarray(32));
+};

package/src/quo/payload.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// The payload: `{ to, by, next, seq, method?, args? }`. `args` is carried as
+// the text it was written in, since Quo reads nothing inside it.
+import { isCount, isHex, readObject } from '../crypto/index.ts';
+
+export type Payload = {
+  readonly to: string | null;
+  readonly by: string;
+  readonly next: string | null;
+  readonly seq: number;
+  readonly method?: string;
+  readonly args?: string;
+};
+
+const OWED = ['to', 'by', 'next', 'seq'];
+const ZERO = '0'.repeat(64);
+const isPk = (text: string): boolean => isHex(text, 32) && text !== ZERO;
+
+// A pk written as a JSON string, or null written as null.
+const pkOrNull = (text: string, nullable: boolean): string | null | undefined => {
+  if (nullable && text === 'null') return null;
+  if (!/^"[0-9a-f]{64}"$/.test(text)) return undefined;
+  const pk = text.slice(1, -1);
+  return isPk(pk) ? pk : undefined;
+};
+
+export const writePayload = (p: Payload): string => {
+  const parts = [`"to":${JSON.stringify(p.to)}`, `"by":"${p.by}"`, `"next":${JSON.stringify(p.next)}`, `"seq":${p.seq}`];
+  if (p.method !== undefined) parts.push(`"method":${JSON.stringify(p.method)}`);
+  if (p.args !== undefined) parts.push(`"args":${p.args}`);
+  return `{${parts.join(',')}}`;
+};
+
+export type PayloadRead = { payload: Payload } | { fault: 'not an object' | 'not well formed' };
+
+// Cases 2 and 3 of the door, before the head is compared.
+export const readPayload = (bytes: Uint8Array): PayloadRead => {
+  const fields = readObject(bytes);
+  if (fields === null) return { fault: 'not an object' };
+  const bad = { fault: 'not well formed' } as const;
+  if (!OWED.every((f) => fields.has(f))) return bad;
+  const to = pkOrNull(fields.get('to')!, true);
+  const by = pkOrNull(fields.get('by')!, false);
+  const next = pkOrNull(fields.get('next')!, true);
+  const seq = fields.get('seq')!;
+  if (to === undefined || !by || next === undefined || !isCount(seq)) return bad;
+  const method = fields.get('method');
+  if (method !== undefined && !method.startsWith('"')) return bad;
+  const args = fields.get('args');
+  if (args !== undefined && !args.startsWith('{')) return bad;
+  return {
+    payload: {
+      to,
+      by,
+      next,
+      seq: Number(seq),
+      ...(method === undefined ? {} : { method: JSON.parse(method) as string }),
+      ...(args === undefined ? {} : { args }),
+    },
+  };
+};

package/src/quo/relations.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a door keeps: its lock, and for each heir it holds the keys and the
+// count of the spec's relation chapter. Keys are written as hex, so a record
+// is a value any memory can keep.
+import type { Lock } from '../crypto/index.ts';
+import { hex, unhex } from '../crypto/index.ts';
+
+export type Keys = { readonly held: string; readonly vouched: string | null; readonly open: string; readonly offered: string };
+
+export type HeirRecord =
+  | { readonly state: 'fresh' }
+  | ({ readonly state: 'spent'; readonly highest: number; readonly honoured: readonly number[] } & Keys)
+  | ({ readonly state: 'kept' } & Keys);
+
+export type KeptLock = { readonly ek: string; readonly dk: string };
+
+// The door's memory. A ward stands it on its partition; `MemoryRelations`
+// is the one that lives in an object.
+export interface Relations {
+  lock(): Lock | undefined;
+  setLock(lock: Lock): void;
+  get(heir: string): HeirRecord | undefined;
+  set(heir: string, record: HeirRecord): void;
+  delete(heir: string): void;
+  // Whether what was written during an arrival is kept, asked once before
+  // the reply is sealed.
+  kept(): Promise<boolean>;
+}
+
+export const lockOf = (kept: KeptLock | undefined): Lock | undefined => (kept ? { ek: unhex(kept.ek), dk: unhex(kept.dk) } : undefined);
+export const keptLock = (lock: Lock): KeptLock => ({ ek: hex(lock.ek), dk: hex(lock.dk) });
+
+// A bound on the kept records of removed relations, oldest out.
+export const GONE = 256;
+
+export class MemoryRelations implements Relations {
+  #lock: KeptLock | undefined;
+  readonly #heirs = new Map<string, HeirRecord>();
+  readonly #gone: string[] = [];
+
+  lock(): Lock | undefined {
+    return lockOf(this.#lock);
+  }
+  setLock(lock: Lock): void {
+    this.#lock = keptLock(lock);
+  }
+  get(heir: string): HeirRecord | undefined {
+    return this.#heirs.get(heir);
+  }
+  set(heir: string, record: HeirRecord): void {
+    this.#heirs.set(heir, record);
+    if (record.state !== 'kept') return;
+    this.#gone.push(heir);
+    while (this.#gone.length > GONE) this.#heirs.delete(this.#gone.shift()!);
+  }
+  delete(heir: string): void {
+    this.#heirs.delete(heir);
+  }
+  kept(): Promise<boolean> {
+    return Promise.resolve(true);
+  }
+}