bound codex scanner input before parse/decode/hash (PB-26-207, v5.0.63)

@@ -0,0 +1,385 @@1+/**2+ * scan-limits.test.ts — PB-26-207 resource bounds on the Codex scan path.3+ *4+ * Every limit here is derived from the Codex format, not from available5+ * memory: raw scanner text ≤ 4 KiB before JSON.parse; `d` ≤ base64url6+ * expansion of one 350-byte shard before atob; decoded chunk ≤ shard size +7+ * explicit headroom; `c`/`h` exact lengths and integer ranges before any8+ * integrity work; buffer bytes/chunks ≤ MAX_STRIPE_COUNT × max shards per9+ * stripe × chunk size. The camera gate allows one parse/add in flight.10+ */11+12+import { beforeEach, describe, expect, it, vi } from "vitest";13+14+import {15+  CHUNK_SIZE,16+  CODEX_MAX_PARITY_SHARDS,17+  MAX_DATA_SHARDS_PER_STRIPE,18+  MAX_STRIPE_COUNT,19+  type ChunkEnvelope,20+} from "../../shared/codex-types";21+import { buildChunkEnvelope, bytesToBase64Url, sha256Hex } from "./helpers";22+import { _resetReedSolomonCacheForTest } from "./rs-loader";23+import {24+  CHUNK_HASH_LENGTH,25+  ChunkBuffer,26+  createScanGate,27+  MAX_BUFFER_BYTES,28+  MAX_BUFFER_CHUNKS,29+  MAX_CHUNK_B64_CHARS,30+  MAX_DECODED_CHUNK_BYTES,31+  MAX_RAW_SCAN_CHARS,32+  MAX_SHARDS_PER_STRIPE,33+  parseRawScan,34+  VERIFY_CODE_LENGTH,35+} from "./restore";36+37+beforeEach(() => {38+  _resetReedSolomonCacheForTest();39+});40+41+const VERIFY_CODE = "PX-TEST-ABCD";42+43+async function makeEnv(opts: {44+  bytes?: Uint8Array;45+  index?: number;46+  total?: number;47+  verifyCode?: string;48+  stripe?: number;49+  stripeCount?: number;50+} = {}): Promise<ChunkEnvelope> {51+  return buildChunkEnvelope(52+    opts.bytes ?? new Uint8Array(CHUNK_SIZE).fill(7),53+    opts.index ?? 0,54+    opts.total ?? 5,55+    false,56+    opts.verifyCode ?? VERIFY_CODE,57+    opts.stripe ?? 0,58+    opts.stripeCount ?? 1,59+  );60+}61+62+describe("PB-26-207 limit constants derive from the Codex format", () => {63+  it("raw scan ceiling is 4 KiB", () => {64+    expect(MAX_RAW_SCAN_CHARS).toBe(4096);65+  });66+67+  it("d ceiling is the base64url expansion of one shard", () => {68+    expect(MAX_CHUNK_B64_CHARS).toBe(Math.ceil(CHUNK_SIZE / 3) * 4);69+  });70+71+  it("decoded chunk ceiling is one shard plus explicit headroom", () => {72+    expect(MAX_DECODED_CHUNK_BYTES).toBeGreaterThan(CHUNK_SIZE);73+    expect(MAX_DECODED_CHUNK_BYTES - CHUNK_SIZE).toBeLessThanOrEqual(128);74+  });75+76+  it("aggregate ceiling is stripes × max shards per stripe × chunk size", () => {77+    expect(MAX_SHARDS_PER_STRIPE).toBe(78+      MAX_DATA_SHARDS_PER_STRIPE + CODEX_MAX_PARITY_SHARDS,79+    );80+    expect(MAX_BUFFER_CHUNKS).toBe(MAX_STRIPE_COUNT * MAX_SHARDS_PER_STRIPE);81+    expect(MAX_BUFFER_BYTES).toBe(MAX_BUFFER_CHUNKS * CHUNK_SIZE);82+  });83+84+  it("c and h lengths match the documented envelope format", () => {85+    expect(VERIFY_CODE_LENGTH).toBe("PX-XXXX-XXXX".length);86+    expect(CHUNK_HASH_LENGTH).toBe(32);87+  });88+});89+90+describe("PB-26-207 parseRawScan bounds", () => {91+  it("rejects oversized raw text without calling JSON.parse", async () => {92+    const env = await makeEnv();93+    const raw = JSON.stringify(env);94+    expect(raw.length).toBeLessThan(MAX_RAW_SCAN_CHARS);95+    const padded = raw.padEnd(MAX_RAW_SCAN_CHARS + 1, " ");96+    const spy = vi.spyOn(JSON, "parse");97+    try {98+      expect(parseRawScan(padded)).toEqual({ error: "parse_error" });99+      expect(spy).not.toHaveBeenCalled();100+    } finally {101+      spy.mockRestore();102+    }103+  });104+105+  it("accepts a valid envelope padded to exactly the raw ceiling", async () => {106+    const env = await makeEnv();107+    const padded = JSON.stringify(env).padEnd(MAX_RAW_SCAN_CHARS, " ");108+    expect(padded.length).toBe(MAX_RAW_SCAN_CHARS);109+    expect(parseRawScan(padded)).toMatchObject({ v: 3, c: VERIFY_CODE });110+  });111+112+  it("rejects non-string raw input without throwing", () => {113+    expect(parseRawScan(12345 as unknown as string)).toEqual({114+      error: "parse_error",115+    });116+  });117+118+  it("honest envelopes sit far below the raw ceiling", async () => {119+    const env = await makeEnv();120+    expect(JSON.stringify(env).length).toBeLessThan(MAX_RAW_SCAN_CHARS / 2);121+  });122+123+  it("rejects wrong-length c and h before integrity work", async () => {124+    const env = await makeEnv();125+    expect(126+      parseRawScan(JSON.stringify({ ...env, c: "PX-SHORT" })),127+    ).toEqual({ error: "parse_error" });128+    expect(129+      parseRawScan(JSON.stringify({ ...env, c: `${VERIFY_CODE}XX` })),130+    ).toEqual({ error: "parse_error" });131+    expect(parseRawScan(JSON.stringify({ ...env, h: "ABCDEF" }))).toEqual({132+      error: "parse_error",133+    });134+    expect(135+      parseRawScan(JSON.stringify({ ...env, h: `${env.h}FF` })),136+    ).toEqual({ error: "parse_error" });137+  });138+139+  it("rejects oversized d before decoding", async () => {140+    const env = await makeEnv();141+    expect(142+      parseRawScan(143+        JSON.stringify({ ...env, d: `${env.d}AAAA` }),144+      ),145+    ).toEqual({ error: "parse_error" });146+  });147+148+  it("rejects out-of-range stripe/chunk indices", async () => {149+    const env = await makeEnv();150+    const cases: Array<Partial<ChunkEnvelope>> = [151+      { S: 0 },152+      { S: MAX_STRIPE_COUNT + 1 },153+      { s: 1, S: 1 },154+      { s: -1 },155+      { i: -1 },156+      { i: env.t },157+      { t: 0 },158+      { t: MAX_SHARDS_PER_STRIPE + 1 },159+    ];160+    for (const patch of cases) {161+      expect(162+        parseRawScan(JSON.stringify({ ...env, ...patch })),163+        JSON.stringify(patch),164+      ).toEqual({ error: "parse_error" });165+    }166+  });167+168+  it("accepts boundary indices: S=64, s=S-1, i=t-1", async () => {169+    const env = await makeEnv({ index: 4, total: 5, stripe: 63, stripeCount: 64 });170+    expect(parseRawScan(JSON.stringify(env))).toMatchObject({171+      v: 3,172+      S: 64,173+      s: 63,174+      i: 4,175+      t: 5,176+    });177+  });178+});179+180+describe("PB-26-207 ChunkBuffer.add validates before decode/hash", () => {181+  it("rejects oversized d with an honest hash as parse_error, not bad_integrity", async () => {182+    // 400-byte chunk: d is ~534 chars and the hash genuinely matches, so a183+    // post-hash check would accept it. parse_error proves the length gate ran184+    // before atob/alloc/hash.185+    const bytes = new Uint8Array(400).fill(9);186+    const env = await buildChunkEnvelope(bytes, 0, 5, false, VERIFY_CODE);187+    expect(env.d.length).toBeGreaterThan(MAX_CHUNK_B64_CHARS);188+    const buf = new ChunkBuffer();189+    expect(await buf.add(env)).toEqual({190+      accepted: false,191+      reason: "parse_error",192+    });193+    expect(buf.size()).toBe(0);194+    expect(buf.bufferedBytes()).toBe(0);195+  });196+197+  it("d boundary: 468 chars accepted, 469 rejected", async () => {198+    // 351 bytes encode to exactly 468 unpadded chars and stay within the199+    // decoded headroom; a padded 469-char twin of a 350-byte chunk is not.200+    const bytes351 = new Uint8Array(351).fill(3);201+    const atLimit = await buildChunkEnvelope(bytes351, 0, 5, false, VERIFY_CODE);202+    expect(atLimit.d.length).toBe(MAX_CHUNK_B64_CHARS);203+    expect((await new ChunkBuffer().add(atLimit)).accepted).toBe(true);204+205+    const base = await makeEnv();206+    const over = { ...base, d: `${base.d}==` };207+    expect(over.d.length).toBe(MAX_CHUNK_B64_CHARS + 1);208+    const buf = new ChunkBuffer();209+    expect(await buf.add(over)).toEqual({210+      accepted: false,211+      reason: "parse_error",212+    });213+    expect(buf.size()).toBe(0);214+  });215+216+  it("rejects wrong-length c/h and non-boolean p without hashing", async () => {217+    const env = await makeEnv();218+    for (const patch of [219+      { c: "PX-SHORT" },220+      { c: `${VERIFY_CODE}XX` },221+      { h: "00" },222+      { h: `${env.h}FF` },223+      { p: "yes" },224+    ]) {225+      const buf = new ChunkBuffer();226+      expect(await buf.add({ ...env, ...patch } as ChunkEnvelope)).toEqual({227+        accepted: false,228+        reason: "parse_error",229+      });230+      expect(buf.getContext()).toBeNull();231+    }232+  });233+234+  it("rejects an oversized stripe count before decoding", async () => {235+    const env = await buildChunkEnvelope(236+      new Uint8Array([1, 2, 3]),237+      0,238+      5,239+      false,240+      VERIFY_CODE,241+      0,242+      MAX_STRIPE_COUNT + 1,243+    );244+    const buf = new ChunkBuffer();245+    expect(await buf.add(env)).toEqual({246+      accepted: false,247+      reason: "parse_error",248+    });249+    expect(buf.getContext()).toBeNull();250+  });251+252+  it("tracks decoded bytes on accept only", async () => {253+    const buf = new ChunkBuffer();254+    expect(buf.bufferedBytes()).toBe(0);255+    const first = await makeEnv({ index: 0, bytes: new Uint8Array(100).fill(1) });256+    expect((await buf.add(first)).accepted).toBe(true);257+    expect(buf.bufferedBytes()).toBe(100);258+259+    // Duplicate, foreign, corrupt, and malformed inputs leave the counter flat.260+    expect(await buf.add(first)).toEqual({261+      accepted: false,262+      reason: "duplicate",263+    });264+    const foreign = await makeEnv({ index: 1, verifyCode: "PX-OTHR-XXXX" });265+    expect(await buf.add(foreign)).toEqual({266+      accepted: false,267+      reason: "foreign_codex",268+    });269+    const badHash = await makeEnv({ index: 1 });270+    expect(await buf.add({ ...badHash, h: `FF${badHash.h.slice(2)}` })).toEqual(271+      {272+        accepted: false,273+        reason: "bad_integrity",274+      },275+    );276+    const malformed = await makeEnv({ index: 1 });277+    expect(await buf.add({ ...malformed, d: "x".repeat(9999) })).toEqual({278+      accepted: false,279+      reason: "parse_error",280+    });281+    expect(buf.bufferedBytes()).toBe(100);282+    expect(buf.size()).toBe(1);283+  });284+285+  it("enforces the aggregate byte/chunk ceiling: exact fits, +1 fails", async () => {286+    // A 1-chunk, 350-byte budget keeps the enforcement path fast: the287+    // production ceiling uses the same comparison against larger constants.288+    const buf = new ChunkBuffer({ maxBytes: CHUNK_SIZE, maxChunks: 1 });289+    const first = await makeEnv({ index: 0 });290+    expect((await buf.add(first)).accepted).toBe(true);291+    expect(buf.bufferedBytes()).toBe(CHUNK_SIZE);292+293+    const second = await makeEnv({ index: 1 });294+    expect(await buf.add(second)).toEqual({295+      accepted: false,296+      reason: "parse_error",297+    });298+    expect(buf.size()).toBe(1);299+    expect(buf.bufferedBytes()).toBe(CHUNK_SIZE);300+  });301+302+  it("honest 350-byte shards count toward the real aggregate ceiling", async () => {303+    const buf = new ChunkBuffer();304+    const env = await makeEnv({ index: 0 });305+    expect((await buf.add(env)).accepted).toBe(true);306+    expect(buf.bufferedBytes()).toBe(CHUNK_SIZE);307+    expect(buf.bufferedBytes()).toBeLessThanOrEqual(MAX_BUFFER_BYTES);308+    expect(buf.size()).toBeLessThanOrEqual(MAX_BUFFER_CHUNKS);309+  });310+});311+312+describe("PB-26-207 camera scan gate", () => {313+  it("runs one scan at a time and drops repeats while busy", async () => {314+    let release!: () => void;315+    const gate = new Promise<void>((resolve) => {316+      release = resolve;317+    });318+    let calls = 0;319+    const scan = createScanGate(async () => {320+      calls++;321+      await gate;322+    });323+324+    scan.onScan("first");325+    scan.onScan("second");326+    scan.onScan("third");327+    await Promise.resolve();328+    await Promise.resolve();329+    expect(calls).toBe(1);330+331+    release();332+    await gate;333+    await Promise.resolve();334+    await Promise.resolve();335+    // Dropped callbacks are never replayed; the next frame starts new work.336+    scan.onScan("fourth");337+    await Promise.resolve();338+    await Promise.resolve();339+    expect(calls).toBe(2);340+  });341+342+  it("a throwing scan resets the gate without an unhandled rejection", async () => {343+    const errors: unknown[] = [];344+    const scan = createScanGate(async () => {345+      throw new Error("boom");346+    });347+    scan.onScan("bad");348+    await new Promise((resolve) => setTimeout(resolve, 10));349+    // Gate is usable again: a second failure would hang or throw here.350+    let second = 0;351+    const ok = createScanGate(async () => {352+      second++;353+    });354+    ok.onScan("good");355+    await new Promise((resolve) => setTimeout(resolve, 10));356+    expect(second).toBe(1);357+    expect(errors).toEqual([]);358+  });359+});360+361+describe("PB-26-207 existing fixtures remain valid", () => {362+  it("a generator-built envelope passes every new gate", async () => {363+    const bytes = new Uint8Array(CHUNK_SIZE).fill(11);364+    const env = await buildChunkEnvelope(bytes, 2, 5, false, VERIFY_CODE);365+    expect(env.d.length).toBeLessThanOrEqual(MAX_CHUNK_B64_CHARS);366+    const parsed = parseRawScan(JSON.stringify(env));367+    expect("error" in parsed).toBe(false);368+    const buf = new ChunkBuffer();369+    expect((await buf.add(parsed as ChunkEnvelope)).accepted).toBe(true);370+    expect(buf.bufferedBytes()).toBe(CHUNK_SIZE);371+  });372+373+  it("base64url helpers still round-trip the shard size", () => {374+    const bytes = new Uint8Array(CHUNK_SIZE).fill(5);375+    const encoded = bytesToBase64Url(bytes);376+    expect(encoded.length).toBeLessThanOrEqual(MAX_CHUNK_B64_CHARS);377+  });378+379+  it("chunk hash helper still emits the exact documented length", async () => {380+    const hash = (381+      await sha256Hex(new Uint8Array(CHUNK_SIZE).fill(5))382+    ).slice(0, 32);383+    expect(hash).toHaveLength(CHUNK_HASH_LENGTH);384+  });385+});