add popup codex library: compression+RS erasure+Aztec roundtrip+PDF render+helpers+28 unit tests

@@ -0,0 +1,130 @@1+/**2+ * Tests for src/background/codex-handlers.ts.3+ *4+ * These exercise the gate logic and error paths without standing up a full5+ * vault — license and vault modules are mocked. The one happy-path that6+ * needs a real vault is exercised via the messages.test.ts harness; here we7+ * focus on the boundary behaviour the handler owns.8+ */9+10+import { beforeEach, describe, expect, it, vi } from "vitest";11+12+type StorageShape = Record<string, unknown>;13+14+describe("codex handlers", () => {15+  let storage: StorageShape;16+17+  beforeEach(() => {18+    vi.resetModules();19+    vi.doUnmock("./vault");20+    vi.doUnmock("./license");21+    storage = {};22+23+    const chromeMock = {24+      storage: {25+        local: {26+          get: vi.fn(async (key?: string | string[]) => {27+            if (!key) return storage;28+            if (typeof key === "string") return { [key]: storage[key] };29+            return key.reduce<Record<string, unknown>>((acc, k) => {30+              acc[k] = storage[k];31+              return acc;32+            }, {});33+          }),34+          set: vi.fn(async (next: Record<string, unknown>) => {35+            Object.assign(storage, next);36+          }),37+          remove: vi.fn(async (keys: string | string[]) => {38+            const list = Array.isArray(keys) ? keys : [keys];39+            for (const k of list) delete storage[k];40+          }),41+        },42+      },43+    } as unknown as typeof chrome;44+    (globalThis as { chrome?: typeof chrome }).chrome = chromeMock;45+  });46+47+  it("handleGetCodexVaultData rejects free users with pro_required", async () => {48+    vi.doMock("./license", () => ({ isProUser: vi.fn(async () => false) }));49+    vi.doMock("./vault", () => ({50+      isUnlocked: () => true,51+      getEntries: () => [],52+      getRecoveryWords: async () => null,53+    }));54+    const { handleGetCodexVaultData } = await import("./codex-handlers");55+    const result = await handleGetCodexVaultData();56+    expect(result).toEqual({ ok: false, error: "pro_required" });57+  });58+59+  it("handleGetCodexVaultData returns VAULT_LOCKED for locked vault", async () => {60+    vi.doMock("./license", () => ({ isProUser: vi.fn(async () => true) }));61+    vi.doMock("./vault", () => ({62+      isUnlocked: () => false,63+      getEntries: () => {64+        throw new Error("vault locked");65+      },66+      getRecoveryWords: async () => {67+        throw new Error("vault locked");68+      },69+    }));70+    const { handleGetCodexVaultData } = await import("./codex-handlers");71+    const result = await handleGetCodexVaultData();72+    expect(result.ok).toBe(false);73+    expect(result.error).toMatch(/^VAULT_LOCKED/);74+  });75+76+  it("handleEstimateCodexPages returns >=1 page for a real slotA blob", async () => {77+    vi.doMock("./license", () => ({ isProUser: vi.fn(async () => true) }));78+    vi.doMock("./vault", () => ({})); // unused on this path79+    // A representative slotA-shaped record; field contents don't matter for80+    // the size estimate — only the JSON-serialised byte count does.81+    storage.peach_vault_a = {82+      version: 1,83+      salt: "00".repeat(16),84+      nonce: "00".repeat(12),85+      // ~2 KiB of hex so the deflated stream lands in a predictable range.86+      ciphertext: "ab".repeat(1024),87+      tag: "00".repeat(16),88+    };89+    storage.peach_vault_b = {90+      version: 1,91+      salt: "11".repeat(16),92+      nonce: "11".repeat(12),93+      ciphertext: "cd".repeat(1024),94+      tag: "11".repeat(16),95+    };96+    const { handleEstimateCodexPages } = await import("./codex-handlers");97+    const result = await handleEstimateCodexPages();98+    expect(result.ok).toBe(true);99+    expect(typeof result.pages).toBe("number");100+    expect(result.pages!).toBeGreaterThanOrEqual(1);101+  });102+103+  it("handleRestoreFromCodex rejects an invalid blob with INVALID_VAULT_BLOB", async () => {104+    vi.doMock("./license", () => ({ isProUser: vi.fn(async () => false) }));105+    const unlockFromCodex = vi.fn();106+    vi.doMock("./vault", () => ({107+      unlockFromCodex,108+      isUnlocked: () => false,109+      getEntries: () => [],110+    }));111+    vi.doMock("../shared/native", () => ({112+      isNativePlatform: () => false,113+      nativePlugin: () => null,114+    }));115+116+    const { handleRestoreFromCodex } = await import("./codex-handlers");117+    const result = await handleRestoreFromCodex({118+      vaultBlob: "this-is-not-valid-base64url-json!!!",119+      timestamp: 0,120+      verifyCode: "PX-AAAA-BBBB",121+      vaultFingerprint: "0".repeat(16),122+      entryCount: 0,123+      masterPassphrase: "ignored",124+    });125+    expect(result).toEqual({ ok: false, error: "INVALID_VAULT_BLOB" });126+    // Restoration must short-circuit before reaching the vault module on a127+    // malformed blob — we never want to touch storage on garbage input.128+    expect(unlockFromCodex).not.toHaveBeenCalled();129+  });130+});

@@ -0,0 +1,281 @@1+/**2+ * codex-handlers.ts — message handlers that back the Peach Codex flow.3+ *4+ * Three pure async functions that messages.ts dispatches to. Each takes its5+ * already-parsed payload and returns the response object that messages.ts6+ * forwards to the popup. No `case` syntax, no chrome.runtime.onMessage glue7+ * here — that lives in messages.ts.8+ *9+ * Design references:10+ *  - /Users/june/Downloads/peach_codex_v2.md ("Message handlers", "Pro gating")11+ *  - src/shared/codex-types.ts for the wire contract12+ *  - src/background/vault.ts for the storage invariants (Projects.md §3.2–3.6)13+ */14+15+import { deflate } from "pako";16+17+import { isProUser } from "./license";18+import * as vault from "./vault";19+import { isNativePlatform, nativePlugin } from "../shared/native";20+import type { VaultEntry } from "../shared/types";21+import {22+  type CodexRestorePayload,23+  type CodexVaultSnapshot,24+  CHUNK_SIZE,25+  CODES_PER_PAGE,26+  PARITY_SHARDS,27+  STORAGE_KEY_LAST_RESTORED,28+  STORAGE_KEY_VERIFY_CODE,29+} from "../shared/codex-types";30+31+// ── Verify-code helpers ─────────────────────────────────────────────────────32+33+const VERIFY_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no I/O/0/134+35+/**36+ * Format: `PX-XXXX-XXXX`. 8 random Crockford-ish characters split into two37+ * groups of four. Stable identifier for a vault across Codex prints — once38+ * minted it lives in storage and is reused for every future Codex from this39+ * device, so the user can recognise "their" Codex visually.40+ */41+function mintVerifyCode(): string {42+  const random = new Uint8Array(8);43+  crypto.getRandomValues(random);44+  let group = "";45+  for (let i = 0; i < 8; i++) {46+    group += VERIFY_CODE_ALPHABET[random[i] % VERIFY_CODE_ALPHABET.length];47+  }48+  return `PX-${group.slice(0, 4)}-${group.slice(4, 8)}`;49+}50+51+async function getOrCreateVerifyCode(): Promise<string> {52+  const raw = await chrome.storage.local.get(STORAGE_KEY_VERIFY_CODE);53+  const existing = (raw as Record<string, unknown>)[STORAGE_KEY_VERIFY_CODE];54+  if (typeof existing === "string" && existing.length > 0) {55+    return existing;56+  }57+  const fresh = mintVerifyCode();58+  await chrome.storage.local.set({ [STORAGE_KEY_VERIFY_CODE]: fresh });59+  return fresh;60+}61+62+// ── base64url decoding ──────────────────────────────────────────────────────63+64+/**65+ * Inlined to keep this module decoupled from popup/passkey helpers. The Codex66+ * vaultBlob is base64url-encoded (no padding) JSON; decode to a UTF-8 string.67+ */68+function base64urlToString(b64url: string): string {69+  const pad = b64url.length % 4 === 0 ? "" : "=".repeat(4 - (b64url.length % 4));70+  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/") + pad;71+  const binary = atob(b64);72+  const bytes = new Uint8Array(binary.length);73+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);74+  return new TextDecoder().decode(bytes);75+}76+77+// ── Mobile autofill bridge — duplicated here intentionally ─────────────────78+// messages.ts has its own copy; we don't import from messages.ts because79+// that would create a cycle. The plugin shape is small and stable.80+81+async function publishInMemoryVault(entries: VaultEntry[]): Promise<void> {82+  const plugin = nativePlugin<{83+    setEntries?: (args: {84+      entries: Array<{85+        id: string;86+        title: string;87+        username: string;88+        email: string;89+        password: string;90+        url: string;91+        totp: string;92+        additionalUrls: string[];93+      }>;94+    }) => Promise<void>;95+  }>("InMemoryVaultPlugin");96+  if (!plugin?.setEntries) return;97+  await plugin.setEntries({98+    entries: entries.map((e) => ({99+      id: e.id,100+      title: e.title ?? "",101+      username: e.username ?? "",102+      email: (e as VaultEntry & { email?: string }).email ?? "",103+      password: e.password ?? "",104+      url: e.url ?? "",105+      totp: (e as VaultEntry & { totp?: string }).totp ?? "",106+      additionalUrls:107+        (e as VaultEntry & { additionalUrls?: string[] }).additionalUrls ?? [],108+    })),109+  });110+}111+112+// ── Handlers ────────────────────────────────────────────────────────────────113+114+/**115+ * Read everything the popup needs to build a CodexPayload. Pro-gated:116+ * generating a Codex is a Pro feature (restoring one is not — see117+ * `handleRestoreFromCodex`).118+ */119+export async function handleGetCodexVaultData(): Promise<{120+  ok: boolean;121+  error?: string;122+  data?: CodexVaultSnapshot;123+}> {124+  if (!(await isProUser())) {125+    return { ok: false, error: "pro_required" };126+  }127+  if (!vault.isUnlocked()) {128+    return { ok: false, error: "VAULT_LOCKED: Unlock your vault first." };129+  }130+131+  const raw = await chrome.storage.local.get([132+    "peach_vault_a",133+    "peach_vault_b",134+    "peach_last_modified_at",135+  ]);136+  const slotARaw = (raw as Record<string, unknown>)["peach_vault_a"];137+  const slotBRaw = (raw as Record<string, unknown>)["peach_vault_b"];138+  const lastModRaw = (raw as Record<string, unknown>)["peach_last_modified_at"];139+140+  if (!slotARaw) {141+    return { ok: false, error: "VAULT_EMPTY: No vault to print." };142+  }143+144+  // chrome.storage stores objects directly; serialise to JSON strings to145+  // produce the slot blobs the Codex format expects.146+  const slotA = JSON.stringify(slotARaw);147+  const slotB = slotBRaw ? JSON.stringify(slotBRaw) : null;148+  const lastModified = typeof lastModRaw === "string" ? lastModRaw : null;149+150+  // Recovery words exist only on v2.12+ vaults that have completed migration.151+  // A missing root key throws; treat that as "no words available" rather than152+  // a hard error so the Codex can still print without them.153+  let recoveryWords: string[] | null = null;154+  try {155+    recoveryWords = await vault.getRecoveryWords();156+  } catch {157+    recoveryWords = null;158+  }159+160+  const verifyCode = await getOrCreateVerifyCode();161+  const entryCount = vault.getEntries().length;162+163+  const snapshot: CodexVaultSnapshot = {164+    slotA,165+    slotB,166+    lastModified,167+    entryCount,168+    recoveryWords,169+    verifyCode,170+    vaultUnlocked: true,171+  };172+  return { ok: true, data: snapshot };173+}174+175+/**176+ * Cheap pre-flight: estimate how many A4 pages the Codex will need so the177+ * popup can warn the user before kicking off the full generation pipeline.178+ * Pro-gated for the same reason as `handleGetCodexVaultData`.179+ *180+ * Falls back to a safe over-estimate (3 pages) on any error — better to181+ * promise more pages than the user actually needs than to surprise them.182+ */183+export async function handleEstimateCodexPages(): Promise<{184+  ok: boolean;185+  error?: string;186+  pages?: number;187+}> {188+  if (!(await isProUser())) {189+    return { ok: false, error: "pro_required" };190+  }191+  try {192+    const raw = await chrome.storage.local.get(["peach_vault_a", "peach_vault_b"]);193+    const slotA = (raw as Record<string, unknown>)["peach_vault_a"];194+    const slotB = (raw as Record<string, unknown>)["peach_vault_b"];195+    if (!slotA) return { ok: true, pages: 3 };196+197+    // Match the generator's payload shape: { a, b } JSON, deflated. The198+    // popup's real generator does the same compression on the actual199+    // CodexPayload, but slot ciphertext dominates the size and dwarfs the200+    // envelope, so a deflate of the slot blobs is a faithful estimate.201+    const blobJson = JSON.stringify({ a: slotA, b: slotB ?? null });202+    const compressed = deflate(new TextEncoder().encode(blobJson));203+    const dataChunks = Math.ceil(compressed.length / CHUNK_SIZE);204+    const totalChunks = dataChunks + PARITY_SHARDS;205+    const pages = Math.max(1, Math.ceil(totalChunks / CODES_PER_PAGE));206+    return { ok: true, pages };207+  } catch {208+    return { ok: true, pages: 3 };209+  }210+}211+212+/**213+ * Restore the vault from a scanned Codex.214+ *215+ * NOT Pro-gated by design. The Codex was earned by a Pro user; we must never216+ * block them from recovering their own vault, even from a free device. See217+ * peach_codex_v2.md "Pro gating".218+ */219+export async function handleRestoreFromCodex(220+  payload: CodexRestorePayload,221+): Promise<{222+  ok: boolean;223+  error?: string;224+  data?: { entryCount: number; verifyCode: string };225+}> {226+  // Parse the base64url-wrapped JSON { a, b }. Malformed input is a hard227+  // refusal — we will not write garbage into slotA.228+  let slotAJson: string;229+  let slotBJson: string | null;230+  try {231+    const decoded = base64urlToString(payload.vaultBlob);232+    const parsed = JSON.parse(decoded) as { a: unknown; b: unknown };233+    if (!parsed || typeof parsed !== "object" || parsed.a == null) {234+      return { ok: false, error: "INVALID_VAULT_BLOB" };235+    }236+    slotAJson = JSON.stringify(parsed.a);237+    slotBJson = parsed.b == null ? null : JSON.stringify(parsed.b);238+  } catch {239+    return { ok: false, error: "INVALID_VAULT_BLOB" };240+  }241+242+  const result = await vault.unlockFromCodex({243+    slotA: slotAJson,244+    slotB: slotBJson,245+    timestamp: payload.timestamp,246+    masterPassphrase: payload.masterPassphrase,247+  });248+249+  if (!result.ok) {250+    if (result.reason === "wrong_passphrase") {251+      return { ok: false, error: "wrong_passphrase" };252+    }253+    return { ok: false, error: "INVALID_VAULT_BLOB" };254+  }255+256+  // Persist the Codex's verify code as this device's verify code so future257+  // Codex prints from here keep the same identifier. Also record the restore258+  // time so Settings can surface "restored from Codex at …".259+  await chrome.storage.local.set({260+    [STORAGE_KEY_VERIFY_CODE]: payload.verifyCode,261+    [STORAGE_KEY_LAST_RESTORED]: Date.now(),262+  });263+264+  // Mirror the UNLOCK handler's mobile-bridge step so the Android autofill265+  // service sees the newly-restored entries without requiring a re-lock.266+  if (isNativePlatform()) {267+    try {268+      await publishInMemoryVault(vault.getEntries());269+    } catch {270+      // Non-fatal — autofill will catch up on the next unlock.271+    }272+  }273+274+  return {275+    ok: true,276+    data: {277+      entryCount: result.entryCount,278+      verifyCode: payload.verifyCode,279+    },280+  };281+}

@@ -0,0 +1,252 @@1+/**2+ * aztec.ts — Aztec 2D barcode generation with round-trip verification.3+ *4+ * The library has two entry points:5+ *   - browser:  `bwip-js` — uses Canvas/OffscreenCanvas for rasterization6+ *   - node:     `bwip-js/node` — uses zlib-PNG, returns a Buffer directly7+ *8+ * We resolve which one to use at runtime so the popup (browser context) and9+ * vitest (node context) both work without any build-time conditional. The10+ * resolved module is cached because importing parses ~500KB of generated JS.11+ *12+ * Round-trip verification: every generated Aztec is decoded back via @zxing13+ * and the decoded text is compared byte-for-byte with the original envelope14+ * JSON. Without the round-trip we have no proof that what we printed is15+ * actually readable. In the popup the decode runs through OffscreenCanvas.16+ * In a pure node test environment OffscreenCanvas is unavailable, so we17+ * fall back to a no-op verification — the generation tests for that path18+ * cover the encoder via separate code paths.19+ */20+21+import {22+  BarcodeFormat,23+  BinaryBitmap,24+  DecodeHintType,25+  HybridBinarizer,26+  MultiFormatReader,27+  RGBLuminanceSource,28+} from "@zxing/library";29+import {30+  AZTEC_ECC_PERCENT,31+  CodexError,32+  type ChunkEnvelope,33+} from "../../shared/codex-types";34+35+export interface AztecImage {36+  pngBytes: Uint8Array;37+  width: number;38+  height: number;39+}40+41+// ── bwip-js loader ───────────────────────────────────────────────────────────42+43+/**44+ * In browser builds the popup bundler resolves `bwip-js` to the browser entry45+ * which exports `toCanvas`. In node (vitest) we want `bwip-js/node` which46+ * exports `toBuffer`. We can't import both unconditionally — node can't load47+ * the browser entry's canvas code, and the browser can't load `node:zlib`.48+ *49+ * The detection is "do we have a working OffscreenCanvas?" rather than50+ * "is `process` defined?" because the popup runs in an MV3 worker context51+ * where some Node globals leak via polyfills.52+ */53+interface BwipBrowserModule {54+  toCanvas: (55+    canvas: OffscreenCanvas | HTMLCanvasElement,56+    opts: Record<string, unknown>,57+  ) => OffscreenCanvas | HTMLCanvasElement;58+}59+60+interface BwipNodeModule {61+  toBuffer: (opts: Record<string, unknown>) => Promise<Buffer>;62+}63+64+let cachedBwip: BwipBrowserModule | BwipNodeModule | null = null;65+let cachedIsBrowser: boolean | null = null;66+67+async function loadBwip(): Promise<{68+  mod: BwipBrowserModule | BwipNodeModule;69+  isBrowser: boolean;70+}> {71+  if (cachedBwip && cachedIsBrowser !== null) {72+    return { mod: cachedBwip, isBrowser: cachedIsBrowser };73+  }74+  const isBrowser = typeof OffscreenCanvas !== "undefined";75+76+  // Pick the entrypoint explicitly. Vite (and therefore vitest) tends to77+  // resolve the bare `bwip-js` specifier against the package's browser export78+  // condition even when running under node — so we route node test runs79+  // through `bwip-js/node` directly, which gives us the toBuffer-shaped API.80+  const spec = isBrowser ? "bwip-js" : "bwip-js" + "/node";81+  const ns = (await import(/* @vite-ignore */ spec)) as Record<string, unknown>;82+  const defaultExport = ns["default"] as Record<string, unknown> | undefined;83+  // ESM dynamic import surface differs between the two builds: the browser84+  // bundle exports `toCanvas` as a named export, while the node bundle is85+  // CJS-shaped and exposes `toBuffer` on `default`. Merge both so callers86+  // can use either method without caring which path resolved.87+  const merged = { ...(defaultExport ?? {}), ...ns } as Record<string, unknown>;88+  const resolved = merged as unknown as BwipBrowserModule | BwipNodeModule;89+  cachedBwip = resolved;90+  cachedIsBrowser = isBrowser;91+  return { mod: resolved, isBrowser };92+}93+94+// ── Aztec PNG generation ────────────────────────────────────────────────────95+96+/**97+ * Render an Aztec barcode at 25% ECC and return its PNG bytes. The PNG is98+ * intentionally monochrome at scale 4 — that's the smallest scale that still99+ * looks crisp at print resolution while keeping per-code rendering well under100+ * 100ms on modest hardware.101+ */102+export async function generateAztecPng(payload: string): Promise<AztecImage> {103+  const { mod, isBrowser } = await loadBwip();104+  const opts = {105+    bcid: "azteccode",106+    text: payload,107+    eclevel: AZTEC_ECC_PERCENT.toString(),108+    scale: 4,109+    padding: 0,110+    monochrome: true,111+  } as const;112+113+  try {114+    if (isBrowser) {115+      const canvas = new OffscreenCanvas(1, 1);116+      const drawn = (mod as BwipBrowserModule).toCanvas(canvas, opts);117+      const out = drawn as OffscreenCanvas;118+      const blob = await out.convertToBlob({ type: "image/png" });119+      const pngBytes = new Uint8Array(await blob.arrayBuffer());120+      return { pngBytes, width: out.width, height: out.height };121+    }122+123+    const buf = await (mod as BwipNodeModule).toBuffer(opts);124+    const pngBytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength).slice();125+    const { width, height } = readPngDimensions(pngBytes);126+    return { pngBytes, width, height };127+  } catch (err) {128+    throw new CodexError(129+      "AZTEC_GENERATION_FAILED",130+      `Aztec render failed: ${err instanceof Error ? err.message : String(err)}`,131+    );132+  }133+}134+135+/** Read a PNG's IHDR width/height. PNGs always have IHDR as the first chunk. */136+function readPngDimensions(png: Uint8Array): { width: number; height: number } {137+  // PNG signature: 8 bytes, then 4-byte chunk length, "IHDR", then width/height as big-endian uint32.138+  if (png.length < 24) {139+    throw new CodexError("AZTEC_GENERATION_FAILED", "PNG buffer too small to contain IHDR");140+  }141+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);142+  const width = view.getUint32(16, false);143+  const height = view.getUint32(20, false);144+  return { width, height };145+}146+147+// ── Aztec PNG decoding (round-trip) ─────────────────────────────────────────148+149+/**150+ * Decode an Aztec PNG via @zxing. Returns the decoded UTF-8 text, or `null`151+ * if decoding fails for any reason (no DOM, malformed PNG, no match found).152+ * Never throws — the caller decides whether a `null` result is a verification153+ * failure or a deliberate skip.154+ */155+export async function decodeAztecFromPng(pngBytes: Uint8Array): Promise<string | null> {156+  // The decoder needs raw pixel data, which means we need a canvas to157+  // rasterize the PNG into ImageData. Skip the round-trip in environments158+  // without OffscreenCanvas (vitest with environment: 'node').159+  if (typeof OffscreenCanvas === "undefined" || typeof createImageBitmap === "undefined") {160+    return null;161+  }162+163+  try {164+    // Copy into a fresh ArrayBuffer-backed view so Blob's typing is satisfied165+    // (the input Uint8Array may be backed by a SharedArrayBuffer in some166+    // bundler typings, which Blob's BlobPart union rejects).167+    const owned = new Uint8Array(pngBytes.byteLength);168+    owned.set(pngBytes);169+    const blob = new Blob([owned], { type: "image/png" });170+    const bitmap = await createImageBitmap(blob);171+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);172+    const ctx = canvas.getContext("2d");173+    if (!ctx) return null;174+    ctx.drawImage(bitmap, 0, 0);175+    const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);176+177+    // RGBLuminanceSource wants packed 32-bit ARGB values, not raw Uint8 RGBA.178+    const argb = new Int32Array(bitmap.width * bitmap.height);179+    const raw = imageData.data;180+    for (let i = 0, j = 0; i < raw.length; i += 4, j++) {181+      argb[j] = (0xff << 24) | (raw[i]! << 16) | (raw[i + 1]! << 8) | raw[i + 2]!;182+    }183+184+    const source = new RGBLuminanceSource(argb, bitmap.width, bitmap.height);185+    const binarizer = new HybridBinarizer(source);186+    const bitmapBinary = new BinaryBitmap(binarizer);187+188+    const reader = new MultiFormatReader();189+    const hints = new Map();190+    hints.set(DecodeHintType.POSSIBLE_FORMATS, [BarcodeFormat.AZTEC]);191+    hints.set(DecodeHintType.TRY_HARDER, true);192+    reader.setHints(hints);193+194+    const result = reader.decode(bitmapBinary);195+    return result.getText();196+  } catch {197+    return null;198+  }199+}200+201+// ── Verified Aztec generation ───────────────────────────────────────────────202+203+/**204+ * Generate the Aztec code for one envelope and confirm it round-trips. The205+ * envelope JSON is serialized once and reused as the decode target so any206+ * encoding mismatch (e.g. UTF-8 surrogate corruption) is caught immediately.207+ *208+ * In environments where round-trip decoding is unavailable (vitest node), the209+ * verification step is skipped — the generator still throws on encoder210+ * failure, which is the only condition this path can detect without a DOM.211+ */212+export async function generateVerifiedAztec(envelope: ChunkEnvelope): Promise<AztecImage> {213+  const envelopeJson = JSON.stringify(envelope);214+215+  let image: AztecImage;216+  try {217+    image = await generateAztecPng(envelopeJson);218+  } catch (err) {219+    if (err instanceof CodexError) throw err;220+    throw new CodexError(221+      "AZTEC_GENERATION_FAILED",222+      `Failed to generate Aztec code for chunk ${envelope.i}: ${err instanceof Error ? err.message : String(err)}`,223+    );224+  }225+226+  if (!image.pngBytes || image.pngBytes.length < 32) {227+    throw new CodexError(228+      "AZTEC_GENERATION_FAILED",229+      `Aztec PNG for chunk ${envelope.i} was empty`,230+    );231+  }232+233+  // Skip round-trip when we can't rasterize — see decodeAztecFromPng().234+  if (typeof OffscreenCanvas === "undefined" || typeof createImageBitmap === "undefined") {235+    return image;236+  }237+238+  const decoded = await decodeAztecFromPng(image.pngBytes);239+  if (decoded === null) {240+    throw new CodexError(241+      "AZTEC_ROUNDTRIP_FAILED",242+      `Chunk ${envelope.i} generated but cannot be decoded back. This Codex cannot be trusted.`,243+    );244+  }245+  if (decoded !== envelopeJson) {246+    throw new CodexError(247+      "AZTEC_CONTENT_MISMATCH",248+      `Chunk ${envelope.i} decoded content does not match original envelope. Possible encoding corruption.`,249+    );250+  }251+  return image;252+}

@@ -0,0 +1,196 @@1+/**2+ * erasure.ts — Reed-Solomon erasure coding around the WASM library.3+ *4+ * The library wants a single contiguous buffer of length5+ *   (dataShards + parityShards) * shardSize6+ * with data shards laid out first, followed by space for parity. `encode()`7+ * fills the parity region in-place. `reconstruct()` rewrites missing shards8+ * in-place using a `shardsAvailable: boolean[]` mask.9+ *10+ * We expose a chunk-oriented API (`encodeWithErasure` / `decodeWithErasure`)11+ * because the rest of the codex pipeline thinks in terms of individual12+ * envelopes. Both adapters allocate a fresh buffer per call — the library is13+ * not re-entrant on a shared buffer.14+ */15+16+import { ReedSolomonErasure } from "@digitaldefiance/reed-solomon-erasure.wasm";17+import {18+  CHUNK_SIZE,19+  CodexError,20+  PARITY_SHARDS,21+} from "../../shared/codex-types";22+import { getReedSolomon } from "./rs-loader";23+24+/**25+ * The shared rs-loader caches a single `ReedSolomonErasure` instance, which26+ * is fine for `encode()` but trips a known library bug on the SECOND call to27+ * `reconstruct()` against the same instance: the internal __wbindgen state28+ * survives between calls and the second reconstruction reports29+ * RESULT_ERROR_TOO_FEW_SHARDS_PRESENT even when enough shards are present.30+ *31+ * To get correct behaviour we (a) use the loader to ensure the WASM is32+ * actually instantiable and to cache the bytes lazily, and (b) build a fresh33+ * `ReedSolomonErasure` instance for every reconstruction. The cost is a few34+ * milliseconds per call — negligible compared to compressing the vault and35+ * rendering Aztec codes.36+ */37+let cachedWasmBytes: Uint8Array | null = null;38+39+async function freshReedSolomon(): Promise<ReedSolomonErasure> {40+  if (cachedWasmBytes) {41+    return ReedSolomonErasure.fromBytes(cachedWasmBytes);42+  }43+  // Capture bytes by intercepting the loader's first instantiation. The44+  // loader caches its own promise, so calling it twice is cheap on the second45+  // pass. We pull bytes from the WASM memory image after the fact — see46+  // `loadWasmBytes` below for the lazy initialization.47+  await getReedSolomon();48+  if (!cachedWasmBytes) {49+    cachedWasmBytes = await loadWasmBytes();50+  }51+  return ReedSolomonErasure.fromBytes(cachedWasmBytes);52+}53+54+/**55+ * Load the WASM bytes through the same probing logic rs-loader uses, so this56+ * file does not assume any specific filesystem layout. In the popup the57+ * loader's fetch path is the source of truth; in vitest it's the on-disk58+ * path under `node_modules/`. This helper is deliberately a duplicate of59+ * the bytes-only portion of rs-loader — we cannot touch rs-loader itself60+ * (orchestrator-owned), and we need raw bytes to work around the library's61+ * reuse bug.62+ */63+async function loadWasmBytes(): Promise<Uint8Array> {64+  const inPopup =65+    typeof chrome !== "undefined" &&66+    typeof chrome.runtime !== "undefined" &&67+    typeof chrome.runtime.getURL === "function";68+  if (inPopup) {69+    const url = chrome.runtime.getURL("codex/reed_solomon_erasure_bg.wasm");70+    const response = await fetch(url);71+    if (!response.ok) {72+      throw new CodexError(73+        "ERASURE_CODING_VERIFICATION_FAILED",74+        `Failed to fetch WASM: ${response.status}`,75+      );76+    }77+    return new Uint8Array(await response.arrayBuffer());78+  }79+  const fs = await import("node:fs");80+  const path = await import("node:path");81+  const wasmPath = path.resolve(82+    "node_modules/@digitaldefiance/reed-solomon-erasure.wasm/dist/reed_solomon_erasure_bg.wasm",83+  );84+  return new Uint8Array(fs.readFileSync(wasmPath));85+}86+87+export interface EncodeResult {88+  dataChunks: Uint8Array[];89+  parityChunks: Uint8Array[];90+  totalChunks: number;91+  dataShards: number;92+}93+94+/**95+ * Split `data` into fixed-size shards and compute `PARITY_SHARDS` parity96+ * shards. Pads the trailing data shard with zeros — the original byte length97+ * is recovered via the `CodexPayload.vaultBlob` (no length prefix needed on98+ * the wire because the outer JSON already bounds the data).99+ */100+export async function encodeWithErasure(data: Uint8Array): Promise<EncodeResult> {101+  const rs = await freshReedSolomon();102+103+  const dataShards = Math.max(1, Math.ceil(data.length / CHUNK_SIZE));104+  const totalShards = dataShards + PARITY_SHARDS;105+  const buffer = new Uint8Array(totalShards * CHUNK_SIZE);106+  buffer.set(data, 0); // Trailing bytes after `data.length` stay zero — the pad.107+108+  const code = rs.encode(buffer, dataShards, PARITY_SHARDS);109+  if (code !== ReedSolomonErasure.RESULT_OK) {110+    throw new CodexError(111+      "ERASURE_CODING_VERIFICATION_FAILED",112+      `Reed-Solomon encode failed: ${ReedSolomonErasure.getResultMessage(code)}`,113+    );114+  }115+116+  // Slice() copies so each shard owns its memory and callers cannot mutate117+  // the working buffer through a returned view.118+  const dataChunks: Uint8Array[] = [];119+  for (let i = 0; i < dataShards; i++) {120+    dataChunks.push(buffer.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE));121+  }122+  const parityChunks: Uint8Array[] = [];123+  for (let i = 0; i < PARITY_SHARDS; i++) {124+    const base = (dataShards + i) * CHUNK_SIZE;125+    parityChunks.push(buffer.slice(base, base + CHUNK_SIZE));126+  }127+128+  return { dataChunks, parityChunks, totalChunks: totalShards, dataShards };129+}130+131+/**132+ * Reassemble the data-shard region from a partial set of chunks. Missing133+ * shards are reconstructed from parity. The returned buffer is exactly134+ * `dataShards * CHUNK_SIZE` bytes long, including any trailing pad bytes135+ * — callers strip the pad using their out-of-band length information.136+ */137+export async function decodeWithErasure(138+  chunks: Map<number, Uint8Array>,139+  dataShards: number,140+  totalShards: number,141+): Promise<Uint8Array> {142+  const parityShards = totalShards - dataShards;143+  if (parityShards < 0) {144+    throw new CodexError(145+      "ERASURE_CODING_VERIFICATION_FAILED",146+      `Invalid shard layout: dataShards=${dataShards} totalShards=${totalShards}`,147+    );148+  }149+150+  if (chunks.size < dataShards) {151+    throw new CodexError(152+      "INSUFFICIENT_CHUNKS",153+      `Need at least ${dataShards} chunks, have ${chunks.size}`,154+    );155+  }156+157+  const rs = await freshReedSolomon();158+  const buffer = new Uint8Array(totalShards * CHUNK_SIZE);159+  const available: boolean[] = new Array(totalShards).fill(false);160+161+  for (const [index, chunk] of chunks) {162+    if (index < 0 || index >= totalShards) {163+      throw new CodexError(164+        "ERASURE_CODING_VERIFICATION_FAILED",165+        `Chunk index ${index} out of range [0, ${totalShards})`,166+      );167+    }168+    if (chunk.length !== CHUNK_SIZE) {169+      throw new CodexError(170+        "ERASURE_CODING_VERIFICATION_FAILED",171+        `Chunk ${index} has length ${chunk.length}, expected ${CHUNK_SIZE}`,172+      );173+    }174+    buffer.set(chunk, index * CHUNK_SIZE);175+    available[index] = true;176+  }177+178+  const code = rs.reconstruct(buffer, dataShards, parityShards, available);179+  if (code !== ReedSolomonErasure.RESULT_OK) {180+    // The library distinguishes "not enough shards" with its own code; map it181+    // back to our INSUFFICIENT_CHUNKS so handlers upstream can surface a182+    // clean "scan more codes" prompt instead of a generic library error.183+    if (code === ReedSolomonErasure.RESULT_ERROR_TOO_FEW_SHARDS_PRESENT) {184+      throw new CodexError(185+        "INSUFFICIENT_CHUNKS",186+        `Need at least ${dataShards} valid chunks for reconstruction`,187+      );188+    }189+    throw new CodexError(190+      "ERASURE_CODING_VERIFICATION_FAILED",191+      `Reed-Solomon reconstruct failed: ${ReedSolomonErasure.getResultMessage(code)}`,192+    );193+  }194+195+  return buffer.slice(0, dataShards * CHUNK_SIZE);196+}