How the encryption works

/// <reference lib="dom" />
/**
 * E2EE crypto primitives using NaCl (tweetnacl).
 *
 * - Key exchange: Curve25519 (nacl.box.before)
 * - Encryption: XSalsa20-Poly1305 secretbox (`SecretboxBackend`, tweetnacl unless one is installed)
 *
 * Bundle format (binary):
 *   [nonce (24 bytes)] [ciphertext...]
 *
 * The encrypted channel chooses the WebSocket representation. Crypto remains
 * byte-oriented so frame kind is never inferred from plaintext contents.
 */

import nacl from "tweetnacl";
import { fromByteArray, toByteArray } from "base64-js";

export interface KeyPair {
  publicKey: Uint8Array; // 32 bytes
  secretKey: Uint8Array; // 32 bytes
}

export type SharedKey = Uint8Array; // 32 bytes (box.before)

const NONCE_LENGTH = nacl.box.nonceLength; // 24
const MAC_LENGTH = nacl.secretbox.overheadLength; // 16
/** One nonce reused by the counter functions: they run to completion and keep no reference. */
const scratchNonce = new Uint8Array(NONCE_LENGTH);
const ZERO_X25519_SHARED_RESULT = new Uint8Array(nacl.box.sharedKeyLength);

/**
 * XSalsa20-Poly1305 secretbox in NaCl's layout, `[MAC (16)] [ciphertext]`: tweetnacl's
 * `secretbox`, libsodium's `crypto_secretbox_easy`. Every sealed relay frame and sealed document
 * goes through it (`box.after` is secretbox under the box.before key).
 *
 * Round 40 T1: tweetnacl runs it in JavaScript, which on the phone (Hermes) took 5–10 % of the JS
 * thread while a reply streamed. The phone installs libsodium over JSI here
 * (packages/app/src/polyfills/relay-secretbox.native.ts); daemons, the cloud, desktop and web keep
 * tweetnacl (WebCrypto has no XSalsa20).
 */
export interface SecretboxBackend {
  readonly name: string;
  seal(message: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
  /** The plaintext, or null when the box does not open under this nonce and key. */
  open(box: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array | null;
}

export const TWEETNACL_SECRETBOX: SecretboxBackend = {
  name: "tweetnacl",
  seal: (message, nonce, key) => nacl.secretbox(message, nonce, key),
  open: (box, nonce, key) => nacl.secretbox.open(box, nonce, key),
};

let secretbox: SecretboxBackend = TWEETNACL_SECRETBOX;

const SELF_TEST_KEY = Uint8Array.from({ length: 32 }, (_, i) => (i * 7 + 1) & 0xff);
const SELF_TEST_NONCE = Uint8Array.from({ length: NONCE_LENGTH }, (_, i) => (i * 13 + 5) & 0xff);
const SELF_TEST_MESSAGE = Uint8Array.from({ length: 131 }, (_, i) => (i * 31 + 11) & 0xff);
/**
 * What tweetnacl seals for the self-test message and for an empty one, written out: sealing them
 * in tweetnacl at every phone start cost 2–3 ms of Hermes before the first screen (round 40 T1).
 * `secretbox-backend.test.ts` checks they are still tweetnacl's bytes.
 */
export const SELF_TEST_SEALED = toByteArray(
  "6Yle1ERanjW+YOuWgURasr3rItcn5IHeHS0v7MeEoE5ilcnAOZu+xymBQRnfS+JLS98IeOQtpzHe/bHFZ4n7LkoncH3WGLey" +
    "nise+JbHVEnRTAhe2qj4RX2VDVEhjZLHInBGK3oLe1FM/SbvU1tjAw9U8Ep6jHXtrWsJ/1wVxaJM+Gxx64YnR1sQsuakguuGHmAl",
);
export const SELF_TEST_SEALED_EMPTY = toByteArray("0yw87bS1raxQRLLoZ4PNXg==");

function sameBytes(a: Uint8Array | null, b: Uint8Array): boolean {
  if (!a || a.byteLength !== b.byteLength) return false;
  for (let i = 0; i < a.byteLength; i += 1) if (a[i] !== b[i]) return false;
  return true;
}

/**
 * True when `backend` seals exactly what tweetnacl (the daemon's and the cloud's implementation)
 * seals, opens it, and refuses a box with one bit changed, an empty and a too-short box.
 */
export function secretboxMatchesTweetnacl(backend: SecretboxBackend): boolean {
  try {
    const expected = SELF_TEST_SEALED;
    const sealed = backend.seal(SELF_TEST_MESSAGE, SELF_TEST_NONCE, SELF_TEST_KEY);
    if (!sameBytes(sealed, expected)) return false;
    if (!sameBytes(backend.open(expected, SELF_TEST_NONCE, SELF_TEST_KEY), SELF_TEST_MESSAGE)) {
      return false;
    }
    const tampered = expected.slice();
    tampered[MAC_LENGTH + 3] ^= 1;
    if (backend.open(tampered, SELF_TEST_NONCE, SELF_TEST_KEY) !== null) return false;
    if (backend.open(new Uint8Array(0), SELF_TEST_NONCE, SELF_TEST_KEY) !== null) return false;
    if (backend.open(expected.subarray(0, 8), SELF_TEST_NONCE, SELF_TEST_KEY) !== null) {
      return false;
    }
    const empty = backend.seal(new Uint8Array(0), SELF_TEST_NONCE, SELF_TEST_KEY);
    return sameBytes(empty, SELF_TEST_SEALED_EMPTY);
  } catch {
    return false;
  }
}

/**
 * Seals and opens every secretbox with `backend` from now on, after it passes
 * `secretboxMatchesTweetnacl`; null (or a backend that fails the check) puts tweetnacl back.
 * Answers the backend in use.
 */
export function installSecretboxBackend(backend: SecretboxBackend | null): string {
  secretbox = backend && secretboxMatchesTweetnacl(backend) ? backend : TWEETNACL_SECRETBOX;
  return secretbox.name;
}

export function secretboxBackendName(): string {
  return secretbox.name;
}

/** NaCl secretbox through the installed backend (`secretbox.seal`, `secretbox.open`). */
export function secretboxSeal(message: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array {
  return secretbox.seal(message, nonce, key);
}

export function secretboxOpen(
  box: Uint8Array,
  nonce: Uint8Array,
  key: Uint8Array,
): Uint8Array | null {
  if (box.byteLength < MAC_LENGTH) return null;
  return secretbox.open(box, nonce, key);
}

let prngReady = false;

interface GlobalWithCrypto {
  crypto?: Crypto;
}

function getGlobalCrypto(): Crypto | undefined {
  const g = globalThis as GlobalWithCrypto;
  return g.crypto;
}

function ensurePrng(): void {
  if (prngReady) return;

  try {
    nacl.randomBytes(1);
    prngReady = true;
    return;
  } catch {
    // fallthrough
  }

  const cryptoObj = getGlobalCrypto();
  if (cryptoObj?.getRandomValues) {
    nacl.setPRNG((x, n) => {
      const buf = new Uint8Array(n);
      cryptoObj.getRandomValues(buf);
      x.set(buf, 0);
    });
    prngReady = true;
    return;
  }

  throw new Error("No secure PRNG available for tweetnacl (missing crypto.getRandomValues)");
}

function encodeBase64(bytes: Uint8Array): string {
  return fromByteArray(bytes);
}

function decodeBase64(base64: string): Uint8Array {
  return toByteArray(base64);
}

function decodePublicKeyBase64(base64: string): Uint8Array {
  if (
    typeof base64 !== "string" ||
    base64.length % 4 !== 0 ||
    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(base64)
  ) {
    throw new Error("Invalid public key encoding");
  }

  const bytes = decodeBase64(base64);
  if (encodeBase64(bytes) !== base64) {
    throw new Error("Invalid public key encoding");
  }
  return bytes;
}

function toUint8(data: string | ArrayBuffer): Uint8Array {
  return typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
}

function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
  // A whole buffer is handed over as it is (the bundles below are fresh); a view is copied.
  if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
    return bytes.buffer as ArrayBuffer;
  }
  const out = new Uint8Array(bytes.byteLength);
  out.set(bytes);
  return out.buffer;
}

/** `[nonce (24)] [box]` in one allocation. */
function bundle(nonce: Uint8Array, box: Uint8Array): ArrayBuffer {
  const out = new Uint8Array(NONCE_LENGTH + box.byteLength);
  out.set(nonce, 0);
  out.set(box, NONCE_LENGTH);
  return out.buffer;
}

export function generateKeyPair(): KeyPair {
  ensurePrng();
  const { publicKey, secretKey } = nacl.box.keyPair();
  return { publicKey, secretKey };
}

export function exportPublicKey(publicKey: Uint8Array): string {
  if (!(publicKey instanceof Uint8Array) || publicKey.byteLength !== nacl.box.publicKeyLength) {
    throw new Error(`Invalid public key length (expected ${nacl.box.publicKeyLength})`);
  }
  return encodeBase64(publicKey);
}

export function importPublicKey(base64: string): Uint8Array {
  const bytes = decodePublicKeyBase64(base64);
  if (bytes.byteLength !== nacl.box.publicKeyLength) {
    throw new Error(`Invalid public key length (expected ${nacl.box.publicKeyLength})`);
  }
  return bytes;
}

export function exportSecretKey(secretKey: Uint8Array): string {
  if (!(secretKey instanceof Uint8Array) || secretKey.byteLength !== nacl.box.secretKeyLength) {
    throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
  }
  return encodeBase64(secretKey);
}

export function importSecretKey(base64: string): Uint8Array {
  const bytes = decodeBase64(base64);
  if (bytes.byteLength !== nacl.box.secretKeyLength) {
    throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
  }
  return bytes;
}

export function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey: Uint8Array): SharedKey {
  if (ourSecretKey.byteLength !== nacl.box.secretKeyLength) {
    throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
  }
  if (peerPublicKey.byteLength !== nacl.box.publicKeyLength) {
    throw new Error(`Invalid peer public key length (expected ${nacl.box.publicKeyLength})`);
  }

  const rawSharedResult = nacl.scalarMult(ourSecretKey, peerPublicKey);
  const isAllZero = nacl.verify(rawSharedResult, ZERO_X25519_SHARED_RESULT);
  rawSharedResult.fill(0);
  if (isAllZero) {
    throw new Error("Invalid peer public key");
  }

  return nacl.box.before(peerPublicKey, ourSecretKey);
}

/**
 * Encrypts data and returns the binary bundle:
 *   [nonce (24)] [ciphertext...]
 */
export function encrypt(sharedKey: SharedKey, data: string | ArrayBuffer): ArrayBuffer {
  ensurePrng();
  const nonce = nacl.randomBytes(NONCE_LENGTH);
  return bundle(nonce, secretboxSeal(toUint8(data), nonce, sharedKey));
}

/** Big-endian 64-bit counter in the last 8 bytes of a 24-byte nonce (session keys, below). */
export function counterNonce(counter: number): Uint8Array {
  return writeCounterNonce(new Uint8Array(NONCE_LENGTH), counter);
}

function writeCounterNonce(nonce: Uint8Array, counter: number): Uint8Array {
  nonce.fill(0);
  let value = counter;
  for (let i = NONCE_LENGTH - 1; i >= NONCE_LENGTH - 8 && value > 0; i -= 1) {
    nonce[i] = value % 256;
    value = Math.floor(value / 256);
  }
  return nonce;
}

/**
 * Seals with a session key under the sender's next counter: `[nonce (24)] [ciphertext...]`, the
 * same bundle as `encrypt`, so the wire format is unchanged. Each direction has its own key, so
 * a counter never repeats under one key.
 */
export function encryptWithCounter(
  key: Uint8Array,
  counter: number,
  data: ArrayBuffer,
): ArrayBuffer {
  const nonce = writeCounterNonce(scratchNonce, counter);
  return bundle(nonce, secretboxSeal(new Uint8Array(data), nonce, key));
}

/**
 * Opens a session-key bundle only when its nonce is exactly the counter the receiver expects:
 * a replayed, dropped, reordered or reflected frame fails (SECURITY.md › Session keys).
 */
export function decryptWithCounter(
  key: Uint8Array,
  counter: number,
  data: ArrayBuffer,
): ArrayBuffer {
  return toArrayBuffer(openWithCounter(key, counter, data));
}

/** `decryptWithCounter` as bytes, without copying them into an ArrayBuffer of their own. */
export function openWithCounter(key: Uint8Array, counter: number, data: ArrayBuffer): Uint8Array {
  const bytes = new Uint8Array(data);
  if (bytes.byteLength < NONCE_LENGTH) throw new Error("Ciphertext bundle too short");
  const nonce = writeCounterNonce(scratchNonce, counter);
  for (let i = 0; i < NONCE_LENGTH; i += 1) {
    if (bytes[i] !== nonce[i]) throw new Error("Out-of-order or replayed frame");
  }
  const opened = secretboxOpen(bytes.subarray(NONCE_LENGTH), nonce, key);
  if (!opened) throw new Error("Decryption failed");
  return opened;
}

/** The raw X25519 result, refused when it is all zeros (a low-order peer key). */
function scalarMultChecked(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array {
  const shared = nacl.scalarMult(secretKey, publicKey);
  if (nacl.verify(shared, ZERO_X25519_SHARED_RESULT)) throw new Error("Invalid peer public key");
  return shared;
}

const SESSION_KEYS_INFO = "shuriken/relay/session-keys/v1";

/**
 * Session keys (Noise NK's shape): the client's ephemeral key meets the daemon's static key (es,
 * which only the real daemon can compute) and the daemon's ephemeral key (ee, which gives forward
 * secrecy: once both ephemeral keys are gone, a stolen static key opens nothing recorded). One key
 * per direction, so a frame reflected back to its sender never opens.
 */
export function deriveSessionKeys(input: {
  role: "client" | "daemon";
  ourEphemeral: KeyPair;
  /** The daemon's static key pair (daemon side) or its static public key (client side). */
  daemonStatic: KeyPair | Uint8Array;
  peerEphemeralPublicKey: Uint8Array;
  clientEphemeralPublicKey: Uint8Array;
  daemonEphemeralPublicKey: Uint8Array;
}): { sendKey: Uint8Array; receiveKey: Uint8Array } {
  const daemonStaticPublic =
    input.daemonStatic instanceof Uint8Array ? input.daemonStatic : input.daemonStatic.publicKey;
  const es =
    input.role === "client"
      ? scalarMultChecked(input.ourEphemeral.secretKey, daemonStaticPublic)
      : scalarMultChecked((input.daemonStatic as KeyPair).secretKey, input.peerEphemeralPublicKey);
  const ee = scalarMultChecked(input.ourEphemeral.secretKey, input.peerEphemeralPublicKey);
  const salt = concatBytes(
    input.clientEphemeralPublicKey,
    daemonStaticPublic,
    input.daemonEphemeralPublicKey,
  );
  const okm = hkdfSha512(concatBytes(es, ee), salt, utf8(SESSION_KEYS_INFO), 64);
  es.fill(0);
  ee.fill(0);
  const clientToDaemon = okm.slice(0, 32);
  const daemonToClient = okm.slice(32, 64);
  okm.fill(0);
  return input.role === "client"
    ? { sendKey: clientToDaemon, receiveKey: daemonToClient }
    : { sendKey: daemonToClient, receiveKey: clientToDaemon };
}

export function utf8(text: string): Uint8Array {
  return new TextEncoder().encode(text);
}

export function concatBytes(...parts: Uint8Array[]): Uint8Array {
  const out = new Uint8Array(parts.reduce((sum, part) => sum + part.byteLength, 0));
  let offset = 0;
  for (const part of parts) {
    out.set(part, offset);
    offset += part.byteLength;
  }
  return out;
}

const SHA512_BLOCK = 128;

/** HMAC-SHA-512 (RFC 2104) over tweetnacl's SHA-512, so every platform runs the same code. */
export function hmacSha512(key: Uint8Array, message: Uint8Array): Uint8Array {
  const block = new Uint8Array(SHA512_BLOCK);
  block.set(key.byteLength > SHA512_BLOCK ? nacl.hash(key) : key);
  const inner = new Uint8Array(SHA512_BLOCK);
  const outer = new Uint8Array(SHA512_BLOCK);
  for (let i = 0; i < SHA512_BLOCK; i += 1) {
    inner[i] = block[i] ^ 0x36;
    outer[i] = block[i] ^ 0x5c;
  }
  return nacl.hash(concatBytes(outer, nacl.hash(concatBytes(inner, message))));
}

/** HKDF-SHA-512 (RFC 5869) for at most one block (64 bytes), which is all Shuriken asks for. */
export function hkdfSha512(
  ikm: Uint8Array,
  salt: Uint8Array,
  info: Uint8Array,
  length: number,
): Uint8Array {
  if (length < 1 || length > 64) throw new Error("hkdfSha512 gives 1 to 64 bytes");
  const prk = hmacSha512(salt.byteLength > 0 ? salt : new Uint8Array(64), ikm);
  const okm = hmacSha512(prk, concatBytes(info, new Uint8Array([1])));
  prk.fill(0);
  return okm.slice(0, length);
}

export function decrypt(sharedKey: SharedKey, data: ArrayBuffer): ArrayBuffer {
  const bytes = new Uint8Array(data);
  if (bytes.byteLength < NONCE_LENGTH) {
    throw new Error("Ciphertext bundle too short");
  }

  const opened = secretboxOpen(
    bytes.subarray(NONCE_LENGTH),
    bytes.subarray(0, NONCE_LENGTH),
    sharedKey,
  );
  if (!opened) {
    throw new Error("Decryption failed");
  }

  return toArrayBuffer(opened);
}

import { deriveAuthKey } from "@shuriken/client";
import { base64ToBytes, bytesToBase64, utf8Decode, utf8Encode } from "./base64";
import type { LegacyKeyParams, VaultInfo } from "./cloud-api";
import type { VaultCryptoBackend } from "./vault-crypto-backend-types";

// Client half of the vault key scheme in docs/cloud.md:
//   KEK = PBKDF2-SHA256(password, vault.salt, vault.iterations, 256 bits)
//   wrappedKey = base64(iv[12] || AES-GCM(KEK, iv, vaultKey[32]) [48])   — 60 bytes
//   item: ciphertext = base64(AES-GCM(vaultKey, iv, JSON)), iv = base64(12 random bytes)

/**
 * Round 36 S3: the KEK's rounds for every new wrap (OWASP's PBKDF2-SHA256 figure, Bitwarden's
 * default). An account still on 310,000 moves the next time its app holds the password.
 */
export const VAULT_KDF_ITERATIONS_NEXT = 600_000;
/**
 * Round 36 S3: the fewest rounds a device derives an auth key with — every account has had at
 * least this many since the vault began. The cloud names the rounds, so a hostile one could ask
 * for a handful and brute-force the password back from the auth key it is sent.
 */
export const VAULT_KDF_ITERATIONS_FLOOR = 310_000;

const IV_BYTES = 12;
const VAULT_KEY_BYTES = 32;
const WRAPPED_KEY_BYTES = IV_BYTES + VAULT_KEY_BYTES + 16;

export class WrongPasswordError extends Error {
  constructor() {
    super("That password does not open this account's vault");
    this.name = "WrongPasswordError";
  }
}

export class VaultItemDecryptError extends Error {
  constructor(id: string) {
    super(`Vault item ${id} could not be decrypted with this account's vault key`);
    this.name = "VaultItemDecryptError";
  }
}

async function deriveKek(
  backend: VaultCryptoBackend,
  password: string,
  vault: VaultInfo,
): Promise<Uint8Array> {
  return backend.deriveKek(password, base64ToBytes(vault.salt), vault.iterations);
}

export async function unwrapVaultKeyWithKek(
  backend: VaultCryptoBackend,
  kek: Uint8Array,
  wrappedKey: string,
): Promise<Uint8Array> {
  const wrapped = base64ToBytes(wrappedKey);
  if (wrapped.length !== WRAPPED_KEY_BYTES) throw new WrongPasswordError();
  try {
    return await backend.decrypt(kek, wrapped.subarray(0, IV_BYTES), wrapped.subarray(IV_BYTES));
  } catch {
    throw new WrongPasswordError();
  }
}

/** The account's vault key, or null while the account has none yet (before the first change). */
export async function unwrapVaultKey(
  backend: VaultCryptoBackend,
  password: string,
  vault: VaultInfo,
): Promise<Uint8Array | null> {
  if (!vault.wrappedKey) return null;
  return unwrapVaultKeyWithKek(
    backend,
    await deriveKek(backend, password, vault),
    vault.wrappedKey,
  );
}

export async function wrapVaultKey(
  backend: VaultCryptoBackend,
  password: string,
  vault: VaultInfo,
  vaultKey: Uint8Array,
): Promise<string> {
  const kek = await deriveKek(backend, password, vault);
  const iv = backend.randomBytes(IV_BYTES);
  const sealed = await backend.encrypt(kek, iv, vaultKey);
  const out = new Uint8Array(IV_BYTES + sealed.length);
  out.set(iv);
  out.set(sealed, IV_BYTES);
  return bytesToBase64(out);
}

/**
 * The `wrappedVaultKey` for a password change: the existing vault key re-wrapped under the new
 * password (items are not re-encrypted), or a fresh key at the forced first change when the
 * account has none. Returns the vault key too, so the device can keep it.
 */
export async function rewrapVaultKey(
  backend: VaultCryptoBackend,
  vault: VaultInfo,
  currentPassword: string,
  newPassword: string,
): Promise<{ wrappedVaultKey: string; vaultKey: Uint8Array }> {
  const vaultKey =
    (await unwrapVaultKey(backend, currentPassword, vault)) ?? backend.randomBytes(VAULT_KEY_BYTES);
  return { wrappedVaultKey: await wrapVaultKey(backend, newPassword, vault, vaultKey), vaultKey };
}

/** What a password gives under a vault's salt and rounds: the KEK, and the auth key from it. */
export interface PasswordSecrets {
  kek: Uint8Array;
  /** Sent to the cloud instead of the password (round 36 S3). */
  authKey: string;
  salt: string;
  iterations: number;
}

export async function passwordSecrets(
  backend: VaultCryptoBackend,
  password: string,
  params: { salt: string; iterations: number },
): Promise<PasswordSecrets> {
  const kek = await backend.deriveKek(password, base64ToBytes(params.salt), params.iterations);
  return { kek, authKey: deriveAuthKey(kek), salt: params.salt, iterations: params.iterations };
}

/** Round 36 S3: the fewest rounds a password hash has ever had (the cloud's PBKDF2 ceiling). */
export const LEGACY_KEY_ITERATIONS_FLOOR = 100_000;
/**
 * Round 36 S3 (adversarial verify): the most rounds a password hash can have — the Worker's
 * WebCrypto refuses PBKDF2 above 100,000, so every hash it (or seed-owner) made has exactly that.
 * The legacy key is the same PBKDF2 as the KEK, whose rounds are never fewer than 310,000: a cloud
 * naming the vault's own salt and rounds as the hash's would otherwise be sent the KEK itself.
 */
export const LEGACY_KEY_ITERATIONS_CEILING = 100_000;
const LEGACY_SALT_BYTES = 16;

export class LegacyParamsError extends Error {
  constructor() {
    super("The cloud named password-hash parameters weaker than any account has had");
    this.name = "LegacyParamsError";
  }
}

/**
 * Round 36 S3: what an account with no auth key yet signs in with instead of the password — the
 * PBKDF2-SHA256 output (256 bits) of the password under its stored hash's salt and rounds, the
 * value the cloud already holds. A cloud naming fewer rounds or a short salt is refused: the
 * output would brute-force back to the password. More rounds than any hash has are refused too:
 * at the KEK's rounds and salt the output would be the KEK.
 */
export async function legacyKey(
  backend: VaultCryptoBackend,
  password: string,
  params: LegacyKeyParams | undefined,
  floor: number = LEGACY_KEY_ITERATIONS_FLOOR,
): Promise<string> {
  if (!params || !Number.isInteger(params.iterations)) throw new LegacyParamsError();
  if (params.iterations < floor) throw new LegacyParamsError();
  if (params.iterations > LEGACY_KEY_ITERATIONS_CEILING) throw new LegacyParamsError();
  let salt: Uint8Array;
  try {
    salt = base64ToBytes(params.salt);
  } catch {
    throw new LegacyParamsError();
  }
  if (salt.length !== LEGACY_SALT_BYTES) throw new LegacyParamsError();
  return bytesToBase64(await backend.deriveKek(password, salt, params.iterations));
}

/**
 * Round 60 #34: what the cloud hands out as a one-time password (admission, the owner's reset,
 * the waitlist page's claim; cloud lib/crypto.ts `newOneTimePassword`): 16 characters from 55
 * with no look-alikes, about 92 random bits.
 */
const ONE_TIME_PASSWORD = /^[abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789]{16}$/;

/**
 * Round 60 #34: whether `password` has a one-time password's shape. A device that moved an account
 * to an auth key refuses to send any legacy key for it again (a cloud asking is fishing for the
 * password), except one of these: after the owner's reset the cloud asks for exactly that, and a
 * legacy key of 92 random bits brute-forces back to nothing.
 */
export function isOneTimePasswordShape(password: string): boolean {
  return ONE_TIME_PASSWORD.test(password);
}

export async function wrapVaultKeyWithKek(
  backend: VaultCryptoBackend,
  kek: Uint8Array,
  vaultKey: Uint8Array,
): Promise<string> {
  const iv = backend.randomBytes(IV_BYTES);
  const sealed = await backend.encrypt(kek, iv, vaultKey);
  const out = new Uint8Array(IV_BYTES + sealed.length);
  out.set(iv);
  out.set(sealed, IV_BYTES);
  return bytesToBase64(out);
}

/**
 * Round 36 S3: a password change (or an account's first auth key) as the cloud takes it — the
 * current secret (the auth key, or the legacy key while the account has none), the new auth key and
 * the vault key wrapped under the new KEK at the new rounds. The new password never leaves here.
 *
 * Round 59 hotfix: `currentPassword` null is the forced first change after the one-time password
 * was forgotten here (an app restart, a restored session): no current secret is sent — the
 * pending session is the proof — and the vault starts with a new key (an admitted or reset
 * account has none to open).
 */
/** The current secret a change sends: the legacy key, else the auth key, else none (forced). */
function currentProof(
  currentLegacyKey: string | null,
  currentAuthKey: string | null,
): { currentLegacyKey: string } | { currentAuthKey: string } | null {
  if (currentLegacyKey !== null) return { currentLegacyKey };
  return currentAuthKey !== null ? { currentAuthKey } : null;
}

/**
 * Audit pass 2 M16: the current password's proof alone (as a change sends it), for the changes
 * that ask for the password without changing it: turning two-factor sign-in on or off.
 */
export async function passwordProof(
  backend: VaultCryptoBackend,
  vault: VaultInfo,
  password: string,
  iterations: number = VAULT_KDF_ITERATIONS_NEXT,
): Promise<{ currentLegacyKey: string } | { currentAuthKey: string }> {
  if (vault.scheme === "password") {
    return {
      currentLegacyKey: await legacyKey(
        backend,
        password,
        vault.legacy,
        Math.min(LEGACY_KEY_ITERATIONS_FLOOR, iterations),
      ),
    };
  }
  return { currentAuthKey: (await passwordSecrets(backend, password, vault)).authKey };
}

export async function passwordChange(
  backend: VaultCryptoBackend,
  vault: VaultInfo,
  currentPassword: string | null,
  newPassword: string,
  iterations: number = VAULT_KDF_ITERATIONS_NEXT,
): Promise<{
  request: {
    currentLegacyKey?: string;
    currentAuthKey?: string;
    newAuthKey: string;
    wrappedVaultKey: string;
    iterations: number;
  };
  vaultKey: Uint8Array;
  /** The KEKs of the current password (null without one) and the new one, for the caller only. */
  keks: { current: Uint8Array | null; next: Uint8Array };
}> {
  // A weak legacy hash is refused before anything else is derived. Tests derive with a handful of
  // rounds; the floor never drops below theirs.
  const currentLegacyKey =
    currentPassword !== null && vault.scheme === "password"
      ? await legacyKey(
          backend,
          currentPassword,
          vault.legacy,
          Math.min(LEGACY_KEY_ITERATIONS_FLOOR, iterations),
        )
      : null;
  const current =
    currentPassword === null ? null : await passwordSecrets(backend, currentPassword, vault);
  const vaultKey =
    vault.wrappedKey && current
      ? await unwrapVaultKeyWithKek(backend, current.kek, vault.wrappedKey)
      : backend.randomBytes(VAULT_KEY_BYTES);
  const next = await passwordSecrets(backend, newPassword, { salt: vault.salt, iterations });
  return {
    request: {
      ...currentProof(currentLegacyKey, current?.authKey ?? null),
      newAuthKey: next.authKey,
      wrappedVaultKey: await wrapVaultKeyWithKek(backend, next.kek, vaultKey),
      iterations,
    },
    vaultKey,
    keks: { current: current?.kek ?? null, next: next.kek },
  };
}

export async function encryptVaultValue(
  backend: VaultCryptoBackend,
  vaultKey: Uint8Array,
  value: unknown,
): Promise<{ ciphertext: string; iv: string }> {
  const iv = backend.randomBytes(IV_BYTES);
  const sealed = await backend.encrypt(vaultKey, iv, utf8Encode(JSON.stringify(value)));
  return { ciphertext: bytesToBase64(sealed), iv: bytesToBase64(iv) };
}

export async function decryptVaultValue(
  backend: VaultCryptoBackend,
  vaultKey: Uint8Array,
  item: { id: string; ciphertext: string; iv: string },
): Promise<unknown> {
  let opened: Uint8Array;
  try {
    opened = await backend.decrypt(
      vaultKey,
      base64ToBytes(item.iv),
      base64ToBytes(item.ciphertext),
    );
  } catch {
    throw new VaultItemDecryptError(item.id);
  }
  return JSON.parse(utf8Decode(opened));
}

export function encodeVaultKey(vaultKey: Uint8Array): string {
  return bytesToBase64(vaultKey);
}

export function decodeVaultKey(stored: string): Uint8Array | null {
  try {
    const bytes = base64ToBytes(stored);
    return bytes.length === VAULT_KEY_BYTES ? bytes : null;
  } catch {
    return null;
  }
}

import { utf8Encode } from "./base64";
import type { VaultCryptoBackend } from "./vault-crypto-backend-types";

// WebCrypto takes BufferSource; copying pins the ArrayBuffer type TypeScript wants.
const buffer = (bytes: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(bytes);

async function aesKey(raw: Uint8Array, usage: KeyUsage): Promise<CryptoKey> {
  return globalThis.crypto.subtle.importKey("raw", buffer(raw), "AES-GCM", false, [usage]);
}

/** Web and Electron: WebCrypto, the same code path the cloud site uses. */
export const webCryptoVaultBackend: VaultCryptoBackend = {
  async deriveKek(password, salt, iterations) {
    const subtle = globalThis.crypto.subtle;
    const material = await subtle.importKey("raw", buffer(utf8Encode(password)), "PBKDF2", false, [
      "deriveBits",
    ]);
    const bits = await subtle.deriveBits(
      { name: "PBKDF2", hash: "SHA-256", salt: buffer(salt), iterations },
      material,
      256,
    );
    return new Uint8Array(bits);
  },
  async encrypt(key, iv, plaintext) {
    const sealed = await globalThis.crypto.subtle.encrypt(
      { name: "AES-GCM", iv: buffer(iv) },
      await aesKey(key, "encrypt"),
      buffer(plaintext),
    );
    return new Uint8Array(sealed);
  },
  async decrypt(key, iv, ciphertext) {
    const opened = await globalThis.crypto.subtle.decrypt(
      { name: "AES-GCM", iv: buffer(iv) },
      await aesKey(key, "decrypt"),
      buffer(ciphertext),
    );
    return new Uint8Array(opened);
  },
  randomBytes(length) {
    const bytes = new Uint8Array(length);
    globalThis.crypto.getRandomValues(bytes);
    return bytes;
  },
};

import { gcm } from "@noble/ciphers/aes.js";
import { pbkdf2Async } from "@noble/hashes/pbkdf2.js";
import { sha256 } from "@noble/hashes/sha2.js";
import { base64ToBytes, bytesToBase64, utf8Encode } from "./base64";
import type { VaultCryptoBackend } from "./vault-crypto-backend-types";

function randomBytes(length: number): Uint8Array {
  const bytes = new Uint8Array(length);
  globalThis.crypto.getRandomValues(bytes);
  return bytes;
}

/** React Native: pure-JS primitives. `pbkdf2Async` yields between rounds so the UI keeps moving. */
export const nobleVaultCryptoBackend: VaultCryptoBackend = {
  deriveKek: (password, salt, iterations) =>
    pbkdf2Async(sha256, utf8Encode(password), salt, { c: iterations, dkLen: 32 }),
  encrypt: async (key, iv, plaintext) => gcm(key, iv).encrypt(plaintext),
  decrypt: async (key, iv, ciphertext) => gcm(key, iv).decrypt(ciphertext),
  randomBytes,
};

/** modules/shuriken-pbkdf2 (Android): PBKDF2-HMAC-SHA256 over base64 bytes, base64 out. */
export interface NativePbkdf2 {
  pbkdf2Sha256(password: string, salt: string, iterations: number, length: number): Promise<string>;
}

/**
 * The noble backend with the platform's PBKDF2 when the build has it. Hermes has no JIT: the
 * pure-JS KDF took about four minutes for the vault's 310,000 iterations on the Android emulator,
 * and sign-in, the password change and the vault unlock each waited that long. The password goes
 * over as its UTF-8 bytes, so the native side hashes exactly what WebCrypto and noble hash.
 */
export function withNativeKdf(
  backend: VaultCryptoBackend,
  native: NativePbkdf2 | null,
): VaultCryptoBackend {
  if (!native) return backend;
  return {
    ...backend,
    deriveKek: async (password, salt, iterations) =>
      base64ToBytes(
        await native.pbkdf2Sha256(
          bytesToBase64(utf8Encode(password)),
          bytesToBase64(salt),
          iterations,
          32,
        ),
      ),
  };
}

/** The bytes as a string of char codes 0–255: a Map key with no encoding work per byte. */
function latin1(bytes: Uint8Array): string {
  let out = "";
  for (let i = 0; i < bytes.length; i += 8192) {
    out += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + 8192)));
  }
  return out;
}

export interface DecryptMemoLimits {
  entries: number;
  /** Larger boxes (pictures) are opened every time. */
  maxCiphertextBytes: number;
}

const DECRYPT_MEMO_LIMITS: DecryptMemoLimits = { entries: 512, maxCiphertextBytes: 16 * 1024 };

/**
 * Round 40 T1: AES-GCM in JavaScript (noble) costs ~2–8 ms a box in Hermes, its GHASH tables
 * built per call, and the phone opened the same small boxes on every project switch (the
 * project's sealed record, its env for the hazard light, sealed settings, device names). A box
 * that opened once answers its plaintext again: the same key, IV and ciphertext can only hold
 * that plaintext, and a box that fails to open is never remembered. The memo is keyed by the key's
 * bytes, so a locked vault (no key) can read nothing from it.
 */
export function withDecryptMemo(
  backend: VaultCryptoBackend,
  limits: DecryptMemoLimits = DECRYPT_MEMO_LIMITS,
): VaultCryptoBackend {
  const opened = new Map<string, Uint8Array>();
  return {
    ...backend,
    decrypt: async (key, iv, ciphertext) => {
      if (ciphertext.length > limits.maxCiphertextBytes)
        return backend.decrypt(key, iv, ciphertext);
      const id = `${latin1(key)}\u0000${latin1(iv)}\u0000${latin1(ciphertext)}`;
      const known = opened.get(id);
      if (known) {
        // Most recently used last, so the oldest goes first.
        opened.delete(id);
        opened.set(id, known);
        return known.slice();
      }
      const plaintext = await backend.decrypt(key, iv, ciphertext);
      opened.set(id, plaintext.slice());
      if (opened.size > limits.entries) opened.delete(opened.keys().next().value as string);
      return plaintext;
    },
  };
}

import { CloudApiError, type CloudApi, type VaultItem } from "./cloud-api";
import { decryptVaultValue, encryptVaultValue, VaultItemDecryptError } from "./vault-crypto";
import type { VaultCryptoBackend } from "./vault-crypto-backend-types";
import { memoryVaultRevisions, type VaultRevisions } from "./vault-revisions";

// The account vault (docs/cloud.md › Vault): ciphertext in the cloud, opened on the device with
// the vault key. The daemon-side accounts module syncs through this client (AccountVaultSync).

export interface VaultEntry<T = unknown> {
  id: string;
  kind: string;
  label: string;
  version: number;
  value: T;
  updatedAt: string;
}

/** An item that is there but this device cannot open (sealed under another key, or damaged). */
export interface UnopenedVaultEntry {
  id: string;
  kind: string;
  label: string;
  version: number;
  updatedAt: string;
  unopened: true;
}

/** A stale or duplicate write. `current` is the stored item (null when it was deleted). */
export class VaultConflictError extends Error {
  readonly current: VaultEntry | null;

  constructor(id: string, current: VaultEntry | null) {
    super(`Vault item ${id} changed on another device`);
    this.name = "VaultConflictError";
    this.current = current;
  }
}

export class VaultLockedError extends Error {
  constructor() {
    super("The vault is locked on this device; unlock it with your password");
    this.name = "VaultLockedError";
  }
}

/**
 * An item's sealed value that this device will not open: older than one it already opened or
 * wrote, or with no revision once every item of the account was sealed with one (audit VAULT-11).
 * A VaultItemDecryptError, so every reader treats it as a value it cannot open (sign in again),
 * never as a removed one.
 */
export class VaultItemRollbackError extends VaultItemDecryptError {
  constructor(id: string) {
    super(id);
    this.message = `Vault item ${id} is older than one this device already has`;
    this.name = "VaultItemRollbackError";
  }
}

/**
 * Security audit (v5.1.0): what an item's ciphertext opens to — its value with the item's id and
 * kind, so whoever writes /api/vault/items cannot move one item's sealed value into another slot
 * or kind. Audit VAULT-11: and a revision, higher at every write (above the highest the writer
 * has seen and no lower than its clock, so an item removed and added again from a device that
 * never saw it still goes up). Each device keeps the highest revision it opened or wrote per item
 * (vault-revisions.ts) and refuses a lower one: the cloud cannot serve back a value the person
 * replaced. A value with no revision (the value alone, or `ITEM_ENVELOPE: 1`, sealed by an app
 * from before) opens until this device's keeper pass (bindLegacyItems) has sealed every item
 * again with one; from then on it is refused (docs/security.md › Moving to sealed data).
 */
const ITEM_ENVELOPE = "shuriken.vault-item";
const ENVELOPE_REVISED = 2;

/** An item's value as it is sealed (also what a rotation seals for an item it rewrites). */
export function bindVaultItem(
  id: string,
  kind: string,
  revision: number,
  value: unknown,
): Record<string, unknown> {
  return { [ITEM_ENVELOPE]: ENVELOPE_REVISED, id, kind, revision, value };
}

/** An opened item's value, and its revision (null: sealed before revisions). */
interface Unbound {
  value: unknown;
  revision: number | null;
}

/** The value of an opened item, checked against the slot it came from. */
function unbindItem(item: VaultItem, opened: unknown): Unbound {
  if (typeof opened !== "object" || opened === null || !(ITEM_ENVELOPE in opened)) {
    return { value: opened, revision: null };
  }
  const envelope = opened as Record<string, unknown> & {
    id?: unknown;
    kind?: unknown;
    revision?: unknown;
    value?: unknown;
  };
  if (envelope.id !== item.id || envelope.kind !== item.kind) {
    throw new VaultItemDecryptError(item.id);
  }
  if (envelope[ITEM_ENVELOPE] === 1) return { value: envelope.value, revision: null };
  const revision = envelope.revision;
  if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 1) {
    throw new VaultItemDecryptError(item.id);
  }
  return { value: envelope.value, revision };
}

export interface VaultClientDeps {
  api: () => CloudApi;
  crypto: VaultCryptoBackend;
  /** The unwrapped vault key held on this device, or null while locked. */
  vaultKey: () => Uint8Array | null;
  /**
   * Asks the user to unlock the vault (the web app keeps the key only for the tab's session).
   * Resolves true once it is unlocked. Without it a locked vault throws VaultLockedError.
   */
  requestUnlock?: () => Promise<boolean>;
  /**
   * Audit VAULT-11: the highest revision this device has seen per item (kept across restarts by
   * the account service). Without it, a record for this client's life only.
   */
  revisions?: VaultRevisions;
  /** The clock a revision is never lower than (ms). */
  now?: () => number;
}

export class VaultClient {
  private readonly revisions: VaultRevisions;

  constructor(private readonly deps: VaultClientDeps) {
    this.revisions = deps.revisions ?? memoryVaultRevisions();
  }

  isUnlocked(): boolean {
    return this.deps.vaultKey() !== null;
  }

  /** True once the vault is open, prompting for the password when this device can. */
  async ensureUnlocked(): Promise<boolean> {
    if (this.isUnlocked()) return true;
    return (await this.deps.requestUnlock?.()) === true && this.isUnlocked();
  }

  async list<T = unknown>(filter?: { kind?: string }): Promise<VaultEntry<T>[]> {
    const items = await this.deps.api().listVaultItems();
    const wanted = filter?.kind ? items.filter((item) => item.kind === filter.kind) : items;
    if (wanted.length === 0) return [];
    const key = await this.key();
    return Promise.all(wanted.map((item) => this.open<T>(item, key)));
  }

  /**
   * Round 42 W2 verify: list() fails whole on one item it cannot open, which stopped every
   * source's sync. A sync that must tell "gone" from "there" lists here: an item it cannot open is
   * listed as such, never left out (left out, it reads as removed elsewhere).
   */
  async listSettled<T = unknown>(filter?: {
    kind?: string;
  }): Promise<Array<VaultEntry<T> | UnopenedVaultEntry>> {
    const items = await this.deps.api().listVaultItems();
    const wanted = filter?.kind ? items.filter((item) => item.kind === filter.kind) : items;
    if (wanted.length === 0) return [];
    const key = await this.key();
    return Promise.all(
      wanted.map(async (item): Promise<VaultEntry<T> | UnopenedVaultEntry> => {
        try {
          return await this.open<T>(item, key);
        } catch (error) {
          if (!(error instanceof VaultItemDecryptError)) throw error;
          const { id, kind, label, version, updatedAt } = item;
          return { id, kind, label, version, updatedAt, unopened: true };
        }
      }),
    );
  }

  async get<T = unknown>(id: string): Promise<VaultEntry<T> | null> {
    const item = await this.deps.api().getVaultItem(id);
    return item ? this.open<T>(item, await this.key()) : null;
  }

  /**
   * Writes `value` under `id`. `version` is the one read (0 creates). A concurrent write answers
   * VaultConflictError carrying the stored item: merge and retry with its version, or use update().
   */
  async put<T>(
    id: string,
    input: { kind: string; label: string; value: T; version: number },
  ): Promise<VaultEntry<T>> {
    const key = await this.key();
    const revision = Math.max(
      (await this.revisions.seen(id)) + 1,
      Math.floor((this.deps.now ?? Date.now)()),
    );
    const sealed = await encryptVaultValue(
      this.deps.crypto,
      key,
      bindVaultItem(id, input.kind, revision, input.value),
    );
    try {
      const stored = await this.deps.api().putVaultItem(id, {
        kind: input.kind,
        label: input.label,
        version: input.version,
        ...sealed,
      });
      await this.revisions.raise(id, revision);
      return this.toEntry(stored, input.value);
    } catch (error) {
      throw await this.conflictOr(id, error);
    }
  }

  async delete(id: string, version: number): Promise<void> {
    try {
      await this.deps.api().deleteVaultItem(id, version);
    } catch (error) {
      throw await this.conflictOr(id, error);
    }
  }

  /**
   * Read-modify-write that retries on conflicts: `mutate` gets the current value (null when
   * absent) and returns the next one. Used for token refreshes written back under a Hub lease.
   */
  async update<T>(
    id: string,
    input: { kind: string; label: string },
    mutate: (current: VaultEntry<T> | null) => T,
    options: { attempts?: number } = {},
  ): Promise<VaultEntry<T>> {
    let current = await this.get<T>(id);
    const attempts = options.attempts ?? 3;
    for (let attempt = 1; ; attempt += 1) {
      try {
        return await this.put(id, {
          ...input,
          value: mutate(current),
          version: current?.version ?? 0,
        });
      } catch (error) {
        if (!(error instanceof VaultConflictError) || attempt >= attempts) throw error;
        current = error.current as VaultEntry<T> | null;
      }
    }
  }

  private async key(): Promise<Uint8Array> {
    if (!(await this.ensureUnlocked())) throw new VaultLockedError();
    const key = this.deps.vaultKey();
    if (!key) throw new VaultLockedError();
    return key;
  }

  /**
   * Audit VAULT-11: the keeper pass. Every item this device opens that carries no revision is
   * sealed again in the bound form, with one (a write at its version: a device that wrote it
   * meanwhile wins, and the pass runs again). Once a pass found every item it can open bound,
   * this device refuses a value with no revision. An empty vault closes nothing: an app from
   * before may still add the first item (there is nothing to serve back yet). Idempotent; true
   * when no item is left to bind.
   */
  async bindLegacyItems(): Promise<boolean> {
    if (await this.revisions.legacyClosed()) return true;
    const items = await this.deps.api().listVaultItems();
    let done = true;
    if (items.length > 0) {
      const key = await this.key();
      for (const item of items) {
        let opened: Unbound;
        try {
          opened = unbindItem(item, await decryptVaultValue(this.deps.crypto, key, item));
        } catch (error) {
          // Sealed with a key this device never had, or damaged: nothing to bind here.
          if (error instanceof VaultItemDecryptError) continue;
          throw error;
        }
        if (opened.revision !== null) continue;
        // One this device saw with a revision is a value served back, not one to keep.
        if ((await this.revisions.seen(item.id)) > 0) continue;
        try {
          await this.put(item.id, {
            kind: item.kind,
            label: item.label,
            value: opened.value,
            version: item.version,
          });
        } catch (error) {
          if (!(error instanceof VaultConflictError)) throw error;
          done = false;
        }
      }
    }
    if (done && items.length > 0) await this.revisions.closeLegacy();
    return done;
  }

  private async open<T>(item: VaultItem, key: Uint8Array): Promise<VaultEntry<T>> {
    const opened = unbindItem(item, await decryptVaultValue(this.deps.crypto, key, item));
    const seen = await this.revisions.seen(item.id);
    if (opened.revision === null) {
      if (seen > 0 || (await this.revisions.legacyClosed())) {
        throw new VaultItemRollbackError(item.id);
      }
    } else {
      if (opened.revision < seen) throw new VaultItemRollbackError(item.id);
      await this.revisions.raise(item.id, opened.revision);
    }
    return this.toEntry(item, opened.value as T);
  }

  private toEntry<T>(item: VaultItem, value: T): VaultEntry<T> {
    return {
      id: item.id,
      kind: item.kind,
      label: item.label,
      version: item.version,
      value,
      updatedAt: item.updatedAt,
    };
  }

  private async conflictOr(id: string, error: unknown): Promise<unknown> {
    if (!(error instanceof CloudApiError) || error.code !== "version_conflict") return error;
    const raw = error.body?.current as VaultItem | null | undefined;
    return new VaultConflictError(id, raw ? await this.open(raw, await this.key()) : null);
  }
}

import type { AccountSecureStore } from "./account-secure-store";

// Audit VAULT-11 (docs/security.md › Moving to sealed data): what this device remembers about the
// account's vault items, so a cloud that serves an older ciphertext of an item is caught. An item's
// sealed value carries a revision (vault-client.ts bindItem); the device keeps the highest one it
// opened or wrote per item, and whether it has found every item of the account sealed that way
// (after that, a value with no revision is refused). It names item ids and numbers only.

/** JSON `{ user, items: { [itemId]: revision }, legacyClosed }`, for one account at a time. */
export const ACCOUNT_VAULT_REVISIONS_KEY = "shuriken.vault-revisions";

export interface VaultRevisions {
  /** The highest revision of `id` this device opened or wrote; 0 for none. */
  seen(id: string): Promise<number>;
  /** Keeps `revision` for `id` when it is higher than the one kept. */
  raise(id: string, revision: number): Promise<void>;
  /** True once this device found every item of the account sealed with a revision. */
  legacyClosed(): Promise<boolean>;
  closeLegacy(): Promise<void>;
}

interface RevisionState {
  user: string;
  items: Record<string, number>;
  legacyClosed: boolean;
}

function parseState(raw: string | null, user: string): RevisionState {
  const fresh: RevisionState = { user, items: {}, legacyClosed: false };
  if (!raw) return fresh;
  try {
    const parsed = JSON.parse(raw) as Partial<RevisionState> | null;
    if (!parsed || parsed.user !== user) return fresh;
    const items: Record<string, number> = {};
    for (const [id, revision] of Object.entries(parsed.items ?? {})) {
      if (typeof revision === "number" && Number.isSafeInteger(revision) && revision > 0) {
        items[id] = revision;
      }
    }
    return { user, items, legacyClosed: parsed.legacyClosed === true };
  } catch {
    // A damaged record is no record: nothing is refused for it, the next write replaces it.
    return fresh;
  }
}

/**
 * The record kept in `store` for the signed-in account (`userId`). A record of another account
 * is not read, and replaced on the first write. A store that cannot write keeps the record for
 * this run only: it never refuses more than it would with the record kept.
 */
export function storedVaultRevisions(
  store: Pick<AccountSecureStore, "get" | "set">,
  userId: () => string | null,
): VaultRevisions {
  let loaded: { user: string; state: Promise<RevisionState> } | null = null;
  let writes: Promise<void> = Promise.resolve();
  const state = (): Promise<RevisionState> => {
    const user = userId() ?? "";
    if (loaded?.user !== user) {
      loaded = {
        user,
        state: store
          .get(ACCOUNT_VAULT_REVISIONS_KEY)
          .catch(() => null)
          .then((raw) => parseState(raw, user)),
      };
    }
    return loaded.state;
  };
  const persist = (current: RevisionState): Promise<void> => {
    if (!current.user) return writes;
    const text = JSON.stringify(current);
    writes = writes.then(() => store.set(ACCOUNT_VAULT_REVISIONS_KEY, text)).catch(() => undefined);
    return writes;
  };
  return {
    seen: async (id) => (await state()).items[id] ?? 0,
    raise: async (id, revision) => {
      const current = await state();
      if (!Number.isSafeInteger(revision) || revision <= (current.items[id] ?? 0)) return;
      current.items[id] = revision;
      await persist(current);
    },
    legacyClosed: async () => (await state()).legacyClosed,
    closeLegacy: async () => {
      const current = await state();
      if (current.legacyClosed) return;
      current.legacyClosed = true;
      await persist(current);
    },
  };
}

/** A record for this run only (a client nobody gave a store). */
export function memoryVaultRevisions(): VaultRevisions {
  const values = new Map<string, string>();
  return storedVaultRevisions(
    {
      get: async (key) => values.get(key) ?? null,
      set: async (key, value) => {
        values.set(key, value);
      },
    },
    () => "this-run",
  );
}

/**
 * The account key: an Ed25519 key pair every device of an account derives from the vault key,
 * which the cloud never holds (docs/cloud.md › Vault key scheme). It is what lets one device
 * trust another's keys without trusting the cloud that carries them (SECURITY.md › Account key):
 *
 * - **Device keys.** A worker's daemon key and a phone's or browser's push key are signed with it.
 *   A client checks the signature before it uses a key the cloud handed it, so a cloud that swaps
 *   in its own key is refused instead of reading the traffic.
 * - **Relay clients.** A client signs each relay handshake with it, so a daemon admits only
 *   devices that hold the vault key, not anyone the cloud lets onto the relay.
 *
 * Deriving it (rather than storing a second secret) means it rotates with the vault key and needs
 * no new backup. The daemon keeps only the public half.
 */

import nacl from "tweetnacl";
import { fromByteArray, toByteArray } from "base64-js";
import { concatBytes, hkdfSha512, utf8 } from "./crypto.js";

export interface AccountKeyPair {
  /** Ed25519 public key, 32 bytes. */
  publicKey: Uint8Array;
  /** Ed25519 secret key (seed and public key), 64 bytes. */
  secretKey: Uint8Array;
}

const ACCOUNT_KEY_INFO = "shuriken/account-key/v1";
const VAULT_KEY_BYTES = 32;

/** What a binding signature covers; one context per kind of key so one can never pass for another. */
export type DeviceKeyPurpose = "daemon" | "push" | "share" | "webpush";

const BINDING_CONTEXT: Record<DeviceKeyPurpose, string> = {
  daemon: "shuriken/device-key/daemon/v1",
  push: "shuriken/device-key/push/v1",
  /** Round 36 S3: the key a rotated vault key is sealed to (vault-rotation.ts). */
  share: "shuriken/device-key/share/v1",
  /**
   * Round 2 A12: a browser's Web Push subscription keys (`webPushKeyBinding`). A worker's daemon
   * seals a chat push to them (RFC 8291) only when this signature verifies, so a cloud that swaps
   * in its own P-256 key gets nothing it can read.
   */
  webpush: "shuriken/device-key/webpush/v1",
};

/**
 * Round 2 A12: what a browser signs for its push subscription (purpose "webpush"): the P-256 key
 * and the auth secret together (base64url has no "."), so neither can be swapped on its own.
 */
export function webPushKeyBinding(p256dh: string, auth: string): string {
  return `${p256dh}.${auth}`;
}
const RELAY_CLIENT_CONTEXT = "shuriken/relay-client/v1";
/** Audit RELAY-6: the proof with its signing time (`at`) in the signed message. */
const RELAY_CLIENT_TIMED_CONTEXT = "shuriken/relay-client/v2";

/**
 * Audit RELAY-6: how far a timed relay proof (account or guest) may be from the daemon's clock,
 * either way. A hello is signed afresh for every connection, so a real one is seconds old; the
 * window only covers clocks that are off. A recording older than this verifies nowhere, and the
 * daemon's replay memory (30 days, persisted) covers everything inside it.
 */
export const RELAY_PROOF_MAX_AGE_MS = 24 * 60 * 60_000;

/** True when a timed proof's `at` is a time inside the window around `now`. */
export function relayProofTimeLive(at: unknown, now: number): at is number {
  return (
    typeof at === "number" &&
    Number.isSafeInteger(at) &&
    at >= now - RELAY_PROOF_MAX_AGE_MS &&
    at <= now + RELAY_PROOF_MAX_AGE_MS
  );
}

/**
 * What signs for the account on a device: the key pair itself where the vault key is at hand, or
 * a key the platform keeps and will not hand out (a browser's non-extractable WebCrypto Ed25519
 * key in IndexedDB), whose `sign` is asynchronous. Ed25519 is deterministic, so both give the same
 * signature.
 */
export interface AccountSigner {
  publicKey: Uint8Array;
  sign(message: Uint8Array): Uint8Array | Promise<Uint8Array>;
}

/** The 32-byte Ed25519 seed of the account key; a platform key store imports it once. */
export function deriveAccountKeySeed(vaultKey: Uint8Array): Uint8Array {
  if (vaultKey.byteLength !== VAULT_KEY_BYTES) {
    throw new Error(`Vault key must be ${VAULT_KEY_BYTES} bytes`);
  }
  return hkdfSha512(vaultKey, new Uint8Array(0), utf8(ACCOUNT_KEY_INFO), 32);
}

export function deriveAccountKeyPair(vaultKey: Uint8Array): AccountKeyPair {
  const seed = deriveAccountKeySeed(vaultKey);
  const pair = nacl.sign.keyPair.fromSeed(seed);
  seed.fill(0);
  return { publicKey: pair.publicKey, secretKey: pair.secretKey };
}

const AUTH_KEY_INFO = "shuriken/auth-key/v1";
const KEK_BYTES = 32;

/**
 * Round 36 S3: what an app signs in with instead of the password (base64, 32 bytes): HKDF of the
 * vault KEK. The cloud stores only a hash of it; the KEK itself never leaves the device, and the
 * auth key does not give it back (docs/cloud.md › Vault key scheme).
 */
export function deriveAuthKey(kek: Uint8Array): string {
  if (kek.byteLength !== KEK_BYTES) throw new Error(`KEK must be ${KEK_BYTES} bytes`);
  const key = hkdfSha512(kek, new Uint8Array(0), utf8(AUTH_KEY_INFO), 32);
  const out = fromByteArray(key);
  key.fill(0);
  return out;
}

export function accountSigner(pair: AccountKeyPair): AccountSigner {
  return {
    publicKey: pair.publicKey,
    sign: (message) => nacl.sign.detached(message, pair.secretKey),
  };
}

export function exportAccountPublicKey(publicKey: Uint8Array): string {
  if (publicKey.byteLength !== nacl.sign.publicKeyLength) throw new Error("Invalid account key");
  return fromByteArray(publicKey);
}

/** The 32-byte account public key from base64, or null when it is not one. */
export function importAccountPublicKey(base64: string): Uint8Array | null {
  try {
    const bytes = toByteArray(base64);
    if (bytes.byteLength !== nacl.sign.publicKeyLength) return null;
    if (fromByteArray(bytes) !== base64) return null;
    return bytes;
  } catch {
    return null;
  }
}

/**
 * Short, readable form of an account key (or any key) for a person to compare across devices:
 * eight groups of four hex digits of its SHA-512.
 */
export function keyFingerprint(publicKeyB64: string): string {
  const digest = nacl.hash(utf8(publicKeyB64));
  const hex = Array.from(digest.subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0"));
  const groups: string[] = [];
  for (let i = 0; i < hex.length; i += 2) groups.push(`${hex[i]}${hex[i + 1]}`);
  return groups.join(" ");
}

function bindingMessage(purpose: DeviceKeyPurpose, deviceId: string, keyB64: string): Uint8Array {
  return utf8(`${BINDING_CONTEXT[purpose]}\n${deviceId}\n${keyB64}`);
}

/** Signs that `keyB64` is `deviceId`'s key for `purpose`. */
export function signDeviceKey(
  account: AccountKeyPair,
  purpose: DeviceKeyPurpose,
  deviceId: string,
  keyB64: string,
): string {
  return fromByteArray(
    nacl.sign.detached(bindingMessage(purpose, deviceId, keyB64), account.secretKey),
  );
}

/** `signDeviceKey` with any signer (a browser's stored key signs asynchronously). */
export async function signDeviceKeyWith(
  signer: AccountSigner,
  purpose: DeviceKeyPurpose,
  deviceId: string,
  keyB64: string,
): Promise<string> {
  return fromByteArray(await signer.sign(bindingMessage(purpose, deviceId, keyB64)));
}

function decodeSignature(signatureB64: string): Uint8Array | null {
  try {
    const bytes = toByteArray(signatureB64);
    return bytes.byteLength === nacl.sign.signatureLength ? bytes : null;
  } catch {
    return null;
  }
}

/** True only when `signatureB64` is the account's signature binding `keyB64` to `deviceId`. */
export function verifyDeviceKey(input: {
  accountPublicKey: Uint8Array;
  purpose: DeviceKeyPurpose;
  deviceId: string;
  keyB64: string;
  signatureB64: string | null | undefined;
}): boolean {
  if (!input.signatureB64) return false;
  const signature = decodeSignature(input.signatureB64);
  if (!signature) return false;
  return nacl.sign.detached.verify(
    bindingMessage(input.purpose, input.deviceId, input.keyB64),
    signature,
    input.accountPublicKey,
  );
}

function relayClientMessage(
  daemonPublicKey: Uint8Array,
  clientEphemeralPublicKey: Uint8Array,
  at?: number,
): Uint8Array {
  if (at === undefined) {
    return concatBytes(utf8(RELAY_CLIENT_CONTEXT), daemonPublicKey, clientEphemeralPublicKey);
  }
  return concatBytes(
    utf8(`${RELAY_CLIENT_TIMED_CONTEXT}\n${at}\n`),
    daemonPublicKey,
    clientEphemeralPublicKey,
  );
}

/** What a client puts in its `e2ee_hello` to prove it holds the account key. */
export interface RelayAccountProof {
  /** The account public key, base64. */
  key: string;
  /** Ed25519 over the context, the daemon's static key and this handshake's client key. */
  sig: string;
  /**
   * Audit RELAY-6: when it was signed (ms since the epoch), inside the signature (context v2).
   * Absent on a 5.0.0 app's proof and on the first hello to a daemon not yet known to read it.
   */
  at?: number;
}

/** `options.at`: sign the timed (v2) proof, for a daemon known to read it (RELAY-6). */
export async function signRelayClient(
  account: AccountSigner,
  daemonPublicKey: Uint8Array,
  clientEphemeralPublicKey: Uint8Array,
  options?: { at?: number },
): Promise<RelayAccountProof> {
  const at = options?.at;
  if (at !== undefined && !Number.isSafeInteger(at)) throw new Error("Not a proof time");
  return {
    key: exportAccountPublicKey(account.publicKey),
    sig: fromByteArray(
      await account.sign(relayClientMessage(daemonPublicKey, clientEphemeralPublicKey, at)),
    ),
    ...(at !== undefined ? { at } : {}),
  };
}

/**
 * The proven account key (base64), or null when the proof is missing or does not verify. A
 * timed proof (RELAY-6) verifies only inside RELAY_PROOF_MAX_AGE_MS of `options.now`.
 */
export function verifyRelayClient(
  proof: RelayAccountProof | undefined,
  daemonPublicKey: Uint8Array,
  clientEphemeralPublicKey: Uint8Array,
  options?: { now?: number },
): string | null {
  if (!proof) return null;
  const key = importAccountPublicKey(proof.key);
  const signature = decodeSignature(proof.sig);
  if (!key || !signature) return null;
  if (proof.at !== undefined && !relayProofTimeLive(proof.at, options?.now ?? Date.now())) {
    return null;
  }
  return nacl.sign.detached.verify(
    relayClientMessage(daemonPublicKey, clientEphemeralPublicKey, proof.at),
    signature,
    key,
  )
    ? proof.key
    : null;
}

/**
 * Round 36 S2: the documents key — a 32-byte key every device of an account derives from the vault
 * key (which the cloud never holds), for the few account documents a worker's daemon must read or
 * write without the vault key itself: the shared usage readings, the notification settings
 * (muted projects), the AI accounts' health (emails, labels). Apps hand it to their workers'
 * daemons (a desktop's own daemon with the worker session; a server through the relay, with the
 * vault sync), so a daemon opens these and nothing else the vault key seals (projects, pictures,
 * provider sign-ins stay the apps').
 *
 * A sealed document is NaCl secretbox (XSalsa20-Poly1305, a random 24-byte nonce) over
 * `{ slot, value }`: the slot inside binds it to where it is stored, so the cloud cannot move one
 * sealed document into another's place. docs/security.md › What the cloud stores.
 */

import nacl from "tweetnacl";
import { fromByteArray, toByteArray } from "base64-js";
import { hkdfSha512, secretboxOpen, secretboxSeal, utf8 } from "./crypto.js";

const DOCUMENTS_KEY_INFO = "shuriken/documents-key/v1";
const VAULT_KEY_BYTES = 32;
export const DOCUMENTS_KEY_BYTES = 32;

/** A sealed document as the cloud stores it. */
export interface SealedDocument {
  v: 1;
  nonce: string;
  box: string;
}

export function deriveDocumentsKey(vaultKey: Uint8Array): Uint8Array {
  if (vaultKey.byteLength !== VAULT_KEY_BYTES) {
    throw new Error(`Vault key must be ${VAULT_KEY_BYTES} bytes`);
  }
  return hkdfSha512(vaultKey, new Uint8Array(0), utf8(DOCUMENTS_KEY_INFO), DOCUMENTS_KEY_BYTES);
}

export function exportDocumentsKey(key: Uint8Array): string {
  return fromByteArray(key);
}

/** The key from its base64 form, or null when it is not one. */
export function importDocumentsKey(base64: unknown): Uint8Array | null {
  if (typeof base64 !== "string" || base64.length === 0 || base64.length > 64) return null;
  try {
    const key = toByteArray(base64);
    return key.byteLength === DOCUMENTS_KEY_BYTES ? key : null;
  } catch {
    return null;
  }
}

export function isSealedDocument(value: unknown): value is SealedDocument {
  if (typeof value !== "object" || value === null) return false;
  const record = value as Record<string, unknown>;
  return record.v === 1 && typeof record.nonce === "string" && typeof record.box === "string";
}

export function sealDocument(key: Uint8Array, slot: string, value: unknown): SealedDocument {
  const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
  const box = secretboxSeal(utf8(JSON.stringify({ slot, value })), nonce, key);
  return { v: 1, nonce: fromByteArray(nonce), box: fromByteArray(box) };
}

export class SealedDocumentError extends Error {
  constructor(readonly slot: string) {
    super(`The sealed document for ${slot} does not open with this key`);
    this.name = "SealedDocumentError";
  }
}

/** Opens a document sealed for `slot`; throws SealedDocumentError on another key, slot or a change. */
export function openDocument(key: Uint8Array, slot: string, sealed: SealedDocument): unknown {
  let opened: Uint8Array | null = null;
  try {
    opened = secretboxOpen(toByteArray(sealed.box), toByteArray(sealed.nonce), key);
  } catch {
    opened = null;
  }
  if (!opened) throw new SealedDocumentError(slot);
  let inner: { slot?: unknown; value?: unknown };
  try {
    inner = JSON.parse(new TextDecoder().decode(opened)) as { slot?: unknown; value?: unknown };
  } catch {
    throw new SealedDocumentError(slot);
  }
  if (inner?.slot !== slot) throw new SealedDocumentError(slot);
  return inner.value;
}

/** A sealed document in one string (a database column): `d1.<nonce>.<box>`. */
export function sealDocumentString(key: Uint8Array, slot: string, value: unknown): string {
  const sealed = sealDocument(key, slot, value);
  return `d1.${sealed.nonce}.${sealed.box}`;
}

export function openDocumentString(key: Uint8Array, slot: string, sealed: string): unknown {
  const [version, nonce, box] = sealed.split(".");
  if (version !== "d1" || !nonce || !box) throw new SealedDocumentError(slot);
  return openDocument(key, slot, { v: 1, nonce, box });
}

import {
  isSealedDocument,
  openDocument,
  sealDocument,
  type SealedDocument,
} from "@shuriken/client";
import { VaultItemDecryptError, decryptVaultValue, encryptVaultValue } from "./vault-crypto";
import type { VaultCryptoBackend } from "./vault-crypto-backend-types";
import { VaultLockedError } from "./vault-client";

// Round 36 S2 (docs/security.md): the account documents only the apps read are sealed with the
// account's vault key before they reach the cloud, so the cloud — its operator, a database leak —
// holds ciphertext for them. `notifications`, which the workers' daemons read too (muted
// projects), is sealed with the account's documents key instead (relay documents-key.ts; every
// worker gets it from an app), with only the owner-alert switches the Hub reads left plain next to
// it. `usage-readings` the daemons seal themselves. docs/security.md says why.
//
// Envelope: `{ sealed: { v: 1, iv, ciphertext }, ...plain }`, where the ciphertext opens to
// `{ key, value }` (the key inside binds a document to its slot: the cloud cannot swap two). The
// only plaintext next to it is what the Hub itself reads: `preferences` keeps `entries.language`,
// the language its pushes are worded in.
//
// Security audit (v5.1.0): a plaintext document in one of these slots is refused (a decrypt error
// with the key, VaultLockedError without it), never applied: the sealing is the documents'
// integrity as well as their secrecy, and anyone who could write /api/settings could otherwise
// choose what every device applies (a new chat's mode). The device's own next write replaces it.

/** The account documents sealed with the vault key. */
export const SEALED_SETTING_KEYS: ReadonlySet<string> = new Set([
  "preferences",
  "new-chat",
  "appearance",
  "device-settings",
  // G-12: the account's prompt snippets (snippets/; protocol snippets/snippet.ts).
  "prompt-snippets",
]);

/** The account documents sealed with the documents key, which the workers' daemons also hold. */
export const WORKER_SEALED_SETTING_KEYS: ReadonlySet<string> = new Set(["notifications"]);

/**
 * The events the Hub raises owner alerts for itself (cloud lib/owner-alerts.ts
 * ALERT_SETTING_EVENT): their switches stay readable next to the sealed notification settings,
 * so the Hub knows whether to push. Booleans and a sound name; no project, no device.
 */
const HUB_ALERT_EVENTS = [
  "worker_offline",
  "update_failed",
  "source_signed_out",
  // Round 37 #29: a new sign-in to the account.
  "new_sign_in",
] as const;

const ENVELOPE_VERSION = 1;

/** `sealed` (vault key) or `box` (documents key), and what stays readable next to it. */
export interface SealedSettingEnvelope {
  sealed?: { v: number; iv: string; ciphertext: string };
  box?: SealedDocument;
  [plain: string]: unknown;
}

export function isSealedSetting(value: unknown): value is SealedSettingEnvelope {
  if (typeof value !== "object" || value === null) return false;
  if (isSealedDocument((value as { box?: unknown }).box)) return true;
  const sealed = (value as { sealed?: unknown }).sealed;
  return (
    typeof sealed === "object" &&
    sealed !== null &&
    typeof (sealed as { iv?: unknown }).iv === "string" &&
    typeof (sealed as { ciphertext?: unknown }).ciphertext === "string"
  );
}

/** What stays readable next to the ciphertext: only what the cloud itself must read. */
export function plainSettingMetadata(
  key: string,
  value: Record<string, unknown>,
): Record<string, unknown> {
  if (key === "notifications") {
    const events = (value.events ?? {}) as Record<string, unknown>;
    const kept: Record<string, unknown> = {};
    for (const event of HUB_ALERT_EVENTS) {
      const entry = events[event] as Record<string, unknown> | undefined;
      if (!entry) continue;
      kept[event] = { desktop: entry.desktop, phone: entry.phone, sound: entry.sound };
    }
    return { events: kept };
  }
  if (key !== "preferences") return {};
  const language = (value.entries as { language?: unknown } | undefined)?.language;
  return language === undefined ? {} : { entries: { language } };
}

export interface OpenedSetting {
  value: Record<string, unknown> | null;
}

export interface SettingsSealer {
  seals(key: string): boolean;
  /** Whether this device holds the key right now. */
  canSeal(): boolean;
  /** Throws VaultLockedError without the key: a sealed document is never sent in plaintext. */
  seal(key: string, value: Record<string, unknown>): Promise<SealedSettingEnvelope>;
  /** Throws VaultLockedError for a sealed document without the key. */
  open(key: string, stored: Record<string, unknown> | null): Promise<OpenedSetting>;
}

export function createSettingsSealer(deps: {
  crypto: VaultCryptoBackend;
  vaultKey: () => Uint8Array | null;
  /** The documents key (derived from the vault key) for WORKER_SEALED_SETTING_KEYS. */
  documentsKey: () => Uint8Array | null;
}): SettingsSealer {
  const requireKey = (): Uint8Array => {
    const key = deps.vaultKey();
    if (!key) throw new VaultLockedError();
    return key;
  };
  const requireDocumentsKey = (): Uint8Array => {
    const key = deps.documentsKey();
    if (!key) throw new VaultLockedError();
    return key;
  };
  return {
    seals: (key) => SEALED_SETTING_KEYS.has(key) || WORKER_SEALED_SETTING_KEYS.has(key),
    canSeal: () => deps.vaultKey() !== null,
    async seal(key, value) {
      if (WORKER_SEALED_SETTING_KEYS.has(key)) {
        const box: SealedDocument = sealDocument(requireDocumentsKey(), key, value);
        return { ...plainSettingMetadata(key, value), box };
      }
      const { iv, ciphertext } = await encryptVaultValue(deps.crypto, requireKey(), {
        key,
        value,
      });
      return {
        ...plainSettingMetadata(key, value),
        sealed: { v: ENVELOPE_VERSION, iv, ciphertext },
      };
    },
    async open(key, stored) {
      if (stored === null) return { value: null };
      if (!isSealedSetting(stored)) {
        // Never applied: proves nothing about who wrote it.
        if (WORKER_SEALED_SETTING_KEYS.has(key)) requireDocumentsKey();
        else requireKey();
        throw new VaultItemDecryptError(`setting:${key}`);
      }
      const { box, sealed } = stored;
      if (isSealedDocument(box)) {
        let inner: unknown;
        try {
          inner = openDocument(requireDocumentsKey(), key, box);
        } catch (error) {
          if (error instanceof VaultLockedError) throw error;
          throw new VaultItemDecryptError(`setting:${key}`);
        }
        if (typeof inner !== "object" || inner === null) {
          throw new VaultItemDecryptError(`setting:${key}`);
        }
        return { value: inner as Record<string, unknown> };
      }
      if (!sealed) throw new VaultItemDecryptError(`setting:${key}`);
      const opened = await decryptVaultValue(deps.crypto, requireKey(), {
        id: `setting:${key}`,
        iv: sealed.iv,
        ciphertext: sealed.ciphertext,
      });
      const inner = opened as { key?: unknown; value?: unknown } | null;
      if (inner?.key !== key || typeof inner.value !== "object" || inner.value === null) {
        throw new VaultItemDecryptError(`setting:${key}`);
      }
      return { value: inner.value as Record<string, unknown> };
    },
  };
}

import nacl from "tweetnacl";
import { utf8Encode } from "./base64";

// Round 59 (the owner: "online they still show the default ones"): the key every picture of the
// account — his profile picture and every project's — is sealed with. It is derived from the vault
// key (HKDF-SHA-512, as relay documents-key.ts derives the documents key), so every device holding
// the vault key has it, and it opens pictures only: a browser tab without the vault key (every
// visit to shuriken.sh/app after the one that signed in) is handed this key alone, sealed to the
// browser's receiver (picture-copies.ts), and never the vault key. docs/security.md › R2.

const PICTURES_KEY_INFO = "shuriken/pictures-key/v1";
const PICTURES_KEY_ID_INFO = "shuriken/pictures-key-id/v1";
export const PICTURES_KEY_BYTES = 32;
/** A key's id travels in every sealed picture's header: 8 bytes, as 16 hex digits. */
export const PICTURES_KEY_ID_BYTES = 8;
const HMAC_BLOCK = 128;

export interface PicturesKey {
  /** 16 hex digits: which pictures key sealed a picture (pictures sealed before a rotation). */
  id: string;
  key: Uint8Array;
}

function hmacSha512(key: Uint8Array, message: Uint8Array): Uint8Array {
  const block = new Uint8Array(HMAC_BLOCK);
  block.set(key.byteLength > HMAC_BLOCK ? nacl.hash(key) : key);
  const inner = new Uint8Array(HMAC_BLOCK + message.byteLength);
  const outer = new Uint8Array(HMAC_BLOCK + 64);
  for (let i = 0; i < HMAC_BLOCK; i += 1) {
    inner[i] = block[i]! ^ 0x36;
    outer[i] = block[i]! ^ 0x5c;
  }
  inner.set(message, HMAC_BLOCK);
  outer.set(nacl.hash(inner), HMAC_BLOCK);
  return nacl.hash(outer);
}

/** RFC 5869 HKDF-SHA-512 for one block (relay crypto.ts hkdfSha512, the same bytes). */
function hkdfSha512(ikm: Uint8Array, info: string, length: number): Uint8Array {
  const prk = hmacSha512(new Uint8Array(64), ikm);
  const infoBytes = utf8Encode(info);
  const message = new Uint8Array(infoBytes.byteLength + 1);
  message.set(infoBytes);
  message[infoBytes.byteLength] = 1;
  const okm = hmacSha512(prk, message).slice(0, length);
  prk.fill(0);
  return okm;
}

function hex(bytes: Uint8Array): string {
  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
}

/** The pictures key and its id, from a key's 32 bytes. */
export function picturesKeyFromBytes(key: Uint8Array): PicturesKey {
  if (key.byteLength !== PICTURES_KEY_BYTES) throw new Error("pictures key must be 32 bytes");
  return {
    id: hex(hkdfSha512(key, PICTURES_KEY_ID_INFO, PICTURES_KEY_ID_BYTES)),
    key: new Uint8Array(key),
  };
}

/** The account's pictures key for a vault key (the current one, or one from before a rotation). */
export function derivePicturesKey(vaultKey: Uint8Array): PicturesKey {
  return picturesKeyFromBytes(hkdfSha512(vaultKey, PICTURES_KEY_INFO, PICTURES_KEY_BYTES));
}

/** The id as the 8 bytes a sealed picture's header carries. */
export function picturesKeyIdBytes(id: string): Uint8Array {
  const out = new Uint8Array(PICTURES_KEY_ID_BYTES);
  for (let i = 0; i < PICTURES_KEY_ID_BYTES; i += 1) {
    out[i] = Number.parseInt(id.slice(i * 2, i * 2 + 2), 16);
  }
  return out;
}

export function picturesKeyIdFromBytes(bytes: Uint8Array): string {
  return hex(bytes.subarray(0, PICTURES_KEY_ID_BYTES));
}

import type { AccountSigner } from "@shuriken/client";
import nacl from "tweetnacl";
import { base64ToBytes, bytesToBase64, utf8Decode, utf8Encode } from "./base64";
import type { CloudApi } from "./cloud-api";
import type { PictureReceiverKeys } from "./kept-picture-store";
import { PICTURES_KEY_BYTES, type PicturesKey, picturesKeyFromBytes } from "./pictures-key";
import { errorLogText } from "@/utils/error-log-text";

// Round 56 #25 (the owner on shuriken.sh: "the profile picture still doesn't show"). The picture is
// sealed with the vault key (round 36 S2) and a browser keeps that key for its tab only (S3), so
// every visit after the one that signed in drew his monogram. Round 52 kept the picture a tab had
// opened, but his tabs never opened it: none had the key. Now each browser keeps a receiver — a
// P-256 key pair it cannot export (kept-picture-store.web.ts) — and publishes the public half
// signed with the account key. Any device holding the vault key checks that signature and seals
// the picture to it; the cloud stores the copy and can open neither it nor make a receiver of its
// own (it has no account key). docs/security.md › R2.

/** What the account key signs: this receiver key is this device's (relay account-key.ts's form). */
const RECEIVER_CONTEXT = "shuriken/device-key/picture/v1";
const COPY_INFO = "shuriken/picture-copy/v1";
const RECEIVER_KEY_BYTES = 65;
const IV_BYTES = 12;

const buffer = (bytes: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(bytes);

export function receiverBinding(deviceId: string, keyB64: string): Uint8Array {
  return utf8Encode(`${RECEIVER_CONTEXT}\n${deviceId}\n${keyB64}`);
}

/** Whether the account key signed `keyB64` as `deviceId`'s receiver. */
export function receiverIsSigned(input: {
  accountPublicKey: Uint8Array;
  deviceId: string;
  key: string;
  signature: string;
}): boolean {
  try {
    const signature = base64ToBytes(input.signature);
    if (signature.byteLength !== nacl.sign.signatureLength) return false;
    return nacl.sign.detached.verify(
      receiverBinding(input.deviceId, input.key),
      signature,
      input.accountPublicKey,
    );
  } catch {
    return false;
  }
}

/** The AES-GCM key both ends derive: ECDH, then HKDF over both public points. */
async function copyKey(
  subtle: SubtleCrypto,
  privateKey: CryptoKey,
  peer: Uint8Array,
  ephemeral: Uint8Array,
  receiver: Uint8Array,
  usage: KeyUsage,
  info: string = COPY_INFO,
): Promise<CryptoKey> {
  const peerKey = await subtle.importKey(
    "raw",
    buffer(peer),
    { name: "ECDH", namedCurve: "P-256" },
    false,
    [],
  );
  const shared = await subtle.deriveBits({ name: "ECDH", public: peerKey }, privateKey, 256);
  const material = await subtle.importKey("raw", shared, "HKDF", false, ["deriveKey"]);
  const salt = new Uint8Array(ephemeral.byteLength + receiver.byteLength);
  salt.set(ephemeral);
  salt.set(receiver, ephemeral.byteLength);
  return subtle.deriveKey(
    { name: "HKDF", hash: "SHA-256", salt, info: buffer(utf8Encode(info)) },
    material,
    { name: "AES-GCM", length: 256 },
    false,
    [usage],
  );
}

/** `ephemeral[65] || iv[12] || AES-GCM([type length][type][image])`, for `receiver` only. */
export async function sealPictureCopy(
  subtle: SubtleCrypto,
  receiver: Uint8Array,
  picture: { mimeType: string; bytes: Uint8Array },
): Promise<Uint8Array> {
  const pair = await subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, false, [
    "deriveBits",
  ]);
  const ephemeral = new Uint8Array(await subtle.exportKey("raw", pair.publicKey));
  const key = await copyKey(subtle, pair.privateKey, receiver, ephemeral, receiver, "encrypt");
  const type = utf8Encode(picture.mimeType);
  const payload = new Uint8Array(1 + type.length + picture.bytes.length);
  payload[0] = type.length;
  payload.set(type, 1);
  payload.set(picture.bytes, 1 + type.length);
  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
  const sealed = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv }, key, payload));
  const out = new Uint8Array(ephemeral.length + IV_BYTES + sealed.length);
  out.set(ephemeral);
  out.set(iv, ephemeral.length);
  out.set(sealed, ephemeral.length + IV_BYTES);
  return out;
}

/** The picture as a data URI, opened with this browser's receiver; null when it does not open. */
export async function openPictureCopy(
  subtle: SubtleCrypto,
  receiver: PictureReceiverKeys,
  sealed: Uint8Array,
): Promise<string | null> {
  if (sealed.length <= RECEIVER_KEY_BYTES + IV_BYTES) return null;
  const ephemeral = sealed.subarray(0, RECEIVER_KEY_BYTES);
  const iv = sealed.subarray(RECEIVER_KEY_BYTES, RECEIVER_KEY_BYTES + IV_BYTES);
  try {
    const key = await copyKey(
      subtle,
      receiver.privateKey,
      ephemeral,
      ephemeral,
      receiver.publicKey,
      "decrypt",
    );
    const payload = new Uint8Array(
      await subtle.decrypt(
        { name: "AES-GCM", iv: buffer(iv) },
        key,
        buffer(sealed.subarray(RECEIVER_KEY_BYTES + IV_BYTES)),
      ),
    );
    const typeLength = payload[0] ?? 0;
    const mimeType = utf8Decode(payload.subarray(1, 1 + typeLength));
    if (!/^image\/(png|jpeg|webp)$/.test(mimeType)) return null;
    return `data:${mimeType};base64,${bytesToBase64(payload.subarray(1 + typeLength))}`;
  } catch {
    return null;
  }
}

/** What the account picture's reader needs; every call is best effort and never throws. */
export interface PictureCopies {
  /** A locked tab: publishes this browser's receiver (once per receiver key and tab). */
  publish(): Promise<void>;
  /** A locked tab: its copy of the picture, opened, or null. */
  read(): Promise<string | null>;
  /** A device that opened the picture with the vault key: seals it for every receiver behind. */
  sealForReceivers(): Promise<void>;
}

export interface PictureCopiesDeps {
  api: Pick<
    CloudApi,
    | "getMyPicture"
    | "putPictureReceiver"
    | "listPictureReceivers"
    | "putPictureCopy"
    | "getPictureCopy"
  >;
  /** This device's id on the account (the session's). */
  deviceId: string;
  subtle: SubtleCrypto | undefined;
  /** This browser's receiver (null: a platform that keeps none). */
  receiver: (create: boolean) => Promise<PictureReceiverKeys | null>;
  /** The account key this device proves the account with (a browser's kept one while locked). */
  signer: () => AccountSigner | null;
  /** The account's current public key, only while the vault key is open here. */
  accountPublicKey: () => Uint8Array | null;
}

/** Receivers this tab already published: one PUT per key, not one per read. */
const published = new Set<string>();

/** Copy-upload failures already logged, by kind and cause. */
const reportedFailures = new Set<string>();

/**
 * A sealed copy's upload failed. A stale receiver (412) is routine: the next pass seals to the
 * new one. Anything else is logged once per kind and cause: the cloud's CORS preflight refused
 * every desktop upload for a release and nothing said so (5.1.0 audit).
 */
function reportCopyFailure(kind: "picture copy" | "pictures key copy", error: unknown): void {
  if ((error as { status?: unknown } | null)?.status === 412) return;
  const cause = errorLogText(error);
  const id = `${kind}:${cause}`;
  if (reportedFailures.has(id)) return;
  reportedFailures.add(id);
  console.warn(`[pictures] ${kind} upload failed:`, cause);
}

export function createPictureCopies(deps: PictureCopiesDeps): PictureCopies {
  return {
    async publish() {
      try {
        const signer = deps.signer();
        if (!signer) return;
        const receiver = await deps.receiver(true);
        if (!receiver) return;
        const key = bytesToBase64(receiver.publicKey);
        const id = `${deps.deviceId}:${key}:${bytesToBase64(signer.publicKey)}`;
        if (published.has(id)) return;
        const signature = bytesToBase64(await signer.sign(receiverBinding(deps.deviceId, key)));
        await deps.api.putPictureReceiver({ key, signature });
        published.add(id);
      } catch {
        // Offline, or a cloud from before receivers: the next read publishes it.
      }
    },
    async read() {
      try {
        const subtle = deps.subtle;
        const receiver = subtle ? await deps.receiver(false) : null;
        if (!subtle || !receiver) return null;
        const sealed = await deps.api.getPictureCopy();
        return sealed ? await openPictureCopy(subtle, receiver, sealed) : null;
      } catch {
        return null;
      }
    },
    async sealForReceivers() {
      try {
        const subtle = deps.subtle;
        const accountPublicKey = deps.accountPublicKey();
        if (!subtle || !accountPublicKey) return;
        const { picture, receivers } = await deps.api.listPictureReceivers();
        const behind = receivers.filter(
          (receiver) =>
            !receiver.current &&
            receiverIsSigned({ accountPublicKey, ...receiver }) &&
            base64ToBytes(receiver.key).byteLength === RECEIVER_KEY_BYTES,
        );
        if (!picture || behind.length === 0) return;
        // Read after the list: a picture changed in between is refused as stale, never mislabeled.
        const opened = await deps.api.getMyPicture();
        if (!opened) return;
        const bytes = base64ToBytes(opened.base64);
        for (const receiver of behind) {
          const sealed = await sealPictureCopy(subtle, base64ToBytes(receiver.key), {
            mimeType: opened.mimeType,
            bytes,
          });
          await deps.api
            .putPictureCopy(receiver.deviceId, sealed, { picture, key: receiver.key })
            .catch((error: unknown) => reportCopyFailure("picture copy", error));
        }
      } catch {
        // Offline, locked meanwhile, or a cloud from before receivers: the next read seals.
      }
    },
  };
}

/**
 * Round 59 (the owner: "online they still show the default ones", for his profile picture and
 * every project's). A copy of the picture itself reached a browser only after a device holding the
 * vault key sealed that one picture to it, and project pictures had no copies at all. Now each
 * receiver is handed the account's pictures key (pictures-key.ts) once:
 * `ephemeral[65] || iv[12] || AES-GCM(key id[8] || key[32])`, the same ECDH and HKDF as a picture
 * copy under its own info. With it a locked tab opens every picture of the account as it is in
 * the cloud now, and a picture changed later needs nothing sealed again. The tab that holds the
 * vault key (the sign-in, an unlock) seals it to its own receiver, so its browser's later tabs need
 * no other device online; any device with the vault key seals it for the receivers still behind.
 */
const KEY_COPY_INFO = "shuriken/pictures-key-copy/v1";
const KEY_ID_BYTES = 8;

export async function sealPicturesKeyCopy(
  subtle: SubtleCrypto,
  receiver: Uint8Array,
  key: PicturesKey,
): Promise<Uint8Array> {
  const pair = await subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, false, [
    "deriveBits",
  ]);
  const ephemeral = new Uint8Array(await subtle.exportKey("raw", pair.publicKey));
  const aes = await copyKey(
    subtle,
    pair.privateKey,
    receiver,
    ephemeral,
    receiver,
    "encrypt",
    KEY_COPY_INFO,
  );
  const payload = new Uint8Array(KEY_ID_BYTES + PICTURES_KEY_BYTES);
  for (let i = 0; i < KEY_ID_BYTES; i += 1) {
    payload[i] = Number.parseInt(key.id.slice(i * 2, i * 2 + 2), 16);
  }
  payload.set(key.key, KEY_ID_BYTES);
  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
  const sealed = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv }, aes, payload));
  payload.fill(0);
  const out = new Uint8Array(ephemeral.length + IV_BYTES + sealed.length);
  out.set(ephemeral);
  out.set(iv, ephemeral.length);
  out.set(sealed, ephemeral.length + IV_BYTES);
  return out;
}

/** The pictures key sealed to this browser's receiver, opened; null when it does not open. */
export async function openPicturesKeyCopy(
  subtle: SubtleCrypto,
  receiver: PictureReceiverKeys,
  sealed: Uint8Array,
): Promise<PicturesKey | null> {
  if (sealed.length <= RECEIVER_KEY_BYTES + IV_BYTES) return null;
  const ephemeral = sealed.subarray(0, RECEIVER_KEY_BYTES);
  const iv = sealed.subarray(RECEIVER_KEY_BYTES, RECEIVER_KEY_BYTES + IV_BYTES);
  try {
    const aes = await copyKey(
      subtle,
      receiver.privateKey,
      ephemeral,
      ephemeral,
      receiver.publicKey,
      "decrypt",
      KEY_COPY_INFO,
    );
    const payload = new Uint8Array(
      await subtle.decrypt(
        { name: "AES-GCM", iv: buffer(iv) },
        aes,
        buffer(sealed.subarray(RECEIVER_KEY_BYTES + IV_BYTES)),
      ),
    );
    if (payload.byteLength !== KEY_ID_BYTES + PICTURES_KEY_BYTES) return null;
    const key = picturesKeyFromBytes(payload.subarray(KEY_ID_BYTES));
    const id = Array.from(payload.subarray(0, KEY_ID_BYTES), (byte) =>
      byte.toString(16).padStart(2, "0"),
    ).join("");
    payload.fill(0);
    // The id inside is the key's own: a copy whose key and id disagree is not opened.
    return id === key.id ? key : null;
  } catch {
    return null;
  }
}

export interface PicturesKeyCopies {
  /** A browser: publishes its receiver, signed with the account key; whether one is published. */
  publish(): Promise<boolean>;
  /** A browser: the pictures key sealed to its receiver, opened; null when there is none yet. */
  read(): Promise<PicturesKey | null>;
  /** A device holding the vault key: seals `key` for every receiver still behind; how many. */
  sealForReceivers(key: PicturesKey): Promise<number>;
}

export type PicturesKeyCopiesDeps = Omit<PictureCopiesDeps, "api"> & {
  api: Pick<
    CloudApi,
    "putPictureReceiver" | "listPictureReceivers" | "putPicturesKeyCopy" | "getPicturesKeyCopy"
  >;
};

export function createPicturesKeyCopies(deps: PicturesKeyCopiesDeps): PicturesKeyCopies {
  return {
    async publish() {
      const signer = deps.signer();
      if (!signer || !deps.subtle) return false;
      const receiver = await deps.receiver(true);
      if (!receiver) return false;
      const key = bytesToBase64(receiver.publicKey);
      const id = `${deps.deviceId}:${key}:${bytesToBase64(signer.publicKey)}`;
      if (published.has(id)) return true;
      const signature = bytesToBase64(await signer.sign(receiverBinding(deps.deviceId, key)));
      await deps.api.putPictureReceiver({ key, signature });
      published.add(id);
      return true;
    },
    async read() {
      const subtle = deps.subtle;
      const receiver = subtle ? await deps.receiver(false) : null;
      if (!subtle || !receiver) return null;
      const sealed = await deps.api.getPicturesKeyCopy();
      return sealed ? openPicturesKeyCopy(subtle, receiver, sealed) : null;
    },
    async sealForReceivers(key) {
      const subtle = deps.subtle;
      const accountPublicKey = deps.accountPublicKey();
      if (!subtle || !accountPublicKey) return 0;
      const { receivers } = await deps.api.listPictureReceivers();
      let sealed = 0;
      for (const receiver of receivers) {
        const behind =
          !receiver.keyCopy ||
          receiver.keyCopy.key !== receiver.key ||
          receiver.keyCopy.keyId !== key.id;
        if (!behind) continue;
        // Only a receiver the account key signed: the cloud cannot slip in one of its own.
        if (!receiverIsSigned({ accountPublicKey, ...receiver })) continue;
        const point = base64ToBytes(receiver.key);
        if (point.byteLength !== RECEIVER_KEY_BYTES) continue;
        const copy = await sealPicturesKeyCopy(subtle, point, key);
        try {
          await deps.api.putPicturesKeyCopy(receiver.deviceId, copy, {
            receiverKey: receiver.key,
            keyId: key.id,
          });
          sealed += 1;
        } catch (error) {
          // Stale (the receiver changed meanwhile: the next pass seals to the new one) or offline.
          reportCopyFailure("pictures key copy", error);
        }
      }
      return sealed;
    },
  };
}

/** Tests: forget which receivers this tab published, and which upload failures it logged. */
export function resetPublishedReceiversForTests(): void {
  published.clear();
  reportedFailures.clear();
}

/// <reference lib="dom" />
/**
 * Encrypted channel that wraps a WebSocket-like transport.
 *
 * Handles ECDH handshake and encrypts/decrypts all messages.
 * Works identically for daemon and client sides.
 */

import {
  generateKeyPair,
  exportPublicKey,
  importPublicKey,
  deriveSharedKey,
  deriveSessionKeys,
  encrypt,
  encryptWithCounter,
  decrypt,
  hkdfSha512,
  hmacSha512,
  openWithCounter,
  secretboxSeal,
  utf8,
  type KeyPair,
  type SharedKey,
} from "./crypto.js";
import {
  signRelayClient,
  verifyRelayClient,
  type AccountSigner,
  type RelayAccountProof,
} from "./account-key.js";
import {
  PROJECT_SHARE_ID_PATTERN,
  signRelayGuest,
  verifyRelayGuest,
  type ProvenGuest,
  type RelayGuestProof,
} from "./guest-proof.js";
import {
  isRelayLoanProofShape,
  signRelayLoan,
  verifyRelayLoan,
  type ProvenLoan,
  type RelayLoanProof,
} from "./loan-proof.js";
import type { SignedLoanDelegation } from "./loan-delegation.js";
import { arrayBufferToBase64, base64ToArrayBuffer } from "./base64.js";

export interface Transport {
  send(data: string | ArrayBuffer): void | Promise<void>;
  close(code?: number, reason?: string): void;
  onmessage: ((message: TransportMessage) => void) | null;
  onclose: ((code: number, reason: string) => void) | null;
  onerror: ((error: Error) => void) | null;
}

export interface TransportMessage {
  data: string | ArrayBuffer;
  isBinary: boolean;
}

export interface EncryptedChannelEvents {
  onopen?: () => void;
  onmessage?: (data: string | ArrayBuffer) => void;
  onclose?: (code: number, reason: string) => void;
  onerror?: (error: Error) => void;
}

type ChannelState = "connecting" | "handshaking" | "open" | "closed";

interface EncryptedChannelOptions {
  /**
   * If set, the channel can validate repeated plaintext `{type:"e2ee_hello"}`
   * messages even after it is open.
   *
   * This is useful for robustness when the client retries the handshake
   * (e.g., it didn't observe the daemon's `{type:"e2ee_ready"}` yet). In that case,
   * the daemon should re-send `{type:"e2ee_ready"}` without changing keys.
   */
  daemonKeyPair?: KeyPair;
  binaryCiphertext?: boolean;
  /**
   * Client side: text sent before `e2ee_ready` goes out at once, sealed as base64 text, which a
   * daemon in either ciphertext mode reads (`createDaemonChannel` replays frames that arrive
   * behind the hello). The session's own hello then travels with the handshake instead of one
   * round trip after it. Binary waits for the negotiated mode, and anything sent after a waiting
   * frame waits too, so order is kept.
   *
   * Audit RELAY-2: an early frame is sealed under the handshake key, which has no ephemeral part,
   * so a recording opens with a later-stolen daemon key. A frame that carries a credential
   * (`carriesSessionCredential`) therefore always waits for the session keys, and so does any
   * text `mayPipeline` refuses.
   */
  pipelineText?: boolean;
  /** Client side, audit RELAY-2: the caller's own rule for which text may ride early. */
  mayPipeline?: (text: string) => boolean;
  /**
   * W7: every sealed frame travels as a binary WebSocket frame and its first plaintext byte
   * says what it holds (`FrameKind`), so text is not base64'd on the wire (a third more bytes).
   */
  framedPlaintext?: boolean;
  /**
   * Audit RELAY-8: the peer reads padded frames (`framed`), so every frame this side seals after
   * the handshake is padded to its size bucket (`paddedFrameLength`).
   */
  padded?: boolean;
  /**
   * Session keys (SECURITY.md › Session keys): one key per direction and a counter per frame.
   * Set on the daemon at the handshake; on the client it holds what the ready needs to finish.
   */
  session?: SessionKeyState;
  /** The daemon's ephemeral public key, which a retried `e2ee_ready` repeats. */
  daemonEphemeralPublicKeyB64?: string;
  /**
   * Client side, audit RELAY-6: the daemon's static key; a ready that says `timedProof` puts it
   * in `timedProofDaemons`, so later hellos to it carry the timed proof. Audit RELAY-10: and the
   * key its channel level is pinned under (`daemonChannelLevels`).
   */
  timedProofDaemonKeyB64?: string;
  /** Client side, audit RELAY-10: the hello exactly as sent, for the transcript hash. */
  helloText?: string;
  /**
   * Client side, audit RELAY-10: the hello carried an account, guest or loan proof. Every daemon
   * that reads one requires session keys, so a ready without them is refused.
   */
  provedPeer?: boolean;
  /**
   * Client side, audit RELAY-10 (D): a credential (`carriesSessionCredential`) is never sealed
   * without session keys. Every daemon from 5.0.0 on agrees to them when asked.
   */
  credentialsNeedSessionKeys?: boolean;
  /** Daemon side, audit RELAY-10: the ready exactly as sent; a retried ready resends it. */
  readyText?: string;
  /**
   * Item 79: a loan channel. Every frame is binary and of kind `L`; text is refused
   * on send, and a frame of any other kind closes the channel with 4403.
   */
  loan?: boolean;
}

interface SessionKeyState {
  /** Client side, until `e2ee_ready` names the daemon's ephemeral key. */
  pending?: { ephemeral: KeyPair; daemonStaticPublicKey: Uint8Array };
  sendKey?: Uint8Array;
  receiveKey?: Uint8Array;
  sendCounter: number;
  receiveCounter: number;
  /**
   * Daemon side: base64 text frames are the client's frames sealed before it read the ready
   * (`pipelineText`), under the handshake's static key. They are accepted only until the first
   * session frame, and each nonce once, so none can be replayed later in the session.
   */
  earlyNonces?: Set<string>;
  sawSessionFrame?: boolean;
  /**
   * Audit D16, daemon side: early frames from a confirming client (`isConfirmingEarlyNonce`),
   * opened but not yet delivered. They reach the app only once a session frame proves the client
   * is live; a replayed handshake never produces one, so they are dropped with the channel.
   */
  heldEarly?: string[];
  /** Daemon side: the hello asked for `confirm`, so the ready (and a retried one) echoes it. */
  confirm?: boolean;
  /** Daemon side, audit RELAY-10: the hello asked for `transcript`, so a bare confirm is refused. */
  transcript?: boolean;
  /**
   * Daemon side, audit RELAY-10: the transcript hash of the hello as read and the ready as sent,
   * which a confirm frame with a body must carry.
   */
  expectedTranscript?: Uint8Array;
  /** Daemon side, audit RELAY-10: the confirm frame arrived and checked out. */
  confirmed?: boolean;
}

/** Security options a client adds to its handshake. */
export interface ClientChannelSecurity {
  /** Signs the handshake with the account key, so the daemon admits this device (account-key.ts). */
  account?: AccountSigner;
  /**
   * Shared projects (v6.0.0): a member signs the handshake with its own account key for one share
   * (guest-proof.ts). Never beside `account`.
   */
  guest?: { shareId: string; signer: AccountSigner };
  /**
   * Item 79: a borrower's daemon signs the handshake with its delegated device key for one loan
   * (loan-proof.ts), and the channel becomes a loan channel. Never beside `account` or `guest`.
   */
  loan?: { loanId: string; delegation: SignedLoanDelegation; device: AccountSigner };
}

/** Security options a daemon adds to its handshake. */
export interface DaemonChannelSecurity {
  /**
   * Client handshake keys this daemon has already accepted. A client makes a fresh key for every
   * connection, so a repeat is a recorded handshake played again and is refused. Defaults to a
   * cache shared by every channel in the process.
   */
  seenClientKeys?: SeenClientKeys;
  /**
   * Shared projects (v6.0.0): read a member's guest proof. Off unless the listener opts in: guests
   * reach a daemon through the cloud relay only, so the direct (LAN) listener refuses them.
   */
  guests?: boolean;
  /**
   * Item 79: read a borrower daemon's loan proof. Off unless the listener opts in: loans reach the
   * serving daemon through the cloud relay only, so the direct (LAN) listener refuses them.
   */
  loans?: boolean;
  /** Audit RELAY-6: the clock a timed proof is checked against; tests set it. */
  now?: () => number;
}

export interface SeenClientKeys {
  /**
   * True when `key` was new (and is now remembered), false for a repeat. `proven`: the hello's
   * account, guest or loan proof verified, which no relay can make up (audit RELAY-6).
   */
  remember(key: string, proven?: boolean): boolean;
}

/** Audit RELAY-6: one remembered handshake, as a durable store keeps it. */
export interface SeenHandshake {
  /** `handshakeReplayKey`: a digest of the handshake's shared key, never the key itself. */
  key: string;
  proven: boolean;
  /** When the daemon first accepted it, ms since the epoch. */
  at: number;
}

/**
 * Audit RELAY-6: a durable copy of the memory, so a daemon restart does not forget what it
 * accepted (the daemon keeps it in `$SHURIKEN_HOME/seen-handshakes`). A store that throws costs
 * only the durability: the memory keeps working.
 */
export interface SeenHandshakeStore {
  load(): SeenHandshake[];
  add(entry: SeenHandshake): void;
  /** Rewrites the store to exactly `entries` (it drops what the memory forgot). */
  replace(entries: SeenHandshake[]): void;
}

export interface SeenClientKeysOptions {
  /** How long a handshake is remembered. A replay inside it is refused, even after a restart. */
  ttlMs?: number;
  /** Proven handshakes held at most; only real devices make them, so this is a backstop. */
  provenLimit?: number;
  /** Unproven handshakes held at most. Past it the oldest unproven one goes, never a proven one. */
  unprovenLimit?: number;
  now?: () => number;
  store?: SeenHandshakeStore;
}

/** Audit RELAY-6: how long a daemon remembers a handshake it accepted. */
export const SEEN_HANDSHAKE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
const SEEN_PROVEN_LIMIT = 100_000;
const SEEN_UNPROVEN_LIMIT = 50_000;
/** A store is rewritten once it holds this many lines beyond twice the live entries. */
const SEEN_STORE_SLACK = 1024;

/**
 * Client handshakes this daemon has accepted, so a recorded one played again is refused.
 *
 * Audit RELAY-6: proven and unproven handshakes are held apart, so hellos a relay makes up (which
 * can never carry a proof that verifies) cannot push a proven one out; entries are kept for
 * `ttlMs`, not dropped by count; and a `store` carries them across a restart.
 */
export function createSeenClientKeys(options: SeenClientKeysOptions | number = {}): SeenClientKeys {
  const opts: SeenClientKeysOptions =
    typeof options === "number" ? { provenLimit: options, unprovenLimit: options } : options;
  const ttlMs = opts.ttlMs ?? SEEN_HANDSHAKE_TTL_MS;
  const now = opts.now ?? Date.now;
  const store = opts.store;
  // Insertion order is acceptance order, so the oldest entry of each is first.
  const proven = new Map<string, number>();
  const unproven = new Map<string, number>();
  const limitOf = (bucket: Map<string, number>): number =>
    bucket === proven
      ? (opts.provenLimit ?? SEEN_PROVEN_LIMIT)
      : (opts.unprovenLimit ?? SEEN_UNPROVEN_LIMIT);
  const expired = (at: number, t: number): boolean => t - at >= ttlMs;
  let storedLines = 0;

  const forgetExpired = (t: number): void => {
    for (const bucket of [proven, unproven]) {
      for (const [key, at] of bucket) {
        if (!expired(at, t)) break;
        bucket.delete(key);
      }
    }
  };
  const entries = (): SeenHandshake[] =>
    [
      ...[...proven].map(([key, at]) => ({ key, proven: true, at })),
      ...[...unproven].map(([key, at]) => ({ key, proven: false, at })),
    ].sort((a, b) => a.at - b.at);
  const rewriteStore = (): void => {
    if (!store) return;
    const live = entries();
    try {
      store.replace(live);
      storedLines = live.length;
    } catch {
      // Durability lost for now; the memory still refuses repeats.
    }
  };
  const add = (bucket: Map<string, number>, key: string, at: number): void => {
    bucket.set(key, at);
    if (bucket.size > limitOf(bucket)) {
      const oldest = bucket.keys().next().value;
      if (oldest !== undefined) bucket.delete(oldest);
    }
  };

  if (store) {
    let loaded: SeenHandshake[] = [];
    try {
      loaded = store.load();
    } catch {
      loaded = [];
    }
    const t = now();
    const valid = loaded
      .filter(
        (entry) =>
          typeof entry?.key === "string" &&
          entry.key.length > 0 &&
          Number.isFinite(entry.at) &&
          !expired(entry.at, t),
      )
      .sort((a, b) => a.at - b.at);
    for (const entry of valid) {
      if (proven.has(entry.key) || unproven.has(entry.key)) continue;
      add(entry.proven === true ? proven : unproven, entry.key, entry.at);
    }
    storedLines = loaded.length;
    if (proven.size + unproven.size < loaded.length) rewriteStore();
  }

  return {
    remember(key, isProven = false) {
      const t = now();
      forgetExpired(t);
      for (const bucket of [proven, unproven]) {
        const at = bucket.get(key);
        if (at === undefined) continue;
        if (!expired(at, t)) return false;
        bucket.delete(key);
      }
      add(isProven ? proven : unproven, key, t);
      if (store) {
        try {
          store.add({ key, proven: isProven, at: t });
          storedLines += 1;
        } catch {
          // As in rewriteStore.
        }
        if (storedLines > 2 * (proven.size + unproven.size) + SEEN_STORE_SLACK) rewriteStore();
      }
      return true;
    },
  };
}

const SEEN_HANDSHAKE_INFO = utf8("shuriken/seen-handshake/v1");

/**
 * Audit RELAY-6: what the memory keys a handshake on: a digest of its shared key, which is what
 * opens its early frames. Every encoding of the same client key (X25519 ignores the top bit, and
 * a few values reduce mod p) gives the same shared key, so a re-encoded recording is still a
 * repeat; the digest is one way, so a stored entry opens nothing.
 */
function handshakeReplayKey(sharedKey: SharedKey): string {
  const digest = hkdfSha512(sharedKey, new Uint8Array(0), SEEN_HANDSHAKE_INFO, 16);
  return arrayBufferToBase64(digest.slice().buffer);
}

let processSeenClientKeys: SeenClientKeys = createSeenClientKeys();

/**
 * Audit RELAY-6: the memory every daemon channel in this process uses unless the caller passes
 * its own. The daemon sets one with a durable store at startup, before it listens.
 */
export function setProcessSeenClientKeys(seen: SeenClientKeys): void {
  processSeenClientKeys = seen;
}

/** Channel options a caller may add to a handshake (the codec its platform has). */
export interface EncryptedChannelCodec {
  /*
   * Audit RELAY-8: there is no `deflate` and no `inflate`. A frame packed before sealing has a
   * length that follows how well its content compresses, which leaks a secret sharing a frame with
   * text an attacker can influence (a page an agent read beside terminal output). Frames are
   * padded instead, and a packed frame (kinds 2 and 3) fails the channel whatever the ready says:
   * the ready is plaintext a relay can write, so an echoed `deflate` the client never asked for
   * (which a 5.0.0 daemon would act on, were the relay to add it to the hello) negotiates nothing.
   */
  /**
   * Client side, audit RELAY-2: which text may be sealed before `e2ee_ready` (under the handshake
   * key, not forward secret). Anything it refuses waits for the session keys. It can only hold
   * back: a frame that carries a credential (`carriesSessionCredential`) waits whatever it says.
   */
  mayPipeline?: (text: string) => boolean;
}

/**
 * Audit RELAY-2: whether `text` is a message with a credential at its top level, the session
 * hello's `auth` (daemon password or local credential) or `device` (a paired device's credential
 * or a pairing token). Such a frame is never sealed under the handshake key alone.
 */
export function carriesSessionCredential(text: string): boolean {
  if (!text.trimStart().startsWith("{")) return false;
  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch {
    return false;
  }
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
  const record = parsed as Record<string, unknown>;
  return (
    (record.auth !== undefined && record.auth !== null) ||
    (record.device !== undefined && record.device !== null)
  );
}

/** First plaintext byte of a framed frame. */
const FrameKind = {
  text: 0,
  binary: 1,
  /**
   * W7's deflate-raw packed text and binary. Audit RELAY-8: never sent, and refused on receipt
   * (`unframe`), even after a ready that echoed `deflate`.
   */
  deflatedText: 2,
  deflatedBinary: 3,
  /**
   * Audit D16: an empty session frame a confirming client sends first, so a daemon holding its
   * early frames knows the client is live. Never delivered; sent only to a daemon that echoed
   * `confirm`, so an older daemon never sees the kind.
   */
  confirm: 4,
  /**
   * Item 79: a loan frame (a preview-tunnel frame of a loan stream, preview-tunnel/protocol.ts).
   * The only kind a loan channel carries, and never on any other channel. ASCII "L".
   */
  loan: 0x4c,
} as const;

/**
 * Audit RELAY-8: a padded frame's kind byte has this bit set and a 4-byte big-endian body length
 * follows it; zero bytes fill the rest of the frame to its size bucket. A receiver reads a padded
 * frame whatever was negotiated, so only the sender needs to know the peer asked for it.
 */
const PADDED_FRAME_FLAG = 0x80;
const PADDED_FRAME_HEADER_BYTES = 5;
const PAD_SMALL_STEP = 256;
const PAD_SMALL_LIMIT = 16 * 1024;
const PAD_LARGE_STEP = 4 * 1024;

/**
 * Audit RELAY-8: the framed plaintext length a padded frame of `unpaddedBytes` (header and body)
 * is sealed at: the next multiple of 256 bytes up to 16 KiB, then of 4 KiB. The relay learns a
 * frame's bucket, not its size.
 */
export function paddedFrameLength(unpaddedBytes: number): number {
  const step = unpaddedBytes <= PAD_SMALL_LIMIT ? PAD_SMALL_STEP : PAD_LARGE_STEP;
  return Math.max(step, Math.ceil(unpaddedBytes / step) * step);
}

/** Item 79: a loan channel closes with this when it receives a frame of any other kind. */
export const LOAN_FRAME_REFUSED_CLOSE_CODE = 4403;
const LOAN_FRAMES_ONLY = "Loan channel carries loan frames only";

/** A frame a loan channel refuses: it closes the channel with LOAN_FRAME_REFUSED_CLOSE_CODE. */
class LoanFrameRefusedError extends Error {
  constructor() {
    super(LOAN_FRAMES_ONLY);
  }
}

/**
 * Audit D16: the first bytes of an early frame's nonce from a client that sends a confirm frame.
 * The nonce is authenticated, so a relay cannot add or remove the mark; a daemon holds marked early
 * frames until a session frame arrives, whatever the (unsigned) hello capabilities say. An older
 * daemon ignores nonce contents, so marked frames still open there. 16 random bytes remain, and a
 * handshake key lives for one connection.
 */
const CONFIRMING_EARLY_NONCE_MARK = new Uint8Array([
  0x53, 0x48, 0x4b, 0x2d, 0x43, 0x4e, 0x46, 0x31,
]);
const NONCE_BYTES = 24;
/** Held early frames past this close the channel: a live client confirms within one round trip. */
const MAX_HELD_EARLY_FRAMES = 1024;

function isConfirmingEarlyNonce(bundle: Uint8Array): boolean {
  if (bundle.byteLength < NONCE_BYTES) return false;
  for (let i = 0; i < CONFIRMING_EARLY_NONCE_MARK.byteLength; i += 1) {
    if (bundle[i] !== CONFIRMING_EARLY_NONCE_MARK[i]) return false;
  }
  return true;
}

/**
 * An early frame sealed under the handshake key on a marked nonce. The random part comes from
 * `encrypt` over nothing, so it uses the same PRNG as every other seal on this platform.
 */
function sealConfirmingEarlyFrame(sharedKey: SharedKey, data: string): string {
  const nonce = new Uint8Array(encrypt(sharedKey, new ArrayBuffer(0)), 0, NONCE_BYTES);
  nonce.set(CONFIRMING_EARLY_NONCE_MARK, 0);
  const box = secretboxSeal(UTF8_ENCODER.encode(data), nonce, sharedKey);
  const out = new Uint8Array(NONCE_BYTES + box.byteLength);
  out.set(nonce, 0);
  out.set(box, NONCE_BYTES);
  return arrayBufferToBase64(out.buffer);
}

interface E2EEHelloMessage {
  type: "e2ee_hello";
  key: string;
  capabilities?: E2EECapabilities;
  /** The client proves it holds the account key (account-key.ts). */
  account?: RelayAccountProof;
  /** Shared projects (v6.0.0): a member proves its own account key for one share. */
  guest?: RelayGuestProof;
  /** Item 79: a borrower's daemon proves a delegated device key for one loan. */
  loan?: RelayLoanProof;
}

/**
 * What a shared project's member puts in its `e2ee_hello` (plan §6.3, guest-proof.ts). It never
 * verifies as an owner `account` proof, nor one as it, never rides beside one, and needs session
 * keys.
 */
export type { ProvenGuest, RelayGuestProof, ProvenLoan, RelayLoanProof };

interface E2EEReadyMessage {
  type: "e2ee_ready";
  capabilities?: E2EECapabilities;
  /** With `sessionKeys`: the daemon's ephemeral public key for this connection. */
  key?: string;
}

interface E2EECapabilities {
  binaryCiphertext?: boolean;
  /** W7: sealed frames all binary, the plaintext's first byte names the kind. */
  framedPlaintext?: boolean;
  /**
   * W7: frames may arrive deflate-raw packed (daemon → client only); needs framedPlaintext.
   * Audit RELAY-8: a current client never asks, a current daemon never echoes it, and neither
   * side reads it: a 5.0.0 client's hello may still carry it.
   */
  deflate?: boolean;
  /** Round 36 S3: forward-secret session keys with per-frame counters; needs framedPlaintext. */
  sessionKeys?: boolean;
  /**
   * Audit RELAY-8: this side reads padded frames, so the peer pads what it sends; needs
   * framedPlaintext. In the hello a client asks; a daemon that reads them echoes it in the ready.
   */
  padded?: boolean;
  /**
   * Audit D16: the client sends a confirm frame first when the ready echoes this; needs session
   * keys. Clients without it (released 5.0.0 apps) keep today's behaviour.
   */
  confirm?: boolean;
  /**
   * Audit RELAY-6, in the ready: this daemon reads a timed relay proof (account-key.ts v2). A
   * client sends one only to a daemon that said so, since a 5.0.0 daemon refuses it.
   */
  timedProof?: boolean;
  /**
   * Audit RELAY-10: the client's confirm frame carries the transcript hash (`handshakeTranscript`)
   * of the hello and ready, and a daemon that echoes this refuses a bare one. A hello that asks
   * for it also asks for everything above but `deflate` and `timedProof`; a ready that echoes it
   * also echoes `sessionKeys`, `confirm`, `padded` and `timedProof`. Either one short is a
   * downgrade.
   */
  transcript?: boolean;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isOptionalBoolean(value: unknown): boolean {
  return value === undefined || typeof value === "boolean";
}

function isE2EECapabilities(value: unknown): value is E2EECapabilities {
  return (
    value === undefined ||
    (isRecord(value) &&
      isOptionalBoolean(value.binaryCiphertext) &&
      isOptionalBoolean(value.framedPlaintext) &&
      isOptionalBoolean(value.deflate) &&
      isOptionalBoolean(value.sessionKeys) &&
      isOptionalBoolean(value.padded) &&
      isOptionalBoolean(value.confirm) &&
      isOptionalBoolean(value.timedProof) &&
      isOptionalBoolean(value.transcript))
  );
}

function isRelayAccountProof(value: unknown): value is RelayAccountProof | undefined {
  return (
    value === undefined ||
    (isRecord(value) &&
      typeof value.key === "string" &&
      typeof value.sig === "string" &&
      (value.at === undefined || typeof value.at === "number"))
  );
}

function isNonEmptyString(value: unknown, max: number): value is string {
  return typeof value === "string" && value.length > 0 && value.length <= max;
}

function isRelayGuestProof(value: unknown): value is RelayGuestProof | undefined {
  return (
    value === undefined ||
    (isRecord(value) &&
      typeof value.shareId === "string" &&
      PROJECT_SHARE_ID_PATTERN.test(value.shareId) &&
      isNonEmptyString(value.key, 128) &&
      isNonEmptyString(value.sig, 256) &&
      (value.at === undefined || typeof value.at === "number"))
  );
}

function isRelayLoanProof(value: unknown): value is RelayLoanProof | undefined {
  return value === undefined || isRelayLoanProofShape(value);
}

function isE2EEHelloMessage(value: unknown): value is E2EEHelloMessage {
  return (
    isRecord(value) &&
    value.type === "e2ee_hello" &&
    typeof value.key === "string" &&
    value.key.trim().length > 0 &&
    isE2EECapabilities(value.capabilities) &&
    isRelayAccountProof(value.account) &&
    isRelayGuestProof(value.guest) &&
    isRelayLoanProof(value.loan)
  );
}

function isE2EEReadyMessage(value: unknown): value is E2EEReadyMessage {
  return (
    isRecord(value) &&
    value.type === "e2ee_ready" &&
    isE2EECapabilities(value.capabilities) &&
    (value.key === undefined || typeof value.key === "string")
  );
}

function supportsBinaryCiphertext(message: E2EEHelloMessage | E2EEReadyMessage): boolean {
  return message.capabilities?.binaryCiphertext === true;
}

/**
 * Framing rides on binary ciphertext; padding (RELAY-8) rides on framing. Audit RELAY-8: `deflate`
 * is read by neither side, so a hello or ready that carries it (a 5.0.0 client's, or one a relay
 * wrote) agrees to nothing.
 */
function negotiatedFraming(message: E2EEHelloMessage | E2EEReadyMessage): {
  framedPlaintext: boolean;
  padded: boolean;
} {
  const framedPlaintext =
    supportsBinaryCiphertext(message) && message.capabilities?.framedPlaintext === true;
  return {
    framedPlaintext,
    padded: framedPlaintext && message.capabilities?.padded === true,
  };
}

function readyCapabilities(options: EncryptedChannelOptions): E2EECapabilities | undefined {
  if (!options.binaryCiphertext) return undefined;
  return {
    binaryCiphertext: true,
    ...(options.framedPlaintext ? { framedPlaintext: true } : {}),
    ...(options.framedPlaintext && options.session ? { sessionKeys: true } : {}),
    ...(options.framedPlaintext && options.padded ? { padded: true } : {}),
    ...(options.framedPlaintext && options.session?.confirm ? { confirm: true } : {}),
    // Audit RELAY-10: the confirm frame will carry the transcript hash, and a bare one is refused.
    ...(options.framedPlaintext && options.session?.transcript ? { transcript: true } : {}),
    // Audit RELAY-6: a daemon reads timed proofs; the client sends them from the next hello on.
    ...(options.framedPlaintext && options.session && options.daemonKeyPair
      ? { timedProof: true }
      : {}),
  };
}

function readyMessage(options: EncryptedChannelOptions): E2EEReadyMessage {
  const capabilities = readyCapabilities(options);
  return {
    type: "e2ee_ready",
    ...(capabilities ? { capabilities } : {}),
    ...(options.session && options.daemonEphemeralPublicKeyB64
      ? { key: options.daemonEphemeralPublicKeyB64 }
      : {}),
  };
}

function buildInvalidHelloError(rawText: string, parsed?: unknown): Error {
  const parsedRecord = isRecord(parsed) ? parsed : null;
  const rawType = parsedRecord?.type;
  function describeType(value: unknown): string {
    if (typeof value === "string") return value;
    if (value === undefined) return "undefined";
    return typeof value;
  }
  const receivedType = describeType(rawType);
  const hasKey = typeof parsedRecord?.key === "string" && parsedRecord.key.trim().length > 0;
  const compact = rawText.replace(/\s+/g, " ").trim();
  const preview = compact.length > 160 ? `${compact.slice(0, 157)}...` : compact;
  return new Error(
    `Invalid hello message (receivedType=${receivedType}, hasKey=${hasKey}, preview=${JSON.stringify(preview)})`,
  );
}

const HANDSHAKE_RETRY_MS = 1000;
const MAX_PENDING_SENDS = 200;
const PENDING_SENDS_FULL_CLOSE_REASON = "Send queue full before the encrypted link was ready";
/**
 * The channel's own failure close (a bad frame, a backlog that failed or overflowed). An
 * app-defined code, not 1011: the browser's WebSocket.close throws for any code but 1000 and
 * 3000–4999, so on the web app and Electron a 1011 never closed the link and nothing reconnected.
 */
const CHANNEL_FAILURE_CLOSE_CODE = 4011;
const REHANDSHAKE_REJECTION_CODE = 1008;
const ENCRYPTED_PAYLOAD_OVERHEAD_BYTES = 40;

export function base64EncryptedWireByteLength(plaintextBytes: number): number {
  return 4 * Math.ceil((plaintextBytes + ENCRYPTED_PAYLOAD_OVERHEAD_BYTES) / 3);
}

export function maxBase64EncryptedPlaintextByteLength(wireBytes: number): number {
  return Math.floor(wireBytes / 4) * 3 - ENCRYPTED_PAYLOAD_OVERHEAD_BYTES;
}
const REHANDSHAKE_KEY_MISMATCH_CLOSE_REASON = "E2EE re-handshake key mismatch";

interface TimeoutWithUnref {
  unref(): void;
}

function hasUnref(timeout: unknown): timeout is TimeoutWithUnref {
  return (
    typeof timeout === "object" &&
    timeout !== null &&
    "unref" in timeout &&
    typeof (timeout as Record<string, unknown>).unref === "function"
  );
}

/**
 * Audit RELAY-6: daemons (static key, base64) whose ready said they read timed proofs, in this
 * process. A hello to one of them carries the time inside its signature; to any other (a 5.0.0
 * daemon, or one not reached yet) the untimed proof, which every daemon reads.
 */
const timedProofDaemons = new Set<string>();

/** Whether a hello to this daemon carries the timed proof (RELAY-6). */
export function daemonTakesTimedProofs(daemonPublicKeyB64: string): boolean {
  return timedProofDaemons.has(daemonPublicKeyB64);
}

/** Records a daemon known to read timed proofs, from a ready or a caller's own memory of one. */
export function rememberTimedProofDaemon(daemonPublicKeyB64: string): void {
  timedProofDaemons.add(daemonPublicKeyB64);
}

/**
 * Audit RELAY-10: the capabilities a client pins per daemon (its static key) once a ready that
 * named them was followed by a session frame the daemon sealed. A later ready from that daemon
 * without one of them is refused (`ChannelDowngradeError`): a relay deleted it, or the daemon was
 * rolled back to an older release.
 */
export const DAEMON_CHANNEL_LEVEL = [
  "sessionKeys",
  "confirm",
  "padded",
  "transcript",
  "timedProof",
] as const;
export type DaemonChannelCapability = (typeof DAEMON_CHANNEL_LEVEL)[number];

/** Audit RELAY-10: each daemon's pinned level in this process (static key, base64). */
const daemonChannelLevels = new Map<string, Set<DaemonChannelCapability>>();
const daemonChannelLevelListeners = new Set<
  (daemonPublicKeyB64: string, level: DaemonChannelCapability[]) => void
>();

function isDaemonChannelCapability(value: unknown): value is DaemonChannelCapability {
  return (DAEMON_CHANNEL_LEVEL as readonly unknown[]).includes(value);
}

/** Audit RELAY-10: what this process has pinned for a daemon, in `DAEMON_CHANNEL_LEVEL` order. */
export function daemonChannelLevel(daemonPublicKeyB64: string): DaemonChannelCapability[] {
  const level = daemonChannelLevels.get(daemonPublicKeyB64);
  return level ? DAEMON_CHANNEL_LEVEL.filter((capability) => level.has(capability)) : [];
}

/**
 * Audit RELAY-10: adds to a daemon's pinned level (it only grows). A caller's stored memory goes
 * in here at startup; names this build does not know are dropped. Listeners are told only of
 * what a handshake pinned, so a store loading itself writes nothing back. True when it grew.
 */
export function rememberDaemonChannelLevel(
  daemonPublicKeyB64: string,
  level: readonly unknown[],
): boolean {
  return pinDaemonChannelLevel(daemonPublicKeyB64, level, false);
}

function pinDaemonChannelLevel(
  daemonPublicKeyB64: string,
  level: readonly unknown[],
  notify: boolean,
): boolean {
  const known = level.filter(isDaemonChannelCapability);
  if (!daemonPublicKeyB64 || known.length === 0) return false;
  let pinned = daemonChannelLevels.get(daemonPublicKeyB64);
  if (!pinned) {
    pinned = new Set();
    daemonChannelLevels.set(daemonPublicKeyB64, pinned);
  }
  const before = pinned.size;
  for (const capability of known) pinned.add(capability);
  if (pinned.has("timedProof")) timedProofDaemons.add(daemonPublicKeyB64);
  if (pinned.size === before) return false;
  if (notify) {
    const snapshot = daemonChannelLevel(daemonPublicKeyB64);
    for (const listener of daemonChannelLevelListeners) {
      try {
        listener(daemonPublicKeyB64, snapshot);
      } catch {
        // A store that fails costs only the durability: the memory still holds the pin.
      }
    }
  }
  return true;
}

/**
 * Audit RELAY-10: told whenever a handshake raises a daemon's pinned level (to store it), and with
 * an empty level when `forgetDaemonChannelLevel` drops it.
 */
export function onDaemonChannelLevel(
  listener: (daemonPublicKeyB64: string, level: DaemonChannelCapability[]) => void,
): () => void {
  daemonChannelLevelListeners.add(listener);
  return () => daemonChannelLevelListeners.delete(listener);
}

/**
 * Audit RELAY-10: drops a daemon's pin (and the timed proof it carried), for a person who
 * knowingly went back to an older server, and for tests. Nothing else lowers a pin. Listeners are
 * told with an empty level, so a store drops it too.
 */
export function forgetDaemonChannelLevel(daemonPublicKeyB64: string): void {
  if (!daemonChannelLevels.delete(daemonPublicKeyB64)) return;
  timedProofDaemons.delete(daemonPublicKeyB64);
  for (const listener of daemonChannelLevelListeners) {
    try {
      listener(daemonPublicKeyB64, []);
    } catch {
      // A store that fails keeps the old pin on disk; the memory has already let it go.
    }
  }
}

/** Audit RELAY-10: the message every refused downgrade starts with. */
export const E2EE_DOWNGRADE_REFUSED = "E2EE downgrade refused";

/**
 * Audit RELAY-10: a client refused a ready that offers less than it must: less than this daemon
 * offered before (`missing`, an older server or a relay rewriting the handshake), or no session
 * keys for a channel that would carry a proof or a credential.
 */
export class ChannelDowngradeError extends Error {
  readonly missing: DaemonChannelCapability[];
  constructor(detail: string, missing: DaemonChannelCapability[] = []) {
    super(`${E2EE_DOWNGRADE_REFUSED}: ${detail}`);
    this.name = "ChannelDowngradeError";
    this.missing = missing;
  }
}

/** Whether a close reason or error message is a refused downgrade (RELAY-10). */
export function isChannelDowngrade(reasonOrMessage: string): boolean {
  return reasonOrMessage.startsWith(E2EE_DOWNGRADE_REFUSED);
}

const TRANSCRIPT_HMAC_KEY = utf8("shuriken/e2ee-transcript/v1");
/** Audit RELAY-10: how many bytes of the transcript HMAC a confirm frame carries. */
export const HANDSHAKE_TRANSCRIPT_BYTES = 32;

/**
 * Audit RELAY-10: T = the first 32 bytes of HMAC-SHA-512(key utf8("shuriken/e2ee-transcript/v1"),
 * u32be(len hello) ‖ hello ‖ u32be(len ready) ‖ ready), over the UTF-8 of the exact wire text:
 * the client's hello as sent and ready as read, the daemon's hello as read and ready as sent. It
 * rides in the client's confirm frame, sealed under the session key, so a relay that changed
 * either text cannot make the daemon's T match.
 */
export function handshakeTranscript(helloText: string, readyText: string): Uint8Array {
  const hello = UTF8_ENCODER.encode(helloText);
  const ready = UTF8_ENCODER.encode(readyText);
  const message = new Uint8Array(8 + hello.byteLength + ready.byteLength);
  const view = new DataView(message.buffer);
  view.setUint32(0, hello.byteLength);
  message.set(hello, 4);
  view.setUint32(4 + hello.byteLength, ready.byteLength);
  message.set(ready, 8 + hello.byteLength);
  return hmacSha512(TRANSCRIPT_HMAC_KEY, message).slice(0, HANDSHAKE_TRANSCRIPT_BYTES);
}

/** What a ready that echoes `transcript` (a RELAY-10 daemon answering a RELAY-10 client) also says. */
const IMPLIED_BY_TRANSCRIPT: readonly DaemonChannelCapability[] = [
  "sessionKeys",
  "confirm",
  "padded",
  "timedProof",
];

/**
 * Client side, audit RELAY-10: throws `ChannelDowngradeError` when a ready offers less than this
 * daemon's pin, or echoes `transcript` without what every daemon that echoes it also says.
 */
function checkReadyLevel(ready: E2EEReadyMessage, daemonPublicKeyB64: string | undefined): void {
  const capabilities = ready.capabilities ?? {};
  const offered = (capability: DaemonChannelCapability) => capabilities[capability] === true;
  const pinned = daemonPublicKeyB64 ? daemonChannelLevel(daemonPublicKeyB64) : [];
  const missing = pinned.filter((capability) => !offered(capability));
  if (missing.length > 0) {
    throw new ChannelDowngradeError(
      `this server's handshake left out ${missing.join(", ")}, which it offered before ` +
        "(the server is older than it was, or the relay rewrote the handshake)",
      missing,
    );
  }
  if (offered("transcript")) {
    const short = IMPLIED_BY_TRANSCRIPT.filter((capability) => !offered(capability));
    if (short.length > 0) {
      throw new ChannelDowngradeError(
        `the ready names transcript without ${short.join(", ")}`,
        short,
      );
    }
  }
}

/** Client side, audit RELAY-10: the level a ready names, pinned once the daemon's frame opens. */
function readyLevel(ready: E2EEReadyMessage): DaemonChannelCapability[] {
  const capabilities = ready.capabilities ?? {};
  return DAEMON_CHANNEL_LEVEL.filter((capability) => capabilities[capability] === true);
}

/** The one proof a client's hello carries, if any: account, guest or loan, never two. */
async function signClientProofs(
  security: ClientChannelSecurity,
  daemonPublicKey: Uint8Array,
  clientPublicKey: Uint8Array,
  at?: number,
): Promise<Pick<E2EEHelloMessage, "account" | "guest" | "loan">> {
  if (security.loan && (security.account || security.guest)) {
    throw new Error("One proof per handshake");
  }
  if (security.account && security.guest) {
    throw new Error("Account and guest proofs together refused");
  }
  if (security.account) {
    return {
      account: await signRelayClient(security.account, daemonPublicKey, clientPublicKey, { at }),
    };
  }
  if (security.guest) {
    const { signer, shareId } = security.guest;
    return {
      guest: await signRelayGuest(signer, shareId, daemonPublicKey, clientPublicKey, { at }),
    };
  }
  if (security.loan) {
    return {
      loan: await signRelayLoan({
        ...security.loan,
        daemonPublicKey,
        clientEphemeralPublicKey: clientPublicKey,
      }),
    };
  }
  return {};
}

/**
 * Creates an encrypted channel as the initiator (client).
 *
 * The client:
 * 1. Receives daemon's public key via QR code
 * 2. Generates own keypair
 * 3. Sends e2ee_hello with own public key
 * 4. Derives shared key and starts encrypted communication
 */
export async function createClientChannel(
  transport: Transport,
  daemonPublicKeyB64: string,
  events: EncryptedChannelEvents = {},
  codec: EncryptedChannelCodec = {},
  security: ClientChannelSecurity = {},
): Promise<EncryptedChannel> {
  const keyPair = generateKeyPair();
  const daemonPublicKey = importPublicKey(daemonPublicKeyB64);
  const sharedKey = deriveSharedKey(keyPair.secretKey, daemonPublicKey);
  const proofs = await signClientProofs(
    security,
    daemonPublicKey,
    keyPair.publicKey,
    timedProofDaemons.has(daemonPublicKeyB64) ? Date.now() : undefined,
  );
  // A loan channel carries only binary loan frames: nothing to pipeline, nothing packed.
  const loan = proofs.loan !== undefined;

  // Send e2ee_hello with our public key. W7: ask for framed binary frames always. Round 36 S3:
  // and for session keys. Audit RELAY-8: and for padded frames, never for packed ones (an older
  // daemon packs only when asked). Audit RELAY-10: and for the transcript in the confirm frame.
  const ourPublicKeyB64 = exportPublicKey(keyPair.publicKey);
  const hello: E2EEHelloMessage = {
    type: "e2ee_hello",
    key: ourPublicKeyB64,
    capabilities: {
      binaryCiphertext: true,
      framedPlaintext: true,
      sessionKeys: true,
      confirm: true,
      padded: true,
      transcript: true,
    },
    ...proofs,
  };
  const helloText = JSON.stringify(hello);

  const channel = new EncryptedChannel(transport, sharedKey, events, {
    pipelineText: !loan,
    ...(codec.mayPipeline && !loan ? { mayPipeline: codec.mayPipeline } : {}),
    ...(loan ? { loan: true } : {}),
    timedProofDaemonKeyB64: daemonPublicKeyB64,
    helloText,
    ...(proofs.account || proofs.guest || proofs.loan ? { provedPeer: true } : {}),
    credentialsNeedSessionKeys: true,
    session: {
      pending: { ephemeral: keyPair, daemonStaticPublicKey: daemonPublicKey },
      sendCounter: 0,
      receiveCounter: 0,
    },
  });

  let retry: ReturnType<typeof setInterval> | null = null;
  const emitSendError = (error: unknown) => {
    const err = error instanceof Error ? error : new Error(String(error));
    events.onerror?.(err);
  };
  const sendHello = () => {
    try {
      const result = transport.send(helloText);
      if (result) {
        void result.catch(emitSendError);
      }
      return true;
    } catch (error) {
      // This can happen during daemon restarts while the socket transitions
      // through CLOSING/CLOSED states. Report it but do not throw from timers.
      emitSendError(error);
      return false;
    }
  };
  const clearRetry = () => {
    if (retry) {
      clearInterval(retry);
      retry = null;
    }
  };

  channel.onTransitionToOpen(() => clearRetry());
  channel.onClose(() => clearRetry());

  sendHello();
  retry = setInterval(() => {
    if (channel.isOpen()) {
      clearRetry();
      return;
    }
    sendHello();
  }, HANDSHAKE_RETRY_MS);
  // Avoid keeping Node processes alive (e.g. tests) if the handshake is stuck.
  if (hasUnref(retry)) {
    retry.unref();
  }

  return channel;
}

/**
 * Who the hello proves it is: the account (the owner's devices) or the member of one share, never
 * both. A proof that is present must verify; a guest proof needs a listener that admits guests.
 */
function provenPeer(
  msg: E2EEHelloMessage,
  daemonPublicKey: Uint8Array,
  clientPublicKey: Uint8Array,
  security: DaemonChannelSecurity,
): { accountKey: string | null; guest: ProvenGuest | null; loan: ProvenLoan | null } {
  // A member is never also the owner: one handshake carries one kind of proof.
  if (msg.loan && (msg.account || msg.guest)) throw new Error("One proof per handshake");
  if (msg.account && msg.guest) throw new Error("Account and guest proofs together refused");
  // Audit RELAY-6: a timed proof verifies only inside its window of this daemon's clock.
  const now = security.now?.() ?? Date.now();
  const accountKey = verifyRelayClient(msg.account, daemonPublicKey, clientPublicKey, { now });
  if (msg.account && !accountKey) throw new Error("Invalid account proof");
  if (msg.guest && security.guests !== true) {
    throw new Error("Guest proof refused on this listener");
  }
  const guest = verifyRelayGuest(msg.guest, daemonPublicKey, clientPublicKey, { now });
  if (msg.guest && !guest) throw new Error("Invalid guest proof");
  if (msg.loan && security.loans !== true) {
    throw new Error("Loan proof refused on this listener");
  }
  const loan = verifyRelayLoan(msg.loan, daemonPublicKey, clientPublicKey);
  if (msg.loan && !loan) throw new Error("Invalid loan proof");
  return { accountKey, guest, loan };
}

/**
 * The daemon's half of a hello: the keys, what was agreed, and the account (or the member of a
 * share) the client proved.
 */
function acceptHello(
  msg: E2EEHelloMessage,
  daemonKeyPair: KeyPair,
  security: DaemonChannelSecurity,
): {
  sharedKey: SharedKey;
  channelOptions: EncryptedChannelOptions;
  accountKey: string | null;
  guest: ProvenGuest | null;
  loan: ProvenLoan | null;
} {
  const clientPublicKey = importPublicKey(msg.key);
  const sharedKey = deriveSharedKey(daemonKeyPair.secretKey, clientPublicKey);
  // Audit RELAY-6: the proofs first, so a hello whose proof fails never takes a place in the
  // memory below.
  const { accountKey, guest, loan } = provenPeer(
    msg,
    daemonKeyPair.publicKey,
    clientPublicKey,
    security,
  );
  // A recorded handshake played again (by the relay, or anyone on the path) would replay
  // its early frames into a new session: every client key is fresh, so a repeat is refused.
  const seen = security.seenClientKeys ?? processSeenClientKeys;
  if (!seen.remember(handshakeReplayKey(sharedKey), Boolean(accountKey || guest || loan))) {
    throw new Error("Replayed E2EE handshake");
  }

  const binaryCiphertext = supportsBinaryCiphertext(msg);
  const framing = negotiatedFraming(msg);
  const sessionKeys = framing.framedPlaintext && msg.capabilities?.sessionKeys === true;
  // Every client that proves the account (or a share) also asks for session keys, so a proof
  // without them is a relay that stripped the request to force the weaker channel.
  if ((accountKey || guest || loan) && !sessionKeys) throw new Error(E2EE_DOWNGRADE_REFUSED);
  const transcript = helloAsksTranscript(msg, sessionKeys, framing.padded);
  const daemonEphemeral = sessionKeys ? generateKeyPair() : null;
  const session: SessionKeyState | undefined = daemonEphemeral
    ? {
        ...deriveSessionKeys({
          role: "daemon",
          ourEphemeral: daemonEphemeral,
          daemonStatic: daemonKeyPair,
          peerEphemeralPublicKey: clientPublicKey,
          clientEphemeralPublicKey: clientPublicKey,
          daemonEphemeralPublicKey: daemonEphemeral.publicKey,
        }),
        sendCounter: 0,
        receiveCounter: 0,
        earlyNonces: new Set(),
        sawSessionFrame: false,
        heldEarly: [],
        ...(msg.capabilities?.confirm === true ? { confirm: true } : {}),
        ...(transcript ? { transcript: true } : {}),
      }
    : undefined;
  daemonEphemeral?.secretKey.fill(0);
  const channelOptions: EncryptedChannelOptions = {
    daemonKeyPair,
    binaryCiphertext,
    framedPlaintext: framing.framedPlaintext,
    ...(loan ? { loan: true } : {}),
    // Audit RELAY-8: pad what goes to a client that reads padding.
    padded: framing.padded,
    ...(session && daemonEphemeral
      ? {
          session,
          daemonEphemeralPublicKeyB64: exportPublicKey(daemonEphemeral.publicKey),
        }
      : {}),
  };
  return { sharedKey, channelOptions, accountKey, guest, loan };
}

/**
 * Daemon side, audit RELAY-10: whether the hello asks for the transcript. A client that asks for
 * it asks for session keys, padding and the confirm frame too, so a hello that kept `transcript`
 * and lost one of them was cut down on the way: refused.
 */
function helloAsksTranscript(
  msg: E2EEHelloMessage,
  sessionKeys: boolean,
  padded: boolean,
): boolean {
  if (msg.capabilities?.transcript !== true) return false;
  if (!(sessionKeys && padded && msg.capabilities.confirm === true)) {
    throw new Error(`${E2EE_DOWNGRADE_REFUSED}: the hello names transcript without the rest`);
  }
  return true;
}

/**
 * Creates an encrypted channel as the responder (daemon).
 *
 * The daemon:
 * 1. Has pre-generated keypair (public key was in QR)
 * 2. Waits for client's e2ee_hello with their public key
 * 3. Derives shared key and starts encrypted communication
 */
export async function createDaemonChannel(
  transport: Transport,
  daemonKeyPair: KeyPair,
  events: EncryptedChannelEvents = {},
  // Audit RELAY-8: a daemon packs nothing, so its codec carries nothing it uses; the slot stays
  // so callers keep their argument order.
  _codec: EncryptedChannelCodec = {},
  security: DaemonChannelSecurity = {},
): Promise<EncryptedChannel> {
  return new Promise((resolve, reject) => {
    const bufferedMessages: TransportMessage[] = [];
    const shouldIgnorePostHelloPlaintext = (message: TransportMessage): boolean => {
      try {
        if (message.isBinary) return false;
        const text = decodeTransportText(message.data);
        const parsed: unknown = JSON.parse(text);
        return isE2EEHelloMessage(parsed) || isE2EEReadyMessage(parsed);
      } catch {
        return false;
      }
    };

    const handleHello = async (message: TransportMessage): Promise<void> => {
      try {
        if (message.isBinary) {
          throw buildInvalidHelloError("<binary frame>");
        }
        const helloText = decodeTransportText(message.data);

        let parsed: unknown;
        try {
          parsed = JSON.parse(helloText);
        } catch {
          throw buildInvalidHelloError(helloText);
        }

        if (!isE2EEHelloMessage(parsed)) {
          throw buildInvalidHelloError(helloText, parsed);
        }

        const msg = parsed;

        // Buffer any subsequent messages that arrive while we're doing async
        // WebCrypto work to derive the shared key. Without this, it's possible
        // for the next message (already encrypted) to be misinterpreted as a
        // second hello, causing the handshake to fail.
        const bufferNext = (next: TransportMessage): void => {
          bufferedMessages.push(next);
        };
        Object.assign(transport, { onmessage: bufferNext });

        const { sharedKey, channelOptions, accountKey, guest, loan } = acceptHello(
          msg,
          daemonKeyPair,
          security,
        );
        // Audit RELAY-10: the ready is sent (and resent) as this one text, and the transcript
        // binds the hello as read to it.
        const readyText = JSON.stringify(readyMessage(channelOptions));
        channelOptions.readyText = readyText;
        if (channelOptions.session?.confirm) {
          channelOptions.session.expectedTranscript = handshakeTranscript(helloText, readyText);
        }
        await transport.send(readyText);

        const channel = new EncryptedChannel(transport, sharedKey, events, channelOptions);
        channel.peerAccountKey = accountKey;
        channel.peerGuest = guest;
        channel.peerLoan = loan;
        channel.setState("open");
        events.onopen?.();

        for (const buffered of bufferedMessages) {
          if (shouldIgnorePostHelloPlaintext(buffered)) continue;
          transport.onmessage?.(buffered);
        }

        resolve(channel);
      } catch (error) {
        reject(error);
      }
    };

    Object.assign(transport, {
      onmessage: handleHello,
      onerror: (error: Error) => {
        reject(error);
      },
      onclose: (code: number, reason: string) => {
        reject(new Error(`Connection closed during handshake: ${code} ${reason}`));
      },
    });
  });
}

/**
 * Audit RELAY-8: a padded frame as the unpadded kind byte and body (a view, no copy); any other
 * frame as it is. A body length past the frame, or padding that is not zero, fails the channel.
 */
function unpadFrame(frame: Uint8Array): Uint8Array {
  if (frame.byteLength === 0 || (frame[0]! & PADDED_FRAME_FLAG) === 0) return frame;
  if (frame.byteLength < PADDED_FRAME_HEADER_BYTES) throw new Error("Truncated padded frame");
  const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
  const end = PADDED_FRAME_HEADER_BYTES + view.getUint32(1);
  if (end > frame.byteLength) throw new Error("Padded frame body past its end");
  for (let i = end; i < frame.byteLength; i += 1) {
    if (frame[i] !== 0) throw new Error("Padded frame with non-zero padding");
  }
  // The kind byte goes in the byte before the body, so the result is one contiguous view.
  const out = frame.subarray(PADDED_FRAME_HEADER_BYTES - 1, end);
  out[0] = frame[0]! & ~PADDED_FRAME_FLAG;
  return out;
}

/**
 * Encrypted channel that wraps a transport with E2EE.
 */
export class EncryptedChannel {
  private transport: Transport;
  private sharedKey: SharedKey;
  private state: ChannelState = "handshaking";
  private events: EncryptedChannelEvents;
  private options: EncryptedChannelOptions;
  private pendingSends: Array<string | ArrayBuffer> = [];
  /**
   * Client side, audits RELAY-6 and RELAY-10: the level the ready named (`timedProof` among it),
   * pinned for the daemon once a session frame it sealed opens; null once pinned or when none.
   */
  private levelPending: DaemonChannelCapability[] | null = null;
  /** Client side, audit RELAY-10: the transcript hash the confirm frames carry. */
  private transcript: Uint8Array | null = null;
  /**
   * Client side, audit RELAY-10: the ready echoed `transcript`, so the daemon's first session
   * frame must be its own confirm, `[0x04] ‖ T`. Only that frame proves the daemon checked T, so
   * only it pins the level: any older daemon seals frames too, after a ready a relay could have
   * raised.
   */
  private awaitingDaemonConfirm = false;
  /**
   * Daemon side, audit RELAY-10: what the daemon sends before a transcript client's confirm has
   * checked out. It goes after the daemon's own confirm, which is its session frame 0.
   */
  private heldForConfirm: Array<{
    data: string | ArrayBuffer;
    sent: (value: void | PromiseLike<void>) => void;
    failed: (error: unknown) => void;
  }> = [];
  private onOpenCallbacks: Array<() => void> = [];
  private onCloseCallbacks: Array<() => void> = [];
  /**
   * Daemon side: the account key the client proved it holds in this handshake (base64), or null
   * when it proved none. Who may use the daemon is decided from this, never from the relay.
   */
  peerAccountKey: string | null = null;
  /**
   * Daemon side, shared projects (v6.0.0): the member account key and share the client proved
   * (guest-proof.ts), or null. It says who asks, never what they may do: that needs a live,
   * owner-signed grant for the share naming this key (project-grant.ts). Never set beside
   * `peerAccountKey`.
   */
  peerGuest: ProvenGuest | null = null;
  /**
   * Daemon side, item 79: the loan and delegated device key a borrower's daemon proved
   * (loan-proof.ts), or null. Admission needs `admitLoan` against a verified grant as well. Never
   * set beside `peerAccountKey` or `peerGuest`; when set, the channel carries loan frames only.
   */
  peerLoan: ProvenLoan | null = null;

  constructor(
    transport: Transport,
    sharedKey: SharedKey,
    events: EncryptedChannelEvents = {},
    options: EncryptedChannelOptions = {},
  ) {
    this.transport = transport;
    this.sharedKey = sharedKey;
    this.events = events;
    this.options = options;

    Object.assign(transport, {
      onmessage: (message: TransportMessage) => this.handleMessage(message),
      onclose: (code: number, reason: string) => {
        this.state = "closed";
        // Audit D16: early frames never confirmed by a live client go with the channel.
        if (this.options.session) this.options.session.heldEarly = undefined;
        this.dropHeldForConfirm();
        this.events.onclose?.(code, reason);
        for (const cb of this.onCloseCallbacks) cb();
      },
      onerror: (error: Error) => {
        this.events.onerror?.(error);
      },
    });
  }

  setState(state: ChannelState): void {
    this.state = state;
  }

  private async handleMessage(message: TransportMessage): Promise<void> {
    if (this.state === "handshaking") {
      try {
        if (message.isBinary) return;
        const text = decodeTransportText(message.data);
        const parsed: unknown = JSON.parse(text);
        if (isE2EEReadyMessage(parsed)) {
          // Audit RELAY-10: a ready short of this daemon's pinned level is refused before
          // anything goes under it.
          try {
            checkReadyLevel(parsed, this.options.timedProofDaemonKeyB64);
          } catch (error) {
            this.refuseDowngrade(error);
            return;
          }
          // Audit RELAY-10: the hello as sent and this ready as read.
          this.transcript =
            this.options.helloText !== undefined
              ? handshakeTranscript(this.options.helloText, text)
              : null;
          // Audit RELAY-6 and RELAY-10: the level this ready names (`timedProof` among it). The
          // ready is plaintext anyone on the path can write, and a frame any daemon seals proves
          // nothing about it (a relay can raise an older daemon's ready and still get its
          // frames), so it is pinned only once the daemon's own confirm frame, which carries T,
          // opens (receiveSessionFrame). A ready without `transcript` pins nothing.
          this.awaitingDaemonConfirm =
            this.transcript !== null &&
            parsed.capabilities?.transcript === true &&
            parsed.capabilities.sessionKeys === true;
          this.levelPending =
            this.awaitingDaemonConfirm && this.options.timedProofDaemonKeyB64 !== undefined
              ? readyLevel(parsed)
              : null;
          this.options.binaryCiphertext = supportsBinaryCiphertext(parsed);
          const framing = negotiatedFraming(parsed);
          this.options.framedPlaintext = framing.framedPlaintext;
          // Audit RELAY-8: pad only for a daemon that reads padding (an older one does not). An
          // echoed `deflate` is ignored, and a packed frame fails the channel.
          this.options.padded = framing.padded;
          try {
            this.finishClientSession(parsed, framing.framedPlaintext);
          } catch (error) {
            this.failHandshake(error);
            return;
          }
          this.state = "open";
          // Taken before anything the open callbacks send, so it is session frame 0.
          const confirmed = this.sendConfirm(parsed);
          confirmed.catch(() => undefined);
          this.events.onopen?.();
          for (const cb of this.onOpenCallbacks) cb();
          try {
            await confirmed;
            await this.flushPendingSends();
          } catch (error) {
            const err = error instanceof Error ? error : new Error(String(error));
            this.events.onerror?.(err);
            this.state = "closed";
            this.transport.close(CHANNEL_FAILURE_CLOSE_CODE, err.message);
          }
        }
      } catch {
        // ignore non-ready handshake traffic
      }
      return;
    }

    if (this.state !== "open") return;

    if (this.options.session) {
      this.receiveSessionFrame(message);
      return;
    }

    await this.receiveOpen(message);
  }

  private async receiveOpen(message: TransportMessage): Promise<void> {
    if (this.state !== "open") return;
    try {
      if (this.options.framedPlaintext && message.isBinary) {
        const plaintext = this.unframe(
          new Uint8Array(decrypt(this.sharedKey, requireArrayBuffer(message.data))),
        );
        this.events.onmessage?.(plaintext);
        return;
      }
      const ciphertext = await (async () => {
        // Handle (or ignore) any stray plaintext handshake traffic.
        try {
          if (message.isBinary) throw new Error("not plaintext handshake traffic");
          const text = decodeTransportText(message.data);
          if (text.trim().startsWith("{")) {
            const parsed: unknown = JSON.parse(text);

            if (isE2EEHelloMessage(parsed)) {
              if (this.options.daemonKeyPair) {
                await this.handleDaemonRehello(parsed);
              }
              return null;
            }

            if (isE2EEReadyMessage(parsed)) {
              return null;
            }

            // Any other JSON-looking payload is plaintext app traffic, which
            // means the peer is not encrypting (or we are out of sync).
            throw new Error("Received plaintext frame on encrypted channel");
          }
        } catch (error) {
          // If we detected plaintext protocol mismatch, fail hard.
          if (error instanceof Error && error.message.includes("plaintext frame")) {
            throw error;
          }
          // Otherwise ignore JSON parse/TextDecoder failures and fall back to
          // decoding ciphertext below.
        }

        if (this.options.binaryCiphertext) {
          return message.isBinary
            ? { data: requireArrayBuffer(message.data), isBinary: true as const }
            : {
                data: base64ToArrayBuffer(decodeTransportText(message.data)),
                isBinary: false as const,
              };
        }

        // COMPAT(binaryCiphertext): added in v0.2.3, remove legacy base64-only
        // receive mode after 2027-01-27.
        if (!message.isBinary) {
          return { data: base64ToArrayBuffer(decodeTransportText(message.data)), isBinary: null };
        }

        // Older transport adapters could lose the opcode. Retain the former
        // base64-first behavior only in the legacy path.
        try {
          return { data: base64ToArrayBuffer(decodeTransportText(message.data)), isBinary: null };
        } catch {
          return { data: requireArrayBuffer(message.data), isBinary: null };
        }
      })();

      if (ciphertext) {
        // Audit D16: only a client that asks for session keys marks its early frames, so one on a
        // daemon channel without them is a hello the relay stripped to deliver it unconfirmed.
        if (
          this.options.daemonKeyPair &&
          ciphertext.isBinary !== true &&
          isConfirmingEarlyNonce(new Uint8Array(ciphertext.data))
        ) {
          throw new Error("Confirming early frame without session keys");
        }
        const plaintextBytes = decrypt(this.sharedKey, ciphertext.data);
        const plaintext = decodePlaintext(plaintextBytes, ciphertext.isBinary);
        this.events.onmessage?.(plaintext);
      }
    } catch (error) {
      const err = error instanceof Error ? error : new Error(String(error));

      // Treat decryption/protocol errors as fatal so the peer can reconnect and
      // re-handshake. Emitting an error event here can cause higher-level code
      // to tear down the session without triggering a clean reconnect.
      try {
        this.transport.close(failureCloseCode(err), err.message);
      } catch {
        // ignore
      }
    }
  }

  async send(data: string | ArrayBuffer): Promise<void> {
    if (this.options.loan && typeof data === "string") throw new Error(LOAN_FRAMES_ONLY);
    if (this.state === "handshaking") {
      if (
        this.options.pipelineText &&
        typeof data === "string" &&
        this.pendingSends.length === 0 &&
        this.mayPipeline(data)
      ) {
        // Audit D16: marked, so a daemon holds it until this client proves it is live.
        await this.transport.send(sealConfirmingEarlyFrame(this.sharedKey, data));
        return;
      }
      if (this.pendingSends.length >= MAX_PENDING_SENDS) {
        // A full backlog never drops a frame (an RPC or a prompt would vanish with no reconnect):
        // close like a protocol error, so the client reconnects and its callers send again.
        this.state = "closed";
        this.pendingSends = [];
        this.transport.close(CHANNEL_FAILURE_CLOSE_CODE, PENDING_SENDS_FULL_CLOSE_REASON);
        throw new Error(PENDING_SENDS_FULL_CLOSE_REASON);
      }
      this.pendingSends.push(data);
      return;
    }

    if (this.state !== "open") {
      throw new Error("Channel not open");
    }

    const session = this.options.session;
    this.refuseUnsealedCredential(data, session);
    if (this.options.daemonKeyPair && session?.transcript && !session.confirmed) {
      return this.holdForConfirm(data);
    }
    if (session?.sendKey) {
      // The counter is taken and the frame handed to the transport in the same turn, so frames
      // leave in counter order however sends interleave.
      const counter = session.sendCounter;
      session.sendCounter += 1;
      await this.transport.send(encryptWithCounter(session.sendKey, counter, this.frame(data)));
      return;
    }

    if (this.options.framedPlaintext) {
      await this.transport.send(encrypt(this.sharedKey, this.frame(data)));
      return;
    }
    const ciphertext = encrypt(this.sharedKey, data);
    if (this.options.binaryCiphertext && data instanceof ArrayBuffer) {
      await this.transport.send(ciphertext);
      return;
    }
    // COMPAT(binaryCiphertext): added in v0.2.3, remove base64 binary sends
    // after 2027-01-27 once the supported peer floor includes negotiation.
    await this.transport.send(arrayBufferToBase64(ciphertext));
  }

  /** Audit RELAY-10 (D): a credential is never sealed under the handshake key, which a
   * later-stolen daemon key opens. Throws (and fails the channel). */
  private refuseUnsealedCredential(
    data: string | ArrayBuffer,
    session: SessionKeyState | undefined,
  ): void {
    if (session?.sendKey || !this.options.credentialsNeedSessionKeys) return;
    if (typeof data !== "string" || !carriesSessionCredential(data)) return;
    const error = new ChannelDowngradeError("a credential needs session keys");
    this.refuseDowngrade(error);
    throw error;
  }

  /**
   * Daemon side, audit RELAY-10: the daemon's confirm is its session frame 0, so nothing goes
   * before a transcript client's confirm checked out. Settles when the frame is handed on, so a
   * caller waiting on the socket still waits.
   */
  private holdForConfirm(data: string | ArrayBuffer): Promise<void> {
    if (this.heldForConfirm.length >= MAX_PENDING_SENDS) {
      this.failChannel(new Error(PENDING_SENDS_FULL_CLOSE_REASON));
      return Promise.reject(new Error(PENDING_SENDS_FULL_CLOSE_REASON));
    }
    return new Promise<void>((sent, failed) => {
      this.heldForConfirm.push({ data, sent, failed });
    });
  }

  /** Audit RELAY-2: a credential never rides early, and the caller's rule may hold back more. */
  private mayPipeline(text: string): boolean {
    if (carriesSessionCredential(text)) return false;
    return this.options.mayPipeline ? this.options.mayPipeline(text) : true;
  }

  /**
   * Kind byte, then the bytes, padded to the bucket when the peer reads padding. Audit RELAY-8:
   * never packed, so a frame's length never follows how well its content compresses.
   */
  private frame(data: string | ArrayBuffer): ArrayBuffer {
    const text = typeof data === "string";
    const bytes = text ? UTF8_ENCODER.encode(data) : new Uint8Array(data);
    if (this.options.loan && text) throw new Error(LOAN_FRAMES_ONLY);
    let kind: number = text ? FrameKind.text : FrameKind.binary;
    if (this.options.loan) kind = FrameKind.loan;
    if (!this.options.padded) {
      const out = new Uint8Array(1 + bytes.byteLength);
      out[0] = kind;
      out.set(bytes, 1);
      return out.buffer;
    }
    const out = new Uint8Array(paddedFrameLength(PADDED_FRAME_HEADER_BYTES + bytes.byteLength));
    out[0] = kind | PADDED_FRAME_FLAG;
    new DataView(out.buffer).setUint32(1, bytes.byteLength);
    out.set(bytes, PADDED_FRAME_HEADER_BYTES);
    return out.buffer;
  }

  private unframe(sealed: Uint8Array): string | ArrayBuffer {
    const plaintext = unpadFrame(sealed);
    const kind = plaintext[0];
    const body = plaintext.subarray(1);
    if (this.options.loan) {
      if (kind !== FrameKind.loan) throw new LoanFrameRefusedError();
      const out = new Uint8Array(body.byteLength);
      out.set(body);
      return out.buffer;
    }
    // Audit RELAY-8: whatever the (plaintext) ready said, this side never unpacks.
    if (kind === FrameKind.deflatedText || kind === FrameKind.deflatedBinary) {
      throw new Error("Packed frame refused");
    }
    if (kind === FrameKind.text) {
      return FATAL_UTF8_DECODER.decode(body);
    }
    if (kind === FrameKind.binary) {
      const out = new Uint8Array(body.byteLength);
      out.set(body);
      return out.buffer;
    }
    throw new Error(`Unknown frame kind ${kind}`);
  }

  outboundWireByteLength(data: string | ArrayBuffer): number {
    const plaintextBytes = utf8ByteLength(data);
    const encryptedBytes = plaintextBytes + ENCRYPTED_PAYLOAD_OVERHEAD_BYTES;
    // Framed: one kind byte, binary on the wire. Audit RELAY-8: padded, the bucket of the
    // header and the body.
    if (this.options.framedPlaintext && this.options.padded) {
      return (
        paddedFrameLength(PADDED_FRAME_HEADER_BYTES + plaintextBytes) +
        ENCRYPTED_PAYLOAD_OVERHEAD_BYTES
      );
    }
    if (this.options.framedPlaintext) return encryptedBytes + 1;
    if (this.options.binaryCiphertext && data instanceof ArrayBuffer) {
      return encryptedBytes;
    }
    return base64EncryptedWireByteLength(plaintextBytes);
  }

  /**
   * Client side, audit D16: a daemon that echoed `confirm` gets an empty confirm frame as the
   * first session frame, which releases the early frames it holds. Nothing for any other daemon.
   */
  private async sendConfirm(ready: E2EEReadyMessage): Promise<void> {
    const session = this.options.session;
    if (!session?.sendKey || ready.capabilities?.confirm !== true) return;
    const counter = session.sendCounter;
    session.sendCounter += 1;
    // Audit RELAY-10: `[0x04] ‖ T`, unpadded. A daemon from D16 on reads the kind byte only.
    const transcript = this.transcript ?? new Uint8Array(0);
    const frame = new Uint8Array(1 + transcript.byteLength);
    frame[0] = FrameKind.confirm;
    frame.set(transcript, 1);
    await this.transport.send(encryptWithCounter(session.sendKey, counter, frame.buffer));
  }

  private async flushPendingSends(): Promise<void> {
    if (this.state !== "open") return;
    const pending = this.pendingSends;
    this.pendingSends = [];
    for (const item of pending) {
      await this.send(item);
    }
  }

  private async handleDaemonRehello(message: E2EEHelloMessage): Promise<void> {
    if (!this.options.daemonKeyPair) return;
    const clientPublicKey = importPublicKey(message.key);
    const retryKey = deriveSharedKey(this.options.daemonKeyPair.secretKey, clientPublicKey);
    if (!keysEqual(retryKey, this.sharedKey)) return this.rejectKeyRotation();
    await this.sendReadyForRetry();
  }

  private async sendReadyForRetry(): Promise<void> {
    // Audit RELAY-10: the same text as the first ready, which the transcript covers.
    await this.transport.send(this.options.readyText ?? JSON.stringify(readyMessage(this.options)));
  }

  /**
   * Client side, on `e2ee_ready`: a daemon that agreed to session keys named its ephemeral key,
   * and both directions switch to their own key. An older daemon agrees to nothing and the
   * channel stays on the handshake key.
   */
  private finishClientSession(ready: E2EEReadyMessage, framedPlaintext: boolean): void {
    const pending = this.options.session?.pending;
    if (!pending) return;
    if (!framedPlaintext || ready.capabilities?.sessionKeys !== true) {
      // A loan proof always rides on session keys; a daemon that drops them is not one to trust.
      // Audit RELAY-10: nor does any daemon that reads an account or guest proof (5.0.0 on).
      if (this.options.loan || this.options.provedPeer) {
        throw new ChannelDowngradeError("no session keys for a proven handshake");
      }
      // Audit RELAY-10 (D): a credential waiting for the session keys never goes without them.
      if (
        this.options.credentialsNeedSessionKeys &&
        this.pendingSends.some((item) => typeof item === "string" && carriesSessionCredential(item))
      ) {
        throw new ChannelDowngradeError("a credential needs session keys");
      }
      this.options.session = undefined;
      return;
    }
    if (!ready.key) throw new Error("Session keys agreed without a daemon key");
    const daemonEphemeralPublicKey = importPublicKey(ready.key);
    const keys = deriveSessionKeys({
      role: "client",
      ourEphemeral: pending.ephemeral,
      daemonStatic: pending.daemonStaticPublicKey,
      peerEphemeralPublicKey: daemonEphemeralPublicKey,
      clientEphemeralPublicKey: pending.ephemeral.publicKey,
      daemonEphemeralPublicKey,
    });
    pending.ephemeral.secretKey.fill(0);
    this.options.session = { ...keys, sendCounter: 0, receiveCounter: 0 };
  }

  /**
   * A frame under session keys. Binary frames carry the next counter in their nonce; anything
   * else fails the channel. Text frames are a daemon's early frames from the client (sealed before
   * the client read the ready), accepted only before the first session frame and once each.
   * Decryption runs before any await, so the counter follows arrival order.
   */
  private receiveSessionFrame(message: TransportMessage): void {
    const session = this.options.session;
    if (!session) return;
    let opened: Uint8Array | null = null;
    try {
      if (message.isBinary) {
        if (!session.receiveKey) throw new Error("Session frame before session keys");
        opened = openWithCounter(
          session.receiveKey,
          session.receiveCounter,
          requireArrayBuffer(message.data),
        );
        session.receiveCounter += 1;
        session.sawSessionFrame = true;
        this.sessionFrameOpened(session, opened);
      } else {
        const text = decodeTransportText(message.data);
        if (text.trim().startsWith("{")) {
          // Handshake retries and stray readies stay plaintext; anything else is not ours.
          const parsed: unknown = JSON.parse(text);
          if (isE2EEHelloMessage(parsed) && this.options.daemonKeyPair) {
            void this.handleDaemonRehello(parsed).catch(() => undefined);
            return;
          }
          if (isE2EEHelloMessage(parsed) || isE2EEReadyMessage(parsed)) return;
          throw new Error("Received plaintext frame on encrypted channel");
        }
        this.receiveEarlyFrame(session, text);
        return;
      }
    } catch (error) {
      this.failChannel(error);
      return;
    }
    // The first session frame proves the client live: what it pipelined goes first, in order.
    const held = session.heldEarly;
    if (held && held.length > 0) {
      session.heldEarly = [];
      for (const early of held) this.events.onmessage?.(early);
    }
    if (opened[0] === FrameKind.confirm) return;
    try {
      const plaintext = this.unframe(opened);
      if (this.state === "open") this.events.onmessage?.(plaintext);
    } catch (error) {
      this.failChannel(error);
    }
  }

  /**
   * Daemon side: one early frame (base64, sealed under the handshake key), accepted only before
   * the first session frame and once per nonce. Audit D16: a confirming client's frame is held
   * until a session frame proves the client live, which a replayed handshake never produces.
   * Throws on anything refused.
   */
  private receiveEarlyFrame(session: SessionKeyState, text: string): void {
    // A loan client pipelines nothing: an early (text) frame is not a loan frame.
    if (this.options.loan) throw new LoanFrameRefusedError();
    if (!session.earlyNonces || session.sawSessionFrame) {
      throw new Error("Early frame after the session began");
    }
    const bundle = new Uint8Array(base64ToArrayBuffer(text));
    const nonceKey = arrayBufferToBase64(bundle.slice(0, NONCE_BYTES).buffer);
    if (session.earlyNonces.has(nonceKey)) throw new Error("Replayed early frame");
    session.earlyNonces.add(nonceKey);
    if (!isConfirmingEarlyNonce(bundle) && session.confirm) {
      // Audit RELAY-6: a client whose hello asked for `confirm` marks every early frame (the web,
      // desktop, iOS and Android channels all do); an unmarked one under its handshake is not its.
      throw new Error("Unmarked early frame from a confirming client");
    }
    const plaintext = FATAL_UTF8_DECODER.decode(decrypt(this.sharedKey, bundle.buffer));
    if (!isConfirmingEarlyNonce(bundle)) {
      this.events.onmessage?.(plaintext);
      return;
    }
    const held = (session.heldEarly ??= []);
    if (held.length >= MAX_HELD_EARLY_FRAMES) throw new Error("Too many early frames");
    held.push(plaintext);
  }

  /**
   * A session frame opened. Client side, audits RELAY-6 and RELAY-10: the daemon sealed it, so the
   * level its ready named is pinned. Daemon side, audit RELAY-10: the first one from a confirming
   * client must be the confirm, with the transcript when asked (throws).
   */
  private sessionFrameOpened(session: SessionKeyState, opened: Uint8Array): void {
    if (!this.options.daemonKeyPair) {
      if (!this.awaitingDaemonConfirm) return;
      this.awaitingDaemonConfirm = false;
      const level = this.levelPending;
      this.levelPending = null;
      checkDaemonConfirmFrame(opened, this.transcript);
      if (level && this.options.timedProofDaemonKeyB64) {
        pinDaemonChannelLevel(this.options.timedProofDaemonKeyB64, level, true);
      }
      return;
    }
    if (session.confirm && !session.confirmed) {
      const transcript = session.expectedTranscript;
      checkConfirmFrame(session, opened);
      if (session.transcript && transcript) this.sendDaemonConfirm(session, transcript);
    }
  }

  /**
   * Daemon side, audit RELAY-10: a transcript client's confirm checked out, so the daemon answers
   * with its own, `[0x04] ‖ T` under its session key (frame 0, unpadded), and then sends what
   * waited for it, in order. That frame is the client's proof that this daemon checked T, which is
   * what lets the client pin the level the ready named.
   */
  private sendDaemonConfirm(session: SessionKeyState, transcript: Uint8Array): void {
    if (!session.sendKey) return;
    const counter = session.sendCounter;
    session.sendCounter += 1;
    const frame = new Uint8Array(1 + transcript.byteLength);
    frame[0] = FrameKind.confirm;
    frame.set(transcript, 1);
    try {
      void Promise.resolve(
        this.transport.send(encryptWithCounter(session.sendKey, counter, frame.buffer)),
      ).catch((error: unknown) => this.failChannel(error));
    } catch (error) {
      this.failChannel(error);
      return;
    }
    const held = this.heldForConfirm;
    this.heldForConfirm = [];
    // Each send takes its counter before its first await, so these leave in order.
    for (const item of held) this.send(item.data).then(item.sent, item.failed);
  }

  /** Client side: a ready that could not be finished; a downgrade is also reported. */
  private failHandshake(error: unknown): void {
    if (error instanceof ChannelDowngradeError) this.refuseDowngrade(error);
    else this.failChannel(error);
  }

  /** Audit RELAY-10: a refused downgrade is reported (`onerror`) and closes like a failure. */
  private refuseDowngrade(error: unknown): void {
    const err = error instanceof Error ? error : new Error(String(error));
    this.events.onerror?.(err);
    this.failChannel(err);
  }

  /**
   * Audit RELAY-10: what waited for the client's confirm goes with the channel (its callers are
   * let go, as the client's own queue lets them go).
   */
  private dropHeldForConfirm(): void {
    for (const held of this.heldForConfirm.splice(0)) held.sent();
  }

  private failChannel(error: unknown): void {
    const err = error instanceof Error ? error : new Error(String(error));
    this.state = "closed";
    this.dropHeldForConfirm();
    try {
      this.transport.close(failureCloseCode(err), err.message);
    } catch {
      // ignore
    }
  }

  private rejectKeyRotation(): void {
    this.state = "closed";
    this.transport.close(REHANDSHAKE_REJECTION_CODE, REHANDSHAKE_KEY_MISMATCH_CLOSE_REASON);
  }

  close(code = 1000, reason = "Normal closure"): void {
    this.state = "closed";
    this.dropHeldForConfirm();
    this.transport.close(code, reason);
  }

  isOpen(): boolean {
    return this.state === "open";
  }

  onTransitionToOpen(cb: () => void): void {
    this.onOpenCallbacks.push(cb);
  }

  onClose(cb: () => void): void {
    this.onCloseCallbacks.push(cb);
  }
}

/**
 * Daemon side, audit RELAY-10: the first session frame from a client whose hello asked for
 * `confirm` (every such client sends the confirm first). A body must be the transcript hash of the
 * hello as read and the ready as sent; a bare confirm passes only when the hello did not ask for
 * `transcript` (the phones before RELAY-10). Runs before held early frames are released. Throws.
 */
function checkConfirmFrame(session: SessionKeyState, opened: Uint8Array): void {
  if (opened[0] !== FrameKind.confirm) throw new Error("E2EE confirm frame missing");
  const body = opened.subarray(1);
  if (body.byteLength === 0) {
    if (session.transcript) throw new Error("E2EE transcript missing");
  } else if (!session.expectedTranscript || !keysEqual(body, session.expectedTranscript)) {
    throw new Error("E2EE transcript mismatch");
  }
  session.confirmed = true;
  session.expectedTranscript = undefined;
}

/**
 * Client side, audit RELAY-10: the daemon's first session frame after a ready that echoed
 * `transcript` must be its confirm, `[0x04] ‖ T` with this side's T (compared in constant time).
 * Throws; the channel then fails and nothing is pinned.
 */
function checkDaemonConfirmFrame(opened: Uint8Array, transcript: Uint8Array | null): void {
  if (opened[0] !== FrameKind.confirm) throw new Error("E2EE daemon confirm frame missing");
  if (!transcript || !keysEqual(opened.subarray(1), transcript)) {
    throw new Error("E2EE transcript mismatch");
  }
}

/** 4403 for a frame a loan channel refuses, the channel's own failure code for anything else. */
function failureCloseCode(error: Error): number {
  return error instanceof LoanFrameRefusedError
    ? LOAN_FRAME_REFUSED_CLOSE_CODE
    : CHANNEL_FAILURE_CLOSE_CODE;
}

function decodeTransportText(data: string | ArrayBuffer): string {
  return typeof data === "string" ? data : UTF8_DECODER.decode(data);
}

function requireArrayBuffer(data: string | ArrayBuffer): ArrayBuffer {
  if (data instanceof ArrayBuffer) return data;
  throw new Error("Binary WebSocket frame did not contain bytes");
}

function decodeLegacyPlaintext(data: ArrayBuffer): string | ArrayBuffer {
  try {
    return FATAL_UTF8_DECODER.decode(data);
  } catch {
    return data;
  }
}

function decodePlaintext(data: ArrayBuffer, isBinary: boolean | null): string | ArrayBuffer {
  if (isBinary === true) return data;
  if (isBinary === false) return FATAL_UTF8_DECODER.decode(data);
  return decodeLegacyPlaintext(data);
}

// Stateless without `stream`, so one of each serves every frame.
const UTF8_ENCODER = new TextEncoder();
const UTF8_DECODER = new TextDecoder();
const FATAL_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });

/** UTF-8 length without encoding; a lone surrogate counts as U+FFFD (3 bytes), as TextEncoder writes it. */
function utf8ByteLength(data: string | ArrayBuffer): number {
  if (typeof data !== "string") return data.byteLength;
  let bytes = 0;
  for (let i = 0; i < data.length; i++) {
    const unit = data.charCodeAt(i);
    if (unit < 0x80) bytes += 1;
    else if (unit < 0x800) bytes += 2;
    else if (unit >= 0xd800 && unit <= 0xdbff && i + 1 < data.length) {
      const next = data.charCodeAt(i + 1);
      if (next >= 0xdc00 && next <= 0xdfff) {
        bytes += 4;
        i++;
      } else bytes += 3;
    } else bytes += 3;
  }
  return bytes;
}

function keysEqual(a: Uint8Array, b: Uint8Array): boolean {
  if (a.byteLength !== b.byteLength) return false;
  let difference = 0;
  for (let i = 0; i < a.byteLength; i += 1) {
    difference |= a[i] ^ b[i];
  }
  return difference === 0;
}