hbengine 0.2.3

package/engine-shell/host/boot.js

@@ -0,0 +1,408 @@
+/**
+ * The shell page: the frame the site launches for an engine game.
+ *
+ *   launch URL  <games host>[/housegames]/engine/play/<slug>/?otp=…&currency=…
+ *               (from House Studio's sandbox, play.housestudio.io: &ticket=… too)
+ *   1. the one-time code is taken off the address bar and exchanged at
+ *      <prefix>/direct/session for a short player token (the House
+ *      Originals' launch, unchanged);
+ *   2. the engine session is minted with it and kept in memory only;
+ *   3. the game's bundle is framed sandboxed (no network, no storage, no
+ *      session) and the router connects the two;
+ *   4. the site hears the same bridge messages Coin Flip sends.
+ *
+ * Every endpoint is this page's own origin, under the path the page itself
+ * was served from (`/housegames` on the site, nothing on games.housebets.*):
+ * nothing in the query can point the shell anywhere else (the PR #211 rule).
+ */
+import { createRgs } from '../core/rgs.js';
+import { createFaults } from '../core/faults.js';
+import { createRouter } from '../core/router.js';
+import { createSiteBridge } from './site-bridge.js';
+import { wordsFor } from './strings.js';
+import { moneyFor } from '../../engine-sdk/money.js';
+
+export const API = () => {
+    const at = location.pathname.indexOf('/engine/play/');
+    return location.origin + (at < 0 ? '/housegames' : location.pathname.slice(0, at));
+};
+
+export const shouldLoadSandboxPanel = (env) => env === 'sandbox';
+
+async function post(path, body, headers = {}) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 10_000);
+    try {
+        const res = await fetch(API() + path, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(body),
+            credentials: 'omit',
+            cache: 'no-store',
+            signal: ctrl.signal,
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok || !json) throw new Error((json && json.error) || `HTTP ${res.status}`);
+        return json;
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+// The site that frames the shell. In production the shell is served from the
+// site's own origin; anywhere else the framing page must be one of the sites
+// below (or, for a shell running on this machine, a page on this machine).
+// Never taken from the URL.
+const SITES = ['https://housebets.com', 'https://www.housebets.com', 'https://beta.housebets.com',
+    'https://housebets.dev', 'https://www.housebets.dev', 'https://arbitrium.housebets.dev']; // staging
+function siteOrigin() {
+    let ref = null;
+    try { ref = document.referrer ? new URL(document.referrer).origin : null; } catch { ref = null; }
+    const local = /^(localhost|127\.0\.0\.1)$/.test(location.hostname) && ref && /^http:\/\/(localhost|127\.0\.0\.1):\d+$/.test(ref);
+    if (ref === location.origin || SITES.includes(ref) || local) return ref;
+    return location.origin;
+}
+
+// The platform's currency payload (the object our own games receive as
+// currentlycurrency) says how the player sees amounts: in the coin, or in a
+// fiat at the platform's rate. The game gets it as `init.wallet`, the shape
+// the Originals' wallet-format.js reads, cut to the fields that shape uses (no
+// picture URLs: the SDK carries our marks). Money stays the server's: the coin
+// must be the session's, and a stake's precision never exceeds what the server
+// takes for it. A payload that disagrees is dropped for the plain coin.
+const CODE = /^[A-Z0-9]{2,10}$/;
+const cleanCode = (v) => (typeof v === 'string' && CODE.test(v.trim().toUpperCase()) ? v.trim().toUpperCase() : null);
+const whole = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : null);
+export function walletFrom(raw, currency) {
+    const plain = { symbol: currency.symbol, name: currency.symbol, isFiat: false, rate: 1, betPrecision: Math.min(8, currency.decimals) };
+    let p;
+    try { p = raw ? JSON.parse(raw) : null; } catch { return plain; }
+    if (!p || typeof p !== 'object' || Array.isArray(p)) return plain;
+    // In a fiat display the platform renames `symbol` to the fiat and keeps
+    // the coin in `name`; `code` is the coin's id, the session's.
+    const coin = cleanCode(p.name) || cleanCode(p.symbol);
+    if (coin !== String(currency.symbol).toUpperCase() || (p.code !== undefined && p.code !== currency.code)) return plain;
+    const own = whole(p.betPrecision) ?? whole(p.decimals) ?? whole(p.precision) ?? 8;
+    const rate = Number(p.rate);
+    const fiat = p.isFiat === true && Number.isFinite(rate) && rate > 0 ? cleanCode(p.fiat) || cleanCode(p.currentFiat) || cleanCode(p.symbol) : null;
+    return {
+        symbol: fiat || coin,
+        name: coin,
+        isFiat: !!fiat,
+        ...(fiat ? { currentFiat: fiat } : {}),
+        rate: fiat ? rate : 1,
+        betPrecision: Math.min(8, own, currency.decimals),
+    };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const NIL_UUID = '00000000-0000-0000-0000-000000000000';
+
+/**
+ * What the site's `housebets-game-control` envelope asks, read as the
+ * Originals read it (limbo host-controls.js): a bare action is the bar's
+ * button — `provably-fair` opens the dialog on the player's seeds,
+ * `site-input` is the site page reporting a trusted press or key the player
+ * made on it, outside the game frame (the click gate shadows the window's
+ * activation for it, as for a press on the shell's own controls: SPEC §5),
+ * the rest goes to the game as a control; an envelope with any of the bet history's
+ * round fields (gameType, roundId, requestId) is the history asking for one
+ * round, and only a whole one counts — this game's catalog slug, a round id
+ * that is a UUID and not nil, a request id that is a UUID — because a
+ * half-filled envelope opened on the seeds would show the player a screen
+ * they could take for the verification they asked for. `provably-fair-cancel`
+ * names the request to abandon. Returns {fairness: roundId|null, requestId?},
+ * {cancel: requestId}, {input: true}, {control: action}, or null for nothing.
+ */
+export function siteCommand(d, gameId) {
+    if (!d || typeof d !== 'object' || typeof d.action !== 'string') return null;
+    const historical = 'gameType' in d || 'roundId' in d || 'requestId' in d;
+    const requestId = String(d.requestId || '').toLowerCase();
+    if (d.action === 'provably-fair-cancel') {
+        return historical && d.gameType === gameId && UUID.test(requestId) ? { cancel: requestId } : null;
+    }
+    if (!historical) {
+        if (d.action === 'provably-fair') return { fairness: null };
+        if (d.action === 'site-input') return { input: true };
+        return { control: d.action };
+    }
+    if (d.action !== 'provably-fair' || d.gameType !== gameId) return null;
+    const roundId = String(d.roundId || '').toLowerCase();
+    if (!UUID.test(roundId) || roundId === NIL_UUID || !UUID.test(requestId)) return null;
+    return { fairness: roundId, requestId };
+}
+
+/**
+ * The dialog's openers. The site's bar, the bet history and the shell's own
+ * button are the player's gesture: the dialog opens afresh, on the seeds or
+ * on the history's round. The game's `fairness.open` is untrusted code
+ * asking: the dialog is told (`fromGame`) and gives up nothing the player
+ * has typed or started in it.
+ */
+export function fairnessOpeners(ui, rgs, ctx) {
+    const open = (roundId, fromGame, requestId) => ui.fairness(rgs, roundId, { ...ctx, fromGame, requestId: requestId || null });
+    return {
+        player: (roundId = null, requestId = null) => open(roundId, false, requestId),
+        game: (roundId) => open(roundId, true, null),
+    };
+}
+
+/**
+ * The site's document, when the shell may listen to it: the shell is served
+ * from the site's own origin in production (www.housebets.com/housegames/
+ * engine/play/…), so it is a same-origin frame of the site page, and a
+ * browser hands a press anywhere in that page — the chat, the header — to the
+ * shell's window as activation too (the HTML activation notification reaches
+ * every same-origin frame of the clicked page). The shell therefore watches
+ * the site's presses and focus moves as it watches its own. A shell on an
+ * origin of its own (a stand, the games host of ARCHITECTURE §7) gets no such
+ * activation and needs no such listener: the parent refuses its document, and
+ * that refusal is the proof. Null when there is no site around the shell, or
+ * when it is another origin.
+ */
+export function siteDocument(win, parentOrigin) {
+    if (!win || win.parent === win || parentOrigin !== win.location.origin) return null;
+    try {
+        const doc = win.parent.document;
+        return doc && typeof doc.addEventListener === 'function' ? doc : null;
+    } catch {
+        return null; // cross-origin after all: its activation never reaches this window
+    }
+}
+
+/**
+ * Where the page asks for its game's descriptor. A launch from House Studio's
+ * sandbox (play.housestudio.io, ADR 0005) carries a ticket, without which the
+ * studio names no version that is not live yet: it goes with the question. The
+ * casino's launch carries none and asks as it always has.
+ */
+export function descriptorURL(ticket) {
+    return ticket ? `./descriptor.json?ticket=${encodeURIComponent(ticket)}` : './descriptor.json';
+}
+
+export async function boot({ ui }) {
+    const params = new URLSearchParams(location.search);
+    const otp = params.get('otp');
+    const ticket = params.get('ticket');
+    const currency = Number(params.get('currency'));
+    const payload = params.get('currencyPayload');
+    // The player's language, as the site names it on the launch (our own
+    // games read the same `lang`), else the browser's. The page's own words
+    // (the Provably Fair dialog) are in it from here on.
+    const locale = (params.get('lang') || params.get('locale') || navigator.language || 'en').slice(0, 12);
+    ui.locale(locale);
+    // The code is single-use; it leaves the address bar before anything else.
+    history.replaceState(null, '', location.pathname);
+    const slug = location.pathname.split('/').filter(Boolean).at(-1);
+    if (!otp || !Number.isSafeInteger(currency) || currency <= 0 || !/^[a-z0-9][a-z0-9-]{1,23}$/.test(slug)) {
+        return ui.fail('This game was opened without a launch. Open it from the casino.');
+    }
+
+    let descriptor, token, session;
+    try {
+        // Where the game's bundle lives and how the site names the game. In
+        // production this comes with the game's live version (in the sandbox,
+        // the newest that passed, for this launch's ticket); without one the
+        // studio says why (not live, or no front end kept for it).
+        const res = await fetch(descriptorURL(ticket), { cache: 'no-store' });
+        descriptor = await res.json().catch(() => null);
+        if (!res.ok || !descriptor || !descriptor.bundleUrl) {
+            return ui.fail((descriptor && descriptor.error) || 'This game is not available right now. Please try again later.');
+        }
+        ({ token } = await post('/direct/session', { otp }));
+        // No origin binding: the session id never leaves this page's memory
+        // (browsers send no Origin on same-origin GETs, which would fail it).
+        session = await post('/engine/v1/sessions', { game: slug, currency }, { 'X-Token': token });
+    } catch (e) {
+        return ui.fail('The game could not start. Please reopen it.', e);
+    }
+    token = null;
+
+    const faults = createFaults(fetch);
+    const rgs = createRgs({ base: API() + '/engine/v1', sessionId: session.sessionId, fetch: faults.fetch });
+    const auth = await rgs.authenticate(locale);
+    if (!auth.ok) return ui.fail('The game could not start. Please reopen it.', auth.error);
+    // The front end the studio named and the maths the round server plays must be
+    // one version: for the seconds a new version takes to reach both, the game waits.
+    if (typeof descriptor.mathHash === 'string' && descriptor.mathHash && auth.body.mathHash !== descriptor.mathHash) {
+        return ui.fail('This game is being updated. Please reopen it in a moment.');
+    }
+    // One launch, counted on the engine with the game's errors and abandoned rounds
+    // (the router sends those): the studio's Reports show the counts per day.
+    rgs.telemetry('boot');
+    // The studio dashboard's sandbox launcher can force the first round to a
+    // row of the table (?force=12, or 3,0,0 for a ladder's steps) to test a
+    // big win or a feature on demand. The server allows it only in the sandbox.
+    const force = params.get('force');
+    if (force && auth.body.env === 'sandbox' && /^\d{1,7}(,\d{1,7}){0,63}$/.test(force)) {
+        const f = await rgs.force(force.split(',').map(Number));
+        if (!f.ok) console.warn('force refused', f.error);
+    }
+    // How amounts are shown (the player's fiat display, as the site shows the
+    // header); money itself is in the wallet currency the server confirmed.
+    const init = { ...auth.body, wallet: walletFrom(payload, auth.body.currency), locale };
+    // How money is shown, the same as the site's header: the autoplay
+    // confirmation shows the stake and the totals in the player's coin, and
+    // the bet it is for by the labels the maths names (the id when it names none).
+    const money = moneyFor(init.wallet);
+    const betLine = (modeId, betId) => {
+        const modes = Array.isArray(init.modes) ? init.modes : [];
+        const label = (x, id) => (x && typeof x.label === 'string' && x.label ? x.label : id);
+        const mode = modes.find((m) => m && m.id === modeId);
+        const bet = label(mode && Array.isArray(mode.bets) ? mode.bets.find((b) => b && b.id === betId) : null, betId);
+        return modes.length > 1 ? `${label(mode, modeId)} · ${bet}` : bet;
+    };
+    // The page reads the player's way: right to left for Arabic, Hebrew,
+    // Persian, Urdu; the game frame inherits it.
+    document.documentElement.lang = locale;
+    document.documentElement.dir = /^(ar|he|fa|ur)\b/i.test(locale) ? 'rtl' : 'ltr';
+
+    const parentOrigin = window.parent !== window ? siteOrigin() : null;
+    const bridge = createSiteBridge({ parent: window.parent, parentOrigin, gameId: descriptor.catalogSlug, currencyId: currency });
+    const frame = ui.frame(descriptor.bundleUrl);
+    // The Provably Fair dialog, the shell's own: on the player's seeds (the
+    // site's bar, the shell's button) or on a round (the game's fairness.open,
+    // the bet history's envelope). It verifies against the maths the shell is
+    // running unless the round names another version, shows money as the
+    // wallet shows it, and holds the rotation while a round is open; the
+    // bets go on behind it, so it is told when a round starts and ends.
+    const fairness = fairnessOpeners(ui, rgs, { game: slug, mathHash: init.mathHash, wallet: init.wallet, roundOpen: () => router.roundOpen() });
+    // The click gate reads this window's user activation (a click inside the
+    // game frame reaches it — and, with the shell on the site's origin, so does
+    // a click anywhere in the site page: those are shadowed below) and the
+    // document's focus (only a click in the frame moves it there: router.js
+    // browserFocusInGame, its default; a focus the game moved there by script
+    // is told apart below); its refusals, and the autoplay control, speak the
+    // player's language.
+    const router = createRouter({
+        self: window,
+        gameWindow: () => frame.contentWindow,
+        gameOrigin: new URL(descriptor.bundleUrl).origin,
+        rgs,
+        init,
+        words: wordsFor(locale),
+        site: {
+            // The shell's own autoplay control over the game: rounds left and
+            // Stop, in this document, where the game cannot cover or press it.
+            autoplay: ui.autoplay,
+            // The autoplay confirmation: the router hands the capped terms in
+            // wallet units; the shell shows them in the player's coin, as the
+            // header does, and starts nothing until the player presses Start.
+            autoplayConfirm: (t) => {
+                const m = (n) => `${money.format(n)} ${money.unit}`;
+                ui.autoplayConfirm({ bet: betLine(t.mode, t.bet), rounds: t.rounds, stake: m(t.stake), total: m(t.total), stopProfit: t.stopOnProfit ? m(t.stopOnProfit) : null, stopLoss: m(t.stopOnLoss) });
+            },
+            // The router took the confirmation down (its deadline, the reality
+            // check, the session over): the dialog closes with the game refused.
+            autoplayDismiss: ui.autoplayDismiss,
+            roundStart: (r) => {
+                bridge.roundStart(r);
+                ui.fairnessRoundChanged(false);
+            },
+            roundEnd: (r, round) => {
+                bridge.roundEnd(r);
+                ui.round({ ...r, round });
+                ui.fairnessRoundChanged(true);
+            },
+            ready: () => {
+                ui.ready();
+                bridge.ready();
+            },
+            loading: ui.loading,
+            fairness: fairness.game,
+            error: (message) => console.warn('[game]', message),
+            ended: () => ui.fail('This game session has ended. Please reopen the game.'),
+        },
+    });
+    // The game asks for its config (hello) on every page it loads; the router
+    // answers. Nothing waits on the frame's load event, which a heavy page
+    // fires late. The site's bar: Provably Fair is the shell's own dialog on
+    // the player's seeds, the same for every game as for every House
+    // Original, open before the first round too (the hash is what the player
+    // checks before playing); the bet history's envelope opens it on that
+    // round (siteCommand); the site's report of the player's own press or key
+    // on its page (`site-input`) shadows this window's activation exactly as
+    // a press on the shell's controls does — the shell shares the site's
+    // origin, so that press armed this window too, and a bundle that stole
+    // the focus back by script must get no bet out of it; the rest is the
+    // game's.
+    bridge.listen((d) => {
+        const cmd = siteCommand(d, descriptor.catalogSlug);
+        if (!cmd) return;
+        if (cmd.cancel) ui.fairnessCancel(cmd.cancel);
+        else if (cmd.input) router.shellInput();
+        else if (cmd.control) router.tell('control', { action: cmd.control });
+        else fairness.player(cmd.fairness, cmd.requestId);
+    });
+    // No site around the shell (opened directly, or a stand): the shell
+    // shows the button the site's bar would.
+    if (window.parent === window) ui.fairButton(() => fairness.player());
+    // The player's Stop on the shell's autoplay control ends the session at once.
+    ui.autoplayStop(() => router.autoplayStop());
+    // The confirmation's Start/Cancel: a real click on the shell's own button
+    // starts the session; anything else refuses it. The game cannot reach these.
+    ui.onAutoplayConfirm((ok) => (ok ? router.confirmAutoplay() : router.cancelAutoplay()));
+    // A press or a key on the shell's own controls arms this window's activation
+    // as a game click does: the router is told, and takes no play on it meanwhile.
+    ui.onShellInput(() => router.shellInput());
+    // So does a press anywhere in the site's page when the shell is a
+    // same-origin frame of it (production): the chat, the header, a button of
+    // the site's. Its presses are shadowed the same way, so a chat click or a
+    // word typed there buys the game nothing (siteDocument says when the site's
+    // document may be listened to; a cross-origin site gives this window no
+    // activation and no document).
+    const siteDoc = siteDocument(window, parentOrigin);
+    if (siteDoc) ui.onShellInput(() => router.shellInput(), siteDoc);
+    // The focus must be the player's: a game can move it into its own frame by
+    // script, and the player's next keystrokes (meant for the chat) would then
+    // land in the game, granting it activation. The page watches the focus
+    // entering and leaving the frame (on this document's moves and the site's,
+    // the presses on either, and by reading document.activeElement besides);
+    // the router says whether the entry was the player's — the activation
+    // live, no shell or site press, no scripted focus and no exit from the
+    // frame within its lifetime (a game can take the focus back the moment
+    // the player tabs out of it, with that Tab's activation still live), or
+    // the player's own Tab key just before it (the page saw the key) — and a
+    // focus that was not is blurred straight back out of the frame and buys no
+    // play until the player focuses the frame themselves.
+    ui.watchGameFocus((viaTab, sinceExitMs) => router.frameFocused(viaTab, sinceExitMs), siteDoc ? [document, siteDoc] : [document]);
+    // A round left open as the page goes is counted as abandoned (pagehide also
+    // fires on a close, which beforeunload may not on a phone), and an autoplay
+    // session ends with the page — as it does when the page is merely hidden
+    // (another tab, the phone locked): a run is for a player who is looking.
+    window.addEventListener('pagehide', router.unload);
+    document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') router.hidden(); });
+    if (shouldLoadSandboxPanel(auth.body.env)) {
+        import('./sandbox-panel.js').then(({ createSandboxPanel }) => createSandboxPanel({
+            rgs,
+            router,
+            faults,
+            api: API(),
+            frame,
+            slug,
+            mathHash: init.mathHash,
+            money,
+            refresh: async () => {
+                const refreshed = await rgs.authenticate(locale);
+                if (refreshed.ok) {
+                    router.refreshInit({ ...refreshed.body, wallet: walletFrom(payload, refreshed.body.currency), locale });
+                }
+                return refreshed;
+            },
+        })).catch((error) => console.warn('[sandbox panel]', error));
+    }
+    // The reality check the server asks for: every N seconds of play the
+    // game is paused and the player told how long it has been.
+    const every = init.rg && init.rg.realityCheckSec > 0 ? init.rg.realityCheckSec * 1000 : 0;
+    if (every) {
+        const started = Date.now();
+        const check = async () => {
+            router.tell('pause', { reason: 'reality-check' });
+            await ui.realityCheck(Math.round((Date.now() - started) / 60000));
+            router.tell('resume', {});
+            setTimeout(check, every);
+        };
+        setTimeout(check, every);
+    }
+    ui.started({ game: init.game, mathHash: init.mathHash, env: init.env, currency: init.currency });
+}