@fairfox/polly 0.38.2 → 0.40.0

package/dist/src/mesh-node.js.map

@@ -3,7 +3,7 @@
   "sources": ["../../src/mesh-node.ts", "../../src/shared/lib/keyring-storage.ts", "../../src/shared/lib/encryption.ts", "../../src/shared/lib/signing.ts", "../../src/shared/lib/pairing.ts"],
   "sourcesContent": [
     "/**\n * @fairfox/polly/mesh/node — Node/Bun conveniences for mesh state.\n *\n * The core mesh API (`createMeshClient`, `$meshState`, the keyring storage\n * interface) is runtime-agnostic and ships from `@fairfox/polly/mesh`. This\n * module adds the Node-specific wiring that makes CLIs, cron jobs, and\n * always-on bridges first-class peers on the mesh:\n *\n *   - {@link fileKeyringStorage} — durable, human-inspectable keyring store\n *     backed by `node:fs`. Atomic writes, missing-file returns `null`.\n *   - {@link bootstrapCliKeyring} — wraps {@link fileKeyringStorage} with the\n *     first-run pairing UX described in the RFC: generate an identity if\n *     no keyring exists, print the public-key fingerprint, read a pairing\n *     token from stdin, apply it, and save.\n *   - {@link readPairingTokenFromStdin} — low-level prompt helper for\n *     consumers that want to compose their own bootstrap.\n *\n * What this module deliberately does **not** do: pick a Node WebRTC\n * implementation. `werift` (pure TypeScript, installs everywhere) and\n * `@roamhq/wrtc` (C++ binding, faster DataChannel, platform-dependent\n * binaries) are both valid choices; the consumer `bun add`s whichever fits\n * their deployment and passes the class into `createMeshClient({ rtc })`.\n *\n * @example\n * ```ts\n * import { createMeshClient } from \"@fairfox/polly/mesh\";\n * import { bootstrapCliKeyring, fileKeyringStorage } from \"@fairfox/polly/mesh/node\";\n * import { RTCPeerConnection } from \"werift\";\n *\n * const storage = fileKeyringStorage(\"./keyring.json\");\n * const keyring = await bootstrapCliKeyring({ storage });\n *\n * const client = await createMeshClient({\n *   signaling: { url: \"wss://example.com/polly/signaling\", peerId: \"cli-a1b2\" },\n *   rtc:       { RTCPeerConnection },\n *   keyring,\n * });\n * ```\n */\n\nimport { mkdir, readFile, rename, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { createInterface } from \"node:readline/promises\";\nimport {\n  deserialiseKeyring,\n  type KeyringStorage,\n  serialiseKeyring,\n} from \"./shared/lib/keyring-storage\";\nimport type { MeshKeyring } from \"./shared/lib/mesh-network-adapter\";\nimport { applyPairingToken, decodePairingToken } from \"./shared/lib/pairing\";\nimport { generateSigningKeyPair } from \"./shared/lib/signing\";\n\n// Re-export runtime-agnostic pieces so a Node consumer only needs one\n// import site.\nexport type { KeyringStorage } from \"./shared/lib/keyring-storage\";\nexport {\n  deserialiseKeyring,\n  memoryKeyringStorage,\n  serialiseKeyring,\n} from \"./shared/lib/keyring-storage\";\n\n/**\n * Filesystem-backed keyring storage. Reads and writes the serialised\n * keyring at {@link path} using the canonical JSON+base64 format. The save\n * path uses a write-to-tmp-then-rename dance so concurrent readers never\n * observe a half-written file; a crash mid-write leaves the previous\n * keyring intact.\n */\nexport function fileKeyringStorage(path: string): KeyringStorage {\n  return {\n    load: async () => {\n      try {\n        const text = await readFile(path, \"utf-8\");\n        return deserialiseKeyring(text);\n      } catch (err) {\n        if (isFileNotFound(err)) return null;\n        throw err;\n      }\n    },\n    save: async (keyring) => {\n      // First-run on a fresh machine often points this storage at a\n      // path whose parent directory hasn't been created yet (the\n      // typical `~/.fairfox/keyring.json` shape). mkdir -p the parent\n      // up front so the write-to-tmp step doesn't fail at open().\n      await mkdir(dirname(path), { recursive: true });\n      const text = serialiseKeyring(keyring);\n      const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;\n      await writeFile(tmp, text, { mode: 0o600 });\n      await rename(tmp, path);\n    },\n  };\n}\n\n/** Options for {@link bootstrapCliKeyring}. */\nexport interface BootstrapCliKeyringOptions {\n  /** Where to persist the keyring. On subsequent runs this file is loaded\n   * and returned without prompting. */\n  storage: KeyringStorage;\n  /** Stream to print pairing prompts to. Defaults to `process.stderr` so\n   * pipelines that consume stdout are not polluted. */\n  promptStream?: NodeJS.WritableStream;\n  /** Stream to read the pairing token from. Defaults to `process.stdin`. */\n  inputStream?: NodeJS.ReadableStream;\n  /** Override the clock (for tests). Forwarded to {@link applyPairingToken}. */\n  now?: () => number;\n}\n\n/**\n * First-run-or-return flow for Node CLIs.\n *\n * - If the storage has a keyring saved, load and return it.\n * - Otherwise: generate a fresh Ed25519 identity, print the public-key\n *   fingerprint to `promptStream`, read one line from `inputStream`\n *   (expected to be a base64 pairing token), apply it, save, return.\n *\n * Token *issuance* is deliberately out of scope for this helper — the\n * expected UX is that a trusted device (a browser on the authorising\n * user's laptop) mints the token and the user pastes it into the CLI's\n * stdin. Node processes that need to issue tokens can use\n * {@link createPairingToken} from the main mesh export.\n */\nexport async function bootstrapCliKeyring(\n  options: BootstrapCliKeyringOptions\n): Promise<MeshKeyring> {\n  const existing = await options.storage.load();\n  if (existing !== null) return existing;\n\n  const identity = generateSigningKeyPair();\n  const keyring: MeshKeyring = {\n    identity,\n    knownPeers: new Map(),\n    documentKeys: new Map(),\n    revokedPeers: new Set(),\n  };\n\n  const promptStream = options.promptStream ?? process.stderr;\n  const fingerprint = fingerprintPublicKey(identity.publicKey);\n  promptStream.write(\n    [\n      \"\",\n      \"Polly mesh-state CLI bootstrap\",\n      \"──────────────────────────────\",\n      `Fingerprint:  ${fingerprint}`,\n      \"\",\n      \"Authorise this peer on a trusted device (open the pairing UI, enter\",\n      \"the fingerprint above, copy the generated token). Then paste the\",\n      \"pairing token below and press enter.\",\n      \"\",\n    ].join(\"\\n\")\n  );\n\n  const token = await readPairingTokenFromStdin({\n    promptStream,\n    inputStream: options.inputStream ?? process.stdin,\n  });\n\n  const applyOptions = options.now ? { now: options.now } : {};\n  applyPairingToken(token, keyring, applyOptions);\n\n  await options.storage.save(keyring);\n  promptStream.write(`Pairing applied. Keyring saved.\\n`);\n  return keyring;\n}\n\n/**\n * Prompt for and read a pairing token from a readable stream (stdin by\n * default). Returns the decoded, validated token. Throws\n * {@link PairingError} on malformed input — callers should surface that\n * message to the user and retry.\n */\nexport async function readPairingTokenFromStdin(\n  options: { promptStream?: NodeJS.WritableStream; inputStream?: NodeJS.ReadableStream } = {}\n) {\n  const rl = createInterface({\n    input: options.inputStream ?? process.stdin,\n    output: options.promptStream ?? process.stderr,\n  });\n  try {\n    const line = await rl.question(\"pairing-token> \");\n    return decodePairingToken(line.trim());\n  } finally {\n    rl.close();\n  }\n}\n\n/** Short, human-readable fingerprint of a public key. */\nfunction fingerprintPublicKey(publicKey: Uint8Array): string {\n  // First 8 bytes, hex-encoded, colon-grouped — familiar from SSH.\n  const slice = publicKey.slice(0, 8);\n  const hex = Array.from(slice)\n    .map((b) => b.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n  return hex.match(/.{2}/g)?.join(\":\") ?? hex;\n}\n\nfunction isFileNotFound(err: unknown): boolean {\n  return typeof err === \"object\" && err !== null && \"code\" in err && err.code === \"ENOENT\";\n}\n",
-    "/**\n * keyring-storage — persistence abstraction for {@link MeshKeyring}.\n *\n * The keyring itself is a plain structural object of `Map`s, `Set`s, and a\n * signing keypair; it is deliberately not coupled to any persistence layer.\n * This module defines a storage interface that applications implement once\n * for their runtime (IndexedDB, the filesystem, a keychain, a secret\n * manager, whatever) and wire into {@link createMeshClient} via its\n * `keyring.storage` option.\n *\n * A canonical JSON-with-base64 serialisation is provided by\n * {@link serialiseKeyring} and {@link deserialiseKeyring}. It is inspectable\n * by humans, survives manual edits, and round-trips every field of the\n * keyring. Storage implementations that write plain strings (files,\n * localStorage, `kv` stores) can lean on these helpers; storage\n * implementations that persist structured data (IndexedDB, a keychain API)\n * can serialise differently if they prefer.\n */\n\nimport type { MeshKeyring } from \"./mesh-network-adapter\";\nimport type { SigningKeyPair } from \"./signing\";\n\n/**\n * A load/save pair for a single {@link MeshKeyring}. Implementations are\n * free to choose where and how the keyring is stored; the factory only\n * cares that `load()` returns the previously-saved keyring or `null`, and\n * that `save(keyring)` durably persists it.\n */\nexport interface KeyringStorage {\n  /** Load the previously-saved keyring, or return `null` if none exists.\n   * Implementations may throw for truly exceptional conditions (disk\n   * errors, permission failures); a missing keyring is not exceptional. */\n  load(): Promise<MeshKeyring | null>;\n  /** Durably persist the keyring. Implementations should atomically replace\n   * any existing stored value; partial writes must not leave the store in\n   * an inconsistent state. */\n  save(keyring: MeshKeyring): Promise<void>;\n}\n\n/**\n * In-memory storage. Useful for tests, ephemeral tools, and the first-run\n * bootstrap path where the keyring only lives for the duration of the\n * process. Calling `save` holds the keyring in a closed-over variable;\n * `load` returns it on subsequent calls within the same process.\n */\nexport function memoryKeyringStorage(): KeyringStorage {\n  let stored: MeshKeyring | null = null;\n  return {\n    load: async () => stored,\n    save: async (keyring) => {\n      stored = keyring;\n    },\n  };\n}\n\n// ─── Canonical JSON+base64 serialisation ───────────────────────────────────\n\ninterface SerialisedKeyring {\n  version: 1;\n  identity: { publicKey: string; secretKey: string };\n  knownPeers: Record<string, string>;\n  documentKeys: Record<string, string>;\n  revokedPeers: string[];\n  revocationAuthority?: string[];\n}\n\n/**\n * Encode a {@link MeshKeyring} to a canonical JSON string. Every\n * `Uint8Array` field (identity keys, public keys, document keys) is\n * base64-encoded; `Map`s and `Set`s become plain objects and arrays. The\n * output is pretty-printed so a human operator can eyeball or hand-edit\n * the file on disk.\n */\nexport function serialiseKeyring(keyring: MeshKeyring): string {\n  const payload: SerialisedKeyring = {\n    version: 1,\n    identity: {\n      publicKey: bytesToBase64(keyring.identity.publicKey),\n      secretKey: bytesToBase64(keyring.identity.secretKey),\n    },\n    knownPeers: mapToBase64Record(keyring.knownPeers),\n    documentKeys: mapToBase64Record(keyring.documentKeys),\n    revokedPeers: [...keyring.revokedPeers],\n  };\n  if (keyring.revocationAuthority && keyring.revocationAuthority.size > 0) {\n    payload.revocationAuthority = [...keyring.revocationAuthority];\n  }\n  return JSON.stringify(payload, null, 2);\n}\n\n/**\n * Decode a keyring from the format produced by {@link serialiseKeyring}.\n * Throws with a descriptive message when the input is malformed, so\n * corrupt storage surfaces as an actionable error rather than a silent\n * downgrade.\n */\nexport function deserialiseKeyring(text: string): MeshKeyring {\n  let raw: unknown;\n  try {\n    raw = JSON.parse(text);\n  } catch (err) {\n    throw new Error(`KeyringStorage: keyring payload is not valid JSON: ${(err as Error).message}`);\n  }\n  if (!raw || typeof raw !== \"object\") {\n    throw new Error(\"KeyringStorage: keyring payload is not an object\");\n  }\n  const r = raw as Partial<SerialisedKeyring>;\n  if (r.version !== 1) {\n    throw new Error(`KeyringStorage: unsupported keyring version: ${String(r.version)}`);\n  }\n  if (!r.identity || typeof r.identity !== \"object\") {\n    throw new Error(\"KeyringStorage: keyring payload is missing identity\");\n  }\n  const identity: SigningKeyPair = {\n    publicKey: base64ToBytes(r.identity.publicKey),\n    secretKey: base64ToBytes(r.identity.secretKey),\n  };\n  const keyring: MeshKeyring = {\n    identity,\n    knownPeers: base64RecordToMap(r.knownPeers ?? {}),\n    documentKeys: base64RecordToMap(r.documentKeys ?? {}),\n    revokedPeers: new Set(r.revokedPeers ?? []),\n  };\n  if (r.revocationAuthority && r.revocationAuthority.length > 0) {\n    keyring.revocationAuthority = new Set(r.revocationAuthority);\n  }\n  return keyring;\n}\n\nfunction mapToBase64Record(map: Map<string, Uint8Array>): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of map) {\n    out[key] = bytesToBase64(value);\n  }\n  return out;\n}\n\nfunction base64RecordToMap(record: Record<string, string>): Map<string, Uint8Array> {\n  const out = new Map<string, Uint8Array>();\n  for (const [key, value] of Object.entries(record)) {\n    out.set(key, base64ToBytes(value));\n  }\n  return out;\n}\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  // btoa is available in browsers, Node 16+, and Bun.\n  let binary = \"\";\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary);\n}\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes;\n}\n",
+    "/**\n * keyring-storage — persistence abstraction for {@link MeshKeyring}.\n *\n * The keyring itself is a plain structural object of `Map`s, `Set`s, and a\n * signing keypair; it is deliberately not coupled to any persistence layer.\n * This module defines a storage interface that applications implement once\n * for their runtime (IndexedDB, the filesystem, a keychain, a secret\n * manager, whatever) and wire into {@link createMeshClient} via its\n * `keyring.storage` option.\n *\n * A canonical JSON-with-base64 serialisation is provided by\n * {@link serialiseKeyring} and {@link deserialiseKeyring}. It is inspectable\n * by humans, survives manual edits, and round-trips every field of the\n * keyring. Storage implementations that write plain strings (files,\n * localStorage, `kv` stores) can lean on these helpers; storage\n * implementations that persist structured data (IndexedDB, a keychain API)\n * can serialise differently if they prefer.\n */\n\nimport type { MeshKeyring } from \"./mesh-network-adapter\";\nimport type { SigningKeyPair } from \"./signing\";\n\n/**\n * A load/save pair for a single {@link MeshKeyring}. Implementations are\n * free to choose where and how the keyring is stored; the factory only\n * cares that `load()` returns the previously-saved keyring or `null`, and\n * that `save(keyring)` durably persists it.\n */\nexport interface KeyringStorage {\n  /** Load the previously-saved keyring, or return `null` if none exists.\n   * Implementations may throw for truly exceptional conditions (disk\n   * errors, permission failures); a missing keyring is not exceptional. */\n  load(): Promise<MeshKeyring | null>;\n  /** Durably persist the keyring. Implementations should atomically replace\n   * any existing stored value; partial writes must not leave the store in\n   * an inconsistent state. */\n  save(keyring: MeshKeyring): Promise<void>;\n}\n\n/**\n * In-memory storage. Useful for tests, ephemeral tools, and the first-run\n * bootstrap path where the keyring only lives for the duration of the\n * process. Calling `save` holds the keyring in a closed-over variable;\n * `load` returns it on subsequent calls within the same process.\n */\nexport function memoryKeyringStorage(): KeyringStorage {\n  let stored: MeshKeyring | null = null;\n  return {\n    load: async () => stored,\n    save: async (keyring) => {\n      stored = keyring;\n    },\n  };\n}\n\n// ─── Canonical JSON+base64 serialisation ───────────────────────────────────\n\ninterface SerialisedKeyring {\n  version: 1;\n  identity: { publicKey: string; secretKey: string };\n  knownPeers: Record<string, string>;\n  documentKeys: Record<string, string>;\n  revokedPeers: string[];\n  revocationAuthority?: string[];\n}\n\n/**\n * Encode a {@link MeshKeyring} to a canonical JSON string. Every\n * `Uint8Array` field (identity keys, public keys, document keys) is\n * base64-encoded; `Map`s and `Set`s become plain objects and arrays. The\n * output is pretty-printed so a human operator can eyeball or hand-edit\n * the file on disk.\n */\nexport function serialiseKeyring(keyring: MeshKeyring): string {\n  const payload: SerialisedKeyring = {\n    version: 1,\n    identity: {\n      publicKey: bytesToBase64(keyring.identity.publicKey),\n      secretKey: bytesToBase64(keyring.identity.secretKey),\n    },\n    knownPeers: mapToBase64Record(keyring.knownPeers),\n    documentKeys: mapToBase64Record(keyring.documentKeys),\n    revokedPeers: [...keyring.revokedPeers],\n  };\n  if (keyring.revocationAuthority && keyring.revocationAuthority.size > 0) {\n    payload.revocationAuthority = [...keyring.revocationAuthority];\n  }\n  return JSON.stringify(payload, null, 2);\n}\n\n/**\n * Decode a keyring from the format produced by {@link serialiseKeyring}.\n * Throws with a descriptive message when the input is malformed, so\n * corrupt storage surfaces as an actionable error rather than a silent\n * downgrade.\n */\nexport function deserialiseKeyring(text: string): MeshKeyring {\n  let raw: unknown;\n  try {\n    raw = JSON.parse(text);\n  } catch (err) {\n    throw new Error(`KeyringStorage: keyring payload is not valid JSON: ${(err as Error).message}`);\n  }\n  if (!raw || typeof raw !== \"object\") {\n    throw new Error(\"KeyringStorage: keyring payload is not an object\");\n  }\n  const r = raw as unknown as Partial<SerialisedKeyring>;\n  if (r.version !== 1) {\n    throw new Error(`KeyringStorage: unsupported keyring version: ${String(r.version)}`);\n  }\n  if (!r.identity || typeof r.identity !== \"object\") {\n    throw new Error(\"KeyringStorage: keyring payload is missing identity\");\n  }\n  const identity: SigningKeyPair = {\n    publicKey: base64ToBytes(r.identity.publicKey),\n    secretKey: base64ToBytes(r.identity.secretKey),\n  };\n  const keyring: MeshKeyring = {\n    identity,\n    knownPeers: base64RecordToMap(r.knownPeers ?? {}),\n    documentKeys: base64RecordToMap(r.documentKeys ?? {}),\n    revokedPeers: new Set(r.revokedPeers ?? []),\n  };\n  if (r.revocationAuthority && r.revocationAuthority.length > 0) {\n    keyring.revocationAuthority = new Set(r.revocationAuthority);\n  }\n  return keyring;\n}\n\nfunction mapToBase64Record(map: Map<string, Uint8Array>): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of map) {\n    out[key] = bytesToBase64(value);\n  }\n  return out;\n}\n\nfunction base64RecordToMap(record: Record<string, string>): Map<string, Uint8Array> {\n  const out = new Map<string, Uint8Array>();\n  for (const [key, value] of Object.entries(record)) {\n    out.set(key, base64ToBytes(value));\n  }\n  return out;\n}\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  // btoa is available in browsers, Node 16+, and Bun.\n  let binary = \"\";\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary);\n}\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes;\n}\n",
     "/**\n * encryption — symmetric authenticated encryption for Polly's $meshState\n * primitive (Phase 2). Wraps tweetnacl's secretbox (XSalsa20-Poly1305) with\n * a small Polly-flavoured API so the rest of the codebase never imports\n * tweetnacl directly.\n *\n * Every $meshState document has a per-document symmetric key that is\n * provisioned to authorised peers at pairing time and never held by any\n * server. Outgoing operations are encrypted under this key before they\n * touch the network adapter; incoming operations are decrypted on receipt.\n * The signing layer in {@link signing.ts} provides authenticity (proof of\n * who sent the message); this layer provides confidentiality (the bytes\n * are unreadable to anything that does not hold the document key).\n *\n * tweetnacl's secretbox uses a 32-byte symmetric key and a 24-byte nonce.\n * The output of `nacl.secretbox` is the ciphertext concatenated with a\n * 16-byte Poly1305 authentication tag. We package the nonce + ciphertext\n * into a single binary blob using a small length-prefixed envelope so the\n * receiver can recover the nonce without out-of-band coordination.\n *\n *   - {@link generateDocumentKey} returns a fresh 32-byte symmetric key.\n *\n *   - {@link encrypt} produces a sealed blob from a payload and a key.\n *\n *   - {@link decrypt} recovers the payload from a sealed blob and a key.\n *     Returns undefined if the blob is malformed or the authentication\n *     tag does not match (i.e. wrong key or tampered ciphertext) — the\n *     undefined signal lets call sites distinguish \"wrong key\" from\n *     \"structurally invalid\" without throwing.\n *\n *   - {@link sealEnvelope} and {@link openEnvelope} are convenience helpers\n *     that wrap encrypt/decrypt in a structured EncryptedEnvelope shape so\n *     the mesh transport layer can handle the binary plumbing uniformly.\n */\n\nimport nacl from \"tweetnacl\";\n\n/** Length in bytes of a secretbox symmetric key. */\nexport const KEY_BYTES = 32;\n/** Length in bytes of a secretbox nonce. */\nexport const NONCE_BYTES = 24;\n/** Length in bytes of the Poly1305 authentication tag. */\nexport const TAG_BYTES = 16;\n\n/**\n * A sealed blob suitable for storage or network transmission. The wire\n * layout is the concatenation of the nonce and the ciphertext+tag from\n * tweetnacl. Callers should not depend on the exact bytes — round-trip\n * through {@link encrypt} / {@link decrypt} or the envelope helpers.\n */\nexport type SealedBytes = Uint8Array;\n\n/** Errors thrown by the encryption subsystem. */\nexport class EncryptionError extends Error {\n  readonly code: \"invalid-key-length\" | \"decrypt-failed\" | \"envelope-malformed\";\n  constructor(message: string, code: EncryptionError[\"code\"]) {\n    super(message);\n    this.name = \"EncryptionError\";\n    this.code = code;\n  }\n}\n\n/**\n * Generate a fresh 32-byte symmetric document key. Calls into tweetnacl's\n * CSPRNG.\n */\nexport function generateDocumentKey(): Uint8Array {\n  return nacl.randomBytes(KEY_BYTES);\n}\n\n/**\n * Encrypt a payload under a symmetric key. The returned blob includes a\n * fresh nonce so the receiver does not need any out-of-band coordination\n * to decrypt.\n */\nexport function encrypt(payload: Uint8Array, key: Uint8Array): SealedBytes {\n  if (key.length !== KEY_BYTES) {\n    throw new EncryptionError(\n      `secretbox key must be ${KEY_BYTES} bytes, got ${key.length}.`,\n      \"invalid-key-length\"\n    );\n  }\n  const nonce = nacl.randomBytes(NONCE_BYTES);\n  const ciphertext = nacl.secretbox(payload, nonce, key);\n  const out = new Uint8Array(NONCE_BYTES + ciphertext.length);\n  out.set(nonce, 0);\n  out.set(ciphertext, NONCE_BYTES);\n  return out;\n}\n\n/**\n * Decrypt a sealed blob under a symmetric key. Returns the original\n * payload on success. Returns undefined if the blob is too short to\n * contain a nonce and tag, or if the authentication tag does not match\n * (which indicates either a wrong key or a tampered ciphertext).\n *\n * The undefined return is deliberate: call sites typically want to fall\n * back to a different key or surface a \"could not decrypt\" message rather\n * than catching an exception. Use {@link decryptOrThrow} when an exception\n * is preferred.\n */\nexport function decrypt(sealed: SealedBytes, key: Uint8Array): Uint8Array | undefined {\n  if (key.length !== KEY_BYTES) {\n    throw new EncryptionError(\n      `secretbox key must be ${KEY_BYTES} bytes, got ${key.length}.`,\n      \"invalid-key-length\"\n    );\n  }\n  if (sealed.length < NONCE_BYTES + TAG_BYTES) {\n    return undefined;\n  }\n  const nonce = sealed.subarray(0, NONCE_BYTES);\n  const ciphertext = sealed.subarray(NONCE_BYTES);\n  const opened = nacl.secretbox.open(ciphertext, nonce, key);\n  return opened ?? undefined;\n}\n\n/**\n * Decrypt a sealed blob, throwing {@link EncryptionError} on failure\n * instead of returning undefined.\n */\nexport function decryptOrThrow(sealed: SealedBytes, key: Uint8Array): Uint8Array {\n  const opened = decrypt(sealed, key);\n  if (!opened) {\n    throw new EncryptionError(\n      `Failed to decrypt sealed blob: wrong key, malformed input, or tampered ciphertext.`,\n      \"decrypt-failed\"\n    );\n  }\n  return opened;\n}\n\n/**\n * A high-level structured envelope combining encryption with a small\n * amount of metadata the receiver needs to find the right key. The mesh\n * network adapter uses this shape on the wire.\n */\nexport interface EncryptedEnvelope {\n  /** Stable identifier for the document this payload belongs to. The\n   * receiver looks this up in its local key store to find the right key. */\n  documentId: string;\n  /** Sealed blob containing the encrypted payload plus its nonce. */\n  sealed: SealedBytes;\n}\n\n/**\n * Encrypt a payload and pack it into an {@link EncryptedEnvelope} along\n * with the document id.\n */\nexport function sealEnvelope(\n  payload: Uint8Array,\n  documentId: string,\n  key: Uint8Array\n): EncryptedEnvelope {\n  return {\n    documentId,\n    sealed: encrypt(payload, key),\n  };\n}\n\n/**\n * Decrypt an {@link EncryptedEnvelope} using the given key. Throws on\n * failure for symmetry with {@link sealEnvelope}.\n */\nexport function openEnvelope(envelope: EncryptedEnvelope, key: Uint8Array): Uint8Array {\n  return decryptOrThrow(envelope.sealed, key);\n}\n\n/**\n * Serialise an {@link EncryptedEnvelope} to a single binary blob.\n *\n * Wire format:\n *\n *   [4 bytes BE: documentId byte length]\n *   [N bytes:    documentId UTF-8]\n *   [remaining:  sealed blob (nonce + ciphertext + tag)]\n */\nexport function encodeEncryptedEnvelope(envelope: EncryptedEnvelope): Uint8Array {\n  const idBytes = new TextEncoder().encode(envelope.documentId);\n  const out = new Uint8Array(4 + idBytes.length + envelope.sealed.length);\n  const view = new DataView(out.buffer);\n  view.setUint32(0, idBytes.length, false);\n  out.set(idBytes, 4);\n  out.set(envelope.sealed, 4 + idBytes.length);\n  return out;\n}\n\n/**\n * Deserialise a binary envelope produced by {@link encodeEncryptedEnvelope}.\n * Throws on malformed input.\n */\nexport function decodeEncryptedEnvelope(bytes: Uint8Array): EncryptedEnvelope {\n  if (bytes.length < 4) {\n    throw new EncryptionError(\n      `Encrypted envelope too short: ${bytes.length} bytes.`,\n      \"envelope-malformed\"\n    );\n  }\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  const idLen = view.getUint32(0, false);\n  if (bytes.length < 4 + idLen) {\n    throw new EncryptionError(\n      `Encrypted envelope truncated: declared id length ${idLen}, total ${bytes.length}.`,\n      \"envelope-malformed\"\n    );\n  }\n  const documentId = new TextDecoder().decode(bytes.subarray(4, 4 + idLen));\n  const sealed = bytes.slice(4 + idLen);\n  return { documentId, sealed };\n}\n",
     "/**\n * signing — Ed25519 signing and verification for Polly's $meshState\n * primitive (Phase 2). Wraps tweetnacl with a small Polly-flavoured API\n * so the rest of the codebase never imports tweetnacl directly.\n *\n * Every operation that flows through a $meshState transport is signed by\n * the originating peer's private key before transmission and verified by\n * every receiving peer against a known public-key set before being applied.\n * This is the Byzantine-tolerance mechanism: a peer whose private key is\n * compromised can be revoked through a further signed operation, after\n * which honest peers reject anything signed by the revoked key.\n *\n * tweetnacl uses the Ed25519 curve. Public keys and signatures are 32 and\n * 64 bytes respectively, which keeps the per-op overhead small enough that\n * signing every Automerge sync message is feasible even on mobile.\n *\n * The shape of the wrapper:\n *\n *   - {@link generateSigningKeyPair} produces a new Ed25519 keypair. The\n *     private key never leaves the device that generated it; the public\n *     key is gossiped through the access set.\n *\n *   - {@link sign} produces a 64-byte detached signature over a payload.\n *\n *   - {@link verify} checks a payload against a signature and a public\n *     key. Returns boolean rather than throwing so call sites can handle\n *     verification failure as a normal control-flow case.\n *\n *   - {@link signEnvelope} and {@link openEnvelope} package payload + sender\n *     id + signature into a single binary envelope, which is what the mesh\n *     network adapter actually puts on the wire.\n */\n\nimport nacl from \"tweetnacl\";\n\n/** Length in bytes of an Ed25519 public key. */\nexport const PUBLIC_KEY_BYTES = 32;\n/** Length in bytes of an Ed25519 secret (private) key. */\nexport const SECRET_KEY_BYTES = 64;\n/** Length in bytes of an Ed25519 detached signature. */\nexport const SIGNATURE_BYTES = 64;\n\n/**\n * An Ed25519 keypair. The {@link publicKey} is safe to share with peers;\n * the {@link secretKey} must never leave the device.\n */\nexport interface SigningKeyPair {\n  publicKey: Uint8Array;\n  secretKey: Uint8Array;\n}\n\n/**\n * A signed envelope. The wire format is the concatenation of the sender id\n * length, the sender id bytes, the signature, and the payload. Callers\n * shouldn't rely on the exact layout — use {@link signEnvelope} and\n * {@link openEnvelope} to round-trip.\n */\nexport interface SignedEnvelope {\n  /** Stable sender peer identifier (UTF-8 string). The receiving side uses\n   * this to look up the sender's public key in the document's access set. */\n  senderId: string;\n  /** The original payload bytes, untouched. */\n  payload: Uint8Array;\n  /** 64-byte Ed25519 signature over the payload. */\n  signature: Uint8Array;\n}\n\n/** Errors thrown by the signing subsystem. */\nexport class SigningError extends Error {\n  readonly code:\n    | \"invalid-secret-key\"\n    | \"invalid-public-key\"\n    | \"invalid-signature-length\"\n    | \"envelope-malformed\";\n\n  constructor(message: string, code: SigningError[\"code\"]) {\n    super(message);\n    this.name = \"SigningError\";\n    this.code = code;\n  }\n}\n\n/**\n * Generate a fresh Ed25519 keypair. Calls into tweetnacl's CSPRNG.\n */\nexport function generateSigningKeyPair(): SigningKeyPair {\n  const pair = nacl.sign.keyPair();\n  return {\n    publicKey: pair.publicKey,\n    secretKey: pair.secretKey,\n  };\n}\n\n/**\n * Reconstruct a keypair from an existing 64-byte secret key. Useful for\n * loading keys from persistent storage. Throws if the key is the wrong size.\n */\nexport function signingKeyPairFromSecret(secretKey: Uint8Array): SigningKeyPair {\n  if (secretKey.length !== SECRET_KEY_BYTES) {\n    throw new SigningError(\n      `Ed25519 secret key must be ${SECRET_KEY_BYTES} bytes, got ${secretKey.length}.`,\n      \"invalid-secret-key\"\n    );\n  }\n  const pair = nacl.sign.keyPair.fromSecretKey(secretKey);\n  return {\n    publicKey: pair.publicKey,\n    secretKey: pair.secretKey,\n  };\n}\n\n/**\n * Produce a 64-byte detached signature over the given payload using the\n * supplied secret key.\n */\nexport function sign(payload: Uint8Array, secretKey: Uint8Array): Uint8Array {\n  if (secretKey.length !== SECRET_KEY_BYTES) {\n    throw new SigningError(\n      `Ed25519 secret key must be ${SECRET_KEY_BYTES} bytes, got ${secretKey.length}.`,\n      \"invalid-secret-key\"\n    );\n  }\n  return nacl.sign.detached(payload, secretKey);\n}\n\n/**\n * Verify a detached signature against a payload and a public key. Returns\n * true if the signature is valid, false otherwise. Wrong-length keys or\n * signatures throw {@link SigningError} so callers can distinguish a bad\n * signature from a misshapen input.\n */\nexport function verify(payload: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean {\n  if (publicKey.length !== PUBLIC_KEY_BYTES) {\n    throw new SigningError(\n      `Ed25519 public key must be ${PUBLIC_KEY_BYTES} bytes, got ${publicKey.length}.`,\n      \"invalid-public-key\"\n    );\n  }\n  if (signature.length !== SIGNATURE_BYTES) {\n    throw new SigningError(\n      `Ed25519 signature must be ${SIGNATURE_BYTES} bytes, got ${signature.length}.`,\n      \"invalid-signature-length\"\n    );\n  }\n  return nacl.sign.detached.verify(payload, signature, publicKey);\n}\n\n/**\n * Sign a payload and pack it into a {@link SignedEnvelope} along with the\n * sender id. The mesh network adapter calls this on every outgoing message\n * before handing it to the transport.\n */\nexport function signEnvelope(\n  payload: Uint8Array,\n  senderId: string,\n  secretKey: Uint8Array\n): SignedEnvelope {\n  const signature = sign(payload, secretKey);\n  return { senderId, payload, signature };\n}\n\n/**\n * Verify a {@link SignedEnvelope} against the sender's known public key.\n * Returns the inner payload on success, throws on failure. The mesh\n * network adapter calls this on every incoming message before forwarding\n * the payload to the underlying Automerge sync subsystem.\n */\nexport function openEnvelope(envelope: SignedEnvelope, publicKey: Uint8Array): Uint8Array {\n  const ok = verify(envelope.payload, envelope.signature, publicKey);\n  if (!ok) {\n    throw new SigningError(\n      `Signature verification failed for envelope from ${envelope.senderId}.`,\n      \"envelope-malformed\"\n    );\n  }\n  return envelope.payload;\n}\n\n/**\n * Serialise a {@link SignedEnvelope} to a single binary blob suitable for\n * transmission over a network adapter. Wire format:\n *\n *   [4 bytes BE: senderId byte length]\n *   [N bytes:    senderId UTF-8]\n *   [64 bytes:   signature]\n *   [remaining:  payload]\n *\n * Callers should not depend on the exact bytes — they should round-trip\n * through {@link encodeSignedEnvelope} / {@link decodeSignedEnvelope}.\n */\nexport function encodeSignedEnvelope(envelope: SignedEnvelope): Uint8Array {\n  const senderBytes = new TextEncoder().encode(envelope.senderId);\n  const total = 4 + senderBytes.length + SIGNATURE_BYTES + envelope.payload.length;\n  const out = new Uint8Array(total);\n  const view = new DataView(out.buffer);\n  view.setUint32(0, senderBytes.length, false);\n  out.set(senderBytes, 4);\n  out.set(envelope.signature, 4 + senderBytes.length);\n  out.set(envelope.payload, 4 + senderBytes.length + SIGNATURE_BYTES);\n  return out;\n}\n\n/**\n * Deserialise a binary envelope produced by {@link encodeSignedEnvelope}.\n * Throws on malformed input.\n */\nexport function decodeSignedEnvelope(bytes: Uint8Array): SignedEnvelope {\n  if (bytes.length < 4 + SIGNATURE_BYTES) {\n    throw new SigningError(\n      `Envelope too short: ${bytes.length} bytes, need at least ${4 + SIGNATURE_BYTES}.`,\n      \"envelope-malformed\"\n    );\n  }\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  const senderLen = view.getUint32(0, false);\n  if (bytes.length < 4 + senderLen + SIGNATURE_BYTES) {\n    throw new SigningError(\n      `Envelope truncated: declared sender length ${senderLen}, total ${bytes.length}.`,\n      \"envelope-malformed\"\n    );\n  }\n  const senderId = new TextDecoder().decode(bytes.subarray(4, 4 + senderLen));\n  const signature = bytes.slice(4 + senderLen, 4 + senderLen + SIGNATURE_BYTES);\n  const payload = bytes.slice(4 + senderLen + SIGNATURE_BYTES);\n  return { senderId, payload, signature };\n}\n",
     "/**\n * pairing — Phase 2 first-cut pairing flow for $meshState.\n *\n * Two devices that want to share a $meshState document must exchange three\n * things before sync can begin: the issuer's Ed25519 signing public key\n * (so the receiver can verify ops authored by the issuer), the symmetric\n * document encryption key (so both sides can encrypt and decrypt the\n * shared document), and the issuer's stable peer id (so the receiver\n * knows which entry in its keyring the public key belongs to). This\n * module packs all three into a {@link PairingToken}, serialises it to a\n * compact binary format suitable for QR codes or copy-paste, and provides\n * the matching parse-and-apply flow on the receiving side.\n *\n * Threat model: pairing tokens are transmitted over an out-of-band channel\n * that the user can authenticate visually — typically a QR code on the\n * issuer's device, scanned by the receiver. Because anyone with the token\n * can decrypt and impersonate, the OOB channel is the only authentication.\n * The token includes a TTL (default 10 minutes) so that a token displayed\n * briefly and then dismissed cannot be replayed by an attacker who later\n * gains access to a screenshot. A production deployment would layer a\n * Short Authentication String (SAS) on top — both devices display a code\n * derived from the shared state, and the user verifies they match — but\n * that is a follow-up.\n *\n * The pairing flow is one-way in the Phase 2 first cut. The issuer\n * generates a token and displays it; the receiver applies it and picks\n * up the issuer's keys. The receiver's own keys reach the issuer through\n * the access set: when the receiver sends its first signed op, the issuer\n * records the receiver's public key alongside its peer id and adds it to\n * the keyring. A bidirectional pairing flow that exchanges both sides'\n * keys in a single QR exchange is straightforward to add later but adds\n * UX surface area that is not needed for the mesh transport to work.\n */\n\nimport { KEY_BYTES as ENCRYPTION_KEY_BYTES, generateDocumentKey } from \"./encryption\";\nimport type { MeshKeyring } from \"./mesh-network-adapter\";\nimport {\n  generateSigningKeyPair,\n  PUBLIC_KEY_BYTES as SIGNING_PUBLIC_KEY_BYTES,\n  type SigningKeyPair,\n} from \"./signing\";\n\n/** Current pairing-token format version. Bumped if the wire format changes. */\nexport const PAIRING_TOKEN_VERSION = 1;\n\n/** Magic header bytes for sanity-checking parsed tokens. ASCII \"PPT1\". */\nexport const PAIRING_TOKEN_MAGIC = new Uint8Array([0x50, 0x50, 0x54, 0x31]);\n\n/** Length of the random nonce embedded in every token. */\nexport const PAIRING_NONCE_BYTES = 16;\n\n/** Default TTL applied when {@link createPairingToken} is called without an\n * explicit `ttlMs` option. */\nexport const DEFAULT_PAIRING_TTL_MS = 10 * 60 * 1000; // 10 minutes\n\n/**\n * The contents of a pairing token. Both sides operate on this shape; the\n * binary serialisation is purely for transport.\n */\nexport interface PairingToken {\n  /** Format version. {@link PAIRING_TOKEN_VERSION} at the time of writing. */\n  version: number;\n  /** Stable peer id of the issuing device. The receiver records this as\n   * the lookup key for the issuer's public key in its keyring. */\n  issuerPeerId: string;\n  /** Issuer's Ed25519 signing public key (32 bytes). */\n  issuerPublicKey: Uint8Array;\n  /** Shared document encryption key (32 bytes). The receiver stores this\n   * under {@link documentKeyId} in its keyring. */\n  documentKey: Uint8Array;\n  /** Identifier under which the receiver stores the document key. For the\n   * Phase 2 first cut this is typically the well-known DEFAULT_MESH_KEY_ID\n   * from mesh-network-adapter; per-document keys (one entry per Automerge\n   * document) are a follow-up. */\n  documentKeyId: string;\n  /** Unix timestamp (milliseconds) after which the token is considered\n   * expired and {@link applyPairingToken} refuses to use it. */\n  expiresAt: number;\n  /** 16-byte random nonce. Carried through serialisation so two tokens\n   * with otherwise-identical contents are still distinguishable. */\n  nonce: Uint8Array;\n}\n\n/** Errors thrown by the pairing subsystem. */\nexport class PairingError extends Error {\n  readonly code:\n    | \"expired\"\n    | \"wrong-magic\"\n    | \"unknown-version\"\n    | \"truncated\"\n    | \"invalid-public-key\"\n    | \"invalid-document-key\"\n    | \"invalid-nonce\";\n\n  constructor(message: string, code: PairingError[\"code\"]) {\n    super(message);\n    this.name = \"PairingError\";\n    this.code = code;\n  }\n}\n\n/**\n * Options for {@link createPairingToken}. The signing identity and the\n * document key are required; everything else is optional with sensible\n * defaults.\n */\nexport interface CreatePairingTokenOptions {\n  /** The issuing device's signing keypair. Only the public key ends up in\n   * the token; the secret never leaves the issuer. */\n  identity: SigningKeyPair;\n  /** Stable peer id for the issuing device. */\n  issuerPeerId: string;\n  /** The symmetric document key the receiver should adopt. If omitted, a\n   * fresh key is generated and the caller is responsible for using the\n   * same key on the issuing side too. */\n  documentKey?: Uint8Array;\n  /** Identifier under which the receiver stores the document key. */\n  documentKeyId: string;\n  /** Time-to-live in milliseconds. Defaults to {@link DEFAULT_PAIRING_TTL_MS}. */\n  ttlMs?: number;\n  /** Override the current time. Intended for tests; production code should\n   * not pass this. */\n  now?: () => number;\n}\n\n/**\n * Generate a fresh {@link PairingToken}. The token is ready to be\n * serialised and displayed to the receiver via an OOB channel.\n */\nexport function createPairingToken(options: CreatePairingTokenOptions): PairingToken {\n  const now = options.now ? options.now() : Date.now();\n  const ttlMs = options.ttlMs ?? DEFAULT_PAIRING_TTL_MS;\n  const documentKey = options.documentKey ?? generateDocumentKey();\n  const nonce = randomBytes(PAIRING_NONCE_BYTES);\n\n  return {\n    version: PAIRING_TOKEN_VERSION,\n    issuerPeerId: options.issuerPeerId,\n    issuerPublicKey: options.identity.publicKey,\n    documentKey,\n    documentKeyId: options.documentKeyId,\n    expiresAt: now + ttlMs,\n    nonce,\n  };\n}\n\n/**\n * Generate a fresh pairing token *and* a fresh signing keypair in one call.\n * Convenience for first-time setup where the device has no existing\n * identity yet. Returns both so the caller can persist the keypair and\n * then display the token.\n */\nexport function createPairingTokenWithFreshIdentity(args: {\n  issuerPeerId: string;\n  documentKeyId: string;\n  ttlMs?: number;\n  now?: () => number;\n}): { identity: SigningKeyPair; token: PairingToken } {\n  const identity = generateSigningKeyPair();\n  const token = createPairingToken({\n    identity,\n    issuerPeerId: args.issuerPeerId,\n    documentKeyId: args.documentKeyId,\n    ttlMs: args.ttlMs,\n    now: args.now,\n  });\n  return { identity, token };\n}\n\n/**\n * Check whether a token has expired against the current wall-clock time\n * (or an injected `now`).\n */\nexport function isPairingTokenExpired(token: PairingToken, now?: () => number): boolean {\n  const t = now ? now() : Date.now();\n  return t >= token.expiresAt;\n}\n\n/**\n * Apply a parsed and validated token to a {@link MeshKeyring}. Mutates the\n * keyring in place: adds the issuer's public key to {@link MeshKeyring.knownPeers}\n * and the document key to {@link MeshKeyring.documentKeys}.\n *\n * Throws {@link PairingError} with code \"expired\" if the token's TTL has\n * elapsed. The receiver is expected to apply the token promptly after\n * scanning; rejecting expired tokens prevents replay of long-lived\n * captures.\n */\nexport function applyPairingToken(\n  token: PairingToken,\n  keyring: MeshKeyring,\n  options: { now?: () => number } = {}\n): void {\n  if (isPairingTokenExpired(token, options.now)) {\n    throw new PairingError(\n      `Pairing token from ${token.issuerPeerId} expired at ${new Date(token.expiresAt).toISOString()}.`,\n      \"expired\"\n    );\n  }\n  keyring.knownPeers.set(token.issuerPeerId, token.issuerPublicKey);\n  keyring.documentKeys.set(token.documentKeyId, token.documentKey);\n}\n\n// ─── binary serialisation ──────────────────────────────────────────────────\n\n/**\n * Serialise a token to a binary blob. The wire format is:\n *\n *   [4 bytes:  magic \"PPT1\"]\n *   [1 byte:   version]\n *   [4 bytes BE: issuer id byte length]\n *   [N bytes:  issuer id UTF-8]\n *   [32 bytes: issuer public key]\n *   [32 bytes: document key]\n *   [4 bytes BE: document key id byte length]\n *   [M bytes:  document key id UTF-8]\n *   [8 bytes BE: expiresAt (uint64 milliseconds)]\n *   [16 bytes: nonce]\n *\n * Use {@link encodePairingToken} to round-trip through a base64 string.\n */\nexport function serialisePairingToken(token: PairingToken): Uint8Array {\n  validateForSerialisation(token);\n  const issuerBytes = new TextEncoder().encode(token.issuerPeerId);\n  const keyIdBytes = new TextEncoder().encode(token.documentKeyId);\n\n  const total =\n    PAIRING_TOKEN_MAGIC.length +\n    1 + // version\n    4 + // issuer id length\n    issuerBytes.length +\n    SIGNING_PUBLIC_KEY_BYTES +\n    ENCRYPTION_KEY_BYTES +\n    4 + // doc key id length\n    keyIdBytes.length +\n    8 + // expiresAt\n    PAIRING_NONCE_BYTES;\n\n  const out = new Uint8Array(total);\n  let offset = 0;\n\n  out.set(PAIRING_TOKEN_MAGIC, offset);\n  offset += PAIRING_TOKEN_MAGIC.length;\n\n  out[offset] = token.version;\n  offset += 1;\n\n  const view = new DataView(out.buffer);\n  view.setUint32(offset, issuerBytes.length, false);\n  offset += 4;\n  out.set(issuerBytes, offset);\n  offset += issuerBytes.length;\n\n  out.set(token.issuerPublicKey, offset);\n  offset += SIGNING_PUBLIC_KEY_BYTES;\n\n  out.set(token.documentKey, offset);\n  offset += ENCRYPTION_KEY_BYTES;\n\n  view.setUint32(offset, keyIdBytes.length, false);\n  offset += 4;\n  out.set(keyIdBytes, offset);\n  offset += keyIdBytes.length;\n\n  // Write expiresAt as uint64 BE. JavaScript numbers are float64 but the\n  // value is an integer count of milliseconds, well within 53-bit safe\n  // range for any practical timestamp.\n  view.setBigUint64(offset, BigInt(token.expiresAt), false);\n  offset += 8;\n\n  out.set(token.nonce, offset);\n  offset += PAIRING_NONCE_BYTES;\n\n  return out;\n}\n\n/**\n * Inverse of {@link serialisePairingToken}. Throws {@link PairingError} on\n * malformed input.\n */\nexport function parsePairingToken(bytes: Uint8Array): PairingToken {\n  let offset = 0;\n\n  // Magic\n  if (bytes.length < PAIRING_TOKEN_MAGIC.length) {\n    throw new PairingError(`Pairing token too short: ${bytes.length} bytes.`, \"truncated\");\n  }\n  for (let i = 0; i < PAIRING_TOKEN_MAGIC.length; i++) {\n    if (bytes[offset + i] !== PAIRING_TOKEN_MAGIC[i]) {\n      throw new PairingError(\n        `Pairing token magic mismatch: not a Polly pairing token.`,\n        \"wrong-magic\"\n      );\n    }\n  }\n  offset += PAIRING_TOKEN_MAGIC.length;\n\n  // Version\n  if (bytes.length < offset + 1) {\n    throw new PairingError(\"Pairing token truncated at version.\", \"truncated\");\n  }\n  const version = bytes[offset] as unknown as number;\n  offset += 1;\n  if (version !== PAIRING_TOKEN_VERSION) {\n    throw new PairingError(\n      `Unknown pairing token version: ${version}. This Polly build supports version ${PAIRING_TOKEN_VERSION}.`,\n      \"unknown-version\"\n    );\n  }\n\n  // Issuer id\n  if (bytes.length < offset + 4) {\n    throw new PairingError(\"Pairing token truncated at issuer id length.\", \"truncated\");\n  }\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  const issuerLen = view.getUint32(offset, false);\n  offset += 4;\n  if (bytes.length < offset + issuerLen) {\n    throw new PairingError(\"Pairing token truncated at issuer id.\", \"truncated\");\n  }\n  const issuerPeerId = new TextDecoder().decode(bytes.subarray(offset, offset + issuerLen));\n  offset += issuerLen;\n\n  // Issuer public key\n  if (bytes.length < offset + SIGNING_PUBLIC_KEY_BYTES) {\n    throw new PairingError(\"Pairing token truncated at public key.\", \"truncated\");\n  }\n  const issuerPublicKey = bytes.slice(offset, offset + SIGNING_PUBLIC_KEY_BYTES);\n  offset += SIGNING_PUBLIC_KEY_BYTES;\n\n  // Document key\n  if (bytes.length < offset + ENCRYPTION_KEY_BYTES) {\n    throw new PairingError(\"Pairing token truncated at document key.\", \"truncated\");\n  }\n  const documentKey = bytes.slice(offset, offset + ENCRYPTION_KEY_BYTES);\n  offset += ENCRYPTION_KEY_BYTES;\n\n  // Document key id\n  if (bytes.length < offset + 4) {\n    throw new PairingError(\"Pairing token truncated at document key id length.\", \"truncated\");\n  }\n  const keyIdLen = view.getUint32(offset, false);\n  offset += 4;\n  if (bytes.length < offset + keyIdLen) {\n    throw new PairingError(\"Pairing token truncated at document key id.\", \"truncated\");\n  }\n  const documentKeyId = new TextDecoder().decode(bytes.subarray(offset, offset + keyIdLen));\n  offset += keyIdLen;\n\n  // Expires at\n  if (bytes.length < offset + 8) {\n    throw new PairingError(\"Pairing token truncated at expiry.\", \"truncated\");\n  }\n  const expiresAtBig = view.getBigUint64(offset, false);\n  offset += 8;\n  const expiresAt = Number(expiresAtBig);\n\n  // Nonce\n  if (bytes.length < offset + PAIRING_NONCE_BYTES) {\n    throw new PairingError(\"Pairing token truncated at nonce.\", \"truncated\");\n  }\n  const nonce = bytes.slice(offset, offset + PAIRING_NONCE_BYTES);\n  offset += PAIRING_NONCE_BYTES;\n\n  return {\n    version,\n    issuerPeerId,\n    issuerPublicKey,\n    documentKey,\n    documentKeyId,\n    expiresAt,\n    nonce,\n  };\n}\n\n/**\n * Serialise a token and base64-encode it for QR-code or copy-paste display.\n * The encoding uses the standard base64 alphabet (not URL-safe) because\n * QR codes encode bytes directly and do not care about URL safety.\n */\nexport function encodePairingToken(token: PairingToken): string {\n  const bytes = serialisePairingToken(token);\n  // btoa expects a binary string. Convert via String.fromCharCode per byte;\n  // safe for the ~150-byte token size and avoids the spread-into-fromCharCode\n  // pattern that runs into argument-count limits on large arrays.\n  let binary = \"\";\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary);\n}\n\n/**\n * Decode a base64-encoded pairing token produced by {@link encodePairingToken}.\n * Throws {@link PairingError} on malformed input.\n */\nexport function decodePairingToken(encoded: string): PairingToken {\n  let binary: string;\n  try {\n    binary = atob(encoded);\n  } catch {\n    throw new PairingError(\"Pairing token is not valid base64.\", \"wrong-magic\");\n  }\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return parsePairingToken(bytes);\n}\n\n// ─── helpers ───────────────────────────────────────────────────────────────\n\nfunction validateForSerialisation(token: PairingToken): void {\n  if (token.issuerPublicKey.length !== SIGNING_PUBLIC_KEY_BYTES) {\n    throw new PairingError(\n      `Issuer public key must be ${SIGNING_PUBLIC_KEY_BYTES} bytes, got ${token.issuerPublicKey.length}.`,\n      \"invalid-public-key\"\n    );\n  }\n  if (token.documentKey.length !== ENCRYPTION_KEY_BYTES) {\n    throw new PairingError(\n      `Document key must be ${ENCRYPTION_KEY_BYTES} bytes, got ${token.documentKey.length}.`,\n      \"invalid-document-key\"\n    );\n  }\n  if (token.nonce.length !== PAIRING_NONCE_BYTES) {\n    throw new PairingError(\n      `Nonce must be ${PAIRING_NONCE_BYTES} bytes, got ${token.nonce.length}.`,\n      \"invalid-nonce\"\n    );\n  }\n}\n\nfunction randomBytes(n: number): Uint8Array {\n  const out = new Uint8Array(n);\n  crypto.getRandomValues(out);\n  return out;\n}\n"