@plane31/blind-relay 0.1.1 → 0.1.3

package/src/codec.ts

@@ -0,0 +1,642 @@
+/**
+ * The wire documents of Kavach v1, protocol sections 3 to 12.
+ *
+ * Parse within bounds first (sizes, ranges, sort orders, counts, nonzero rules), then verify the
+ * signature under the key the caller's trust state names, then anything else. Every parser here
+ * refuses trailing bytes and never touches a signature. Type 5 is retired and rejected.
+ */
+import {
+  MAX_DOCUMENT_BYTES,
+  MAX_PAYLOAD_BYTES,
+  Reader,
+  Writer,
+  compareBytes,
+  concat,
+  equalBytes,
+  isAllZero,
+  u32
+} from "./bytes.js";
+import {
+  C,
+  DEVICE_ID_BYTES,
+  HASH_BYTES,
+  KEY_BYTES,
+  NONCE_BYTES,
+  PUBLIC_KEY_BYTES,
+  RECOVERY_CODE_PREFIX,
+  SEED_BYTES,
+  SIGNATURE_BYTES,
+  TAG_BYTES,
+  WIRE_VERSION,
+  accountKeypair,
+  aeadOpen,
+  aeadSeal,
+  assertValidBoxKey,
+  assertValidSigningKey,
+  bodyHash,
+  sign,
+  verify,
+  type Label
+} from "./crypto.js";
+import { KavachError } from "./errors.js";
+
+export const MAX_MEMBERS = 100;
+export const MAX_RESET_KEYS = 8;
+export const MAX_RESET_KEY_LIST_LIFETIME_MS = 2_592_000_000n; // 30 days
+/** The encrypted envelope in front of every payload (revision 8): version, kind, event time. */
+export const ENVELOPE_VERSION = 1;
+export const ENVELOPE_BYTES = 1 + 1 + 8;
+export const MIN_RECORD_CIPHERTEXT = ENVELOPE_BYTES + TAG_BYTES;
+/** The size of a sealed record on the wire for a payload of this length: header, nonce, length, envelope, payload, tag, signature. */
+export function recordWireBytes(payloadLength: number): number {
+  return RECORD_HEADER_BYTES + NONCE_BYTES + 4 + ENVELOPE_BYTES + payloadLength + TAG_BYTES + SIGNATURE_BYTES;
+}
+export const MAX_RECORD_CIPHERTEXT = ENVELOPE_BYTES + MAX_PAYLOAD_BYTES + TAG_BYTES;
+export const MIN_VAULT_CIPHERTEXT = 90;
+export const MAX_VAULT_CIPHERTEXT = 4_990;
+export const VAULT_ENTRY_BYTES = 49;
+export const RECORD_HEADER_BYTES = 51;
+/** Header flags: bits 1 and 2 carry the record's header class (0 to 3), the one thing about a record the relay may see; bit 0 and bits 3 to 7 are reserved. */
+export const HEADER_CLASS_SHIFT = 1;
+export const HEADER_CLASS_MASK = 0x06;
+const RESERVED_FLAGS = ~HEADER_CLASS_MASK & 0xff;
+export type HeaderClass = 0 | 1 | 2 | 3;
+
+export enum DocumentType {
+  AccountDevice = 1,
+  CircleSnapshot = 2,
+  EpochManifest = 3,
+  EncryptedRecord = 4,
+  AccountVault = 6,
+  AccountResetReceipt = 7,
+  ResetKeyList = 8
+}
+
+/** A record kind: an opaque small integer the product declares (section 9). It travels inside the encrypted envelope. */
+export type RecordKind = number;
+export const MAX_KIND = 255;
+
+export interface AccountDevice {
+  readonly type: DocumentType.AccountDevice;
+  readonly accountName: string;
+  readonly accountKey: Uint8Array;
+  readonly generation: bigint;
+  readonly deviceId: Uint8Array;
+  readonly signingKey: Uint8Array;
+  readonly boxKey: Uint8Array;
+}
+
+export interface CircleSnapshot {
+  readonly type: DocumentType.CircleSnapshot;
+  readonly circleId: Uint8Array;
+  readonly ownerIdentityId: Uint8Array;
+  readonly revision: bigint;
+  readonly members: readonly Uint8Array[];
+}
+
+export interface AudienceRow {
+  readonly identityId: Uint8Array;
+  readonly certificateHash: Uint8Array;
+  readonly wrapHash: Uint8Array;
+}
+
+export interface EpochManifest {
+  readonly type: DocumentType.EpochManifest;
+  readonly streamId: Uint8Array;
+  readonly authorIdentityId: Uint8Array;
+  readonly authorCertificateHash: Uint8Array;
+  readonly epoch: number;
+  readonly createdAt: bigint;
+  readonly keyCommitment: Uint8Array;
+  readonly audience: readonly AudienceRow[];
+}
+
+export interface EncryptedRecord {
+  readonly type: DocumentType.EncryptedRecord;
+  readonly streamId: Uint8Array;
+  readonly epoch: number;
+  readonly counter: number;
+  readonly sentAt: bigint;
+  readonly flags: number;
+  /** What the relay may see of the record's kind: the product's declared header class, or 0. */
+  readonly headerClass: HeaderClass;
+  /** The 51-byte header, which the AEAD authenticates as `C("record-aad") || header`. */
+  readonly header: Uint8Array;
+  readonly nonce: Uint8Array;
+  readonly ciphertext: Uint8Array;
+}
+
+export interface AccountResetReceipt {
+  readonly type: DocumentType.AccountResetReceipt;
+  readonly accountName: string;
+  readonly oldIdentityId: Uint8Array;
+  readonly newIdentityId: Uint8Array;
+  readonly resetId: Uint8Array;
+  readonly issuedAt: bigint;
+  readonly authorityKeyId: Uint8Array;
+}
+
+export interface ResetKeyEntry {
+  readonly keyId: Uint8Array;
+  readonly publicKey: Uint8Array;
+}
+
+export interface ResetKeyList {
+  readonly type: DocumentType.ResetKeyList;
+  readonly version: bigint;
+  readonly issuedAt: bigint;
+  readonly expiresAt: bigint;
+  readonly keys: readonly ResetKeyEntry[];
+}
+
+export type SignedDocument = AccountDevice | CircleSnapshot | EpochManifest | EncryptedRecord | AccountResetReceipt | ResetKeyList;
+
+/** A parsed signed document together with the exact body and signature bytes. */
+export type Parsed<T extends SignedDocument = SignedDocument> = T & {
+  readonly body: Uint8Array;
+  readonly signature: Uint8Array;
+  readonly bodyHash: Uint8Array;
+};
+
+export const LABEL_BY_TYPE: Readonly<Record<number, Label>> = {
+  [DocumentType.AccountDevice]: "account-sig",
+  [DocumentType.CircleSnapshot]: "snapshot-sig",
+  [DocumentType.EpochManifest]: "epoch-sig",
+  [DocumentType.EncryptedRecord]: "record-sig",
+  [DocumentType.AccountResetReceipt]: "reset-sig",
+  [DocumentType.ResetKeyList]: "reset-keys-sig"
+};
+
+// Parsing --------------------------------------------------------------------------------------
+
+function strictlySortedUnique(items: readonly Uint8Array[]): boolean {
+  for (let i = 1; i < items.length; i++) {
+    const a = items[i - 1];
+    const b = items[i];
+    if (!a || !b || compareBytes(a, b) >= 0) return false;
+  }
+  return true;
+}
+
+function malformed(stage: string, why: string): KavachError {
+  return new KavachError("MALFORMED", stage, why);
+}
+
+/**
+ * Parse a signed document (types 1 to 4, 7, 8). The signature is split off but not checked;
+ * call `verifyDocument` for that. Type 6 is not a signed document and type 5 is retired.
+ */
+export function parseDocument(wire: Uint8Array): Parsed {
+  const stage = "parse";
+  if (wire.length > MAX_DOCUMENT_BYTES) throw new KavachError("SIZE_LIMIT", stage, "document over 16,384 bytes");
+  const r = new Reader(wire, stage);
+  if (r.u8() !== WIRE_VERSION) throw new KavachError("UNSUPPORTED_VERSION", stage);
+  const type = r.u8();
+  let fields: SignedDocument;
+  switch (type) {
+    case DocumentType.AccountDevice: {
+      const accountName = r.name();
+      const accountKey = r.take(PUBLIC_KEY_BYTES);
+      const generation = r.u64();
+      const deviceId = r.take(DEVICE_ID_BYTES);
+      const signingKey = r.take(PUBLIC_KEY_BYTES);
+      const boxKey = r.take(PUBLIC_KEY_BYTES);
+      if (generation === 0n) throw malformed(stage, "generation zero");
+      if (isAllZero(deviceId)) throw malformed(stage, "device id zero");
+      fields = { type, accountName, accountKey, generation, deviceId, signingKey, boxKey };
+      break;
+    }
+    case DocumentType.CircleSnapshot: {
+      const circleId = r.take(16);
+      const ownerIdentityId = r.take(HASH_BYTES);
+      const revision = r.u64();
+      const count = r.u16();
+      if (revision === 0n) throw malformed(stage, "revision zero");
+      if (count < 1 || count > MAX_MEMBERS) throw malformed(stage, "member count");
+      const members: Uint8Array[] = [];
+      for (let i = 0; i < count; i++) members.push(r.take(HASH_BYTES));
+      if (!strictlySortedUnique(members)) throw malformed(stage, "members not strictly sorted");
+      if (!members.some((m) => equalBytes(m, ownerIdentityId))) throw malformed(stage, "owner missing");
+      fields = { type, circleId, ownerIdentityId, revision, members };
+      break;
+    }
+    case DocumentType.EpochManifest: {
+      const streamId = r.take(HASH_BYTES);
+      const authorIdentityId = r.take(HASH_BYTES);
+      const authorCertificateHash = r.take(HASH_BYTES);
+      const epoch = r.u32();
+      const createdAt = r.u64();
+      const keyCommitment = r.take(HASH_BYTES);
+      const count = r.u16();
+      if (epoch === 0) throw malformed(stage, "epoch zero");
+      if (count < 1 || count > MAX_MEMBERS) throw malformed(stage, "audience count");
+      const audience: AudienceRow[] = [];
+      for (let i = 0; i < count; i++) {
+        audience.push({ identityId: r.take(HASH_BYTES), certificateHash: r.take(HASH_BYTES), wrapHash: r.take(HASH_BYTES) });
+      }
+      if (!strictlySortedUnique(audience.map((a) => a.identityId))) throw malformed(stage, "audience not strictly sorted");
+      if (!audience.some((a) => equalBytes(a.identityId, authorIdentityId))) throw malformed(stage, "author missing from audience");
+      fields = { type, streamId, authorIdentityId, authorCertificateHash, epoch, createdAt, keyCommitment, audience };
+      break;
+    }
+    case DocumentType.EncryptedRecord: {
+      const streamId = r.take(HASH_BYTES);
+      const epoch = r.u32();
+      const counter = r.u32();
+      const sentAt = r.u64();
+      const flags = r.u8();
+      if (epoch === 0) throw malformed(stage, "epoch zero");
+      if ((flags & RESERVED_FLAGS) !== 0) throw malformed(stage, "reserved flag bit set");
+      const header = r.consumed();
+      const nonce = r.take(NONCE_BYTES);
+      const length = r.u32();
+      if (length < MIN_RECORD_CIPHERTEXT || length > MAX_RECORD_CIPHERTEXT) {
+        throw new KavachError("SIZE_LIMIT", stage, "record ciphertext length");
+      }
+      const ciphertext = r.take(length);
+      fields = { type, streamId, epoch, counter, sentAt, flags, headerClass: ((flags & HEADER_CLASS_MASK) >> HEADER_CLASS_SHIFT) as HeaderClass, header, nonce, ciphertext };
+      break;
+    }
+    case DocumentType.AccountResetReceipt: {
+      const accountName = r.name();
+      const oldIdentityId = r.take(HASH_BYTES);
+      const newIdentityId = r.take(HASH_BYTES);
+      const resetId = r.take(16);
+      const issuedAt = r.u64();
+      const authorityKeyId = r.take(16);
+      if (equalBytes(oldIdentityId, newIdentityId)) throw malformed(stage, "old and new identity equal");
+      fields = { type, accountName, oldIdentityId, newIdentityId, resetId, issuedAt, authorityKeyId };
+      break;
+    }
+    case DocumentType.ResetKeyList: {
+      const version = r.u64();
+      const issuedAt = r.u64();
+      const expiresAt = r.u64();
+      const count = r.u8();
+      if (version === 0n) throw malformed(stage, "version zero");
+      if (count > MAX_RESET_KEYS) throw malformed(stage, "too many keys");
+      const lifetime = expiresAt - issuedAt;
+      if (lifetime <= 0n || lifetime > MAX_RESET_KEY_LIST_LIFETIME_MS) throw malformed(stage, "key-list lifetime");
+      const keys: ResetKeyEntry[] = [];
+      for (let i = 0; i < count; i++) keys.push({ keyId: r.take(16), publicKey: r.take(PUBLIC_KEY_BYTES) });
+      if (!strictlySortedUnique(keys.map((k) => k.keyId))) throw malformed(stage, "key ids not strictly sorted");
+      if (keys.some((k) => isAllZero(k.keyId))) throw malformed(stage, "zero key id");
+      for (let i = 0; i < keys.length; i++) {
+        for (let j = i + 1; j < keys.length; j++) {
+          const a = keys[i];
+          const b = keys[j];
+          if (a && b && equalBytes(a.publicKey, b.publicKey)) throw malformed(stage, "duplicate key");
+        }
+      }
+      for (const k of keys) assertValidSigningKey(k.publicKey, stage);
+      fields = { type, version, issuedAt, expiresAt, keys };
+      break;
+    }
+    default:
+      // 5 is retired; 6 is not a signed document; everything else is unknown.
+      throw new KavachError("UNSUPPORTED_TYPE", stage, `type ${type}`);
+  }
+  const body = r.consumed();
+  const signature = r.take(SIGNATURE_BYTES);
+  r.end();
+  return { ...fields, body, signature, bodyHash: bodyHash(body) };
+}
+
+/**
+ * Parse and verify. A type 1 certificate is verified under the key it carries, which establishes
+ * key possession only. Every other type needs the key the caller's trust state names.
+ */
+export function verifyDocument(wire: Uint8Array, publicKey?: Uint8Array): Parsed {
+  const doc = parseDocument(wire);
+  const label = LABEL_BY_TYPE[doc.type];
+  if (!label) throw new KavachError("UNSUPPORTED_TYPE", "verify");
+  let key = publicKey;
+  if (doc.type === DocumentType.AccountDevice) key = doc.accountKey;
+  if (!key) throw new KavachError("METADATA_REQUIRED", "verify", "verification key required");
+  verify(key, label, doc.body, doc.signature);
+  if (doc.type === DocumentType.AccountDevice) {
+    assertValidSigningKey(doc.signingKey);
+    assertValidBoxKey(doc.boxKey);
+  }
+  return doc;
+}
+
+/** Narrow a parsed document to one type, or fail as MALFORMED. */
+export function expectType<T extends SignedDocument>(doc: Parsed, type: T["type"], stage = "verify"): Parsed<T> {
+  if (doc.type !== type) throw malformed(stage, `expected type ${type}, got ${doc.type}`);
+  return doc as unknown as Parsed<T>;
+}
+
+// Building -------------------------------------------------------------------------------------
+
+function signed(body: Uint8Array, label: Label, secretKey: Uint8Array): Uint8Array {
+  return concat(body, sign(secretKey, label, body));
+}
+
+export function encodeAccountDeviceBody(f: Omit<AccountDevice, "type">): Uint8Array {
+  return new Writer()
+    .u8(WIRE_VERSION)
+    .u8(DocumentType.AccountDevice)
+    .name(f.accountName)
+    .bytes(f.accountKey)
+    .u64(f.generation)
+    .bytes(f.deviceId)
+    .bytes(f.signingKey)
+    .bytes(f.boxKey)
+    .finish();
+}
+
+export function buildAccountDevice(f: Omit<AccountDevice, "type">, accountSecretKey: Uint8Array): Uint8Array {
+  return signed(encodeAccountDeviceBody(f), "account-sig", accountSecretKey);
+}
+
+export function encodeCircleSnapshotBody(f: Omit<CircleSnapshot, "type">): Uint8Array {
+  const members = [...f.members].sort(compareBytes);
+  const w = new Writer().u8(WIRE_VERSION).u8(DocumentType.CircleSnapshot).bytes(f.circleId).bytes(f.ownerIdentityId).u64(f.revision).u16(members.length);
+  for (const m of members) w.bytes(m);
+  return w.finish();
+}
+
+export function buildCircleSnapshot(f: Omit<CircleSnapshot, "type">, ownerAccountSecretKey: Uint8Array): Uint8Array {
+  return signed(encodeCircleSnapshotBody(f), "snapshot-sig", ownerAccountSecretKey);
+}
+
+export function encodeEpochManifestBody(f: Omit<EpochManifest, "type">): Uint8Array {
+  const rows = [...f.audience].sort((a, b) => compareBytes(a.identityId, b.identityId));
+  const w = new Writer()
+    .u8(WIRE_VERSION)
+    .u8(DocumentType.EpochManifest)
+    .bytes(f.streamId)
+    .bytes(f.authorIdentityId)
+    .bytes(f.authorCertificateHash)
+    .u32(f.epoch)
+    .u64(f.createdAt)
+    .bytes(f.keyCommitment)
+    .u16(rows.length);
+  for (const row of rows) w.bytes(row.identityId).bytes(row.certificateHash).bytes(row.wrapHash);
+  return w.finish();
+}
+
+export function buildEpochManifest(f: Omit<EpochManifest, "type">, deviceSigningSecretKey: Uint8Array): Uint8Array {
+  return signed(encodeEpochManifestBody(f), "epoch-sig", deviceSigningSecretKey);
+}
+
+export interface RecordHeaderFields {
+  readonly streamId: Uint8Array;
+  readonly epoch: number;
+  readonly counter: number;
+  readonly sentAt: bigint;
+  readonly headerClass: HeaderClass;
+}
+
+export function encodeRecordHeader(f: RecordHeaderFields): Uint8Array {
+  if (f.epoch === 0) throw malformed("encode", "epoch zero");
+  return new Writer()
+    .u8(WIRE_VERSION)
+    .u8(DocumentType.EncryptedRecord)
+    .bytes(f.streamId)
+    .u32(f.epoch)
+    .u32(f.counter)
+    .u64(f.sentAt)
+    .u8((f.headerClass << HEADER_CLASS_SHIFT) & HEADER_CLASS_MASK)
+    .finish();
+}
+
+/** What the envelope carries about a record, readable only by a holder of the epoch key. */
+export interface Envelope {
+  readonly kind: RecordKind;
+  /** The event time the product supplied, if any; a reader clamps it to `sentAt` before ordering by it. */
+  readonly eventTime?: bigint | undefined;
+}
+
+/** `u8(1) || u8(kind) || u64(eventTime or 0) || payload`: the plaintext under the AEAD. */
+export function encodeEnvelope(e: Envelope, payload: Uint8Array): Uint8Array {
+  if (!Number.isInteger(e.kind) || e.kind < 0 || e.kind > MAX_KIND) throw malformed("encode", "kind out of range");
+  if (payload.length > MAX_PAYLOAD_BYTES) throw new KavachError("SIZE_LIMIT", "encode", "payload over 4,096 bytes");
+  if (e.eventTime !== undefined && e.eventTime < 0n) throw malformed("encode", "event time before the epoch");
+  return new Writer().u8(ENVELOPE_VERSION).u8(e.kind).u64(e.eventTime ?? 0n).bytes(payload).finish();
+}
+
+export function decodeEnvelope(plaintext: Uint8Array): Envelope & { readonly payload: Uint8Array } {
+  const stage = "envelope";
+  if (plaintext.length < ENVELOPE_BYTES) throw malformed(stage, "envelope too short");
+  const r = new Reader(plaintext, stage);
+  if (r.u8() !== ENVELOPE_VERSION) throw malformed(stage, "envelope version");
+  const kind = r.u8();
+  const t = r.u64();
+  const payload = plaintext.subarray(ENVELOPE_BYTES);
+  if (payload.length > MAX_PAYLOAD_BYTES) throw new KavachError("SIZE_LIMIT", stage, "payload over 4,096 bytes");
+  return { kind, eventTime: t === 0n ? undefined : t, payload };
+}
+
+export function recordAad(header: Uint8Array): Uint8Array {
+  return concat(C("record-aad"), header);
+}
+
+/** Encrypt and sign one record from its complete plaintext (the envelope with the payload). The caller supplies a fresh random nonce and never reuses it. */
+export function buildEncryptedRecord(f: RecordHeaderFields, plaintext: Uint8Array, epochKey: Uint8Array, nonce: Uint8Array, deviceSigningSecretKey: Uint8Array): Uint8Array {
+  if (plaintext.length < ENVELOPE_BYTES || plaintext.length > ENVELOPE_BYTES + MAX_PAYLOAD_BYTES) throw new KavachError("SIZE_LIMIT", "encode", "record plaintext length");
+  const header = encodeRecordHeader(f);
+  const ciphertext = aeadSeal(epochKey, nonce, recordAad(header), plaintext);
+  const body = concat(header, nonce, u32(ciphertext.length), ciphertext);
+  return signed(body, "record-sig", deviceSigningSecretKey);
+}
+
+/** The same from a kind, an optional event time and a payload: the envelope is encoded here. */
+export function buildRecordWire(f: RecordHeaderFields & Envelope, payload: Uint8Array, epochKey: Uint8Array, nonce: Uint8Array, deviceSigningSecretKey: Uint8Array): Uint8Array {
+  return buildEncryptedRecord(f, encodeEnvelope(f, payload), epochKey, nonce, deviceSigningSecretKey);
+}
+
+/** Decrypt a parsed record under its epoch key to its plaintext (the envelope with the payload). Verify the signature first; this does not. */
+export function openRecord(record: EncryptedRecord, epochKey: Uint8Array): Uint8Array {
+  return aeadOpen(epochKey, record.nonce, recordAad(record.header), record.ciphertext);
+}
+
+export function encodeResetReceiptBody(f: Omit<AccountResetReceipt, "type">): Uint8Array {
+  return new Writer()
+    .u8(WIRE_VERSION)
+    .u8(DocumentType.AccountResetReceipt)
+    .name(f.accountName)
+    .bytes(f.oldIdentityId)
+    .bytes(f.newIdentityId)
+    .bytes(f.resetId)
+    .u64(f.issuedAt)
+    .bytes(f.authorityKeyId)
+    .finish();
+}
+
+export function buildResetReceipt(f: Omit<AccountResetReceipt, "type">, resetSecretKey: Uint8Array): Uint8Array {
+  return signed(encodeResetReceiptBody(f), "reset-sig", resetSecretKey);
+}
+
+export function encodeResetKeyListBody(f: Omit<ResetKeyList, "type">): Uint8Array {
+  const keys = [...f.keys].sort((a, b) => compareBytes(a.keyId, b.keyId));
+  const w = new Writer().u8(WIRE_VERSION).u8(DocumentType.ResetKeyList).u64(f.version).u64(f.issuedAt).u64(f.expiresAt).u8(keys.length);
+  for (const k of keys) w.bytes(k.keyId).bytes(k.publicKey);
+  return w.finish();
+}
+
+export function buildResetKeyList(f: Omit<ResetKeyList, "type">, managementSecretKey: Uint8Array): Uint8Array {
+  return signed(encodeResetKeyListBody(f), "reset-keys-sig", managementSecretKey);
+}
+
+// Account vault (type 6) -----------------------------------------------------------------------
+
+export interface VaultEntry {
+  readonly circleId: Uint8Array;
+  readonly ownerIdentityId: Uint8Array;
+  readonly sharingEnabled: boolean;
+}
+
+export interface VaultContents {
+  readonly accountSeed: Uint8Array;
+  readonly lastDeviceGeneration: bigint;
+  readonly lastCertificateHash: Uint8Array;
+  readonly entries: readonly VaultEntry[];
+}
+
+export interface VaultHeader {
+  readonly accountName: string;
+  readonly accountKey: Uint8Array;
+  readonly vaultRevision: bigint;
+}
+
+export function encodeVaultHeader(h: VaultHeader): Uint8Array {
+  return new Writer().u8(WIRE_VERSION).u8(DocumentType.AccountVault).name(h.accountName).bytes(h.accountKey).u64(h.vaultRevision).finish();
+}
+
+export function encodeVaultPlaintext(v: VaultContents): Uint8Array {
+  if (v.accountSeed.length !== SEED_BYTES) throw malformed("encodeVault", "seed length");
+  if (v.entries.length > MAX_MEMBERS) throw malformed("encodeVault", "too many entries");
+  const entries = [...v.entries].sort((a, b) => compareBytes(a.circleId, b.circleId));
+  if (!strictlySortedUnique(entries.map((e) => e.circleId))) throw malformed("encodeVault", "duplicate circle");
+  const w = new Writer().bytes(v.accountSeed).u64(v.lastDeviceGeneration).bytes(v.lastCertificateHash).u16(entries.length);
+  for (const e of entries) w.bytes(e.circleId).bytes(e.ownerIdentityId).u8(e.sharingEnabled ? 1 : 0);
+  return w.finish();
+}
+
+export function decodeVaultPlaintext(plain: Uint8Array): VaultContents {
+  const stage = "decodeVault";
+  const r = new Reader(plain, stage);
+  const accountSeed = r.take(SEED_BYTES);
+  const lastDeviceGeneration = r.u64();
+  const lastCertificateHash = r.take(HASH_BYTES);
+  const count = r.u16();
+  if (lastDeviceGeneration === 0n) throw malformed(stage, "generation zero");
+  if (count > MAX_MEMBERS) throw malformed(stage, "too many entries");
+  const entries: VaultEntry[] = [];
+  for (let i = 0; i < count; i++) {
+    const circleId = r.take(16);
+    const ownerIdentityId = r.take(HASH_BYTES);
+    const flag = r.u8();
+    if (flag !== 0 && flag !== 1) throw malformed(stage, "sharing flag");
+    entries.push({ circleId, ownerIdentityId, sharingEnabled: flag === 1 });
+  }
+  r.end();
+  if (!strictlySortedUnique(entries.map((e) => e.circleId))) throw malformed(stage, "entries not strictly sorted");
+  return { accountSeed, lastDeviceGeneration, lastCertificateHash, entries };
+}
+
+/** Encrypt a vault. The caller supplies a fresh random nonce. */
+export function sealVault(header: VaultHeader, contents: VaultContents, recoveryKey: Uint8Array, nonce: Uint8Array): Uint8Array {
+  if (header.vaultRevision === 0n) throw malformed("sealVault", "revision zero");
+  const h = encodeVaultHeader(header);
+  const ciphertext = aeadSeal(recoveryKey, nonce, concat(C("vault-aad"), h), encodeVaultPlaintext(contents));
+  return concat(h, nonce, u32(ciphertext.length), ciphertext);
+}
+
+/** Read a vault's public header without opening it (the host's compare-and-swap uses it). */
+export function parseVaultHeader(wire: Uint8Array): VaultHeader & { readonly hash: Uint8Array } {
+  const stage = "vaultHeader";
+  if (wire.length > MAX_DOCUMENT_BYTES) throw new KavachError("SIZE_LIMIT", stage);
+  const r = new Reader(wire, stage);
+  if (r.u8() !== WIRE_VERSION) throw new KavachError("UNSUPPORTED_VERSION", stage);
+  if (r.u8() !== DocumentType.AccountVault) throw new KavachError("UNSUPPORTED_TYPE", stage);
+  const accountName = r.name();
+  const accountKey = r.take(PUBLIC_KEY_BYTES);
+  const vaultRevision = r.u64();
+  if (vaultRevision === 0n) throw malformed(stage, "revision zero");
+  return { accountName, accountKey, vaultRevision, hash: bodyHash(wire) };
+}
+
+export interface OpenedVault extends VaultContents {
+  readonly header: VaultHeader;
+}
+
+/**
+ * Open a vault under the recovery key. Binds the header to the expected account before decrypting
+ * and checks that `AK` derives from the recovered seed before trusting the entries.
+ */
+export function openVault(wire: Uint8Array, recoveryKey: Uint8Array, expectedName: string, expectedAccountKey: Uint8Array): OpenedVault {
+  const stage = "openVault";
+  if (wire.length > MAX_DOCUMENT_BYTES) throw new KavachError("SIZE_LIMIT", stage);
+  const r = new Reader(wire, stage);
+  if (r.u8() !== WIRE_VERSION) throw new KavachError("UNSUPPORTED_VERSION", stage);
+  if (r.u8() !== DocumentType.AccountVault) throw new KavachError("UNSUPPORTED_TYPE", stage);
+  const accountName = r.name();
+  const accountKey = r.take(PUBLIC_KEY_BYTES);
+  const vaultRevision = r.u64();
+  if (accountName !== expectedName || !equalBytes(accountKey, expectedAccountKey) || vaultRevision === 0n) {
+    throw new KavachError("VAULT_BINDING", stage);
+  }
+  const header = r.consumed();
+  const nonce = r.take(NONCE_BYTES);
+  const length = r.u32();
+  if (length < MIN_VAULT_CIPHERTEXT || length > MAX_VAULT_CIPHERTEXT) throw new KavachError("SIZE_LIMIT", stage, "vault ciphertext length");
+  const ciphertext = r.take(length);
+  r.end();
+  if (recoveryKey.length !== KEY_BYTES) throw new KavachError("INVALID_KEY", stage);
+  const plain = aeadOpen(recoveryKey, nonce, concat(C("vault-aad"), header), ciphertext, stage);
+  const contents = decodeVaultPlaintext(plain);
+  if (!equalBytes(accountKeypair(contents.accountSeed).publicKey, accountKey)) throw new KavachError("VAULT_BINDING", stage, "seed does not derive AK");
+  return { ...contents, header: { accountName, accountKey, vaultRevision } };
+}
+
+// Recovery code --------------------------------------------------------------------------------
+
+const B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+function base64url(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i] ?? 0;
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    out += B64URL[a >> 2];
+    out += B64URL[((a & 3) << 4) | ((b ?? 0) >> 4)];
+    if (b !== undefined) out += B64URL[((b & 15) << 2) | ((c ?? 0) >> 6)];
+    if (c !== undefined) out += B64URL[c & 63];
+  }
+  return out;
+}
+
+function unbase64url(text: string): Uint8Array | undefined {
+  if (!/^[A-Za-z0-9_-]+$/.test(text) || text.length % 4 === 1) return undefined;
+  const out: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const ch of text) {
+    buffer = (buffer << 6) | B64URL.indexOf(ch);
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buffer >> bits) & 0xff);
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+/** `"KV1R-" || base64url(recoveryKey)`, 48 characters, no padding. */
+export function encodeRecoveryCode(recoveryKey: Uint8Array): string {
+  if (recoveryKey.length !== KEY_BYTES) throw new KavachError("INVALID_KEY", "recoveryCode");
+  return RECOVERY_CODE_PREFIX + base64url(recoveryKey);
+}
+
+export function decodeRecoveryCode(text: string): Uint8Array {
+  const stage = "recoveryCode";
+  if (!text.startsWith(RECOVERY_CODE_PREFIX)) throw malformed(stage, "prefix");
+  const value = text.slice(RECOVERY_CODE_PREFIX.length);
+  const raw = unbase64url(value);
+  if (!raw || raw.length !== KEY_BYTES || base64url(raw) !== value) throw malformed(stage, "not a recovery key");
+  return raw;
+}

package/src/crypto/backend.ts

@@ -0,0 +1,48 @@
+/**
+ * The primitive backend behind `crypto.ts`. Two implementations exist: `noble` (pure
+ * JavaScript, runs on Hermes and in workerd, the default) and `sodium` (libsodium's wasm, for
+ * Node and tests). Both are checked against the same vectors; the protocol never sees which one
+ * is loaded.
+ */
+export interface SignKeypair {
+  readonly publicKey: Uint8Array; // 32
+  readonly secretKey: Uint8Array; // 64, libsodium layout: seed || public
+}
+
+export interface BoxKeypair {
+  readonly publicKey: Uint8Array; // 32
+  readonly secretKey: Uint8Array; // 32
+}
+
+export interface CryptoBackend {
+  readonly name: "noble" | "sodium";
+  blake2b(data: Uint8Array, outLen: number, key?: Uint8Array): Uint8Array;
+  randomBytes(length: number): Uint8Array;
+  signKeypairFromSeed(seed: Uint8Array): SignKeypair;
+  signDetached(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  verifyDetached(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+  /** Canonical, on the curve, on the main subgroup, not the identity. */
+  isValidSignPoint(publicKey: Uint8Array): boolean;
+  /** `crypto_box_seed_keypair`: scalar = SHA-512(seed)[0..32], public = X25519 base point multiple. */
+  boxKeypairFromSeed(seed: Uint8Array): BoxKeypair;
+  boxKeypair(): BoxKeypair;
+  /** X25519; throws on an all-zero shared secret. */
+  scalarMult(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+  /** `crypto_box_easy`: XSalsa20-Poly1305 under HSalsa20(X25519(sk, pk)); output mac || ciphertext. */
+  boxEasy(message: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  boxOpenEasy(box: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  /** XChaCha20-Poly1305 with the tag appended. */
+  aeadEncrypt(plaintext: Uint8Array, aad: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+  aeadDecrypt(ciphertextAndTag: Uint8Array, aad: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+  memzero(bytes: Uint8Array): void;
+}
+
+let current: CryptoBackend | undefined;
+
+export function setCryptoBackend(backend: CryptoBackend): void {
+  current = backend;
+}
+
+export function currentBackend(): CryptoBackend | undefined {
+  return current;
+}