nervur 0.19.2 → 0.20.0

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 a 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 a 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: a 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);
+  }
+}

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