helpers.ts

1/**2 * helpers.ts — shared utilities for Codex generation and restoration.3 *4 * These primitives are deliberately small and independent so they can be5 * reused from both `generate.ts` and the (sibling-agent-owned) `restore.ts`6 * without any cross-import surface.7 *8 * SHA-256 stands in for BLAKE3 from the design doc. SHA-256 is available9 * everywhere via WebCrypto (no WASM, no polyfill), preimage-resistant, and10 * gives a stable 8-char-prefix fingerprint that is more than sufficient for11 * catching per-chunk corruption. The on-paper format (`codex-types.ts`)12 * already documents SHA-256 as the canonical hash.13 */1415import {16  CodexError,17  STORAGE_KEY_VERIFY_CODE,18  type ChunkEnvelope,19} from "../../shared/codex-types";2021// ── base64url ────────────────────────────────────────────────────────────────2223/**24 * Encode bytes to base64url (RFC 4648 §5): URL-safe alphabet, no padding.25 * Padding-free output keeps the ChunkEnvelope JSON as small as possible —26 * every byte saved shrinks the printed page count.27 */28export function bytesToBase64Url(bytes: Uint8Array): string {29  let binary = "";30  for (let i = 0; i < bytes.length; i++) {31    binary += String.fromCharCode(bytes[i]!);32  }33  const b64 = (typeof btoa !== "undefined" ? btoa(binary) : Buffer.from(binary, "binary").toString("base64"));34  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");35}3637/** Decode a base64url string back into raw bytes. Tolerant of missing padding. */38export function base64UrlToBytes(s: string): Uint8Array {39  const b64 = s.replace(/-/g, "+").replace(/_/g, "/");40  // base64 requires length % 4 === 0; we strip padding on encode so add it back here.41  const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);42  const binary =43    typeof atob !== "undefined"44      ? atob(padded)45      : Buffer.from(padded, "base64").toString("binary");46  const out = new Uint8Array(binary.length);47  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);48  return out;49}5051/**52 * Total variant of base64UrlToBytes: returns null instead of throwing on53 * invalid input (atob throws InvalidCharacterError on out-of-alphabet chars).54 * Used by ChunkBuffer.add, whose documented contract is "never throws"55 * (PCH-01-026 #2).56 */57export function tryBase64UrlToBytes(s: string): Uint8Array | null {58  try {59    return base64UrlToBytes(s);60  } catch {61    return null;62  }63}6465// ── SHA-256 ─────────────────────────────────────────────────────────────────6667/**68 * Return uppercase hex of SHA-256(bytes). Used for both the per-chunk integrity69 * hash (32-char prefix, 128 bits) and the vault fingerprint (32-char prefix,70 * 128 bits). AUD-004: prefixes were extended from 64 to 128 bits.71 */72export async function sha256Hex(bytes: Uint8Array): Promise<string> {73  // Copy into a fresh ArrayBuffer so the input never reaches SubtleCrypto as74  // a SharedArrayBuffer-backed view — some platforms reject that, and the TS75  // BufferSource typing under `lib.dom` insists on ArrayBuffer-backed views.76  const owned = new Uint8Array(bytes.byteLength);77  owned.set(bytes);78  const hash = await crypto.subtle.digest("SHA-256", owned);79  const view = new Uint8Array(hash);80  let hex = "";81  for (let i = 0; i < view.length; i++) {82    hex += view[i]!.toString(16).padStart(2, "0");83  }84  return hex.toUpperCase();85}8687// ── Chunk envelopes ─────────────────────────────────────────────────────────8889/**90 * Build a ChunkEnvelope for one data or parity chunk. The envelope's `h`91 * field is the first 32 hex chars (128 bits) of SHA-256(rawChunkBytes), so92 * per-chunk corruption introduced after generation (smudge, scan glitch) is93 * detectable at scan time. AUD-004 raised the prefix from 64 to 128 bits.94 *95 * `index` / `total` are within-stripe; `stripe` / `stripeCount` describe the96 * stripe layout for v3. Generators always emit v3 envelopes — even when there97 * is only one stripe — so the format on paper is unambiguous.98 */99export async function buildChunkEnvelope(100  chunkBytes: Uint8Array,101  index: number,102  total: number,103  isParity: boolean,104  verifyCode: string,105  stripe: number = 0,106  stripeCount: number = 1,107): Promise<ChunkEnvelope> {108  const hash = (await sha256Hex(chunkBytes)).slice(0, 32);109  return {110    v: 3,111    c: verifyCode,112    s: stripe,113    S: stripeCount,114    i: index,115    t: total,116    p: isParity,117    d: bytesToBase64Url(chunkBytes),118    h: hash,119  };120}121122/**123 * Confirm the envelope's recorded hash still matches its data. Returns false124 * on any mismatch — caller decides whether to reconstruct from parity or125 * surface a CodexError.126 */127export async function verifyChunkIntegrity(envelope: ChunkEnvelope): Promise<boolean> {128  // AUD-004: accept only the documented prefix lengths — 16 (legacy v1) and129  // 32 (current v2). An empty or truncated hash must not verify true via a130  // zero-length prefix match, and an oversize hash cannot be a valid SHA-256131  // prefix at all.132  if (envelope.h.length !== 16 && envelope.h.length !== 32) return false;133  const bytes = base64UrlToBytes(envelope.d);134  const fullHash = await sha256Hex(bytes);135  const expected = fullHash.slice(0, envelope.h.length);136  return expected === envelope.h;137}138139// ── Verify code lifecycle ───────────────────────────────────────────────────140141/**142 * Unambiguous alphabet: drops `0/O`, `1/I/L`, and `S`. Keeps every character143 * legible at 6pt print or scrawled on paper next to a Codex. Same alphabet144 * used by hardware wallet seed-export QR codes.145 */146const VERIFY_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";147148/** PX-XXXX-XXXX — 12 chars including the literal `PX-` prefix and the dash. */149const VERIFY_CODE_PATTERN = /^PX-[A-Z0-9]{4}-[A-Z0-9]{4}$/;150151/**152 * Read the persisted verify code, or generate-and-persist a fresh one on first153 * call. The code is a stable per-vault identifier — every Codex printed from154 * this vault carries the same code so a user can prove "this Codex matches155 * this Peach install" without revealing any secret.156 *157 * Mirrors the storage pattern from `src/shared/storage.ts` so the same call158 * sites work in both popup and service-worker contexts.159 */160export async function getOrCreateCodexVerifyCode(): Promise<string> {161  const existing = await readStoredVerifyCode();162  if (existing && VERIFY_CODE_PATTERN.test(existing)) return existing;163164  const fresh = generateVerifyCode();165  await writeStoredVerifyCode(fresh);166  return fresh;167}168169function generateVerifyCode(): string {170  const bytes = new Uint8Array(8);171  crypto.getRandomValues(bytes);172  const chars: string[] = [];173  for (let i = 0; i < 8; i++) {174    // Modulo bias is negligible for a 32-char alphabet over a 256-value byte175    // and the verify code is identification, not key material.176    chars.push(VERIFY_CODE_ALPHABET[bytes[i]! % VERIFY_CODE_ALPHABET.length]!);177  }178  return `PX-${chars.slice(0, 4).join("")}-${chars.slice(4, 8).join("")}`;179}180181async function readStoredVerifyCode(): Promise<string | null> {182  if (typeof chrome === "undefined" || !chrome.storage?.local) return null;183  const result = await chrome.storage.local.get(STORAGE_KEY_VERIFY_CODE);184  const value = (result as Record<string, unknown>)[STORAGE_KEY_VERIFY_CODE];185  return typeof value === "string" ? value : null;186}187188async function writeStoredVerifyCode(code: string): Promise<void> {189  if (typeof chrome === "undefined" || !chrome.storage?.local) {190    throw new CodexError(191      "PDF_GENERATION_FAILED",192      "chrome.storage.local is unavailable; cannot persist Codex verify code",193    );194  }195  await chrome.storage.local.set({ [STORAGE_KEY_VERIFY_CODE]: code });196}197198/** Removes the stored verify code so the next call to getOrCreateCodexVerifyCode generates a fresh one. */199export async function clearVerifyCode(): Promise<void> {200  if (typeof chrome === "undefined" || !chrome.storage?.local) return;201  await chrome.storage.local.remove(STORAGE_KEY_VERIFY_CODE);202}