Phase B / B5.8a: sk-creator client-side store + backup module

public/sk-creator-store.js owns the lifecycle of the v3 poll
creator's secret key. generateSkCreator draws 32 bytes from the
platform CSPRNG and reduces mod the BabyJubJub subgroup order;
save/load/clear persist under per-poll localStorage keys; the
backup writer/reader serializes a versioned JSON envelope and
recomputes pk = G·sk on read so a tampered file fails loudly at
restore time rather than later during proof submission.

Includes a memory-storage shim for tests so the unit test runs
without a browser. 19 Node-side checks cover the CSPRNG path,
storage roundtrip, malformed-entry tolerance, backup
parse/tamper-detection, and version/format gating, wired into
go test ./internal/server/...

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: stackdump

internal/server/sk_creator_store_jsparity_test.go

@@ -0,0 +1,24 @@
+package server
+
+import (
+	"os/exec"
+	"testing"
+)
+
+// TestSkCreatorStoreJS runs the Node-side unit tests for
+// public/sk-creator-store.js. The module is pure-data (save/load
+// roundtrip, backup parse, tamper detection) and a divergence here
+// would silently break the v3 close flow at runtime, so we gate it
+// on `go test`.
+func TestSkCreatorStoreJS(t *testing.T) {
+	if _, err := exec.LookPath("node"); err != nil {
+		t.Skip("node not installed; skipping sk-creator-store JS tests")
+	}
+	cmd := exec.Command("node", "public/sk_creator_store_test.mjs")
+	cmd.Dir = findProjectRoot(t)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("sk-creator-store JS tests failed:\n%s\n%v", out, err)
+	}
+	t.Logf("%s", out)
+}

public/sk-creator-store.js

@@ -0,0 +1,186 @@
+// sk-creator-store.js — local storage and backup for the v3 poll
+// creator's secret key (sk_creator).
+//
+// Per the locked-in custody decision (client-only), sk_creator is
+// generated in the browser at poll creation, saved to localStorage,
+// and a JSON backup is offered for download. The server NEVER sees it.
+// Loss of localStorage + backup means the poll cannot be closed —
+// callers must surface that risk in the UI before calling generate.
+
+import { SUBGROUP_ORDER, scalarMulBase, encodePointHex, decodePointHex } from './pedersen.js';
+
+// localStorage key prefix. Includes the poll id so multiple polls'
+// keys coexist without ambiguity.
+const KEY_PREFIX = 'bitwrap-sk-creator-';
+
+// Backup file format version. Bump if the schema changes; restoreFromFile
+// rejects unknown versions to avoid silently mis-parsing future formats.
+const BACKUP_FORMAT_VERSION = 1;
+
+// generateSkCreator returns a fresh sk_creator drawn uniformly from
+// [0, ℓ) where ℓ is the BabyJubJub prime-order subgroup. Uses the
+// platform CSPRNG; throws if crypto.getRandomValues is unavailable.
+export function generateSkCreator() {
+    if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+        throw new Error('sk-creator-store: crypto.getRandomValues unavailable');
+    }
+    // 32 random bytes ≈ 256 bits, then reduce mod ℓ (~252-bit). The
+    // resulting bias is < 2^-252 — negligible for the cryptosystem.
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    let v = 0n;
+    for (const b of bytes) v = (v << 8n) | BigInt(b);
+    return v % SUBGROUP_ORDER;
+}
+
+// derivePkCreator returns the BabyJubJub point pk = G·sk encoded as
+// 32-byte compressed hex. Matches the server's pkCreator wire format.
+export function derivePkCreator(sk) {
+    const pk = scalarMulBase(BigInt(sk));
+    return encodePointHex(pk);
+}
+
+// saveSkCreator persists sk under the per-poll localStorage key.
+// Pass `storage` to use a custom backend (test shim); defaults to
+// browser localStorage. Throws if localStorage is unavailable.
+export function saveSkCreator(pollId, sk, storage) {
+    const s = storage || _defaultStorage();
+    if (!s) throw new Error('sk-creator-store: localStorage unavailable');
+    s.setItem(KEY_PREFIX + pollId, BigInt(sk).toString(10));
+}
+
+// loadSkCreator returns the BigInt sk for pollId, or null if absent.
+// A malformed value (non-decimal) is treated as absent so a junk
+// localStorage entry doesn't cascade into a crypto failure later.
+export function loadSkCreator(pollId, storage) {
+    const s = storage || _defaultStorage();
+    if (!s) return null;
+    const raw = s.getItem(KEY_PREFIX + pollId);
+    if (!raw) return null;
+    try {
+        return BigInt(raw);
+    } catch {
+        return null;
+    }
+}
+
+// clearSkCreator removes the persisted key. Call after a successful
+// close — the key is no longer needed and lingering keys are an
+// avoidable footgun.
+export function clearSkCreator(pollId, storage) {
+    const s = storage || _defaultStorage();
+    if (!s) return;
+    s.removeItem(KEY_PREFIX + pollId);
+}
+
+// makeSkBackupBlob serializes the backup payload as a Blob suitable
+// for FileSaver-style download. Pure data; the actual download is
+// triggered by downloadSkBackup which uses the browser DOM.
+export function makeSkBackupPayload(pollId, sk, pkHex, extras = {}) {
+    return {
+        format: 'bitwrap-sk-creator',
+        version: BACKUP_FORMAT_VERSION,
+        pollId,
+        sk: BigInt(sk).toString(10),
+        pkCreator: pkHex,
+        timestamp: new Date().toISOString(),
+        warning: 'Anyone with this file can decrypt the poll tally. Store it securely.',
+        ...extras,
+    };
+}
+
+// downloadSkBackup triggers a browser download of the sk backup file.
+// Filename includes the poll id prefix. Caller must run in a context
+// where document is defined.
+export function downloadSkBackup(pollId, sk, pkHex, extras = {}) {
+    const payload = makeSkBackupPayload(pollId, sk, pkHex, extras);
+    const json = JSON.stringify(payload, null, 2);
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `bitwrap-poll-${pollId.slice(0, 12)}-creator-key.json`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+
+// restoreFromFile reads a previously-downloaded sk backup file and
+// returns {pollId, sk: BigInt, pkHex}. Validates format/version and
+// asserts pk = G·sk so a tampered file (mismatched sk and pk) fails
+// loudly at restore time rather than later during proof submission.
+export async function restoreFromFile(file) {
+    const text = await readFileAsText(file);
+    return parseSkBackupText(text);
+}
+
+// parseSkBackupText is the synchronous parser used by restoreFromFile;
+// exposed so callers with the JSON already in memory (e.g. a
+// drag-n-drop preview) can validate without touching the File API.
+export function parseSkBackupText(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    } catch (e) {
+        throw new Error('not a valid JSON backup: ' + e.message);
+    }
+    if (parsed.format !== 'bitwrap-sk-creator') {
+        throw new Error(`unexpected backup format: ${parsed.format}`);
+    }
+    if (parsed.version !== BACKUP_FORMAT_VERSION) {
+        throw new Error(`unsupported backup version ${parsed.version} (this build expects ${BACKUP_FORMAT_VERSION})`);
+    }
+    if (!parsed.pollId || !parsed.sk || !parsed.pkCreator) {
+        throw new Error('backup missing required fields (pollId, sk, pkCreator)');
+    }
+    let sk;
+    try {
+        sk = BigInt(parsed.sk);
+    } catch (e) {
+        throw new Error('backup sk is not a decimal big integer');
+    }
+    // Recompute pk = G·sk and check against the embedded pkCreator. A
+    // mismatch means the file has been corrupted or hand-edited; reject
+    // before the caller tries to use the key.
+    const expectedPk = derivePkCreator(sk);
+    if (expectedPk !== parsed.pkCreator.toLowerCase()) {
+        throw new Error('backup pkCreator does not match G·sk — file is corrupted or has been tampered with');
+    }
+    // Round-trip pk through decode to confirm it parses cleanly.
+    decodePointHex(parsed.pkCreator);
+    return {
+        pollId: parsed.pollId,
+        sk,
+        pkHex: parsed.pkCreator,
+    };
+}
+
+// readFileAsText — Promise-wrap FileReader. Lives here rather than
+// poll.js so the test harness can use restoreFromFile against a Blob
+// without pulling in DOM-only globals at module load time.
+function readFileAsText(file) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result);
+        reader.onerror = () => reject(reader.error || new Error('file read failed'));
+        reader.readAsText(file);
+    });
+}
+
+function _defaultStorage() {
+    if (typeof localStorage !== 'undefined') return localStorage;
+    return null;
+}
+
+// Test-friendly export: a tiny in-memory storage shim that mimics the
+// Web Storage API. Lets unit tests run without a browser.
+export function makeMemoryStorage() {
+    const map = new Map();
+    return {
+        getItem: (k) => (map.has(k) ? map.get(k) : null),
+        setItem: (k, v) => map.set(k, String(v)),
+        removeItem: (k) => map.delete(k),
+        clear: () => map.clear(),
+    };
+}

public/sk_creator_store_test.mjs

@@ -0,0 +1,144 @@
+// Unit tests for sk-creator-store.js. Pure-data paths only — the
+// download flow is DOM-bound and exercised by the Playwright E2E in
+// B5.10. Run: node public/sk_creator_store_test.mjs
+
+import { SUBGROUP_ORDER } from './pedersen.js';
+import {
+    generateSkCreator,
+    derivePkCreator,
+    saveSkCreator,
+    loadSkCreator,
+    clearSkCreator,
+    makeSkBackupPayload,
+    parseSkBackupText,
+    makeMemoryStorage,
+} from './sk-creator-store.js';
+
+let failures = 0;
+function ok(cond, msg) {
+    if (!cond) { console.error('FAIL:', msg); failures++; }
+    else console.log('OK:  ', msg);
+}
+function eq(got, want, msg) {
+    if (got !== want) {
+        console.error(`FAIL: ${msg}\n     got:  ${got}\n     want: ${want}`);
+        failures++;
+    } else console.log('OK:  ', msg);
+}
+
+// 1. generateSkCreator returns a BigInt in [0, ℓ).
+{
+    const sk = generateSkCreator();
+    ok(typeof sk === 'bigint', 'generateSkCreator returns BigInt');
+    ok(sk >= 0n && sk < SUBGROUP_ORDER, 'sk is in [0, ℓ)');
+}
+
+// 2. Two consecutive generations differ (CSPRNG, not stub).
+{
+    const a = generateSkCreator();
+    const b = generateSkCreator();
+    ok(a !== b, 'two generations differ');
+}
+
+// 3. derivePkCreator returns a 32-byte (64-hex-char) compressed hex string.
+{
+    const sk = generateSkCreator();
+    const pk = derivePkCreator(sk);
+    eq(pk.length, 64, 'pk is 32 bytes (64 hex chars)');
+    ok(/^[0-9a-f]+$/.test(pk), 'pk is lowercase hex');
+}
+
+// 4. save/load roundtrip.
+{
+    const storage = makeMemoryStorage();
+    const sk = 0xfeedfacecafebeef0123456789abcdefn;
+    saveSkCreator('poll-1', sk, storage);
+    const loaded = loadSkCreator('poll-1', storage);
+    ok(loaded === sk, 'save/load roundtrip');
+
+    // distinct poll
+    ok(loadSkCreator('poll-2', storage) === null, 'unrelated poll returns null');
+}
+
+// 5. load returns null on absent / malformed entries.
+{
+    const storage = makeMemoryStorage();
+    ok(loadSkCreator('nope', storage) === null, 'absent returns null');
+    storage.setItem('bitwrap-sk-creator-junk', 'not-a-bigint');
+    ok(loadSkCreator('junk', storage) === null, 'malformed returns null');
+}
+
+// 6. clearSkCreator removes the entry.
+{
+    const storage = makeMemoryStorage();
+    saveSkCreator('p', 42n, storage);
+    clearSkCreator('p', storage);
+    ok(loadSkCreator('p', storage) === null, 'clear removes entry');
+}
+
+// 7. makeSkBackupPayload + parseSkBackupText roundtrip.
+{
+    const sk = generateSkCreator();
+    const pk = derivePkCreator(sk);
+    const payload = makeSkBackupPayload('poll-abc', sk, pk);
+    const text = JSON.stringify(payload);
+    const parsed = parseSkBackupText(text);
+    eq(parsed.pollId, 'poll-abc', 'parsed pollId');
+    ok(parsed.sk === sk, 'parsed sk matches');
+    eq(parsed.pkHex, pk, 'parsed pkHex matches');
+}
+
+// 8. parseSkBackupText rejects mismatched sk/pk (tamper detection).
+{
+    const sk = generateSkCreator();
+    const pk = derivePkCreator(sk);
+    const altSk = generateSkCreator(); // different key
+    const tampered = JSON.stringify({
+        format: 'bitwrap-sk-creator',
+        version: 1,
+        pollId: 'poll-x',
+        sk: altSk.toString(10),
+        pkCreator: pk, // belongs to the original sk, not altSk
+    });
+    let threw = false;
+    try { parseSkBackupText(tampered); }
+    catch (e) {
+        threw = true;
+        ok(/G·sk/.test(e.message), 'tampered file rejected with G·sk message');
+    }
+    ok(threw, 'tampered file throws');
+}
+
+// 9. parseSkBackupText rejects unknown format / version.
+{
+    let threw = false;
+    try { parseSkBackupText('{"format":"other-format"}'); }
+    catch { threw = true; }
+    ok(threw, 'rejects unknown format');
+
+    threw = false;
+    try {
+        parseSkBackupText(JSON.stringify({
+            format: 'bitwrap-sk-creator', version: 999,
+            pollId: 'p', sk: '1', pkCreator: 'x',
+        }));
+    } catch { threw = true; }
+    ok(threw, 'rejects unknown version');
+}
+
+// 10. parseSkBackupText handles missing fields.
+{
+    let threw = false;
+    try { parseSkBackupText(JSON.stringify({ format: 'bitwrap-sk-creator', version: 1 })); }
+    catch (e) {
+        threw = true;
+        ok(/required fields/.test(e.message), 'missing-fields error message');
+    }
+    ok(threw, 'rejects missing fields');
+}
+
+if (failures > 0) {
+    console.error(`\n${failures} check(s) FAILED`);
+    process.exit(1);
+}
+console.log('\nAll sk-creator-store checks passed.');