Add an incremental SHA-256 library for the browser and node tests

2026-09-30 07:27:31 +00:00
parent a27788a80a
commit b56be586ee
7 changed files with 169 additions and 2 deletions
--- a/plans/done/011-browser-sha256-e1793d.md
+++ b/plans/done/011-browser-sha256-e1793d.md
@@ -0,0 +1,248 @@
+---
+id: 011-browser-sha256-e1793d
+title: Add an incremental SHA-256 library for the browser and node tests
+created: 2026-09-29
+depends_on: []
+est_files: 5
+---
+
+# 011 — Incremental SHA-256 for the browser
+
+## Objective
+
+Devices must compute a file's content id (SHA-256) while bytes stream past —
+during a download, a peer transfer, or a chunked OPFS read — without holding the
+file in memory. WebCrypto's `digest()` needs the whole input at once, so add a
+small pure-JS incremental hasher, usable from the page, from Web Workers
+(`importScripts('/sha256.js')`) and from node tests. Pre-tested: all vectors and
+every length 0–200 match `node:crypto`; random chunking of a 3 MiB buffer matches;
+~116 MB/s in Node.
+
+## Context the executor must NOT rediscover
+
+- Module style to copy: `frontend/stats-core.js` — an IIFE `(function (root) { … })(typeof globalThis !== 'undefined' ? globalThis : this);`
+  that sets `module.exports` under node and `root.StatsCore` in the browser. Tests are
+  CommonJS `node:test` (`frontend/stats-core.test.js`).
+- `frontend/index.html:562-569` loads scripts in this order:
+  ```html
+      <script src="fingerprint.js"></script>
+      <script src="opfs.js"></script>
+      <script src="video-edit.js"></script>
+      <script src="lyrics-core.js"></script>
+      <script src="stats-core.js"></script>
+      <script src="async-guard.js"></script>
+      <script src="sw-update.js"></script>
+      <script src="app.js"></script>
+  ```
+- `frontend/sw.js` `SHELL` array (~line 55) must list every shell file.
+
+## Steps
+
+1. Create `frontend/sha256.js` — copy VERBATIM from Appendix A.
+2. Create `frontend/sha256.test.js` — copy VERBATIM from Appendix B.
+3. `frontend/index.html` — add `    <script src="sha256.js"></script>` directly after the
+   `stats-core.js` script line.
+4. `frontend/sw.js` `SHELL` — add `'/sha256.js',` directly after `'/stats-core.js',`.
+5. `CLAUDE.md` "Testing" section — in the list `(sw, sw-update, async-guard, video-edit, lyrics-core, stats-core)`
+   add `, sha256`.
+
+## Out of scope / do NOT touch
+
+- No callers yet (plans 012/013/017 use it). Do not touch `app.js`.
+
+## Verification
+
+```bash
+cd /home/user/ytplayer && node --test frontend/*.test.js 2>&1 | grep -E "^# (pass|fail)"
+node -e "const S=require('./frontend/sha256');console.log(S.hex(new TextEncoder().encode('abc')))"
+grep -c "sha256.js" frontend/index.html frontend/sw.js
+```
+
+Expected: `# fail 0`; `ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad`; each grep `1`.
+
+## Report format (executor: follow exactly)
+
+Output ONLY the following, no other prose:
+
+1. `git diff` (unified) of all changes.
+2. Raw output of the Verification commands.
+3. `Findings:` — max 10 lines.
+
+Do not commit. Do not push. Do not touch files outside the Steps.
+
+---
+
+## Appendix A — frontend/sha256.js
+
+```js
+/* ============================================================================
+ * sha256.js — incremental SHA-256 (pure JS; window.Sha256 / worker / node)
+ *
+ * WebCrypto's digest() needs the whole input at once, which would pull a
+ * multi-hundred-MB video into memory. This hasher takes chunks as they stream
+ * past (downloads, peer transfers, OPFS reads) and keeps ~100 bytes of state.
+ *
+ *   const h = Sha256.create(); h.update(u8); …; const hex = h.hex();
+ *   Sha256.hex(u8)   // one-shot convenience
+ * ========================================================================== */
+(function (root) {
+  'use strict';
+
+  const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+  ]);
+
+  function create() {
+    const H = new Uint32Array([
+      0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const W = new Uint32Array(64);
+    const block = new Uint8Array(64);
+    let blockLen = 0;
+    let total = 0; // bytes hashed so far (safe to 2^53)
+    let done = false;
+
+    function compress(buf, off) {
+      for (let i = 0; i < 16; i++) {
+        const j = off + i * 4;
+        W[i] = (buf[j] << 24) | (buf[j + 1] << 16) | (buf[j + 2] << 8) | buf[j + 3];
+      }
+      for (let i = 16; i < 64; i++) {
+        const w15 = W[i - 15], w2 = W[i - 2];
+        const s0 = ((w15 >>> 7) | (w15 << 25)) ^ ((w15 >>> 18) | (w15 << 14)) ^ (w15 >>> 3);
+        const s1 = ((w2 >>> 17) | (w2 << 15)) ^ ((w2 >>> 19) | (w2 << 13)) ^ (w2 >>> 10);
+        W[i] = (W[i - 16] + s0 + W[i - 7] + s1) | 0;
+      }
+      let a = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
+      for (let i = 0; i < 64; i++) {
+        const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+        const ch = (e & f) ^ (~e & g);
+        const t1 = (h + S1 + ch + K[i] + W[i]) | 0;
+        const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+        const maj = (a & b) ^ (a & c) ^ (b & c);
+        const t2 = (S0 + maj) | 0;
+        h = g; g = f; f = e; e = (d + t1) | 0;
+        d = c; c = b; b = a; a = (t1 + t2) | 0;
+      }
+      H[0] = (H[0] + a) | 0; H[1] = (H[1] + b) | 0; H[2] = (H[2] + c) | 0; H[3] = (H[3] + d) | 0;
+      H[4] = (H[4] + e) | 0; H[5] = (H[5] + f) | 0; H[6] = (H[6] + g) | 0; H[7] = (H[7] + h) | 0;
+    }
+
+    function update(data) {
+      if (done) throw new Error('sha256: update() after digest');
+      const u8 = data instanceof Uint8Array ? data : new Uint8Array(data);
+      let i = 0;
+      total += u8.length;
+      if (blockLen) {
+        const take = Math.min(64 - blockLen, u8.length);
+        block.set(u8.subarray(0, take), blockLen);
+        blockLen += take;
+        i = take;
+        if (blockLen === 64) { compress(block, 0); blockLen = 0; }
+      }
+      for (; i + 64 <= u8.length; i += 64) compress(u8, i);
+      if (i < u8.length) { block.set(u8.subarray(i), 0); blockLen = u8.length - i; }
+      return api;
+    }
+
+    function digest() {
+      if (!done) {
+        done = true;
+        const bits = total * 8;
+        block[blockLen++] = 0x80;
+        if (blockLen > 56) { block.fill(0, blockLen); compress(block, 0); blockLen = 0; }
+        block.fill(0, blockLen, 56);
+        const hi = Math.floor(bits / 0x100000000), lo = bits >>> 0;
+        block[56] = hi >>> 24; block[57] = hi >>> 16; block[58] = hi >>> 8; block[59] = hi;
+        block[60] = lo >>> 24; block[61] = lo >>> 16; block[62] = lo >>> 8; block[63] = lo;
+        compress(block, 0);
+      }
+      const out = new Uint8Array(32);
+      for (let i = 0; i < 8; i++) {
+        out[i * 4] = H[i] >>> 24; out[i * 4 + 1] = H[i] >>> 16; out[i * 4 + 2] = H[i] >>> 8; out[i * 4 + 3] = H[i];
+      }
+      return out;
+    }
+
+    function hex() {
+      let s = '';
+      for (const b of digest()) s += (b < 16 ? '0' : '') + b.toString(16);
+      return s;
+    }
+
+    const api = { update, digest, hex, get bytes() { return total; } };
+    return api;
+  }
+
+  const Sha256 = {
+    create,
+    hex: (data) => create().update(data).hex(),
+    isHex: (s) => typeof s === 'string' && /^[0-9a-f]{64}$/.test(s),
+  };
+  if (typeof module !== 'undefined' && module.exports) module.exports = Sha256;
+  else root.Sha256 = Sha256;
+})(typeof globalThis !== 'undefined' ? globalThis : this);
+```
+
+## Appendix B — frontend/sha256.test.js
+
+```js
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+const crypto = require('node:crypto');
+const Sha256 = require('./sha256');
+
+const ref = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+test('known vectors', () => {
+  assert.strictEqual(Sha256.hex(new Uint8Array(0)), 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
+  assert.strictEqual(Sha256.hex(new TextEncoder().encode('abc')), 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad');
+  assert.strictEqual(
+    Sha256.hex(new TextEncoder().encode('abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq')),
+    '248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1');
+});
+
+test('every length around block boundaries matches node:crypto', () => {
+  for (let n = 0; n <= 200; n++) {
+    const buf = crypto.randomBytes(n);
+    assert.strictEqual(Sha256.hex(new Uint8Array(buf)), ref(buf), 'length ' + n);
+  }
+});
+
+test('random chunk boundaries give the same digest as one shot', () => {
+  const buf = crypto.randomBytes(3 * 1024 * 1024 + 17);
+  for (let round = 0; round < 5; round++) {
+    const h = Sha256.create();
+    let pos = 0;
+    while (pos < buf.length) {
+      const n = Math.min(buf.length - pos, 1 + Math.floor(Math.random() * 200000));
+      h.update(new Uint8Array(buf.buffer, buf.byteOffset + pos, n));
+      pos += n;
+    }
+    assert.strictEqual(h.hex(), ref(buf));
+    assert.strictEqual(h.bytes, buf.length);
+  }
+});
+
+test('update after digest throws; isHex', () => {
+  const h = Sha256.create();
+  h.hex();
+  assert.throws(() => h.update(new Uint8Array(1)));
+  assert.ok(Sha256.isHex(ref(Buffer.from('x'))));
+  assert.ok(!Sha256.isHex('ABC'));
+});
+```
+
+## Execution log
+
+- Executor: in-session Agent (haiku). Attempts: 1. Fix rounds: 0.
+- Orchestrator re-ran Verification: `sha256.js` and `sha256.test.js` byte-identical to the tested versions; `node --test frontend/*.test.js` 56 pass / 0 fail; `abc` digest `ba7816bf...15ad`; index.html and sw.js each reference `sha256.js` once; the CLAUDE.md change is the single plan-authorized line.
+- Executor Findings (verbatim): All steps completed successfully. Two new files created (frontend/sha256.js and frontend/sha256.test.js copied verbatim from appendices). Three existing files modified: index.html (script tag added), sw.js (SHELL array entry added), CLAUDE.md (Testing list updated). All verification commands passed: unit tests 56 pass/0 fail; sha256 hash correct; sha256.js referenced exactly once in each of index.html and sw.js.