nervur 0.19.2 → 0.20.1

package/src/quo/reply.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// The reply text: `{ object, seen }`, `{ silence: true }` or `{ quo: word }`.
+// `object` is carried as the text it was written in.
+import { readObject } from '../crypto/index.ts';
+
+export const WORDS = ['removed', 'unannounced', 'repeated'] as const;
+export type Word = (typeof WORDS)[number];
+
+export type Reply = { readonly object: string; readonly seen: string | null } | { readonly silence: true } | { readonly quo: Word };
+
+export const SILENCE = '{"silence":true}';
+
+export const writeReply = (reply: Reply): string => {
+  if ('silence' in reply) return SILENCE;
+  if ('quo' in reply) return `{"quo":"${reply.quo}"}`;
+  return `{"object":${reply.object},"seen":${JSON.stringify(reply.seen)}}`;
+};
+
+const exactly = (fields: ReadonlyMap<string, string>, ...keys: string[]): boolean => fields.size === keys.length && keys.every((k) => fields.has(k));
+
+// A reply text of one of the three shapes, or null for anything else, which
+// the reader takes as silence.
+export const readReply = (bytes: Uint8Array): Reply | null => {
+  const fields = readObject(bytes);
+  if (fields === null) return null;
+  if (exactly(fields, 'silence')) return fields.get('silence') === 'true' ? { silence: true } : null;
+  if (exactly(fields, 'quo')) {
+    const text = fields.get('quo')!;
+    const word = text.startsWith('"') ? (JSON.parse(text) as string) : null;
+    return WORDS.find((w) => w === word) ? { quo: word as Word } : null;
+  }
+  if (exactly(fields, 'object', 'seen')) {
+    const seen = fields.get('seen')!;
+    if (seen === 'null') return { object: fields.get('object')!, seen: null };
+    return seen.startsWith('"') ? { object: fields.get('object')!, seen: JSON.parse(seen) as string } : null;
+  }
+  return null;
+};

package/src/quo/seal.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// The three boxes and the keys between them.
+//
+//   ask box    lid (32) || AES( head ) || AES( body )
+//   knock box  lid (32) || AES( head ) || ML-KEM ciphertext (1088) || AES( body )
+//   reply box  ephemeral pk (32) || AES( body )
+//   body       JSON text || signature (64)
+//
+// The head of an ask and the body of a reply are sealed under `quo-seal`
+// over the agreement. The body of an ask is sealed under `quo-edge-seal`
+// over the agreement and then the edge key. Every ciphertext's additional
+// data is its own box's ephemeral pk.
+import { CIPHERTEXT, concat, decrypt, encrypt, hkdf, sign, TAG, verify } from '../crypto/index.ts';
+import { Ephemeral, LABEL, type Draw, type SigningKey } from './keys.ts';
+
+export const SIZE = 1_048_576;
+export const HEAD = 32;
+export const SIGNATURE = 64;
+export const SEALED_HEAD = HEAD + TAG;
+export const ZERO_EDGE = new Uint8Array(32);
+export const ZERO_HEAD = new Uint8Array(HEAD);
+
+const cipher = async (label: Uint8Array, ...material: Uint8Array[]) => {
+  const out = await hkdf(concat(...material), label, 44);
+  return { key: out.subarray(0, 32), nonce: out.subarray(32) };
+};
+const seal = async (label: Uint8Array, material: Uint8Array[], lid: Uint8Array, plaintext: Uint8Array) => {
+  const { key, nonce } = await cipher(label, ...material);
+  return encrypt(key, nonce, lid, plaintext);
+};
+const open = async (label: Uint8Array, material: Uint8Array[], lid: Uint8Array, ciphertext: Uint8Array) => {
+  const { key, nonce } = await cipher(label, ...material);
+  return decrypt(key, nonce, lid, ciphertext);
+};
+
+// A knock's edge key, from the shared secret the lock decapsulates.
+export const knockEdge = (shared: Uint8Array): Promise<Uint8Array> => hkdf(shared, LABEL.lock, 32);
+
+// The edge key that follows `edge` after a reply of this agreement.
+export const follow = (edge: Uint8Array, agreement: Uint8Array): Promise<Uint8Array> => hkdf(concat(edge, agreement), LABEL.edge, 32);
+
+export const signBody = async (text: Uint8Array, key: SigningKey): Promise<Uint8Array> => concat(text, await sign(key.secret, text));
+
+// The text and signature of a body, or null for a body of sixty-four bytes
+// or fewer.
+export const splitBody = (body: Uint8Array): { text: Uint8Array; signature: Uint8Array } | null =>
+  body.length <= SIGNATURE ? null : { text: body.subarray(0, -SIGNATURE), signature: body.subarray(-SIGNATURE) };
+
+export const checkBody = (pk: Uint8Array, body: { text: Uint8Array; signature: Uint8Array }): Promise<boolean> => verify(pk, body.text, body.signature);
+
+// An ask box sealed under `lid` to a padlock, or null for a padlock that
+// takes no seal. `ciphertext` makes it a knock box.
+export const sealAsk = async (lid: Ephemeral, padlock: Uint8Array, head: Uint8Array, edge: Uint8Array, body: Uint8Array, ciphertext?: Uint8Array): Promise<Uint8Array | null> => {
+  const agreement = await lid.agree(padlock);
+  if (agreement === null) return null;
+  const sealedHead = await seal(LABEL.seal, [agreement], lid.pk, head);
+  const sealedBody = await seal(LABEL.edgeSeal, [agreement, edge], lid.pk, body);
+  return concat(lid.pk, sealedHead, ciphertext ?? new Uint8Array(0), sealedBody);
+};
+
+// What a door reads before it knows which edge key to try.
+export type OpenedHead = { lid: Uint8Array; agreement: Uint8Array; head: Uint8Array; rest: Uint8Array };
+
+export const openHead = async (bytes: Uint8Array, agreement: Uint8Array): Promise<OpenedHead | null> => {
+  if (bytes.length < HEAD + SEALED_HEAD) return null;
+  const lid = bytes.subarray(0, HEAD);
+  const head = await open(LABEL.seal, [agreement], lid, bytes.subarray(HEAD, HEAD + SEALED_HEAD));
+  return head === null ? null : { lid, agreement, head, rest: bytes.subarray(HEAD + SEALED_HEAD) };
+};
+
+// A knock's rest split into its ciphertext and sealed body.
+export const splitKnock = (rest: Uint8Array): { ciphertext: Uint8Array; sealedBody: Uint8Array } | null =>
+  rest.length < CIPHERTEXT ? null : { ciphertext: rest.subarray(0, CIPHERTEXT), sealedBody: rest.subarray(CIPHERTEXT) };
+
+export const openBody = (opened: OpenedHead, edge: Uint8Array, sealedBody: Uint8Array): Promise<Uint8Array | null> =>
+  open(LABEL.edgeSeal, [opened.agreement, edge], opened.lid, sealedBody);
+
+export type SealedReply = { bytes: Uint8Array; agreement: Uint8Array };
+
+// The reply's ephemeral key and its agreement with the lid, drawn before the
+// reply is written, since the edge keys move by that agreement.
+export type ReplyKey = { ephemeral: Ephemeral; agreement: Uint8Array };
+
+export const replyKey = async (draw: Draw, lid: Uint8Array): Promise<ReplyKey | null> => {
+  const ephemeral = await Ephemeral.draw(draw);
+  const agreement = await ephemeral.agree(lid);
+  return agreement === null ? null : { ephemeral, agreement };
+};
+
+export const sealReply = async (key: ReplyKey, body: Uint8Array): Promise<Uint8Array> =>
+  concat(key.ephemeral.pk, await seal(LABEL.seal, [key.agreement], key.ephemeral.pk, body));
+
+// A reply's body and agreement, opened with the lid's secret, or null.
+export const openReply = async (bytes: Uint8Array, lid: Ephemeral): Promise<SealedReply | null> => {
+  if (bytes.length > SIZE || bytes.length < HEAD + TAG) return null;
+  const pk = bytes.subarray(0, HEAD);
+  const agreement = await lid.agree(pk);
+  if (agreement === null) return null;
+  const body = await open(LABEL.seal, [agreement], pk, bytes.subarray(HEAD));
+  return body === null ? null : { bytes: body, agreement };
+};

package/src/quo/standing.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// The standing's side of a relation: it seals asks and reads replies, and
+// moves to its announced key and the following edge key when an object
+// comes back to an ask above every ask it has moved on, and on nothing else.
+//
+// Its state is a value, so a ward keeps it in its partition.
+import { encapsulate, hex, unhex } from '../crypto/index.ts';
+import type { Invitation } from './invitation.ts';
+import { Ephemeral, SigningKey, wardHalves, type Draw } from './keys.ts';
+import { writePayload } from './payload.ts';
+import { readReply, type Reply } from './reply.ts';
+import { checkBody, follow, knockEdge, openReply, sealAsk, signBody, splitBody } from './seal.ts';
+
+export type Read = Reply | { readonly nothing: true };
+
+// A knock that brought no object back: its bytes, sent again as they are,
+// and what the standing moves to if it bound.
+type Knock = { readonly bytes: string; readonly lid: string; readonly next: string; readonly edge: string; readonly seq: number };
+
+export type StandingState = {
+  readonly key: string | null;
+  readonly edge: string | null;
+  readonly sent: number;
+  readonly moved: number;
+  readonly knock: Knock | null;
+  // Whether the last ask after an unanswered knock asked under its own key,
+  // so the next sends the knock again.
+  readonly probed: boolean;
+};
+
+export const freshStanding = (): StandingState => ({ key: null, edge: null, sent: 0, moved: 0, knock: null, probed: false });
+
+// One ask out: what `read` needs to read its reply and to move.
+export type Sent = { readonly bytes: Uint8Array; readonly lid: Ephemeral; readonly next: string; readonly edge: string; readonly seq: number };
+
+export class Standing {
+  readonly invitation: Invitation;
+  state: StandingState;
+  readonly draw: Draw;
+
+  constructor(invitation: Invitation, state: StandingState, draw: Draw) {
+    this.invitation = invitation;
+    this.state = state;
+    this.draw = draw;
+  }
+
+  async ask(method?: string, args?: string): Promise<Sent | null> {
+    const s = this.state;
+    if (s.key !== null) return this.#ask(unhex(s.key), unhex(s.edge!), method, args);
+    if (s.knock === null) return this.#knock(method, args);
+    if (!s.probed) {
+      this.state = { ...s, probed: true };
+      return this.#ask(unhex(s.knock.next), unhex(s.knock.edge), method, args);
+    }
+    this.state = { ...s, probed: false };
+    // The same bytes again: a new lid would be a new box.
+    return { bytes: unhex(s.knock.bytes), lid: await Ephemeral.from(unhex(s.knock.lid)), next: s.knock.next, edge: s.knock.edge, seq: s.knock.seq };
+  }
+
+  async read(sent: Sent, bytes: Uint8Array | null): Promise<Read> {
+    if (bytes === null) return { nothing: true };
+    const reply = await this.#open(sent, bytes);
+    if (reply === null) return { silence: true };
+    if ('object' in reply.text && sent.seq > this.state.moved) {
+      const edge = await follow(unhex(sent.edge), reply.agreement);
+      this.state = { ...this.state, key: sent.next, edge: hex(edge), moved: sent.seq, knock: null, probed: false };
+    }
+    return reply.text;
+  }
+
+  async #knock(method?: string, args?: string): Promise<Sent | null> {
+    const heir = await SigningKey.from(unhex(this.invitation.secret));
+    const next = await SigningKey.draw(this.draw);
+    const lid = await Ephemeral.draw(this.draw);
+    const sent = encapsulate(unhex(this.invitation.lock), this.draw(32));
+    if (sent === null) return null;
+    const edge = await knockEdge(sent.shared);
+    const seq = this.state.sent + 1;
+    const body = await this.#body(heir, next, seq, method, args);
+    const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body, sent.ciphertext);
+    if (bytes === null) return null;
+    this.state = { ...this.state, sent: seq, knock: { bytes: hex(bytes), lid: hex(lid.secret), next: hex(next.secret), edge: hex(edge), seq } };
+    return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+  }
+
+  async #ask(secret: Uint8Array, edge: Uint8Array, method?: string, args?: string): Promise<Sent | null> {
+    const by = await SigningKey.from(secret);
+    const next = await SigningKey.draw(this.draw);
+    const lid = await Ephemeral.draw(this.draw);
+    const seq = this.state.sent + 1;
+    const body = await this.#body(by, next, seq, method, args);
+    const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body);
+    if (bytes === null) return null;
+    this.state = { ...this.state, sent: seq };
+    return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+  }
+
+  #body(by: SigningKey, next: SigningKey, seq: number, method?: string, args?: string): Promise<Uint8Array> {
+    const text = writePayload({ to: this.invitation.heir, by: by.id, next: next.id, seq, ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) });
+    return signBody(new TextEncoder().encode(text), by);
+  }
+
+  async #open(sent: Sent, bytes: Uint8Array): Promise<{ text: Reply; agreement: Uint8Array } | null> {
+    const opened = await openReply(bytes, sent.lid);
+    const body = opened && splitBody(opened.bytes);
+    if (!opened || !body) return null;
+    if (!(await checkBody(unhex(wardHalves(this.invitation.ward).signing), body))) return null;
+    const text = readReply(body.text);
+    return text && { text, agreement: opened.agreement };
+  }
+}

package/src/stand/main.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// The stand program: one JSON request a line on stdin, one answer a line on
+// stdout, until stdin closes.
+import { createInterface } from 'node:readline';
+import { Stand } from './stand.ts';
+
+const stand = new Stand((n) => globalThis.crypto.getRandomValues(new Uint8Array(n)));
+const pending: Promise<void>[] = [];
+
+for await (const line of createInterface({ input: process.stdin, crlfDelay: Infinity })) {
+  if (line === '') continue;
+  pending.push(
+    stand.handle(line).then(
+      (answer) => void process.stdout.write(`${JSON.stringify(answer)}\n`),
+      (error: unknown) => void process.stderr.write(`${String(error)}\n`),
+    ),
+  );
+}
+await Promise.all(pending);
+await stand.close();

package/src/stand/stand.ts

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: Apache-2.0
+// 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;
+type Error = (typeof ERRORS)[number];
+class Refused {
+  readonly error: Error;
+  constructor(error: Error) {
+    this.error = error;
+  }
+}
+const refuse = (error: Error): never => {
+  throw new Refused(error);
+};
+
+// What the verifier names behind a door.
+const REACHES: Record<string, (p: Payload) => Choice> = {
+  echo: (p) => ({ object: p.method === undefined ? '{}' : (p.args ?? '{}'), seen: null }),
+  marked: (p) => ({ object: p.method === undefined ? '{}' : (p.args ?? '{}'), seen: p.method === undefined ? null : '1' }),
+  null: () => ({ object: 'null', seen: null }),
+  silent: () => ({ silence: true }),
+};
+
+class StandWard implements Behind {
+  readonly door: Door;
+  readonly zero: boolean;
+  readonly #zero: string | undefined;
+  readonly names = new Map<string, string>();
+  readonly reaches = new Map<string, string>();
+  readonly standings = new Map<string, { standing: Standing; last?: Sent }>();
+
+  constructor(key: WardKey, zero: string | undefined, draw: Draw) {
+    this.#zero = zero;
+    this.zero = zero !== undefined;
+    this.door = new Door(key, new MemoryRelations(), this, draw);
+  }
+
+  answer(heir: string | null, p: Payload): Promise<Choice> {
+    const reach = heir === null ? this.#zero! : this.reaches.get(heir);
+    return Promise.resolve(reach === undefined ? { silence: true } : REACHES[reach]!(p));
+  }
+}
+
+const OPS = new Set(['ward', 'invite', 'release', 'arrive', 'ask', 'read', 'listen', 'route', 'send']);
+
+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 {
+      request = JSON.parse(line);
+    } catch {
+      return { id: null, error: 'bad request' };
+    }
+    if (typeof request !== 'object' || request === null || Array.isArray(request)) return { id: null, error: 'bad request' };
+    const r = request as Record<string, unknown>;
+    if (typeof r.id !== 'string') return { id: null, error: 'bad request' };
+    try {
+      return { id: r.id, ...(await this.#op(r)) };
+    } catch (e) {
+      if (e instanceof Refused) return { id: r.id, error: e.error };
+      throw e;
+    }
+  }
+
+  async #op(r: Record<string, unknown>): Promise<Answer> {
+    if (typeof r.op !== 'string') return refuse('bad request');
+    if (!OPS.has(r.op)) return refuse('no such op');
+    switch (r.op) {
+      case 'ward':
+        return this.#ward(text(r.seed), optional(r.reach));
+      case 'invite':
+        return this.#invite(r);
+      case 'release':
+        return this.#release(r);
+      case 'arrive':
+        return this.#arrive(r);
+      case 'ask':
+        return this.#ask(r);
+      case 'read':
+        return this.#read(r);
+      case 'listen':
+        return this.#listen();
+      case 'route':
+        return this.#route(r);
+      default:
+        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);
+    if (this.#wards.has(key.pk)) refuse('ward stood');
+    this.#wards.set(key.pk, new StandWard(key, reach, this.#draw));
+    return { ward: key.pk };
+  }
+
+  async #invite(r: Record<string, unknown>): Promise<Answer> {
+    const name = text(r.heir);
+    const reach = optional(r.reach) ?? 'echo';
+    const ward = this.#ward_(r.ward);
+    reached(reach);
+    if (ward.names.has(name)) refuse('name held');
+    const { heir, invitation } = await ward.door.invite();
+    ward.names.set(name, heir);
+    ward.reaches.set(heir, reach);
+    return { invitation };
+  }
+
+  #release(r: Record<string, unknown>): Answer {
+    const name = text(r.heir);
+    const ward = this.#ward_(r.ward);
+    const heir = ward.names.get(name);
+    if (heir === undefined) return { released: null };
+    ward.names.delete(name);
+    ward.door.remove(heir);
+    return { released: name };
+  }
+
+  async #arrive(r: Record<string, unknown>): Promise<Answer> {
+    const box = r.box;
+    if (!isHex(box)) return refuse('bad request');
+    const ward = this.#ward_(r.ward);
+    const judged = await ward.door.arrive(unhex(box));
+    return { reply: hex(judged.bytes) };
+  }
+
+  async #ask(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;
+    return { box: hex(sent.bytes) };
+  }
+
+  async #read(r: Record<string, unknown>): Promise<Answer> {
+    const invitation = inviteOf(r.invitation);
+    if (r.reply !== null && !isHex(r.reply)) return refuse('bad request');
+    const ward = this.#ward_(r.ward);
+    const held = this.#standing(ward, invitation);
+    if (held.last === undefined) return refuse('bad request');
+    const read = await held.standing.read(held.last, r.reply === null ? null : unhex(r.reply as string));
+    return { read: readOf(read) };
+  }
+
+  #standing(ward: StandWard, invitation: Invitation): { standing: Standing; last?: Sent } {
+    const key = `${invitation.ward}.${invitation.heir}`;
+    let held = ward.standings.get(key);
+    if (!held) ward.standings.set(key, (held = { standing: new Standing(invitation, freshStanding(), this.#draw) }));
+    return held;
+  }
+
+  #ward_(pk: unknown): StandWard {
+    if (!isHex(pk, 64)) return refuse('bad request');
+    return this.#wards.get(pk) ?? refuse('no such ward');
+  }
+}
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : refuse('bad request'));
+const optional = (value: unknown): string | undefined => (value === undefined ? undefined : text(value));
+const reached = (reach: string | undefined): void => {
+  if (reach !== undefined && !Object.hasOwn(REACHES, reach)) refuse('not reached');
+};
+const inviteOf = (value: unknown): Invitation => readInvitation(value) ?? refuse('bad request');
+const objectText = (value: unknown): string => (typeof value === 'object' && value !== null && !Array.isArray(value) ? JSON.stringify(value) : refuse('bad request'));
+const readOf = (read: Read): unknown => ('object' in read ? { object: JSON.parse(read.object) as unknown, seen: read.seen } : read);

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;
+};