@xgamesfun/xcore 0.2.1 → 0.4.0

package/README.md

@@ -31,6 +31,7 @@ xcore add multiplayer ./my-game            # rooms players share (Godot's own mu
 xcore backend use custom ./my-game --url https://api.my-game.example   # only if it calls a backend you run
 xcore loot add ./my-game                   # only if it gets an economy (a Solana economy on loot)
 xcore add vouchers ./my-game               # its server pays results it checked from a grant, with its own key
+xcore review ./my-game                     # the security review: what a cheater gets (--live once published)
 xcore login && xcore publish ./my-game
 xcore embed add https://mygame.com ./my-game     # your own site may show it (an <iframe>)
 xcore domain add play.mygame.com ./my-game       # Creator or Scale: it plays at your own domain
@@ -190,13 +191,35 @@ has behind it, so the whole game runs before it is published:
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `http://127.0.0.1:8787/game/` | the published files (it runs `page.build` first, unless `--no-build`), with the play host's headers                                                                                                                                                                                                                                                                                                                |
 | `/game/api/*`                 | the game's `server/` under workerd, the runtime xgames.fun runs it on: Durable Objects with their storage kept, WebSockets, `env.GF`, the game's database (a local D1 in `.gamesfun/dev/d1/`, its migrations applied), and its secrets from `.dev.vars`. A change under `server/` or to `.dev.vars` reloads it. Miniflare (with workerd, about 140 MB) is installed once, the first time a game with a server runs |
-| `/platform/v1/*`              | sign-in, saves and leaderboards: `gamesfun.js` signs in a local player (each tab its own, so two tabs play a room together), and `env.GF.verifyPlayer` accepts its token. Saves and scores are kept in `.gamesfun/dev-platform.json`, never published                                                                                                                                                              |
+| `/platform/v1/*`              | sign-in, saves and leaderboards: `gamesfun.js` signs in a local player (each tab its own, so two tabs play a room together), and `env.GF.verifyPlayer` accepts its token. Saves and scores are kept in `.gamesfun/dev-platform.json`, never published, and held to the limits of the plan it imitates (below)                                                                                                      |
+| `/platform/v1/live`           | the game's live settings (`gf.live`, below): its announcement, config and maintenance, from `.gamesfun/live.json` (read again on each request, never published). With maintenance on there, the game's pages show the holding page and its `api/` and `/platform/v1/*` answer `503` with code `maintenance`, as hosted                                                                                             |
 | `http://127.0.0.1:8788/`      | the game's public project files (`env.GF.files`, `xcore files`), kept in `.gamesfun/dev/files/`: another origin, as `<slug>.xgamesusercontent.com` is to the published game                                                                                                                                                                                                                                        |
 | `/loot/v1/rpc`                | the economy's Solana devnet RPC: xgames.fun's shared relay (what a published page talks to unless the game brings its own: `xcore add rpc`), or your own with `XSOLANA_RPC_URL` in `.env` (its URL is never shown; a call the shared relay would refuse is said in the terminal). The economy's calls answer once it is live on devnet (`xcore loot approve`)                                                      |
 
 Games made with any engine get all of it through `gamesfun.js` (`xcore add signin`): on a plain local server it stands
-in with this browser's storage; under `xcore dev` it uses the real thing. What is not the same as hosted: no CPU or
-request limits, and the server's outbound `fetch` is not limited to `backend.json`'s origins.
+in with this browser's storage; under `xcore dev` it uses the real thing.
+
+**The plan's limits, refused as published.** `xcore dev` imitates one plan, Free unless `--plan creator` or `--plan
+scale` (it says which when it starts), and its platform refuses what xgames.fun refuses on that plan, with the same
+codes: the plan's boards (8 on Free) and board rules (16), entries a board (10,000), save bytes a game (10 MB), and
+reads (1,200) and writes (600 saves, 600 scores) a minute, the server's and the pages' counted apart; project files'
+total and the plan's file calls a minute (120). What a page may do is the same on every plan: it makes `high` boards
+only, two a player and half the plan's boards in all (the game's server makes the rest, `low` ones too, and
+`GF.scores.list` shows who made each); one player's saves from the page keep at most 1/128 of the game's save bytes
+(80 KB on Free), and with the game's saves full a player still keeps 4 KB; one player writes 60 saves and 30 scores a
+minute; a body is JSON (`content-type: application/json`) of at most 96 KB. A board read from the page shows each player
+as an id of the game's own (16 letters and digits), never their account, with `me: true` on the caller's entry; without
+a player token it reads the top 100 only (`offset` plus `limit` past 100 answers 401), may get the same answer again
+for 5 seconds, and has its own minute (a tenth of the plan's reads). Ranks and offsets are counted to 10,000 (past it a
+rank is `10001` with `rankAtLeast: true`). A public project file is an image, audio, video, a font, JSON or plain text
+whose first bytes are that type (else private), and `env.GF.files.put` holds at most 1 MB of a string or ArrayBuffer
+body (a bigger file goes as a stream with its `length`).
+
+What is not imitated, and said instead: one player's requests to the game's server a minute and its CPU a request (the
+dev log says when a request would pass them), and one address's reads of `/platform/v1` at the play edge (120 a minute;
+here every tab is one address). Not imitated at all: the network's delays, the owner's moderation (bans, blocked
+words), the board ids of the published game (these are this machine's own), and the server's outbound `fetch`, which is
+not limited to `backend.json`'s origins. The counts a minute start again when `xcore dev` does.
 
 ## 3. Players, a database, a backend
 
@@ -212,17 +235,28 @@ engine takes:
 | A Godot 4 project | `addons/gamesfun/gamesfun.gd`, autoloaded as `GamesFun`                                             | `await GamesFun.sign_in()`, `await GamesFun.saves_put("main", {})` |
 | A Unity project   | `Assets/Plugins/GamesFun/` (`GamesFun.jslib`, `GamesFun.cs`)                                        | `await GamesFun.SignIn()`, `await GamesFun.SavesPut("main", json)` |
 
-The same calls everywhere: sign in and out, the player (`id`, `name`, `level`, `wallet`, `x`), saves (any JSON, 64 KB
-each, 16 a player), leaderboards (submit, top, the player's own), the game's database (below) and its own server
+The same calls everywhere: sign in and out, the player (`id`, `name`, `level`, `wallet`, `x`; `id` is the player's
+account, `x:<X id>` or for a Google account `g:<id>`, an id different in every game, and never the wallet, which is
+`wallet`, empty when the account has none), saves (any JSON, 64 KB each, 16 a player), leaderboards (submit, top, the player's own), the game's database (below) and its own server
 (`api`). Every call answers `{data, error, status}` and none throws, so a game plays on as a guest wherever xgames.fun is
 not there.
 
+**Full screen.** Most players meet a game in a post on X or on a phone, where it shows in a small frame first; `xcore
+adopt` warns when a game has no way to go full screen. A button that calls `GamesFun.fullscreen()` from the click
+(`await GamesFun.fullscreen()` in Godot; `Screen.fullScreen` in Unity) does it wherever the game is: in xgames.fun's
+play page the page around the game goes full screen (or fills the screen in an app's own browser, X's among them), on
+its own link the browser does, and in a frame that allows none (a post on X on a computer) the game opens in a tab of
+its own. It answers `{on, how: 'page' | 'browser' | 'tab' | 'none'}` (`none`: an iPhone's Safari, which has no full
+screen for a page); pressed again it comes back, and `GamesFun.onFullscreen(on => …)` follows every change.
+
 **A leaderboard is the player's own word until the server takes it.** A signed-in player submits their own scores
 from the page, so anyone can submit any score for themselves from the browser's console. A game with its own server
 makes a board nobody can write that way: `env.GF.scores.setup('ranked', {writer: 'server'})` (or a pattern for boards
 to come, `'daily-*'`), then the page's submits
 to it are refused (their answer's `code` is `'server-only'`, HTTP 403) and the server submits each run it checked; the page reads the board as before
-([docs/SERVER.md](docs/SERVER.md)).
+([docs/SERVER.md](docs/SERVER.md)). A board a page makes ranks higher first; a lower-first board (a time) is made by
+the game's server, and a page's `order: 'low'` for a new board is refused (`code: 'order'`). `scores.top` gives each
+entry's `player` as an id of this game's own and marks the signed-in player's own entry `me: true`.
 
 Where the sign-in comes from:
 
@@ -236,9 +270,15 @@ Where the sign-in comes from:
   can be made and tested before it is published. Under `xcore dev`, a local sign-in (one player a tab) and the
   platform answer as xgames.fun does, and the game's `server/` accepts its token.
 
-The token lasts an hour and stays in the page's memory. The game's `server/` checks it with `env.GF.verifyPlayer`; a
-backend of your own checks it with any JWT library against `https://<slug>-play.xgames.fun/player/v1/key` (issuer
-`xgames.fun`, audience `game:<slug>`).
+The token lasts an hour and stays in the page's memory. The game's `server/` checks it with `env.GF.verifyPlayer`,
+first thing, before any work: a request without one answers 401 at once, since strangers' requests that do work count
+toward what caps a game ([docs/SERVER.md](docs/SERVER.md), "Check the token first"). A backend of your own checks it
+with any JWT library against `https://<slug>-play.xgames.fun/player/v1/key` (issuer `xgames.fun`, audience
+`game:<slug>`). Its `sub` is the player's account (`x:<X id>`, or `g:<id>` for Google, different in every game);
+`wallet` is a claim of its own, and may be absent: a game that keeps a player's data by wallet reads `wallet`.
+xgames.fun replaces its signing key from time to time: a backend that keeps the key set must fetch it again when a
+token names a key id (`kid`) it does not hold, once, not in a loop (most JWT libraries' remote key sets do).
+`gamesfun.js` and the Godot and Unity clients check no token themselves.
 
 The page calls the game's own server with `GamesFun.api(path, init)` (Godot `GamesFun.api(path, init)`, Unity
 `GamesFun.Api(path, initJson)`): `path` is relative to the game's `api/` (`'finish'` is `api/finish`, at the
@@ -246,6 +286,59 @@ published origin and under a folder alike), `init` is `fetch`'s (an object `body
 player's token goes with it as `Authorization: Bearer …`, which the server checks with `env.GF.verifyPlayer` before
 it trusts who is asking. It answers `{data, error, status}` like every other call.
 
+### Live: an announcement, a remote config and maintenance, with no republish (`gf.live`)
+
+On xgames.fun/console, a game's **Live** tab sets three things its players get within about 35 seconds, with no
+republish (xgames.fun's play edge answers them itself from one cached record a game):
+
+- **an announcement**: a short line of plain text (280 characters), `info` or `warning`, with an optional start and end;
+- **a remote config**: a small JSON object (8 KB) the game reads at run time: a difficulty, an event on or off. The
+  console keeps its last 10 versions and reverts with a click;
+- **maintenance**: the game paused with a message. Players who open it get a plain holding page from xgames.fun instead
+  of the game, its server's `api/*` (WebSockets too) and the page's saves and leaderboards answer `503` with code
+  `maintenance` (the server's code does not run), and turning it off brings the game back within about 35 seconds (up
+  to a minute). What is already running (an open WebSocket, an alarm) is not stopped.
+
+`gamesfun.js` (1.5.0) reads them:
+
+```js
+const { data: live } = await GamesFun.live.get(); // {announcement, config, version, maintenance}
+const hard = live.config.difficulty === 'hard';
+GamesFun.live.onChange(live => applyEvent(live.config.event)); // asked again every minute while the page is in view
+await GamesFun.live.refresh(); // ask now
+```
+
+`get()` answers what it knows if that is under a minute old, else asks; like every call it answers
+`{data, error, status}` and never throws (unreachable: the last value, else nothing live). `announcement` is null
+outside its start and end, `config` is `{}` when none is set, `maintenance` is null or `{message, since}`.
+
+**The banner.** By default `gamesfun.js` shows the announcement in a small closable line at the top of the page (each
+announcement until the player closes it), and a pause that starts while the game is open (any call answering
+`maintenance` shows it at once). A game that shows them its own way turns it off with `data-live-banner="off"` on its
+`<script src="gamesfun.js">`, `globalThis.GAMESFUN_LIVE_BANNER = false` before it loads, or
+`GamesFun.live.banner(false)` before the page has loaded. Without the banner and without `onChange`, nothing is asked
+until the game calls `get()`.
+
+**On this machine** nothing is live on a plain local server; under `xcore dev`, `.gamesfun/live.json` stands in for the
+console (read again on every request):
+
+```json
+{
+  "announcement": {
+    "text": "Double XP all weekend!",
+    "level": "info",
+    "startsAt": null,
+    "endsAt": "2026-11-12T00:00:00Z"
+  },
+  "config": { "difficulty": "hard", "event": true },
+  "maintenance": null
+}
+```
+
+`"maintenance": {"message": "Back at 7pm"}` (or `true`) pauses the game as hosted. Times are ms or ISO text; what the
+console would refuse (a config over 8 KB or not an object, an announcement over 280 characters) is said in the
+terminal. Godot and Unity reach `gf.live` only through their JavaScript bridge for now.
+
 ### A database of its own: `xcore add database`
 
 `xcore add database <folder>` adds sign-in, and a database the game owns: **one D1 database** (SQLite) a game, made on
@@ -435,7 +528,7 @@ holds the addresses the economy went live at stays in the project (keep it in gi
 runs the tools from a terminal. Going live is the person's own step, approved in their own wallet: `xcore loot
 approve` in the folder with `xsolana.json`.
 
-**When loot is upgraded.** This package pins the tools for one build of loot (0.25.0). loot is upgraded in place on
+**When loot is upgraded.** This package pins the tools for one build of loot (0.26.0, on devnet since 2026-11-10). loot is upgraded in place on
 devnet, and no version so far has carried accounts over: an economy that went live on an earlier build goes live
 again (`xcore loot approve`), and the next publish brings `gf/loot/` up to the installed package. **Nothing runs by
 itself** on chain: the page client sends what a player needs (settles, refunds, claims, a draw that is due); a
@@ -460,10 +553,36 @@ only to players signed in with X (`VOUCHERS.payOnly`). A grant names up to three
 pay the same grant while you move from one to the other.
 [docs/SERVER.md](docs/SERVER.md), "Paying a result", has both, side by side.
 
+### Review: `xcore review`
+
+A game that pays is read the way a cheater reads it before players are paid. `xcore review <folder>` writes
+`evidence/review-N/review.md` and `review.json`, prints what it found, and exits 1 on any high finding:
+
+- **The economy**: `@xgamesfun/solana`'s own review (`xcore loot review`): each route that pays, what it trusts, its
+  ceiling, and the trade-offs in words. An installed version without it says so in one line, and the rest goes on.
+- **The server**: `PAY.check` still the template (it pays nothing) or one that pays from the request alone (it never
+  reads `env`, so nothing the server keeps); `VOUCHERS.payOnly` against the grants (`'any'` with `perPerson`, whose
+  claims fail; `'any'` on a grant worth farming); a voucher key and the grants that name it; `trust` on every grant a
+  voucher pays; `.dev.vars` in git or in the published folder; a seed or key in the page's files; the test key in a
+  grant; every `api/` route the code names.
+- **Live** (`--live`, after publishing; `--live <origin>` for another, such as `xcore dev`'s
+  `http://127.0.0.1:<port>/game/`): each of those routes asked with no sign-in and with a forged one, GET and POST (a
+  route that pays gets an empty body: nothing it sends can spend or sign); `api/vouchers/key` against the grants' keys;
+  the published economy's `live` against the folder's.
+
+Each grant a voucher pays says how much its server checks before signing: `"trust": "decides"`, `"replays"` or
+`"bounds"` (docs/SERVER.md, "How much your server can check"; the field needs the `@xgamesfun/solana` that has
+`review`: 0.25.0 refuses it). `review.md` ends with the trade-offs for the person: for each paid route, its level,
+what a cheater gets, and what the stronger level would cost. `xcore publish` says when a game that pays through
+vouchers changed since its last review (it never refuses for it).
+
 ## 5. Publish
 
 `xcore login` signs this computer in (your browser signs in to xgames.fun and hands it a publish token for 30
-days; xcore never sees your password). `xcore publish <folder>` then builds the game, checks it (the page
+days; xcore never sees your password). On the approval page you tick the games this computer may work on, or your
+whole account, and `xcore login` says which it got (`login --status` says it again). A game you publish as new from
+that sign-in is added to it; a command for any other game is refused with code `not-granted` ("your sign-in was not
+given this game"): run `xcore login` again and tick it. `xcore publish <folder>` then builds the game, checks it (the page
 check on exactly the files built), and uploads its published folder with its `server/` bundle:
 
 1. **The files**: the published folder, without hidden files, `evidence/`, `node_modules/`, `server/`, `supabase/` and the makers' notes at its top (`README.md`, `NOTES.md`, `LAUNCH.md` and the like). A `.env` file or a link
@@ -537,8 +656,11 @@ free their slot unless their link is still live. What the game's server, saves a
 | Sites that embed it  | 3 (`xcore embed`)                                                  | 10                                                   | 25                      |
 | Domains of your own  | none                                                               | 1 (`xcore domain`)                                   | 5                       |
 
-Past what is included, a game is **capped** until the month ends: its server answers at most 60 requests a minute (20
-from one player) and saves and scores slow down, but nothing is lost and the game keeps working. Paid slots are $15 for
+Past what is included, a game is **capped** until the month ends: **its server is switched off** (every `api/*` request
+answers 451 with `reason: "capped"`, and a room that is running stops within about five minutes), and saves and scores
+slow down (60 save writes, 30 score submits and 60 reads a minute). Its pages keep loading and nothing is lost: the server comes
+back by itself when the cap lifts ([docs/SERVER.md](docs/SERVER.md), "Publishing it"). An unpublished or taken-down
+game's server is switched off the same way. Paid slots are $15 for
 30 days, prepaid in SOL or USDC on xgames.fun (your console → Plans; no automatic renewal, 7 days' grace after the period
 ends; when they end, their games go back to free slots and nothing is taken down).
 Usage credit, bought the same way, lets Creator games go past what their slots include, at twice what xgames.fun pays,
@@ -579,7 +701,7 @@ A game made with xcore 0.1.0 that has `server/database.js` (`xcore add database`
 without one needs none: the D1 database, `xcore db` and `xcore files` are new.
 
 1. **Run `xcore add database` again.** It brings `server/database.js` up to date (your `RULES` and `LIMITS` are
-   kept), with `gamesfun.js` (1.4.0) and the Godot or Unity glue, and lists each `dataOf(env)` call in `server/` that
+   kept), with `gamesfun.js` (1.6.0) and the Godot or Unity glue, and lists each `dataOf(env)` call in `server/` that
    needs an owner (step 3) as `file:line` with its change; `xcore publish` lists them again until each names its
    owner. On its first start the new `database.js` moves the documents to a table keyed by collection, owner and id,
    each under its owner. After that, do not roll the game back to a version with 0.1.0's `database.js`: its writes
@@ -620,9 +742,9 @@ without one needs none: the D1 database, `xcore db` and `xcore files` are new.
   WebAssembly). Such a server runs on a host of your own, declared with `backend use custom`; or its logic moves into
   `server/`, or into the page itself (WebAssembly is allowed: Pyodide runs Python in the browser). Each is a change to
   how the game is built: the person who made it decides.
-- **A Node server as the backend on xgames.fun**: `server/` is a Worker, not Node (Node built-ins only with
-  `nodejs_compat`, and no `fs`, `child_process` or listening sockets). A Node backend runs on a host of your own,
-  declared with `backend use custom`.
+- **A Node server as the backend on xgames.fun**: `server/` is a Worker, not Node (no Node built-ins: `nodejs_compat`
+  is not offered; no `fs`, `child_process`, raw sockets or listening sockets). A Node backend runs on a host of your
+  own, declared with `backend use custom`.
 - **Scripts, style sheets and fonts from a CDN**: the page loads code and styles from its own files only, so a copy goes
   in the game (or the package is bundled).
 - **A fallback to `index.html` for every path**: deep links of a client-side router reload to "not found"; use a hash

package/commands/dev.mjs

@@ -4,21 +4,25 @@ import { guard, parse, printJson, UsageError } from '../lib/cli.mjs';
 import { resolveGame, shown } from '../lib/games.mjs';
 import { madeByKit } from '../lib/publish/index.mjs';
 import { CMD } from '../lib/command.mjs';
+import { PLAN_NAMES } from '../lib/dev/plans.mjs';
 
-const usage = `Usage: xcore dev [dir] [--port <n>] [--no-build] [--open] [--json]
+const usage = `Usage: xcore dev [dir] [--port <n>] [--plan <name>] [--no-build] [--open] [--json]
 
 Play the game on this machine as xgames.fun will host it, with everything a published game has behind it:
   http://127.0.0.1:<port>/game/   the published files, with the play host's headers
   /game/api/*                     the game's own server/ (Durable Objects, WebSockets, env.GF), reloaded on change
-  /platform/v1/*                  sign-in (a local player), saves and leaderboards, the same store env.GF uses
+  /platform/v1/*                  sign-in (a local player), saves and leaderboards, the same store env.GF uses,
+                                  with xgames.fun's limits on the plan it imitates (Free unless --plan)
   /loot/v1/rpc                    the economy's Solana devnet RPC (XSOLANA_RPC_URL in .env, else xgames.fun's relay)
 gamesfun.js (${CMD} add signin|database|multiplayer) uses all of it here, from any engine: open the page in two
 windows to play a room together. Running server/ needs Miniflare (workerd), installed once on first use (~140 MB).
 Saves, scores and Durable Object storage are kept in <dir>/.gamesfun/ (never published).
-  --port <n>   the port (default 8787)
-  --no-build   serve what is built already; do not run gamesfun.json page.build first
-  --open       open the page in your browser
-  --json       print where it runs as JSON, then keep running`;
+  --port <n>      the port (default 8787)
+  --plan <name>   the plan to imitate: free (the default), creator or scale: its boards, saves, reads and writes a
+                  minute and file sizes, as xgames.fun holds a game on that plan (${CMD} plan shows a game's own)
+  --no-build      serve what is built already; do not run gamesfun.json page.build first
+  --open          open the page in your browser
+  --json          print where it runs as JSON, then keep running`;
 
 export default {
   name: 'dev',
@@ -28,12 +32,20 @@ export default {
     guard(async () => {
       const { values, positionals } = parse(
         args,
-        { port: { type: 'string' }, 'no-build': { type: 'boolean' }, open: { type: 'boolean' } },
+        {
+          port: { type: 'string' },
+          plan: { type: 'string' },
+          'no-build': { type: 'boolean' },
+          open: { type: 'boolean' },
+        },
         usage,
       );
       const port = values.port === undefined ? 8787 : Number(values.port);
       if (!Number.isInteger(port) || port < 0 || port > 65535)
         throw new UsageError(`--port is a port number\n\n${usage}`);
+      const plan = String(values.plan ?? 'free').toLowerCase();
+      if (!PLAN_NAMES.includes(plan))
+        throw new UsageError(`--plan is ${PLAN_NAMES.slice(0, -1).join(', ')} or ${PLAN_NAMES.at(-1)}\n\n${usage}`);
       const dir = await resolveGame(positionals[0]);
       if (madeByKit(dir)) {
         console.error(
@@ -45,18 +57,27 @@ export default {
       const { startDev } = await import('../lib/dev/index.mjs');
       let dev;
       try {
-        dev = await startDev(dir, { port, noBuild: values['no-build'] === true, log: say });
+        dev = await startDev(dir, { port, plan, noBuild: values['no-build'] === true, log: say });
       } catch (e) {
         if (e.code === 'EADDRINUSE')
           throw new Error(`port ${port} is in use: pick another with --port <n>`, { cause: e });
         throw e;
       }
       if (values.json)
-        printJson({ url: dev.url, origin: dev.origin, files: dev.files, server: dev.server, rpc: dev.rpc });
+        printJson({
+          url: dev.url,
+          origin: dev.origin,
+          files: dev.files,
+          server: dev.server,
+          rpc: dev.rpc,
+          plan: dev.plan,
+        });
       else {
         say(`\n${shown(dir)} on this machine: ${dev.url}`);
         say(`  server: ${dev.server ? (dev.server.running ? 'running' : 'not running (above)') : 'none (no server/)'}`);
-        say(`  sign-in, saves, scores: a local player; kept in ${shown(dev.store.file)}`);
+        say(
+          `  sign-in, saves, scores: a local player, with the ${dev.store.plan.name} plan's limits; kept in ${shown(dev.store.file)}`,
+        );
         say(`  project files (env.GF.files, xcore files): public ones at ${dev.files}/, an origin of their own`);
         say(`  economy RPC: ${dev.rpc}`);
         say('Ctrl+C stops it.');

package/commands/login.mjs

@@ -1,17 +1,20 @@
 import { createInterface } from 'node:readline/promises';
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { openUrl } from '../lib/open.mjs';
-import { login, signInState, storeWords, studioOrigin } from '../lib/publish/client.mjs';
+import { signInState, studioOrigin } from '../lib/publish/client.mjs';
+import { currentReach, loginWithReach, loginWords, reachWords } from '../lib/login-reach.mjs';
 import { storeName } from '../lib/credentials.mjs';
 import { CMD } from '../lib/command.mjs';
 
 const usage = `Usage: xcore login [--code] [--status] [--json]
 
 Sign in to xgames.fun so you can publish your games (${CMD} publish). Your browser opens xgames.fun: sign in
-there and approve this computer. xcore never sees your password; it keeps a publish token for 30 days in
-${storeName()} (never in a game or in this folder). ${CMD} logout ends it.
+there, tick the games this computer may work on (or your whole account) and approve. xcore says which it got; a game
+you publish as new from here is added to them, and for another, run ${CMD} login again and tick it. xcore never sees
+your password; it keeps a publish token for 30 days in ${storeName()} (never in a game or in this folder).
+${CMD} logout ends it.
   --code     no browser on this machine (SSH, a container): open the printed link anywhere and paste the code it shows
-  --status   who this computer is signed in as, and where the token is kept
+  --status   who this computer is signed in as, which games it reaches, and where the token is kept
 GAMESFUN_STUDIO=<origin> signs in to another xgames.fun (a local Studio while developing).`;
 
 export default {
@@ -24,13 +27,24 @@ export default {
       const origin = studioOrigin();
       if (values.status) {
         const { token: _token, words, ...s } = await signInState(origin);
-        if (values.json) printJson({ ...s, signedIn: s.state === 'signed-in' });
-        else console.log(s.state === 'signed-in' ? words : `${words} Run: ${s.next}`);
+        const reach = s.state === 'signed-in' ? await currentReach(origin) : null;
+        if (values.json)
+          printJson({
+            ...s,
+            signedIn: s.state === 'signed-in',
+            ...(reach ? { scope: reach.scope, games: reach.games, reachChecked: reach.checked } : {}),
+          });
+        else
+          console.log(
+            s.state === 'signed-in'
+              ? `${words}${reachWords(reach) ? ` ${reachWords(reach)}` : ''}`
+              : `${words} Run: ${s.next}`,
+          );
         return 0;
       }
       const rl = values.code ? createInterface({ input: process.stdin, output: process.stderr }) : null;
       try {
-        const r = await login({
+        const r = await loginWithReach({
           origin,
           code: values.code,
           open: url => openUrl(url, { web: true }),
@@ -38,10 +52,7 @@ export default {
           log: m => console.error(m),
         });
         if (values.json) printJson({ studio: origin, ...r });
-        else
-          console.log(
-            `Signed in to ${origin} as ${r.email}. The token is kept in ${storeWords(r.store)} until ${new Date(r.expiresAt).toISOString().slice(0, 10)}. Next: ${CMD} publish`,
-          );
+        else console.log(loginWords(r));
         return 0;
       } finally {
         rl?.close();

package/commands/logout.mjs

@@ -1,5 +1,6 @@
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { logout, studioOrigin } from '../lib/publish/client.mjs';
+import { forgetReach } from '../lib/login-reach.mjs';
 
 const usage = `Usage: xcore logout [--json]
 
@@ -26,6 +27,7 @@ export default {
       const { values } = parse(args, {}, usage);
       const origin = studioOrigin();
       const r = await logout(origin);
+      await forgetReach(origin);
       if (values.json) printJson({ studio: origin, ...r });
       else
         console.log(

package/commands/loot.mjs

@@ -9,10 +9,11 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { resolveGame, shown } from '../lib/games.mjs';
-import { ECONOMY_FILE, solanaCommand } from '../lib/economy.mjs';
+import { ECONOMY_FILE, solanaCommand, solanaHas } from '../lib/economy.mjs';
 import { addLoot } from '../lib/publish/adopt.mjs';
 import { solanaRpc } from '../lib/solana-rpc.mjs';
 import { CMD } from '../lib/command.mjs';
+import { NO_REVIEW } from '../lib/review.mjs';
 
 const usage = `Usage: xcore loot <command> [options]
 
@@ -21,6 +22,8 @@ A game's economy on loot, one shared Solana program (devnet only until it is aud
   xcore loot add [game]            where the game's economy (${ECONOMY_FILE}) and its page client (gf/loot/) go, and the
                                    copy once the economy is there (a brought game: the folder its build copies as it is)
   xcore loot check|simulate|cost|explain [file]   refusals and warnings; where the money goes; what it costs; in words
+  xcore loot review [file]         what a cheater gets from each route that pays, and the trade-offs in words (xcore
+                                   review adds the game's server and, with --live, the published game)
   xcore loot approve [file]        in a game's folder: put its economy live, approved in your own wallet
   xcore loot help                  everything else xsolana does (its help says \`xsolana <command>\`: run each as
                                    \`xcore loot <command>\`)
@@ -35,7 +38,7 @@ copy: never edit it; publish brings it up to date). A brought game with a build
 copies as it is (gamesfun.json page.static), so every build carries them. It prints the next steps.`;
 
 /** xsolana's commands that read an economy file ([file], default xsolana.json). */
-const ON_FILE = new Set(['check', 'simulate', 'cost', 'explain', 'publish', 'status', 'approve']);
+const ON_FILE = new Set(['check', 'simulate', 'cost', 'explain', 'review', 'publish', 'status', 'approve']);
 
 export default {
   name: 'loot',
@@ -70,6 +73,11 @@ export default {
       );
       return 1;
     }
+    // an installed package from before `review`: what to do, instead of its help
+    if (args[0] === 'review' && !solanaHas('review')) {
+      console.error(`xcore: ${NO_REVIEW}.`);
+      return 1;
+    }
     // a game made before the file was named xsolana.json keeps loot.json: given to the command when it names no file
     const named = args.slice(1).some(a => a.endsWith('.json'));
     let rest =
@@ -99,9 +107,10 @@ export default {
 };
 
 /** xsolana's commands a person runs as `xcore loot <command>`. */
-const COMMANDS = 'guide|examples|check|simulate|cost|explain|publish|approve|status|connect|mcp|tool|version|help';
+const COMMANDS =
+  'guide|examples|check|simulate|cost|explain|review|publish|approve|status|connect|mcp|tool|version|help';
 /** Its tools an agent calls (xsolana_check …) that are also a command here. */
-const TOOLS = 'guide|examples|check|simulate|cost|explain|publish|status';
+const TOOLS = 'guide|examples|check|simulate|cost|explain|review|publish|status';
 
 /**
  * xsolana's text as xcore's: its pinned npx forms and its `xsolana <command>` become `xcore loot <command>`, and the

package/commands/publish.mjs

@@ -8,6 +8,7 @@ import { studioOrigin } from '../lib/publish/client.mjs';
 import { gate } from '../lib/publish/gate.mjs';
 import { buildFailure, pageRoots, runBuild } from '../lib/publish/page.mjs';
 import { CMD } from '../lib/command.mjs';
+import { reviewNudge } from '../lib/review.mjs';
 
 const usage = `Usage: xcore publish [dir] [--draft] [--new] [--title <name>] [--status] [--check [--verify [--port <n>]]] [--json]
 
@@ -68,6 +69,9 @@ export function publishCommand({
         );
         const dir = await resolveGame(positionals[0]);
         const origin = studioOrigin();
+        // a game that pays results through vouchers, changed since its last security review: one line, never a refusal
+        const nudge = values.status || values.json ? null : reviewNudge(dir);
+        if (nudge) console.error(nudge);
         if (values.status) {
           const s = await publishStatus(dir, { origin });
           if (values.json) printJson(s);

package/commands/review.mjs

@@ -0,0 +1,106 @@
+// `xcore review [game] [--live [origin]]`: the security review of a brought game (../lib/review.mjs): its economy by
+// @xgamesfun/solana's own review, its server and page by this package's reading, and with --live the published game
+// asked as a stranger. The record goes in <game>/evidence/review-N/; any high finding exits 1.
+import { guard, parse, printJson, UsageError } from '../lib/cli.mjs';
+import { resolveGame, shown } from '../lib/games.mjs';
+import { readLinks } from '../lib/publish/index.mjs';
+import { studioOrigin } from '../lib/publish/client.mjs';
+import { CMD } from '../lib/command.mjs';
+
+const usage = `Usage: xcore review [game] [--live [origin]] [--out <dir>] [--json]
+
+The security review of a game, read as a cheater would: what a script gets without playing, and what to fix first.
+  the economy  @xgamesfun/solana's own review of the economy file (each route that pays: what it trusts, its ceiling,
+               its findings, the trade-offs in words), when the installed one has it
+  the server   PAY.check written or still the template, or paying from the request alone; VOUCHERS.payOnly against
+               the grants; the voucher key and the grants that name it; "trust" on every grant a voucher pays;
+               .dev.vars in git or in the published folder; a seed or key in the page's files; every api/ route
+  --live       the published game asked as a stranger: each api/ route with no sign-in and with a forged one (GET
+               and POST; a route that pays gets an empty body, so nothing it sends can spend or sign);
+               api/vouchers/key against the grants' keys; the published economy's "live" against this folder's.
+               The origin defaults to the game's link from its last publish; under ${CMD} dev, give its address
+               (--live http://127.0.0.1:<port>/game/).
+  --out <dir>  where the record goes (default: <game>/evidence/review-N/: review.md and review.json)
+  --json       the record as JSON
+review.md ends with the trade-offs for the person: for each route that pays, how the server checks it (decides,
+replays or bounds), what a cheater gets, and what the stronger level would cost. Any high finding exits 1.
+docs/SERVER.md, "How much your server can check", is the guide.`;
+
+/** --live takes an origin or nothing: `--live`, `--live <http…>`, `--live=<http…>`. → {args without it, live} */
+export function liveFlag(args) {
+  const rest = [];
+  let live = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--live') {
+      live = true;
+      if (/^https?:\/\//i.test(args[i + 1] ?? '')) live = args[++i];
+    } else if (a.startsWith('--live=')) live = a.slice('--live='.length) || true;
+    else rest.push(a);
+  }
+  return { rest, live };
+}
+
+export default {
+  name: 'review',
+  summary: 'the security review: what a cheater gets from its economy and server, with --live the published game',
+  usage,
+  run: args =>
+    guard(async () => {
+      const { rest, live } = liveFlag(args);
+      const { values, positionals } = parse(rest, { out: { type: 'string' } }, usage);
+      const dir = await resolveGame(positionals[0]);
+      let base = null,
+        liveWhy = `not asked for (${CMD} review --live)`;
+      if (typeof live === 'string') {
+        try {
+          base = new URL(live).href;
+        } catch {
+          throw new UsageError(`--live takes an address (https://… or http://127.0.0.1:<port>/game/)\n\n${usage}`);
+        }
+      } else if (live) {
+        const known = (await readLinks(dir))[studioOrigin()];
+        base = known?.gameUrl ?? null;
+        if (!base) {
+          liveWhy = `${shown(dir)} has no published link here: publish it, or run ${CMD} dev and give its address (--live http://127.0.0.1:<port>/game/)`;
+          if (!values.json) console.error(`Not asked live: ${liveWhy}.`);
+        }
+      }
+      const { reviewGame } = await import('../lib/review.mjs');
+      if (base && !values.json) console.error(`Asking ${base} as a stranger (no sign-in, and a forged one)…`);
+      const r = await reviewGame(dir, { live: base, liveWhy, out: values.out ?? null });
+      if (values.json) printJson(r);
+      else console.log(summary(r, shown(dir)));
+      return r.ok ? 0 : 1;
+    }, args),
+};
+
+/** What the command prints: the verdict, each finding, and where the record and the trade-offs are. */
+function summary(r, where) {
+  const c = r.counts;
+  const lines = [
+    `review: ${r.ok ? 'PASS' : 'FAIL'} ${c.high} high, ${c.medium} medium, ${c.low} low, ${c.info} info · evidence ${shown(r.outDir)}`,
+  ];
+  for (const f of r.findings) {
+    lines.push(`  ${f.severity.padEnd(6)} ${f.id}${f.route ? ` (${f.route})` : ''}: ${f.message}`);
+    if (f.fix && f.severity !== 'info') lines.push(`         fix: ${f.fix}`);
+  }
+  lines.push(
+    r.economy.file
+      ? r.economy.available
+        ? `economy: ${r.economy.file}, ${r.economy.routes.length} routes reviewed by @xgamesfun/solana ${r.economy.version}`
+        : `economy: ${r.economy.file} not reviewed: ${r.economy.why}`
+      : `economy: ${where} has none`,
+    `server: ${r.server.routes.length} api/ routes named${r.server.facts.vouchers ? `; PAY.check ${r.server.facts.pay === 'template' ? 'is still the template' : r.server.facts.pay}, payOnly ${r.server.facts.payOnly ?? '?'}` : ''}`,
+    r.live ? `live: ${r.live.base}, ${r.live.probes.length} requests` : `live: ${r.liveWhy}`,
+  );
+  for (const t of r.tradeoffs)
+    lines.push(
+      `paid route ${t.route}: ${t.trust ? `${t.trust}${t.declared ? '' : ' (read so by the economy review; not declared)'}` : 'trust not declared'}`,
+    );
+  if (r.tradeoffs.length)
+    lines.push(
+      `For the person: ${shown(r.outDir)}/review.md ends with each paid route's level, what a cheater gets and what the stronger level costs. Tell them, and let them choose.`,
+    );
+  return lines.join('\n');
+}