hbengine 0.2.3

package/engine-shell/host/engine-v1.js

@@ -0,0 +1,438 @@
+/**
+ * `engine-v1` in the browser: the pack hash of SPEC.md §1.3 and the derivation
+ * of §2, as the Verify tab of the shell's Provably Fair dialog (page.js) runs
+ * them for a player. Web Crypto for HMAC-SHA256 and SHA-256, BigInt for the
+ * 64-bit draws, nothing imported — the page's policy is `script-src 'self'`
+ * and a verifier that pulls code from elsewhere is not one the player can
+ * trust.
+ *
+ * The reference is the backend's CommonJS verifier, kept byte for byte at
+ * ../verifiers/engine-verify.js (housegames-backend
+ * internal/engine/verifiers/engine-verify.js, whose sha256 engine-v1.test.js
+ * pins). Node's `crypto` is synchronous and the browser's is not, and the
+ * reference reads files where this reads the public /math document, so this
+ * is a port, not a copy: engine-v1.test.js holds it to the reference on both
+ * golden packs (BAD CAT, and the parity pack whose rows carry every escape
+ * the canonical form has a rule for), on random seeds, nonces, modes and
+ * bets, on a byte order mark, on a document that is not UTF-8 and on every
+ * pack the reference refuses, so the two cannot drift apart unnoticed.
+ */
+
+const subtle = globalThis.crypto.subtle;
+const utf8 = new TextEncoder();
+
+// ---- bytes → text, as the Go reference reads them ----------------------------
+// A pack is UTF-8. The /math document's manifest is the studio's submitted
+// bytes as they are — hashed, served and kept on record as they are — so a
+// manifest that is not well-formed UTF-8 is refused at upload
+// (mathpack.Load), by the reference (readManifestText) and by the retention
+// that keeps the document, never admitted as U+FFFD into a document no text
+// column could hold. A table's bytes are canonicalised on the way in (one
+// U+FFFD per byte that is not well-formed, as Go decodes), so the rows the
+// document carries are UTF-8 already. The document is therefore UTF-8 end to
+// end, and one that is not is not the server's: it is refused here as the
+// reference refuses the manifest. `fatal` refuses; `ignoreBOM` keeps a byte
+// order mark as the character it is to Go and to the reference, wherever it
+// stands — a decoder that stripped one at the start would hash a manifest
+// the server never hashed.
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+/** The text of `bytes` (Uint8Array or ArrayBuffer); an Error when they are not well-formed UTF-8. */
+export function textFromBytes(bytes) {
+    try {
+        return utf8Decoder.decode(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+    } catch (e) {
+        throw new Error('the document is not UTF-8');
+    }
+}
+
+// ---- canonical JSON: keys sorted, no whitespace, numbers as written ---------
+// A tiny parser that keeps each number's source text, so `2.50` stays `2.50`
+// exactly as the Go reference does. Strings are escaped the way Go's
+// encoding/json escapes them: `"` `\` and the short escapes \b \f \n \r \t,
+// every other control character as \u00xx, `<` `>` `&` U+2028 U+2029 as
+// \uXXXX, everything else as itself. An escaped surrogate pair is one code
+// point; a lone surrogate is U+FFFD. Keys sort by code point.
+
+export function canonicalJSON(text) {
+    let i = 0;
+    const ws = () => { while (i < text.length && ' \t\r\n'.includes(text[i])) i++; };
+    const fail = (m) => { throw new Error(`canonical json: ${m} at ${i}`); };
+    function value() {
+        ws();
+        const c = text[i];
+        if (c === '{') return object();
+        if (c === '[') return array();
+        if (c === '"') return string();
+        if (c === 't' && text.startsWith('true', i)) { i += 4; return 'true'; }
+        if (c === 'f' && text.startsWith('false', i)) { i += 5; return 'false'; }
+        if (c === 'n' && text.startsWith('null', i)) { i += 4; return 'null'; }
+        const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(text.slice(i));
+        if (!m) fail('unexpected token');
+        i += m[0].length;
+        return m[0];
+    }
+    function object() {
+        i++; ws();
+        const entries = [];
+        if (text[i] === '}') { i++; return '{}'; }
+        for (;;) {
+            ws();
+            if (text[i] !== '"') fail('expected key');
+            const k = rawString();
+            ws();
+            if (text[i] !== ':') fail('expected :');
+            i++;
+            entries.push([k, value()]);
+            ws();
+            if (text[i] === ',') { i++; continue; }
+            if (text[i] === '}') { i++; break; }
+            fail('expected , or }');
+        }
+        if (new Set(entries.map(([k]) => k)).size !== entries.length) fail('duplicate key');
+        entries.sort((a, b) => compareCodePoints(a[0], b[0]));
+        return '{' + entries.map(([k, v]) => escapeString(k) + ':' + v).join(',') + '}';
+    }
+    function array() {
+        i++; ws();
+        const items = [];
+        if (text[i] === ']') { i++; return '[]'; }
+        for (;;) {
+            items.push(value());
+            ws();
+            if (text[i] === ',') { i++; continue; }
+            if (text[i] === ']') { i++; break; }
+            fail('expected , or ]');
+        }
+        return '[' + items.join(',') + ']';
+    }
+    function rawString() {
+        // returns the decoded string
+        i++;
+        let out = '';
+        for (;;) {
+            if (i >= text.length) fail('unterminated string');
+            const c = text[i++];
+            if (c === '"') return out;
+            // A raw control character inside a string is not JSON; Go's scanner
+            // refuses it, so a verifier that escaped it would hash a pack the
+            // gate never takes.
+            if (c.charCodeAt(0) < 0x20) fail('control character in string');
+            if (c !== '\\') { out += c; continue; }
+            const e = text[i++];
+            if (e === 'u') { out += String.fromCodePoint(unicodeEscape()); continue; }
+            const short = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' }[e];
+            if (short === undefined) fail('bad escape');
+            out += short;
+        }
+    }
+    // unicodeEscape reads the XXXX of a \uXXXX (i is just past the u). A high
+    // surrogate followed by an escaped low surrogate is one code point. A
+    // surrogate on its own is U+FFFD, as Go's decoder has it, and whatever
+    // escape follows a lone high surrogate is read on its own.
+    function unicodeEscape() {
+        const cp = hex4(i);
+        i += 4;
+        if (cp < 0xd800 || cp > 0xdfff) return cp;
+        if (cp <= 0xdbff && text[i] === '\\' && text[i + 1] === 'u') {
+            const low = hex4(i + 2);
+            if (low >= 0xdc00 && low <= 0xdfff) {
+                i += 6;
+                return 0x10000 + ((cp - 0xd800) << 10) + (low - 0xdc00);
+            }
+        }
+        return 0xfffd;
+    }
+    function hex4(at) {
+        const h = text.slice(at, at + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(h)) fail('bad \\u escape');
+        return parseInt(h, 16);
+    }
+    function string() { return escapeString(rawString()); }
+    const out = value();
+    ws();
+    if (i !== text.length) fail('trailing data');
+    return out;
+}
+
+// compareCodePoints orders keys as the Go reference does: by code point,
+// which is UTF-8 byte order. JavaScript's own `<` compares UTF-16 code
+// units, which would put an emoji before U+E000..U+FFFF.
+export function compareCodePoints(a, b) {
+    let i = 0, j = 0;
+    while (i < a.length && j < b.length) {
+        const x = a.codePointAt(i), y = b.codePointAt(j);
+        if (x !== y) return x - y;
+        i += x > 0xffff ? 2 : 1;
+        j += y > 0xffff ? 2 : 1;
+    }
+    return (a.length - i) - (b.length - j);
+}
+
+export function escapeString(s) {
+    let out = '"';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (ch === '"') out += '\\"';
+        else if (ch === '\\') out += '\\\\';
+        else if (ch === '\b') out += '\\b';
+        else if (ch === '\f') out += '\\f';
+        else if (ch === '\n') out += '\\n';
+        else if (ch === '\r') out += '\\r';
+        else if (ch === '\t') out += '\\t';
+        else if (cp < 0x20 || ch === '<' || ch === '>' || ch === '&' || cp === 0x2028 || cp === 0x2029) {
+            out += '\\u' + cp.toString(16).padStart(4, '0');
+        } else out += ch;
+    }
+    return out + '"';
+}
+
+// ---- pack ------------------------------------------------------------------------
+
+// A weight is what Go's strconv.ParseUint(s, 10, 64) takes: ASCII digits and
+// nothing else. BigInt() alone would also take `0x10`, `+5` and ` 5`, and a
+// verifier must not hash a table the gate refuses.
+const WEIGHT = /^[0-9]+$/;
+
+export function parseTable(name, text) {
+    const rows = [];
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '') lines.pop();
+    for (const line of lines) {
+        if (line.startsWith('#') && rows.length === 0) continue;
+        const tab = line.indexOf('\t');
+        const field = tab < 0 ? line : line.slice(0, tab);
+        if (!WEIGHT.test(field)) throw new Error(`${name}: weight ${JSON.stringify(field)} is not a decimal integer`);
+        const w = BigInt(field);
+        if (w <= 0n) throw new Error(`${name}: weight must be > 0`);
+        let data = null;
+        if (tab >= 0) {
+            // The data column is one JSON value: never empty, never holding a
+            // second tab or a carriage return (a CRLF file is refused, as in Go).
+            const rest = line.slice(tab + 1);
+            if (rest === '' || /[\t\r]/.test(rest)) throw new Error(`${name}: malformed data column`);
+            data = canonicalJSON(rest);
+        }
+        rows.push({ weight: w, data });
+    }
+    if (rows.length < 2) throw new Error(`${name}: needs at least 2 rows`);
+    const cum = [];
+    let sum = 0n;
+    for (const r of rows) { sum += r.weight; cum.push(sum); }
+    if (sum > (1n << 63n)) throw new Error(`${name}: weights sum past 2^63`);
+    return { name, rows, cum, sum };
+}
+
+export function tableBytes(t) {
+    return t.rows.map((r) => r.weight.toString() + (r.data === null ? '' : '\t' + r.data) + '\n').join('');
+}
+
+/**
+ * The raw text of one member of the JSON object `text`, exactly as written:
+ * what the hash commits to is the manifest's own bytes, canonicalised, and a
+ * JSON.parse → JSON.stringify round trip would rewrite them.
+ */
+export function rawMember(text, key) {
+    let i = 0;
+    const ws = () => { while (i < text.length && ' \t\r\n'.includes(text[i])) i++; };
+    const fail = (m) => { throw new Error(`json: ${m} at ${i}`); };
+    function skipString() {
+        i++;
+        for (;;) {
+            if (i >= text.length) fail('unterminated string');
+            const c = text[i++];
+            if (c === '"') return;
+            if (c === '\\') i++;
+        }
+    }
+    function skipValue() {
+        ws();
+        const c = text[i];
+        if (c === '"') return skipString();
+        if (c === '{' || c === '[') {
+            const close = c === '{' ? '}' : ']';
+            i++; ws();
+            if (text[i] === close) { i++; return; }
+            for (;;) {
+                if (c === '{') { ws(); if (text[i] !== '"') fail('expected key'); skipString(); ws(); if (text[i] !== ':') fail('expected :'); i++; }
+                skipValue();
+                ws();
+                if (text[i] === ',') { i++; continue; }
+                if (text[i] === close) { i++; return; }
+                fail('expected , or ' + close);
+            }
+        }
+        const m = /^(true|false|null|-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?)/.exec(text.slice(i));
+        if (!m) fail('unexpected token');
+        i += m[0].length;
+    }
+    ws();
+    if (text[i] !== '{') fail('expected an object');
+    i++; ws();
+    if (text[i] === '}') return null;
+    for (;;) {
+        ws();
+        if (text[i] !== '"') fail('expected key');
+        const start = i;
+        skipString();
+        const k = JSON.parse(text.slice(start, i));
+        ws();
+        if (text[i] !== ':') fail('expected :');
+        i++; ws();
+        const from = i;
+        skipValue();
+        if (k === key) return text.slice(from, i);
+        ws();
+        if (text[i] === ',') { i++; continue; }
+        if (text[i] === '}') return null;
+        fail('expected , or }');
+    }
+}
+
+export const FORMAT = 'house-engine-math/1';
+
+/**
+ * A pack from the public document GET /engine/v1/math/<slug>?version=<hash>
+ * answers: `{format, hash, manifest, tables{name: tsv}, report}`. Takes the
+ * response bytes (or its text), never the parsed object, so the manifest's
+ * bytes are the server's own; the manifest is canonicalised here, so a
+ * document the reference refuses (a repeated key, a control character, bytes
+ * that are not UTF-8) is refused before anything is drawn from it.
+ */
+export function packFromDocument(source) {
+    const text = typeof source === 'string' ? source : textFromBytes(source);
+    const doc = JSON.parse(text);
+    if (!doc || typeof doc !== 'object' || doc.format !== FORMAT) throw new Error(`not a ${FORMAT} document`);
+    const manifestText = rawMember(text, 'manifest');
+    if (!manifestText || !doc.manifest || !Array.isArray(doc.manifest.modes)) throw new Error('the document has no manifest');
+    if (!doc.tables || typeof doc.tables !== 'object') throw new Error('the document has no tables');
+    const manifestCanonical = canonicalJSON(manifestText);
+    const tables = {};
+    for (const m of doc.manifest.modes) {
+        const names = m.kind === 'table' ? [m.table] : (m.steps || []).map((s) => s.table);
+        for (const n of names) {
+            if (tables[n]) continue;
+            if (typeof doc.tables[n] !== 'string') throw new Error(`the document lacks table ${n}`);
+            tables[n] = parseTable(n, doc.tables[n]);
+        }
+    }
+    return { manifest: doc.manifest, manifestText, manifestCanonical, tables, hash: typeof doc.hash === 'string' ? doc.hash : '', report: doc.report };
+}
+
+/**
+ * Loads and verifies one public maths document for the shell. The Provably Fair
+ * dialog and the sandbox test panel share this owner so they ask for the same
+ * version and hash the exact bytes the round server served.
+ */
+export async function loadPack(api, game, version, fetcher = globalThis.fetch) {
+    if (!/^[0-9a-f]{64}$/.test(version)) throw new Error('version');
+    const url = `${api}/engine/v1/math/${encodeURIComponent(game)}?version=${version}`;
+    const res = await fetcher(url, { credentials: 'omit' });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const pack = packFromDocument(new Uint8Array(await res.arrayBuffer()));
+    pack.recomputed = await mathHash(pack);
+    return pack;
+}
+
+export const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function sha256Hex(text) {
+    return hex(new Uint8Array(await subtle.digest('SHA-256', utf8.encode(text))));
+}
+
+export async function mathHash(pack) {
+    let s = 'house-engine-math/1\n';
+    s += 'manifest\n' + (pack.manifestCanonical || canonicalJSON(pack.manifestText)) + '\n';
+    for (const name of Object.keys(pack.tables).sort(compareCodePoints)) s += 'table ' + name + '\n' + tableBytes(pack.tables[name]);
+    return sha256Hex(s);
+}
+
+// ---- engine-v1 stream and draw ----------------------------------------------------
+
+/**
+ * The stream of §2: block_i = HMAC_SHA256(key = serverSeed, msg =
+ * "clientSeed:nonce:i"), consumed 8 bytes at a time, big-endian. `blocks`
+ * keeps every block computed (message and digest) for anyone walking a draw
+ * by hand; the draw itself reads nothing from it.
+ */
+export function stream(serverSeed, clientSeed, nonce) {
+    let key = null, block = 0, buf = new Uint8Array(0), off = 0;
+    const blocks = [];
+    const byte = async () => {
+        if (off >= buf.length) {
+            if (!key) key = await subtle.importKey('raw', utf8.encode(serverSeed), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+            const message = `${clientSeed}:${nonce}:${block}`;
+            buf = new Uint8Array(await subtle.sign('HMAC', key, utf8.encode(message)));
+            blocks.push({ block, message, digest: hex(buf) });
+            block++; off = 0;
+        }
+        return buf[off++];
+    };
+    return {
+        async u64() { let v = 0n; for (let k = 0; k < 8; k++) v = (v << 8n) | BigInt(await byte()); return v; },
+        blocks,
+    };
+}
+
+export const TWO64 = 1n << 64n;
+
+/** One row of `table` from the stream `s`, with the rejected count and, for the page, the arithmetic. */
+export async function pick(table, s) {
+    const rem = TWO64 % table.sum;
+    const limit = TWO64 - rem;
+    let rejected = 0;
+    for (;;) {
+        const v = await s.u64();
+        if (v < limit) {
+            const r = v % table.sum;
+            let lo = 0, hi = table.cum.length - 1;
+            while (lo < hi) { const mid = (lo + hi) >> 1; if (table.cum[mid] > r) hi = mid; else lo = mid + 1; }
+            return { raw: v, rejected, index: lo, table: table.name, sum: table.sum, limit, r };
+        }
+        rejected++;
+    }
+}
+
+const inRanges = (rs, i) => rs.some(([lo, hi]) => i >= lo && i <= hi);
+
+/**
+ * A round re-derived: the same draws, multiplier and ladder outcome the server
+ * computed for (serverSeed, clientSeed, nonce) under `pack`, SPEC §2. A ladder
+ * is drawn every step at the bet; a cash-out after k steps pays ladderBp[k-1],
+ * which the receipt's `multBp` names.
+ */
+export async function play(pack, modeId, betId, serverSeed, clientSeed, nonce) {
+    const mode = pack.manifest.modes.find((m) => m.id === modeId);
+    if (!mode) throw new Error(`no mode ${modeId}`);
+    const bet = mode.bets.find((b) => b.id === betId);
+    if (!bet) throw new Error(`no bet ${betId}`);
+    const s = stream(serverSeed, clientSeed, nonce);
+    if (mode.kind === 'table') {
+        const d = await pick(pack.tables[mode.table], s);
+        const tier = bet.tiers.find((t) => inRanges(t.outcomes, d.index));
+        return { mode: modeId, bet: betId, kind: 'table', draws: [d], multBp: tier ? tier.multBp : 0, blocks: s.blocks };
+    }
+    const draws = []; let survived = 0, busted = false;
+    for (const step of mode.steps) {
+        const d = await pick(pack.tables[step.table], s);
+        draws.push(d);
+        if (!busted && inRanges(bet.survive, d.index)) survived++; else busted = true;
+    }
+    busted = survived < mode.steps.length;
+    const multBp = mode.autoAdvance && !busted ? mode.ladderBp[mode.steps.length - 1] : 0;
+    return { mode: modeId, bet: betId, kind: 'ladder', draws, multBp, survived, busted, ladderBp: mode.ladderBp, blocks: s.blocks };
+}
+
+/**
+ * What a stake pays at a multiplier, as the server computes it (housegames-backend
+ * internal/services/engine.go enginePayout → moneymath.TruncateProduct): both
+ * sides in whole 1e-8 units, the product truncated to a unit, never rounded up.
+ */
+export function payoutOf(amount, multBp) {
+    const a = Number(amount), m = Number(multBp);
+    if (!(a > 0) || !(m > 0) || !Number.isFinite(a) || !Number.isSafeInteger(m)) return 0;
+    const units = BigInt(Math.round(a * 1e8));
+    const mult = BigInt(Math.round((m / 10000) * 1e8));
+    if (units >= (1n << 62n) || mult >= (1n << 62n)) return 0;
+    return Number((units * mult) / 100000000n) / 1e8;
+}