From 058432130628d00764663ecf819a9adc6793768d Mon Sep 17 00:00:00 2001 From: salmonik Date: Sun, 8 Nov 2026 03:29:35 +0100 Subject: v5.0.0: protocol v5 and the browser frontend Protocol v5 replaces newline lines with bounded [u32 len][text] frames and REQ/RES/EVT envelopes. Requests carry correlation ids and the server replays the last 256 replies per connection, so a gateway retry cannot double-debit and a late reply cannot clobber a newer request. HELLO/PONG carry server time; crash rounds announce started_at and push coalesced 10 Hz ticks. Crash now commits sha256(seed) before a round and reveals the seed when it ends, so clients recompute the crash point. Adds the webd/ gateway: one blocking thread, one ClientCore and one pinned upstream TLS connection per session, an HttpOnly session cookie, takeover, and a 60-second grace window. The browser sends Command JSON and renders View JSON; it never speaks the game protocol or stores credentials. Adds the vanilla TypeScript browser app at /play/ (login, lobby, all four games, history, notices, crash verification), the nginx /play and /ws routes, and the headless DOM smoke test. webd and the app stay out of the TUI/GUI/server build graph. The client/server version moves to 5.0.0 in lockstep; v4 peers are refused at HELLO. --- web/play/README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 web/play/README.md (limited to 'web/play/README.md') diff --git a/web/play/README.md b/web/play/README.md new file mode 100644 index 0000000..610c7a8 --- /dev/null +++ b/web/play/README.md @@ -0,0 +1,56 @@ +# `web/play` — browser frontend + +Vanilla TypeScript + esbuild. The browser sends `Command` JSON and renders +`View` JSON; it contains no game rules, no payout math and no wire protocol. +The gateway in `webd/` owns the upstream TLS connection. + +## Build + +```sh +npm ci +npm run build # writes app.js +npm run typecheck +npm test # headless DOM smoke test (jsdom) +``` + +Commit the generated `app.js` so the site deploys without Node. + +## Local development + +Serve the repository's `web/` directory (for `/play/`) and put the gateway +behind the same origin at `/ws`. The simplest local setup is nginx with the +`web/nginx.conf.example` block pointed at a staging root and +`ZAGAN_WEB_ORIGIN=http://127.0.0.1:8899`. For the app alone: + +```sh +python3 -m http.server 8900 -d web/play +``` + +It will load, but the WebSocket will only connect through nginx or another +proxy that routes `/ws` to `webd`. + +## Screens + +- Auth: login/register. The password is hashed with Web Crypto (`SHA-256`) + before it leaves the page; the gateway and browser never store it. +- Lobby: four games, per-game bet, history. +- Slots: five reels, win cells and paylines. +- Roulette: canvas felt with straight, dozen, column and outside chips; + left click adds, right click removes. +- Blackjack: dealer/player cards, hit/stand/double/forfeit. +- Crash: curve, live multiplier, cash-out, commit/seed verification. +- History: settled plays with net result. + +## Theme + +`style.css` mirrors the palette in `gui/src/theme.rs`: near-black ground, +cyan focus, green for wins, gold for chips, felt green only for roulette. +Do not introduce a second palette or hard-code colours in the render modules. + +## Security + +- The session cookie is HttpOnly and SameSite=Strict; JavaScript never reads + it and never stores a credential. +- Notices are inserted with `textContent`, not HTML. +- The app is play-money only. Do not add deposits, withdrawals, KYC or + real-money claims without a product decision and an ADR. -- cgit v1.2.3