@plane31/blind-relay 0.1.1 → 0.1.3

package/src/crypto/noble.ts

@@ -0,0 +1,104 @@
+/** The portable backend over the noble libraries (audited pure JavaScript). */
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { hsalsa, xsalsa20poly1305 } from "@noble/ciphers/salsa";
+import { ed25519, x25519 } from "@noble/curves/ed25519";
+import { blake2b } from "@noble/hashes/blake2b";
+import { sha512 } from "@noble/hashes/sha512";
+import { randomBytes } from "@noble/hashes/utils";
+import type { BoxKeypair, CryptoBackend, SignKeypair } from "./backend.js";
+
+// "expand 32-byte k" as little-endian u32 words: the Salsa constant.
+const SIGMA = new Uint32Array([0x61707865, 0x3320646e, 0x79622d32, 0x6b206574]);
+
+function u32(bytes: Uint8Array): Uint32Array {
+  const out = new Uint32Array(bytes.length / 4);
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let i = 0; i < out.length; i++) out[i] = dv.getUint32(i * 4, true);
+  return out;
+}
+
+function fromU32(words: Uint32Array): Uint8Array {
+  const out = new Uint8Array(words.length * 4);
+  const dv = new DataView(out.buffer);
+  for (let i = 0; i < words.length; i++) dv.setUint32(i * 4, words[i] ?? 0, true);
+  return out;
+}
+
+/** `crypto_box_beforenm`: HSalsa20 of the X25519 shared secret with a zero nonce. */
+function beforeNm(publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array {
+  const shared = x25519.getSharedSecret(secretKey, publicKey);
+  const out = new Uint32Array(8);
+  hsalsa(SIGMA, u32(shared), u32(new Uint8Array(16)), out);
+  return fromU32(out);
+}
+
+function isCanonicalY(bytes: Uint8Array): boolean {
+  // y < 2^255 - 19, read little-endian with the sign bit cleared.
+  const y = Uint8Array.from(bytes);
+  y[31] = (y[31] ?? 0) & 0x7f;
+  const P = Uint8Array.from([
+    0xed, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f
+  ]);
+  for (let i = 31; i >= 0; i--) {
+    const a = y[i] ?? 0;
+    const b = P[i] ?? 0;
+    if (a < b) return true;
+    if (a > b) return false;
+  }
+  return false;
+}
+
+export const nobleBackend: CryptoBackend = {
+  name: "noble",
+  blake2b: (data, outLen, key) => blake2b(data, key ? { dkLen: outLen, key } : { dkLen: outLen }),
+  randomBytes: (length) => randomBytes(length),
+  signKeypairFromSeed(seed): SignKeypair {
+    const publicKey = ed25519.getPublicKey(seed);
+    const secretKey = new Uint8Array(64);
+    secretKey.set(seed, 0);
+    secretKey.set(publicKey, 32);
+    return { publicKey, secretKey };
+  },
+  signDetached: (message, secretKey) => ed25519.sign(message, secretKey.subarray(0, 32)),
+  verifyDetached(signature, message, publicKey) {
+    try {
+      return ed25519.verify(signature, message, publicKey, { zip215: false });
+    } catch {
+      return false;
+    }
+  },
+  isValidSignPoint(publicKey) {
+    if (publicKey.length !== 32 || !isCanonicalY(publicKey)) return false;
+    try {
+      const p = ed25519.ExtendedPoint.fromHex(publicKey);
+      p.assertValidity();
+      return !p.equals(ed25519.ExtendedPoint.ZERO) && !p.isSmallOrder() && p.isTorsionFree();
+    } catch {
+      return false;
+    }
+  },
+  boxKeypairFromSeed(seed): BoxKeypair {
+    const secretKey = sha512(seed).slice(0, 32);
+    return { publicKey: x25519.getPublicKey(secretKey), secretKey };
+  },
+  boxKeypair(): BoxKeypair {
+    const secretKey = randomBytes(32);
+    return { publicKey: x25519.getPublicKey(secretKey), secretKey };
+  },
+  scalarMult(secretKey, publicKey) {
+    const shared = x25519.getSharedSecret(secretKey, publicKey); // throws on an all-zero result
+    let acc = 0;
+    for (const b of shared) acc |= b;
+    if (acc === 0) throw new Error("low-order point");
+    return shared;
+  },
+  boxEasy(message, nonce, publicKey, secretKey) {
+    return xsalsa20poly1305(beforeNm(publicKey, secretKey), nonce).encrypt(message); // mac || ciphertext
+  },
+  boxOpenEasy(box, nonce, publicKey, secretKey) {
+    return xsalsa20poly1305(beforeNm(publicKey, secretKey), nonce).decrypt(box);
+  },
+  aeadEncrypt: (plaintext, aad, nonce, key) => xchacha20poly1305(key, nonce, aad).encrypt(plaintext),
+  aeadDecrypt: (ciphertextAndTag, aad, nonce, key) => xchacha20poly1305(key, nonce, aad).decrypt(ciphertextAndTag),
+  memzero: (bytes) => bytes.fill(0)
+};

package/src/crypto/node-module.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one Node API the optional `/sodium` entry uses, declared here so the protocol package keeps
+ * no dependency on Node's type definitions: the rest of core imports no platform module.
+ */
+declare module "node:module" {
+  export function createRequire(from: string | URL): (id: string) => unknown;
+}
+
+interface ImportMeta {
+  readonly url: string;
+}

package/src/crypto/sodium.ts

@@ -0,0 +1,53 @@
+/**
+ * The libsodium backend (wasm). Loaded only when asked for, so the default bundle never carries
+ * the wasm; use it on Node, where it is faster than the portable backend, and to cross-check it.
+ */
+import { createRequire } from "node:module";
+import type { BoxKeypair, CryptoBackend, SignKeypair } from "./backend.js";
+
+type Sodium = typeof import("libsodium-wrappers-sumo");
+
+/**
+ * Node only. The wrapper is loaded through its `require` condition, the CommonJS build, which is
+ * self-contained; its ESM build has shipped broken (0.7.16 imports a sibling file the package does
+ * not contain), and a consumer's plain `import` would hit that. The release smoke test loads this
+ * entry from the packed tarball in a clean Node to keep it so.
+ */
+export async function loadSodiumBackend(): Promise<CryptoBackend> {
+  const require = createRequire(import.meta.url);
+  const mod = require("libsodium-wrappers-sumo") as { default?: Sodium } & Sodium;
+  const sodium: Sodium = mod.default ?? mod;
+  await sodium.ready;
+  return {
+    name: "sodium",
+    blake2b: (data, outLen, key) => sodium.crypto_generichash(outLen, data, key ?? null),
+    randomBytes: (length) => sodium.randombytes_buf(length),
+    signKeypairFromSeed(seed): SignKeypair {
+      const kp = sodium.crypto_sign_seed_keypair(seed);
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    signDetached: (message, secretKey) => sodium.crypto_sign_detached(message, secretKey),
+    verifyDetached(signature, message, publicKey) {
+      try {
+        return sodium.crypto_sign_verify_detached(signature, message, publicKey);
+      } catch {
+        return false;
+      }
+    },
+    isValidSignPoint: (publicKey) => publicKey.length === 32 && sodium.crypto_core_ed25519_is_valid_point(publicKey),
+    boxKeypairFromSeed(seed): BoxKeypair {
+      const kp = sodium.crypto_box_seed_keypair(seed);
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    boxKeypair(): BoxKeypair {
+      const kp = sodium.crypto_box_keypair();
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    scalarMult: (secretKey, publicKey) => sodium.crypto_scalarmult(secretKey, publicKey),
+    boxEasy: (message, nonce, publicKey, secretKey) => sodium.crypto_box_easy(message, nonce, publicKey, secretKey),
+    boxOpenEasy: (box, nonce, publicKey, secretKey) => sodium.crypto_box_open_easy(box, nonce, publicKey, secretKey),
+    aeadEncrypt: (plaintext, aad, nonce, key) => sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, aad, null, nonce, key),
+    aeadDecrypt: (ciphertextAndTag, aad, nonce, key) => sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertextAndTag, aad, nonce, key),
+    memzero: (bytes) => sodium.memzero(bytes)
+  };
+}

package/src/crypto.ts

@@ -0,0 +1,266 @@
+/**
+ * The one cipher suite of Kavach v1 (protocol section 3) over a primitive backend.
+ *
+ * Everything here is a thin, checked wrapper: no algorithm choice, no fallback, no key
+ * derivation other than the three the protocol names. Call `ready()` once before anything else;
+ * it selects the portable backend unless `setCryptoBackend` chose another first.
+ */
+import { concat, isAllZero, u32, encodeName } from "./bytes.js";
+import { KavachError } from "./errors.js";
+import { currentBackend, setCryptoBackend, type BoxKeypair, type CryptoBackend, type SignKeypair as SigningKeypair } from "./crypto/backend.js";
+import { nobleBackend } from "./crypto/noble.js";
+
+export type { CryptoBackend, BoxKeypair, SigningKeypair };
+export { setCryptoBackend };
+
+/** Kept from the protocol's earlier name on purpose: changing it changes every vector. */
+export const LABEL_PREFIX = "SealedStream/5/";
+export const WIRE_VERSION = 5;
+export const HASH_BYTES = 32;
+export const KEY_BYTES = 32;
+export const SEED_BYTES = 32;
+export const NONCE_BYTES = 24;
+export const TAG_BYTES = 16;
+export const SIGNATURE_BYTES = 64;
+export const PUBLIC_KEY_BYTES = 32;
+export const SEALED_BOX_BYTES = 80;
+export const DEVICE_ID_BYTES = 16;
+/** Recovery code prefix, also kept from the earlier name. */
+export const RECOVERY_CODE_PREFIX = "KV1R-";
+
+export type Label =
+  | "identity"
+  | "stream"
+  | "record-id"
+  | "doc-hash"
+  | "device-sign"
+  | "device-box"
+  | "account-sig"
+  | "snapshot-sig"
+  | "epoch-sig"
+  | "record-sig"
+  | "reset-sig"
+  | "reset-keys-sig"
+  | "epoch-key"
+  | "wrap"
+  | "record-aad"
+  | "vault-aad";
+
+/** Select a backend if none is set (the portable one) and resolve. Idempotent. */
+export async function ready(): Promise<void> {
+  if (!currentBackend()) {
+    // The portable backend draws randomness from the Web Crypto global; Hermes has none until the
+    // app installs one (the Expo helper does, from expo-crypto). Say so, rather than fail later.
+    const g = globalThis as { crypto?: { getRandomValues?: unknown } };
+    if (typeof g.crypto?.getRandomValues !== "function") throw new KavachError("INVALID_KEY", "ready", "no crypto.getRandomValues: install a secure random source before opening Kavach");
+    setCryptoBackend(nobleBackend);
+  }
+}
+
+/** The portable backend needs no loading, so it is selected on first use when nothing else was. */
+function be(): CryptoBackend {
+  const b = currentBackend();
+  if (b) return b;
+  setCryptoBackend(nobleBackend);
+  return nobleBackend;
+}
+
+export function backendName(): CryptoBackend["name"] {
+  return be().name;
+}
+
+function ascii(text: string): Uint8Array {
+  const out = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c > 0x7f) throw new RangeError("label is not ASCII");
+    out[i] = c;
+  }
+  return out;
+}
+
+/** `C(label)` = ASCII("SealedStream/5/" + label) || 0x00. */
+export function C(label: Label): Uint8Array {
+  return concat(ascii(LABEL_PREFIX + label), Uint8Array.of(0));
+}
+
+/** `H(x)`: BLAKE2b, 32-byte output, unkeyed. */
+export function H(data: Uint8Array): Uint8Array {
+  return be().blake2b(data, HASH_BYTES);
+}
+
+/** `D(seed, label)`: BLAKE2b keyed with the seed over `C(label)`, 32-byte output. */
+export function D(seed: Uint8Array, label: Label): Uint8Array {
+  if (seed.length !== SEED_BYTES) throw new KavachError("INVALID_KEY", "derive", "seed must be 32 bytes");
+  return be().blake2b(C(label), HASH_BYTES, seed);
+}
+
+export function bodyHash(body: Uint8Array): Uint8Array {
+  return H(concat(C("doc-hash"), body));
+}
+
+export function identityId(accountName: string, accountPublicKey: Uint8Array): Uint8Array {
+  return H(concat(C("identity"), encodeName(accountName), accountPublicKey));
+}
+
+export function streamId(identity: Uint8Array, deviceId: Uint8Array): Uint8Array {
+  return H(concat(C("stream"), identity, deviceId));
+}
+
+export function recordId(stream: Uint8Array, epoch: number, counter: number): Uint8Array {
+  return H(concat(C("record-id"), stream, u32(epoch), u32(counter)));
+}
+
+export function wrapHash(wrap: Uint8Array): Uint8Array {
+  return H(concat(C("wrap"), wrap));
+}
+
+export function keyCommitment(stream: Uint8Array, epoch: number, epochKey: Uint8Array): Uint8Array {
+  return H(concat(C("epoch-key"), stream, u32(epoch), epochKey));
+}
+
+// Keys ---------------------------------------------------------------------------------------
+
+/** `AK` from `accountSeed`. The only thing the account seed ever derives. */
+export function accountKeypair(accountSeed: Uint8Array): SigningKeypair {
+  return signingKeypairFromSeed(accountSeed);
+}
+
+/** `DSK` = Ed25519 from `D(deviceSeed, "device-sign")`. */
+export function deviceSigningKeypair(deviceSeed: Uint8Array): SigningKeypair {
+  return signingKeypairFromSeed(D(deviceSeed, "device-sign"));
+}
+
+/** `DEK` = `crypto_box_seed_keypair(D(deviceSeed, "device-box"))`. The seed is never used as a scalar. */
+export function deviceBoxKeypair(deviceSeed: Uint8Array): BoxKeypair {
+  return be().boxKeypairFromSeed(D(deviceSeed, "device-box"));
+}
+
+export function signingKeypairFromSeed(seed: Uint8Array): SigningKeypair {
+  if (seed.length !== SEED_BYTES) throw new KavachError("INVALID_KEY", "keypair", "seed must be 32 bytes");
+  return be().signKeypairFromSeed(seed);
+}
+
+/** An Ed25519 public key must be a canonical point on the main subgroup and not the identity. */
+export function assertValidSigningKey(publicKey: Uint8Array, stage = "verify"): void {
+  if (publicKey.length !== PUBLIC_KEY_BYTES || !be().isValidSignPoint(publicKey)) {
+    throw new KavachError("INVALID_KEY", stage, "invalid Ed25519 public key");
+  }
+}
+
+/**
+ * An X25519 public key must not yield an all-zero shared secret. A fixed non-secret scalar
+ * probes it; libsodium refuses the low-order result.
+ */
+const PROBE_SCALAR = new Uint8Array(32).fill(0x42);
+export function assertValidBoxKey(publicKey: Uint8Array, stage = "verify"): void {
+  if (publicKey.length !== PUBLIC_KEY_BYTES || isAllZero(publicKey)) {
+    throw new KavachError("INVALID_KEY", stage, "invalid X25519 public key");
+  }
+  try {
+    const shared = be().scalarMult(PROBE_SCALAR, publicKey);
+    if (isAllZero(shared)) throw new Error("zero");
+  } catch {
+    throw new KavachError("INVALID_KEY", stage, "low-order X25519 public key");
+  }
+}
+
+// Signatures ----------------------------------------------------------------------------------
+
+/** Detached Ed25519 over `C(label) || body`. Not Ed25519ph, no intermediate hash. */
+export function sign(secretKey: Uint8Array, label: Label, body: Uint8Array): Uint8Array {
+  return be().signDetached(concat(C(label), body), secretKey);
+}
+
+// The Ed25519 group order L, little-endian, for the canonical-scalar check.
+const L = Uint8Array.from([
+  0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10
+]);
+
+function isCanonicalScalar(s: Uint8Array): boolean {
+  // s < L, comparing little-endian from the most significant byte.
+  for (let i = 31; i >= 0; i--) {
+    const a = s[i] ?? 0;
+    const b = L[i] ?? 0;
+    if (a < b) return true;
+    if (a > b) return false;
+  }
+  return false;
+}
+
+/**
+ * Verify a detached signature. Throws `INVALID_KEY` for an invalid or small-order key and
+ * `BAD_SIGNATURE` for anything else that does not verify, including a non-canonical scalar.
+ */
+export function verify(publicKey: Uint8Array, label: Label, body: Uint8Array, signature: Uint8Array, stage = "verify"): void {
+  assertValidSigningKey(publicKey, stage);
+  if (signature.length !== SIGNATURE_BYTES || !isCanonicalScalar(signature.subarray(32))) {
+    throw new KavachError("BAD_SIGNATURE", stage);
+  }
+  if (!be().verifyDetached(signature, concat(C(label), body), publicKey)) throw new KavachError("BAD_SIGNATURE", stage);
+}
+
+// AEAD ---------------------------------------------------------------------------------------
+
+/** XChaCha20-Poly1305: returns ciphertext with the 16-byte tag appended. */
+export function aeadSeal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): Uint8Array {
+  if (key.length !== KEY_BYTES || nonce.length !== NONCE_BYTES) throw new KavachError("INVALID_KEY", "aead");
+  return be().aeadEncrypt(plaintext, aad, nonce, key);
+}
+
+export function aeadOpen(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, ciphertextAndTag: Uint8Array, stage = "decrypt"): Uint8Array {
+  if (key.length !== KEY_BYTES || nonce.length !== NONCE_BYTES) throw new KavachError("INVALID_KEY", stage);
+  try {
+    return be().aeadDecrypt(ciphertextAndTag, aad, nonce, key);
+  } catch {
+    throw new KavachError("DECRYPT_FAILED", stage);
+  }
+}
+
+// Sealed boxes -------------------------------------------------------------------------------
+
+/** The sealed-box nonce: BLAKE2b-24 over the ephemeral and recipient public keys, as libsodium defines it. */
+export function sealedBoxNonce(ephemeralPublicKey: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array {
+  return be().blake2b(concat(ephemeralPublicKey, recipientPublicKey), NONCE_BYTES);
+}
+
+/** `crypto_box_seal` with a given ephemeral keypair (tests reproduce fixture wraps with it). */
+export function sealBoxWith(epochKey: Uint8Array, recipientPublicKey: Uint8Array, ephemeral: BoxKeypair): Uint8Array {
+  const nonce = sealedBoxNonce(ephemeral.publicKey, recipientPublicKey);
+  return concat(ephemeral.publicKey, be().boxEasy(epochKey, nonce, recipientPublicKey, ephemeral.secretKey));
+}
+
+/** `crypto_box_seal` of a 32-byte epoch key: exactly 80 bytes. */
+export function sealBox(epochKey: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array {
+  if (epochKey.length !== KEY_BYTES) throw new KavachError("INVALID_KEY", "seal");
+  assertValidBoxKey(recipientPublicKey, "seal");
+  return sealBoxWith(epochKey, recipientPublicKey, be().boxKeypair());
+}
+
+export function openSealedBox(box: Uint8Array, recipient: BoxKeypair, stage = "open-wrap"): Uint8Array {
+  if (box.length !== SEALED_BOX_BYTES) throw new KavachError("MALFORMED", stage, "wrap must be 80 bytes");
+  try {
+    const ephemeralPublic = box.subarray(0, PUBLIC_KEY_BYTES);
+    const nonce = sealedBoxNonce(ephemeralPublic, recipient.publicKey);
+    return be().boxOpenEasy(box.subarray(PUBLIC_KEY_BYTES), nonce, ephemeralPublic, recipient.secretKey);
+  } catch {
+    throw new KavachError("DECRYPT_FAILED", stage);
+  }
+}
+
+/** `crypto_box_seed_keypair`, exposed for tests that rebuild fixture wraps from their ephemeral seeds. */
+export function boxKeypairFromSeed(seed: Uint8Array): BoxKeypair {
+  return be().boxKeypairFromSeed(seed);
+}
+
+// Randomness and hygiene ----------------------------------------------------------------------
+
+export function randomBytes(length: number): Uint8Array {
+  return be().randomBytes(length);
+}
+
+/** Best-effort zeroisation. JavaScript gives no guarantee; the protocol says so. */
+export function zero(bytes: Uint8Array): void {
+  be().memzero(bytes);
+}

package/src/epoch.ts

@@ -0,0 +1,201 @@
+/**
+ * Epochs, wraps, publication and the reader side (protocol section 8).
+ */
+import { equalBytes, toHex } from "./bytes.js";
+import type { ResolvedAudience } from "./audience.js";
+import { DocumentType, buildEpochManifest, expectType, parseDocument, verifyDocument, type EpochManifest, type Parsed } from "./codec.js";
+import { KEY_BYTES, bodyHash, keyCommitment, openSealedBox, randomBytes, sealBox, wrapHash, type BoxKeypair } from "./crypto.js";
+import { KavachError } from "./errors.js";
+
+export const MAX_COUNTER = 0xffff_ffff;
+export const MAX_EPOCH = 0xffff_ffff;
+
+export interface AuthorKeys {
+  readonly identityId: Uint8Array;
+  readonly certificateHash: Uint8Array;
+  readonly streamId: Uint8Array;
+  readonly signingSecretKey: Uint8Array;
+}
+
+/** Everything T4 persists before any network call. */
+export interface PreparedEpoch {
+  readonly epoch: number;
+  readonly manifest: Uint8Array;
+  readonly manifestHash: Uint8Array;
+  /** Wrap per recipient identity id (hex), the author's own included. */
+  readonly wraps: ReadonlyMap<string, Uint8Array>;
+  readonly epochKey: Uint8Array;
+  readonly capturedRevision: bigint;
+  readonly audienceKey: string;
+  readonly createdAt: bigint;
+}
+
+/** Prepare an epoch: fresh random key, one sealed box per row, one signature. */
+export function prepareEpoch(input: {
+  readonly author: AuthorKeys;
+  readonly epoch: number;
+  readonly createdAt: bigint;
+  readonly audience: ResolvedAudience;
+  readonly desiredRevision: bigint;
+  readonly epochKey?: Uint8Array;
+}): PreparedEpoch {
+  const stage = "prepareEpoch";
+  if (input.epoch < 1 || input.epoch > MAX_EPOCH) throw new KavachError("COUNTER_EXHAUSTED", stage, "epoch space exhausted; replace the stream");
+  const epochKey = input.epochKey ?? randomBytes(KEY_BYTES);
+  const wraps = new Map<string, Uint8Array>();
+  const rows = input.audience.rows.map((row) => {
+    const wrap = sealBox(epochKey, row.boxKey);
+    wraps.set(toHex(row.identityId), wrap);
+    return { identityId: row.identityId, certificateHash: row.certificateHash, wrapHash: wrapHash(wrap) };
+  });
+  if (!rows.some((r) => equalBytes(r.identityId, input.author.identityId))) throw new KavachError("MALFORMED", stage, "author missing from audience");
+  const manifest = buildEpochManifest(
+    {
+      streamId: input.author.streamId,
+      authorIdentityId: input.author.identityId,
+      authorCertificateHash: input.author.certificateHash,
+      epoch: input.epoch,
+      createdAt: input.createdAt,
+      keyCommitment: keyCommitment(input.author.streamId, input.epoch, epochKey),
+      audience: rows
+    },
+    input.author.signingSecretKey
+  );
+  return {
+    epoch: input.epoch,
+    manifest,
+    manifestHash: bodyHash(manifest.subarray(0, manifest.length - 64)),
+    wraps,
+    epochKey,
+    capturedRevision: input.desiredRevision,
+    audienceKey: input.audience.key,
+    createdAt: input.createdAt
+  };
+}
+
+// Publication ----------------------------------------------------------------------------------
+
+export type PublishOutcome =
+  | { readonly status: "COMMITTED" }
+  | { readonly status: "ALREADY_COMMITTED" }
+  | { readonly status: "CONFLICT"; readonly currentEpoch: number; readonly currentManifest: Uint8Array | undefined }
+  | { readonly status: "RETRYABLE" }
+  | { readonly status: "UNAUTHORIZED" }
+  | { readonly status: "PERMANENT_FAILURE" };
+
+export type PublishResolution = "COMMITTED" | "RETRY";
+
+/**
+ * Resolve a publish outcome for a prepared epoch. Identical bytes at the slot mean committed; a
+ * different valid body at the same epoch is `EQUIVOCATION`; a higher committed epoch than the one
+ * prepared means local state was lost and the device must replace its stream.
+ */
+export function resolvePublish(prepared: PreparedEpoch, outcome: PublishOutcome): PublishResolution {
+  const stage = "publishEpoch";
+  switch (outcome.status) {
+    case "COMMITTED":
+    case "ALREADY_COMMITTED":
+      return "COMMITTED";
+    case "RETRYABLE":
+      return "RETRY";
+    case "UNAUTHORIZED":
+      throw new KavachError("NOT_AUTHORIZED", stage);
+    case "PERMANENT_FAILURE":
+      throw new KavachError("STORAGE_FAILURE", stage, "host refused the epoch permanently");
+    case "CONFLICT": {
+      if (outcome.currentEpoch === prepared.epoch && outcome.currentManifest) {
+        if (equalBytes(outcome.currentManifest, prepared.manifest)) return "COMMITTED";
+        const theirs = parseDocument(outcome.currentManifest);
+        if (theirs.type === DocumentType.EpochManifest && theirs.epoch === prepared.epoch) {
+          throw new KavachError("EQUIVOCATION", stage, "a different manifest is committed at this epoch");
+        }
+      }
+      if (outcome.currentEpoch >= prepared.epoch) {
+        throw new KavachError("RECOVERY_REQUIRED", stage, "the host holds a higher epoch for this stream; local state was lost");
+      }
+      return "RETRY";
+    }
+  }
+}
+
+export type PromotionOutcome = "PROMOTED" | "OBSOLETE";
+
+/** After commit: promote only if the captured revision and the exact audience still match. */
+export function promote(prepared: PreparedEpoch, currentDesiredRevision: bigint, currentAudienceKey: string): PromotionOutcome {
+  return prepared.capturedRevision === currentDesiredRevision && prepared.audienceKey === currentAudienceKey ? "PROMOTED" : "OBSOLETE";
+}
+
+// Rotation triggers -----------------------------------------------------------------------------
+
+export type RotationReason = "counterExhausted" | "hygiene" | "clockReversal";
+
+export interface ActiveEpochView {
+  readonly createdAt: bigint;
+  readonly nextCounter: number;
+  readonly lastSentAt: bigint | undefined;
+}
+
+export function rotationReason(active: ActiveEpochView, now: bigint, hygieneRotationMs: bigint): RotationReason | undefined {
+  if (active.nextCounter > MAX_COUNTER) return "counterExhausted";
+  if (active.lastSentAt !== undefined && now < active.lastSentAt) return "clockReversal";
+  if (now - active.createdAt > hygieneRotationMs) return "hygiene";
+  return undefined;
+}
+
+// Reader side ----------------------------------------------------------------------------------
+
+export interface AuthorCertificateView {
+  readonly certificateHash: Uint8Array;
+  readonly signingKey: Uint8Array;
+  readonly streamId: Uint8Array;
+  readonly current: boolean;
+}
+
+export interface AuthorView {
+  readonly identityId: Uint8Array;
+  /** The author's current certificate and any archived ones the reader still holds, by hash (hex). */
+  readonly certificates: ReadonlyMap<string, AuthorCertificateView>;
+}
+
+export interface SelfView {
+  readonly identityId: Uint8Array;
+  readonly certificateHash: Uint8Array;
+  readonly box: BoxKeypair;
+}
+
+export interface OpenedEpoch {
+  readonly manifest: Parsed<EpochManifest>;
+  readonly epochKey: Uint8Array;
+  /** The manifest belongs to a device of the author that is no longer current: history only. */
+  readonly superseded: boolean;
+}
+
+/**
+ * Every check of section 8 before a key is stored: manifest signature under the certificate it
+ * names, that certificate's identity and stream, the author's own row, the reader's own row at
+ * its current certificate, the wrap hash, the sealed box and the key commitment.
+ */
+export function openEpoch(manifestWire: Uint8Array, author: AuthorView, self: SelfView, wrap: Uint8Array): OpenedEpoch {
+  const stage = "openEpoch";
+  const parsed = expectType<EpochManifest>(parseDocument(manifestWire), DocumentType.EpochManifest, stage);
+  const cert = author.certificates.get(toHex(parsed.authorCertificateHash));
+  if (!cert) throw new KavachError("SUPERSEDED_DEVICE", stage, "manifest names a certificate that is not the author's current one");
+  const manifest = expectType<EpochManifest>(verifyDocument(manifestWire, cert.signingKey), DocumentType.EpochManifest, stage);
+  if (!equalBytes(manifest.authorIdentityId, author.identityId) || !equalBytes(manifest.streamId, cert.streamId)) {
+    throw new KavachError("MALFORMED", stage, "manifest identity or stream does not match the certificate");
+  }
+  const authorRow = manifest.audience.find((r) => equalBytes(r.identityId, author.identityId));
+  if (!authorRow || !equalBytes(authorRow.certificateHash, manifest.authorCertificateHash)) {
+    throw new KavachError("MALFORMED", stage, "author row does not name the author certificate");
+  }
+  const selfRow = manifest.audience.find((r) => equalBytes(r.identityId, self.identityId));
+  if (!selfRow || !equalBytes(selfRow.certificateHash, self.certificateHash)) {
+    throw new KavachError("NOT_AUTHORIZED", stage, "this device is not addressed by the epoch");
+  }
+  if (!equalBytes(wrapHash(wrap), selfRow.wrapHash)) throw new KavachError("WRAP_HASH_MISMATCH", stage);
+  const epochKey = openSealedBox(wrap, self.box, stage);
+  if (!equalBytes(keyCommitment(manifest.streamId, manifest.epoch, epochKey), manifest.keyCommitment)) {
+    throw new KavachError("KEY_COMMITMENT_MISMATCH", stage);
+  }
+  return { manifest, epochKey, superseded: !cert.current };
+}