@nano133/nanoterra 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.11.0 (2026-11-01)
+
+- **New path `@nano133/nanoterra/admin-signin`: the admin's wallet sign-in, on one fixed route in every game, `/api/admin-signin`.** The game starter's admin
+  sign-in moved into the package with every check and every signed text unchanged: Berry Wallet signs the page `https://<host>/admin` (no query), Nautilus the
+  label "ADMIN of <host> sign-in ABCD-EFGH from <country>"; a request lives 2 minutes, is delivered one more minute and works once; only the browser that started it
+  and only the game's own address (`owner`; another wallet gets `not_owner`) make an admin login; the cookie `admin` (`__Host-admin` on https, one day) and the
+  database's `sha256("admin:" + token)` keep it apart from the player's login; each login writes the sign-in list (time, country, short browser name, 30 days).
+  `createAdminSignin({ store, owner, ... })` gives `handle`, `session` (for `createAdminHandler`), `signOut`, `signOutEverywhere`, `recentLogins` and `clean`.
+- **NanChat is off for the admin** (`nanchat: false`, the default): its text must start "Login to <host>" and cannot name the ADMIN, so a start is refused with
+  "NanChat cannot open the admin yet. Use Berry Wallet or Nautilus." `nanchat: true` turns it on (its "Login to <host>" text, the same admin checks). Berry
+  Wallet is first in every wallet list.
+- Stores: `createD1AdminSignin` on the starter's own tables (`signin_requests` and `sessions` with `scope = 'admin'`, `admin_logins`: **no migration** for the
+  starter; a new game adds `/admin-signin/d1.sql`), `createFirestoreAdminSignin`, `createMemoryAdminSignin`, and `adminSigninStoreConformance`
+  (`/admin-signin/conformance`) for a store a game writes itself.
+- The panel `/admin-signin/panel`: `adminSignIn()` and `adminSignOut()` fit `mountAdmin`'s `signIn` and `signOut`; Berry Wallet and Nautilus as tiles (NanChat with
+  `nanchat: true`), one key on a phone, a QR code on a computer (the package's own; Nautilus's link is too long for it and shows as a link). Its stylesheet
+  `/admin-signin/style.css` is the player sheet's (which gets a two-tile row).
+- The package's tests run `adminSigninConformance` (the player's sign-in and the admin's side by side, Berry Wallet, Nautilus and NanChat turned on) and
+  `adminConformance` (with `createAdminHandler` and the sign-in's `session`) on the memory store and on D1.
+
 ## 0.10.1 (2026-11-01)
 
 - **The admin conformance suite's heavy checks are one case for each route.** "Other spellings of EVERY admin path" and "a request from another

package/README.md

@@ -74,6 +74,10 @@ Each path loads only what it needs. A page that reads a ticket loads no Three.js
 | `@nano133/nanoterra/admin/d1`, `/admin/firestore` | the admin store for D1 (the starter's tables) or Firestore (a small interface, no Firebase dependency): `createD1Store`, `createFirestoreStore` (since 0.2.0) | no | 1.5 kB each |
 | `@nano133/nanoterra/admin/panel` | the admin page, drawn in the browser into one element, and its stylesheet `@nano133/nanoterra/admin/style.css` (since 0.2.0) | no | 18.9 kB with the tabbed layout (10.6 kB on 0.3.0, 8.5 kB on 0.2.0) + 5.9 kB of CSS (minified) |
 | `@nano133/nanoterra/admin/conformance` | test cases that a game runs against its own admin (a dev dependency in practice; since 0.2.0) | no | n/a |
+| `@nano133/nanoterra/admin-signin` | the admin's wallet sign-in on one fixed route, `/api/admin-signin`: the routes, `session(request)` for the admin handler, "Sign out everywhere", the sign-in list, a memory store (server code; it needs `@nano133/signin`; since 0.11.0) | no | 5.5 kB without `@nano133/signin` |
+| `@nano133/nanoterra/admin-signin/d1`, `/admin-signin/firestore` | its store on D1 (the starter's own tables; a new game adds `/admin-signin/d1.sql`) or Firestore (a small interface, no Firebase dependency) (since 0.11.0) | no | 1.4 kB, 1.7 kB |
+| `@nano133/nanoterra/admin-signin/panel` | the admin's sign-in in the browser, for `mountAdmin`'s `signIn` and `signOut`: `adminSignIn()`, `adminSignOut()`, with its own QR code; its stylesheet `@nano133/nanoterra/admin-signin/style.css` is the player sheet's (since 0.11.0) | no | 6.8 kB |
+| `@nano133/nanoterra/admin-signin/conformance` | the store's rules as test cases, for a store a game writes itself (since 0.11.0) | no | n/a |
 | `@nano133/nanoterra/friends` | the game's own friends list: the handler, the rules, a memory store (server code; since 0.6.0) | no | 3.7 kB |
 | `@nano133/nanoterra/friends/d1`, `/friends/firestore` | the friends store for D1 (with the migration `/friends/d1.sql`) or Firestore (a small interface, no Firebase dependency): `createD1Friends`, `createFirestoreFriends` (since 0.6.0) | no | 3.0 kB each |
 | `@nano133/nanoterra/friends/panel` | the Friends key and panel: the nano133 window, or the game's own list, and its stylesheet `@nano133/nanoterra/friends/style.css` (since 0.6.0) | no | 5.0 kB + 4.8 kB of CSS (minified) |
@@ -580,8 +584,8 @@ when your store has the call and your host can move its clock: a host that then
 
 **List the other routes that your own router serves under the admin base** in `host.otherRoutes` (`{ method, path }`: an old `/api/admin/orders`, a debug route, a route kept for an old page).
 The suite sends each one as every visitor who is not the owner and requires a refusal. It cannot find a route that your router hides from it, so a route that answers BEFORE the handler with no
-guard is a fault only if you list it. **What the suite cannot see:** the code that CREATES admin logins (your wallet sign-in). Test that separately: only a wallet signature started from the
-admin may make an admin login, and never from another sign-in. A security read found these gaps in the first version of this suite, and each one is a test now.
+guard is a fault only if you list it. **What the suite cannot see:** the code that CREATES admin logins (your wallet sign-in). Test that separately (the sign-in chain contract above;
+the package's own sign-in, `/admin-signin`, passes it): only a wallet signature started from the admin may make an admin login, and never from another sign-in. A security read found these gaps in the first version of this suite, and each one is a test now.
 
 ### The store (an adapter for your database)
 
@@ -618,7 +622,8 @@ With D1: `createD1Store(db, { logins: true })` needs the table `admin_logins (id
 `sessions` (`'admin'` for an admin login) and a `scope` column and a `delivered` column on `signin_requests` ("Sign out everywhere" also marks every admin request that was started and not delivered as
 delivered and ends it (`expires_at = 0`, so the wallet app does not show "Signed in" for it either), so a request that the owner signed a moment ago, or signs a moment later, cannot make a new admin login afterwards). The panel shows a browser name only when it is words (letters and spaces, 40 at most): anything else
 a store gives, such as a raw browser text or an address, is shown as "Unknown browser". Without the option the store has neither call, so a game without those tables is not broken. The store contract has cases for both calls.
-The Firestore store does not have them yet (a game's sessions are its own): a game with Firestore writes its own `recentLogins` and `signOutEverywhere`.
+The Firestore store does not have them yet (a game's sessions are its own): a game with Firestore gives it the admin sign-in's (`store.recentLogins = signin.recentLogins;
+store.signOutEverywhere = signin.signOutEverywhere`, see "The admin's sign-in"), or writes its own.
 
 ### Later ideas (not built)
 
@@ -690,7 +695,8 @@ element that holds it. The keys, inputs, switches, swatches and price steps are
 width (a container query), not the window's: on a phone two cards a row and the five tabs as icons over their words; three cards a row and the orders as a table from
 760 px; four cards from 1000 px. The panel can be up to 1200 px wide: the page that holds it sets the width (the starter's admin page is 900 px).
 
-The wallet sign-in stays yours (`signIn`), because only your game can start a request in the ADMIN scope with its own cookie. The panel never signs anyone in.
+The panel never signs anyone in: `signIn` draws the sign-in. Since 0.11.0 the package has one, `adminSignIn()` from `@nano133/nanoterra/admin-signin/panel` (see "The admin's
+sign-in"); a game with its own keeps giving its own.
 
 **Light and dark** (since 0.7.0). The top bar has a theme key (44 px, a half circle, a sun or a moon; its name says the choice: "Theme: Dark", "Theme: Device (dark
 now)"). A press opens a menu of three: **Device** (the default: it follows the device's setting, `prefers-color-scheme`, and a live change of it), **Light** and **Dark**.
@@ -723,6 +729,94 @@ html[data-n133-theme="dark"] body.admin-page {
 The pictures: a look's flat picture and the character previews (`createLookPreview` draws with a clear background) stand on the `stage` colour, which is a mid grey
 blue in dark, so a dark outfit and the outlines still show. The panel draws no QR code.
 
+## The admin's sign-in (`/admin-signin`; since 0.11.0)
+
+The wallet sign-in that makes the ADMIN login, in the package, on **one fixed route in every game: `/api/admin-signin`** (`ADMIN_SIGNIN_BASE`). Before it, every game put it
+somewhere else (the game starter: `/api/signin` with `scope: "admin"` in the body; AI helpers: their own `/api/admin-signin`). It is the game starter's admin sign-in moved into
+the package, **with every check and every signed text unchanged**; only the paths are new. The checks are `@nano133/signin`'s (install it with this package).
+
+```ts
+// The Worker (D1)
+import { createAdminSignin } from "@nano133/nanoterra/admin-signin";
+import { createD1AdminSignin } from "@nano133/nanoterra/admin-signin/d1";
+import { createAdminHandler } from "@nano133/nanoterra/admin";
+import { createD1Store } from "@nano133/nanoterra/admin/d1";
+
+const adminSignin = createAdminSignin({
+  store: createD1AdminSignin(env.DB),           // the starter's own tables: no migration (a new game adds "@nano133/nanoterra/admin-signin/d1.sql")
+  owner: receiveAddress(env),                    // the game's own address, or null: ONLY it makes an admin login
+  limit: (key, n, ms, now) => d1Limit(env.DB, key, n, ms, now),   // optional: your limiter for the starts (default: this copy's memory)
+  visitor: (req) => visitorKey(env.DB, req),     // optional: a keyed hash of the IP address
+  personCheck: (token, req) => turnstileCheck(env, token, req.headers.get("CF-Connecting-IP")),   // optional (Turnstile)
+});
+const admin = createAdminHandler({
+  store: createD1Store(env.DB, { logins: true }),   // the Sign-ins card and "Sign out everywhere", on the same tables
+  defaults, owner: receiveAddress(env),
+  session: (req, now) => adminSignin.session(req, now),   // the ADMIN cookie only
+  status, lookName, check,
+});
+const answer = (await adminSignin.handle(request)) ?? (await admin.handle(request));   // null: not theirs; the game goes on
+// the cron: await adminSignin.clean();
+
+// The admin page
+import { mountAdmin } from "@nano133/nanoterra/admin/panel";
+import { adminSignIn, adminSignOut } from "@nano133/nanoterra/admin-signin/panel";
+import "@nano133/nanoterra/admin/style.css";
+import "@nano133/nanoterra/admin-signin/style.css";
+mountAdmin(el, { looks, signIn: adminSignIn({ personCheck }), signOut: adminSignOut() });
+```
+
+| Route (`base` "/api/admin-signin") | Who calls it | What it does |
+|---|---|---|
+| `POST {base}/start` `{ way, turnstile? }` | the admin page | starts an admin request (`way` "berry", the default, or "nautilus"): `{ way, id, link, walletLink?, code?, expiresAt }` and the starter cookie `starter-admin` (30 minutes) |
+| `GET`, `POST {base}/nano/:id` | Berry Wallet | reads the request; posts its signature (204 and no body when accepted, 401 and the words when refused) |
+| `POST {base}/nautilus?id=` | Nautilus | its signature (always 200: Nautilus shows only a 200's words) |
+| `POST {base}/nanchat` | NanChat's relay server | only with `nanchat: true` (else no route): its signature (always 200; a refusal starts "NOT signed in") |
+| `POST {base}/check` `{ id, way }` | the admin page, every 2 s | `{ status }`: `waiting`, `expired`, `elsewhere`, `used`, `not_owner` (with `address`: another wallet signed; no login, the request stays unused), or `signedin` with `address` and the admin cookie |
+| `POST {base}/signout` | the admin page | ends this browser's ADMIN login only: `{ ok: true }` |
+
+**What the wallet signs names the ADMIN**, so a link that a stranger sends to the owner does not look like any sign-in. Berry Wallet signs the page `https://<host>/admin`
+(`page`, with **no query**: Berry refused `/admin?from=US`); Nautilus signs the label `ADMIN of <host> sign-in ABCD-EFGH from <country>` and shows "Sign in to the ADMIN of
+<host>. Started <time> UTC from <country>. If you did not start this, do not sign." It names the owner's address (no key, no payment). An admin request **lives 2
+minutes**, is delivered for **one more minute**, and works **once**; only the browser that started it gets the login.
+
+**NanChat is OFF by default.** Its text must start "Login to <host>" and **cannot name the ADMIN**, so the owner who is asked to sign cannot tell an admin sign-in from a game
+sign-in. A start with `way: "nanchat"` is refused: "NanChat cannot open the admin yet. Use Berry Wallet or Nautilus." A game may turn it on with `nanchat: true` (and the
+panel's `nanchat: true`): it then signs "Login to <host>" as a player's NanChat sign-in does, with the same admin checks, and the panel says that its text cannot say ADMIN.
+**Berry Wallet is first** in every list of wallets. **No passkey opens /admin** yet.
+
+**The two logins stay apart, on the server.** The admin login is its own cookie, `admin` (`__Host-admin` on https; HttpOnly, SameSite=Lax, **one day**), beside the player's
+`session`, so the game and /admin can have different people signed in at once. The database keeps the SHA-256 of `"admin:"` and the token (`adminKey`), and the player's
+session its plain hash: a player's token put in the admin cookie opens nothing, a player's starter copied to `starter-admin` finishes nothing, and an admin request never
+makes a player's login (the store reads only its own scope's rows). **Only the game's own address (`owner`) makes an admin login**; the guard (`adminAccess`) decides again
+on every call of /admin. `session(request)` gives `{ address, createdAt, via }` (a stored word other than `"wallet"` or `"nanoterra"` is `"unknown"`: refused).
+
+**What it keeps.** Each admin login writes one row of the sign-in list: the time, the country of Cloudflare's country header (two letters, or none) and a short browser
+name from fixed lists ("Chrome on macOS"): no address, no IP and no browser text. A row is kept 30 days. `signOutEverywhere()` deletes every admin login and ends every admin
+request that was not delivered; `recentLogins(limit)` reads the list (give both to an admin store that has neither: the Firestore one, or the memory one in a test).
+
+**The stores** read and write only their three tables or collections, and only the admin's rows:
+
+- **D1:** `createD1AdminSignin(env.DB)` works on the game starter's own tables and columns: `signin_requests` (`scope = 'admin'`), `sessions` (`scope = 'admin'`)
+  and `admin_logins (id, at, country, browser)`. **The starter needs no migration**, and every creator who is signed in stays signed in. A new game adds
+  `@nano133/nanoterra/admin-signin/d1.sql` to its migrations (the same tables, `CREATE TABLE IF NOT EXISTS`; beside the player sign-in's d1.sql it adds only `admin_logins`).
+  "Sign out everywhere" is the same two statements as `createD1Store(db, { logins: true })`. Other table names: `createD1AdminSignin(db, { requests, sessions, logins })`.
+- **Firestore:** `createFirestoreAdminSignin(db, { requests, sessions, logins })` (default `signin_requests`, `sessions`, `admin_logins`; the player sign-in's
+  adapter keeps its own documents in the first two with `scope: "play"`). Each document carries `deleteAt`: set a TTL policy on it.
+- **Your own database:** an `AdminSigninStore` that passes `adminSigninStoreConformance` from `@nano133/nanoterra/admin-signin/conformance`. The whole chain (the
+  player's sign-in and the admin's, side by side) passes `adminSigninConformance` from `@nano133/nanoterra/admin/conformance`: the package runs it on the memory store and on D1,
+  with Berry Wallet, Nautilus and NanChat turned on.
+
+**The rest:** `base` (keep the default), `page` (default `/admin`), `domain` (the host every text names; a call to another host is refused), `cookies`
+(default `{ session: "admin", starter: "starter-admin" }`), `now`, `onError`. Starts: 20 in 10 minutes per visitor (the player's key: one count for both);
+checks 90 a minute and the wallets' calls 30 a minute per IP address. **The panel** (`adminSignIn(options)`, `adminSigninView(options)`, `adminSignOut(options)`): the
+wallets as tiles, on a phone one key that opens the app, on a computer a QR code (the package's own; a link that is too long for it, Nautilus's, shows as a link), the
+check every 2 seconds, and `done()` once the owner has signed in. Options: `base`, `nanchat`, `personCheck(box)`, `qr(text)`, `touch`, `fetch`. Text 16 px, keys 48 px.
+
+**Moving the game starter onto it:** use `createD1AdminSignin(env.DB)` (no migration), answer `adminSignin.handle(request)` before the player's sign-in, give the admin handler
+`session: adminSignin.session`, and in `admin.ts` `signIn: adminSignIn(...)`, `signOut: adminSignOut()`. The player's sign-in then needs no `sharedPaths`, and
+`src/worker/signin.ts` and `src/client/ui/signin.ts` go. Old requests started on `/api/signin` with `scope: "admin"` are 2 minutes long: none outlive the deploy.
+
 ## The friends list (`/friends`; since 0.6.0)
 
 A Friends key for the game, and a list behind it. The admin's **Game** card chooses which list (`friends` in the settings; Nanoterra by default):
@@ -1127,7 +1221,8 @@ These are the game starter's own routes and answers, so its page works unchanged
   exchange and returns the Set-Cookie value; `signin.signOut(request)` likewise; `signin.forget(player)` is for **"Delete my data"** (every session, signed
   request and once-only row of the player); `signin.clean()` is for a cron.
 - **`sharedPaths: true`** for a game whose own admin signs in on the same paths (the starter's `scope: "admin"`): the admin's calls, and a wallet's call for a
-  request this store does not hold, answer null, and the game's admin code answers them.
+  request this store does not hold, answer null, and the game's admin code answers them. A game that uses the package's admin sign-in (`/admin-signin`, on its own
+  route) does not need it.
 - `ways` (default all three), `passkey: false`, `base`, `signOutPath`, `cookies`, `sessionDays` change the rest.
 
 **The stores** read and write only their three tables or collections, and only the player's rows:
@@ -1427,6 +1522,8 @@ counter** as they are, and the page needs no change for the server part.
 - First-person arms, swimming, climbing and the room's other moves: only idle, walk, run, jump and wave, and the emotes (`/emotes`, which sit too).
 - Shared geometry for many characters at once, and a react-three-fiber wrapper.
 - `WebGPURenderer`: the ink is a GLSL `ShaderMaterial`, so use `WebGLRenderer`.
+- A passkey for the admin: the owner's linked passkey comes in a later version. Today only a wallet signature opens /admin.
+- A creator option to accept Berry Wallet only.
 - Move money. The shop (`/shop`) reads the Nano ledger to see a payment to the creator's address; no part of the package holds a key or sends.
 
 ## Build and test

package/ai/SPEC.md

@@ -3,7 +3,7 @@
 Package: `@nano133/nanoterra` (0.1.0 or later). Follow these steps in order. Each step ends with a check. Ask the owner when a step says
 "ask". The package has five parts: the sign-in ticket (`/ticket`), the player's character (`/character`, Three.js), the
 looks ladder (`/looks`), held input that does not stick (`/input`), the friends list (`/friends`, with its panel), the options menu (`/options`), the emotes (`/emotes`, with the wheel), the player's sign-in (`/player-signin`: a passkey or a wallet app, with
-`@nano133/signin`) and the shop (`/shop`, with its panel). Use only the parts the game needs. Only the player's sign-in and the shop have Nano code; the shop holds no key and sends nothing: it reads the ledger. Read the package README first.
+`@nano133/signin`), the admin's sign-in (`/admin-signin`, with `@nano133/signin`) and the shop (`/shop`, with its panel). Use only the parts the game needs. Only the two sign-ins and the shop have Nano code; the shop holds no key and sends nothing: it reads the ledger. Read the package README first.
 
 ## 0. What the owner decides (ask)
 
@@ -255,7 +255,35 @@ import "@nano133/nanoterra/shop/style.css";
 address and `TEST_MODE` off, the pay sheet shows the QR code and the exact amount; a second player gets the next step (0.0001 XNO more); another player's
 order id answers 404; a payment of one raw too little is not matched. Test with a small real payment only when the owner says so, to the owner's own address.
 
-## 14. Do not
+## 14. The admin's sign-in (a game with /admin)
+
+```sh
+npm install @nano133/nanoterra @nano133/signin
+```
+
+The admin's sign-in is the package's, on ONE fixed route in every game: `/api/admin-signin`. Do not write your own admin sign-in, do not put it on another path, and
+do not change what the wallet signs.
+
+1. **The store.** D1: `createD1AdminSignin(env.DB)` from `@nano133/nanoterra/admin-signin/d1` (a game made from the starter has the tables already: no migration; a
+   new game adds `@nano133/nanoterra/admin-signin/d1.sql` to its migrations). Firestore: `createFirestoreAdminSignin(db)` with a TTL policy on `deleteAt`. Another
+   database: a store that passes `adminSigninStoreConformance`.
+2. **The server.** `const adminSignin = createAdminSignin({ store, owner, limit, visitor, personCheck })`, where `owner` is the creator's own address (RECEIVE_ADDRESS) or
+   null. Answer `adminSignin.handle(request)` under `/api/`, and give the admin handler `session: (req, now) => adminSignin.session(req, now)`. Only the owner's wallet
+   makes an admin login; a player's login never does. A cron calls `adminSignin.clean()`.
+3. **"Sign out everywhere" and the Sign-ins card.** D1: `createD1Store(env.DB, { logins: true })` for the admin handler (the same tables). Another store: give it
+   `recentLogins: adminSignin.recentLogins` and `signOutEverywhere: adminSignin.signOutEverywhere`.
+4. **The page.** `mountAdmin(el, { looks, signIn: adminSignIn({ personCheck }), signOut: adminSignOut() })` from `@nano133/nanoterra/admin-signin/panel`, with
+   `@nano133/nanoterra/admin-signin/style.css`.
+5. **NanChat stays off** unless the owner asks for it: its text cannot name the ADMIN, so the owner cannot tell an admin sign-in from a game sign-in. To turn it on, pass
+   `nanchat: true` to `createAdminSignin` AND to `adminSignIn`. No passkey opens /admin yet.
+6. **Tests.** Run `adminSigninConformance` (`@nano133/nanoterra/admin/conformance`) on the game's own chain (its player sign-in and the admin's), and `adminConformance` with
+   the admin handler and `adminSignin.session`.
+
+**Check:** on the game's public https address, Berry Wallet shows "URI: https://<host>/admin" and Nautilus "ADMIN of <host>"; the owner's wallet opens /admin; another
+wallet gets "That wallet is not this game's address"; the player's login (the owner's own address too) does not open /admin; a NanChat start says "NanChat cannot open the
+admin yet."
+
+## 15. Do not
 
 - Do not edit the geometry, the skeleton or the toon and ink materials.
 - Do not add the katana, the headband or other brands' art. A game's own worn model goes on a socket (`c.socket("head" | "hand" | "back")` or

package/dist/admin-signin/adapters/d1.d.ts

@@ -0,0 +1,10 @@
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { type AdminSigninStore } from "../types.js";
+export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
+/** The tables' names. Default: the game starter's. A game with other names changes d1.sql to match. */
+export type D1AdminSigninTables = {
+    requests?: string;
+    sessions?: string;
+    logins?: string;
+};
+export declare function createD1AdminSignin(db: D1Like, tables?: D1AdminSigninTables): AdminSigninStore;

package/dist/admin-signin/adapters/d1.js

@@ -0,0 +1,106 @@
+// The admin sign-in's store for a game on Cloudflare D1, on the game starter's OWN tables and columns: `signin_requests` and `sessions` (their admin
+// rows, scope = 'admin') and `admin_logins`. A starter moves onto it with no migration, and every creator who is signed in to /admin stays signed in.
+// A new game adds ./d1.sql to its migrations ("@nano133/nanoterra/admin-signin/d1.sql": the same tables, `IF NOT EXISTS`).
+//
+//   import { createD1AdminSignin } from "@nano133/nanoterra/admin-signin/d1";
+//   const store = createD1AdminSignin(env.DB);
+//
+// It reads and writes ONLY the admin's rows (scope = 'admin'): a game whose players sign in through the same tables (the player sign-in's scope 'play')
+// keeps its rows, and this adapter never reads, delivers, ends or deletes one. D1 has no transaction that reads and then writes, so each change is ONE
+// statement that holds its own check, and a delivery and its session are one batch (the session is written only when the delivery changed a row).
+// "Sign out everywhere" is the same two statements as the admin store's (`createD1Store(db, { logins: true })`): either one may run it.
+import { ADMIN_LOGIN_KEEP_MS, ADMIN_WAYS } from "../types.js";
+const toRequest = (r) => ({
+    id: r.rid ?? r.id,
+    starter: r.starter,
+    status: r.status === "signedin" ? "signedin" : "waiting",
+    expiresAt: Number(r.expires_at),
+    ...(r.label ? { label: r.label } : {}),
+    ...(r.nonce ? { nonce: r.nonce } : {}),
+    ...(r.issued_at ? { issuedAt: Number(r.issued_at) } : {}),
+    ...(r.account ? { account: r.account } : {}),
+});
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+const changes = (res) => Number(res?.meta?.changes ?? 0);
+export function createD1AdminSignin(db, tables = {}) {
+    const T = { requests: tables.requests ?? "signin_requests", sessions: tables.sessions ?? "sessions", logins: tables.logins ?? "admin_logins" };
+    for (const n of Object.values(T))
+        if (!NAME.test(n))
+            throw new Error(`not a table name: ${n}`);
+    const COLS = "id, rid, starter, status, expires_at, nonce, issued_at, label, account";
+    const stores = new Map();
+    for (const way of ADMIN_WAYS) {
+        stores.set(way, {
+            async create(key, r) {
+                // The starter's own insert: `scope` is written when the request is created, so a request started for the admin is the admin's for good.
+                await db
+                    .prepare(`INSERT INTO ${T.requests} (id, rid, way, starter, status, expires_at, nonce, issued_at, label, scope) VALUES (?, ?, ?, ?, 'waiting', ?, ?, ?, ?, 'admin')`)
+                    .bind(key, r.id, way, r.starter, r.expiresAt, r.nonce ?? null, r.issuedAt ?? null, r.label ?? null)
+                    .run();
+            },
+            async get(key) {
+                const r = await db.prepare(`SELECT ${COLS} FROM ${T.requests} WHERE id = ? AND way = ? AND scope = 'admin'`).bind(key, way).first();
+                return r ? toRequest(r) : null;
+            },
+            async find(id) {
+                const r = await db.prepare(`SELECT ${COLS} FROM ${T.requests} WHERE rid = ? AND way = ? AND scope = 'admin'`).bind(id, way).first();
+                return r ? { key: r.id, request: toRequest(r) } : null;
+            },
+            async finish(key, account) {
+                return changes(await db.prepare(`UPDATE ${T.requests} SET status = 'signedin', account = ? WHERE id = ? AND way = ? AND status = 'waiting' AND scope = 'admin'`).bind(account, key, way).run()) === 1;
+            },
+        });
+    }
+    return {
+        requests: (way) => {
+            const s = stores.get(way);
+            if (!s)
+                throw new Error(`no such way: ${String(way)}`);
+            return s;
+        },
+        async deliver(way, key, s) {
+            // The starter's batch: the delivery, and the session only when the delivery changed a row.
+            const done = await db.batch([
+                db.prepare(`UPDATE ${T.requests} SET delivered = 1 WHERE id = ? AND way = ? AND delivered = 0 AND status = 'signedin' AND scope = 'admin'`).bind(key, way),
+                db.prepare(`INSERT INTO ${T.sessions} (id_hash, address, created_at, expires_at, via, scope) SELECT ?, ?, ?, ?, ?, 'admin' WHERE changes() = 1`).bind(s.idHash, s.address, s.createdAt, s.expiresAt, s.via),
+            ]);
+            return changes(done[0]) === 1;
+        },
+        async session(idHash, now) {
+            const r = await db
+                .prepare(`SELECT id_hash, address, created_at, expires_at, via FROM ${T.sessions} WHERE id_hash = ? AND expires_at > ? AND scope = 'admin'`)
+                .bind(idHash, now)
+                .first();
+            return r ? { idHash: r.id_hash, address: r.address, createdAt: Number(r.created_at), expiresAt: Number(r.expires_at), via: String(r.via) } : null;
+        },
+        async endSession(idHash) {
+            await db.prepare(`DELETE FROM ${T.sessions} WHERE id_hash = ? AND scope = 'admin'`).bind(idHash).run();
+        },
+        async signOutEverywhere() {
+            const done = await db.batch([
+                db.prepare(`DELETE FROM ${T.sessions} WHERE scope = 'admin'`),
+                db.prepare(`UPDATE ${T.requests} SET delivered = 1, expires_at = 0 WHERE scope = 'admin' AND delivered = 0`),
+            ]);
+            return changes(done[0]);
+        },
+        async recordLogin(login) {
+            await db.batch([
+                db.prepare(`INSERT INTO ${T.logins} (at, country, browser) VALUES (?, ?, ?)`).bind(login.at, login.country, login.browser),
+                db.prepare(`DELETE FROM ${T.logins} WHERE at < ?`).bind(login.at - ADMIN_LOGIN_KEEP_MS),
+            ]);
+        },
+        async recentLogins(limit) {
+            const n = Math.min(Math.max(Math.floor(Number(limit)) || 0, 0), 50);
+            const rows = (await db.prepare(`SELECT at, country, browser FROM ${T.logins} ORDER BY at DESC, id DESC LIMIT ?`).bind(n).all()).results;
+            return rows.map((r) => ({ at: Number(r.at), country: r.country, browser: r.browser }));
+        },
+        async clean(now) {
+            // The starter's clean-up of its admin rows (its `cleanUp`, without the game's own `hits`).
+            await db.batch([
+                db.prepare(`DELETE FROM ${T.requests} WHERE expires_at < ? AND scope = 'admin'`).bind(now - 2 * 3_600_000),
+                db.prepare(`DELETE FROM ${T.sessions} WHERE expires_at < ? AND scope = 'admin'`).bind(now),
+                db.prepare(`DELETE FROM ${T.logins} WHERE at < ?`).bind(now - ADMIN_LOGIN_KEEP_MS),
+            ]);
+        },
+    };
+}

package/dist/admin-signin/adapters/firestore.d.ts

@@ -0,0 +1,49 @@
+import { type AdminSigninStore } from "../types.js";
+export type AdminSigninDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface AdminSigninDocRef {
+    get(): Promise<AdminSigninDocSnap>;
+}
+export type AdminSigninQuerySnap = {
+    docs: {
+        id: string;
+        ref: AdminSigninDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface AdminSigninQuery {
+    where(field: string, op: "==" | "<", value: unknown): AdminSigninQuery;
+    orderBy(field: string, direction?: "asc" | "desc"): AdminSigninQuery;
+    limit(n: number): AdminSigninQuery;
+    get(): Promise<AdminSigninQuerySnap>;
+}
+export interface AdminSigninCollection extends AdminSigninQuery {
+    doc(id: string): AdminSigninDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface AdminSigninTransaction {
+    get(ref: AdminSigninDocRef): Promise<AdminSigninDocSnap>;
+    set(ref: AdminSigninDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: AdminSigninDocRef): unknown;
+}
+export interface AdminSigninBatch {
+    set(ref: AdminSigninDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: AdminSigninDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestoreAdminSigninLike {
+    collection(name: string): AdminSigninCollection;
+    runTransaction<T>(fn: (tx: AdminSigninTransaction) => Promise<T>): Promise<T>;
+    batch(): AdminSigninBatch;
+}
+export declare function createFirestoreAdminSignin(db: FirestoreAdminSigninLike, collections?: {
+    requests?: string;
+    sessions?: string;
+    logins?: string;
+}): AdminSigninStore;

package/dist/admin-signin/adapters/firestore.js

@@ -0,0 +1,179 @@
+// The admin sign-in's store for a game on Firestore (the Admin SDK). The package has no Firebase dependency: the adapter uses the small interface
+// below, which the Admin SDK's `Firestore` fits. It reads and writes ONLY its three collections, and only the admin's documents (scope "admin") of the
+// first two: the player sign-in's Firestore adapter keeps its own (scope "play") in the same collections.
+//
+//   import { createFirestoreAdminSignin } from "@nano133/nanoterra/admin-signin/firestore";
+//   const store = createFirestoreAdminSignin(getFirestore());
+//
+// The data model (the three collection names can be changed):
+//   signin_requests/{key}   { id, way, starter, status, expiresAt, nonce?, issuedAt?, label?, account?, delivered, scope: "admin", deleteAt }
+//   sessions/{idHash}       { address, createdAt, expiresAt, via, scope: "admin", deleteAt }
+//   admin_logins/{id}       { at, country, browser, deleteAt }
+// Times are ms numbers; `deleteAt` is a Date (a Timestamp in Firestore): set a TTL policy on `deleteAt` for each collection. `{key}` is the request's id;
+// `{idHash}` the SHA-256 of "admin:" and the session's token. Every change that reads first is a transaction. Indexes: Firestore's own single-field
+// indexes are enough (`id`, `scope`, `expiresAt`, `at`).
+//
+// The admin store for Firestore (`createFirestoreStore`) has no sign-in list and no "Sign out everywhere": give it this sign-in's,
+// `store.recentLogins = signin.recentLogins` and `store.signOutEverywhere = signin.signOutEverywhere`.
+import { ADMIN_LOGIN_KEEP_MS, ADMIN_WAYS } from "../types.js";
+const DAY = 86_400_000;
+/** At most this many documents go in one batch (Firestore's limit is 500). */
+const BATCH = 400;
+const text = (v) => (typeof v === "string" ? v : undefined);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const hex = (bytes) => Array.from(crypto.getRandomValues(new Uint8Array(bytes)), (x) => x.toString(16).padStart(2, "0")).join("");
+function requestOf(d, key, way) {
+    if (!d || d.scope !== "admin" || d.way !== way || typeof d.starter !== "string" || num(d.expiresAt) === undefined)
+        return null;
+    const nonce = text(d.nonce);
+    const issuedAt = num(d.issuedAt);
+    const label = text(d.label);
+    const account = text(d.account);
+    return {
+        id: text(d.id) ?? key,
+        starter: d.starter,
+        status: d.status === "signedin" ? "signedin" : "waiting",
+        expiresAt: num(d.expiresAt),
+        ...(label !== undefined ? { label } : {}),
+        ...(nonce !== undefined ? { nonce } : {}),
+        ...(issuedAt !== undefined ? { issuedAt } : {}),
+        ...(account !== undefined ? { account } : {}),
+    };
+}
+export function createFirestoreAdminSignin(db, collections = {}) {
+    const requestsCol = () => db.collection(collections.requests ?? "signin_requests");
+    const sessionsCol = () => db.collection(collections.sessions ?? "sessions");
+    const loginsCol = () => db.collection(collections.logins ?? "admin_logins");
+    const sessionData = (s) => ({ address: s.address, createdAt: s.createdAt, expiresAt: s.expiresAt, via: s.via, scope: "admin", deleteAt: new Date(s.expiresAt) });
+    const stores = new Map();
+    for (const way of ADMIN_WAYS) {
+        stores.set(way, {
+            async create(key, r) {
+                const ref = requestsCol().doc(key);
+                await db.runTransaction(async (tx) => {
+                    if ((await tx.get(ref)).exists)
+                        throw new Error("a request with this key exists");
+                    tx.set(ref, {
+                        id: r.id,
+                        way,
+                        starter: r.starter,
+                        status: "waiting",
+                        expiresAt: r.expiresAt,
+                        ...(r.nonce !== undefined ? { nonce: r.nonce } : {}),
+                        ...(r.issuedAt !== undefined ? { issuedAt: r.issuedAt } : {}),
+                        ...(r.label !== undefined ? { label: r.label } : {}),
+                        delivered: false,
+                        scope: "admin",
+                        deleteAt: new Date(r.expiresAt + DAY),
+                    });
+                });
+            },
+            async get(key) {
+                return requestOf((await requestsCol().doc(key).get()).data(), key, way);
+            },
+            async find(id) {
+                for (const d of (await requestsCol().where("id", "==", id).limit(10).get()).docs) {
+                    const request = requestOf(d.data(), d.id, way);
+                    if (request)
+                        return { key: d.id, request };
+                }
+                return null;
+            },
+            async finish(key, account) {
+                const ref = requestsCol().doc(key);
+                return db.runTransaction(async (tx) => {
+                    const cur = requestOf((await tx.get(ref)).data(), key, way);
+                    if (!cur || cur.status !== "waiting")
+                        return false;
+                    tx.set(ref, { status: "signedin", account }, { merge: true });
+                    return true;
+                });
+            },
+        });
+    }
+    async function deleteAll(docs) {
+        for (let i = 0; i < docs.length; i += BATCH) {
+            const b = db.batch();
+            for (const d of docs.slice(i, i + BATCH))
+                b.delete(d.ref);
+            await b.commit();
+        }
+        return docs.length;
+    }
+    return {
+        requests: (way) => {
+            const s = stores.get(way);
+            if (!s)
+                throw new Error(`no such way: ${String(way)}`);
+            return s;
+        },
+        async deliver(way, key, session) {
+            const ref = requestsCol().doc(key);
+            const sref = sessionsCol().doc(session.idHash);
+            return db.runTransaction(async (tx) => {
+                const raw = (await tx.get(ref)).data();
+                const cur = requestOf(raw, key, way);
+                await tx.get(sref);
+                if (!cur || cur.status !== "signedin" || raw?.delivered === true)
+                    return false;
+                tx.set(ref, { delivered: true }, { merge: true });
+                tx.set(sref, sessionData(session));
+                return true;
+            });
+        },
+        async session(idHash, now) {
+            const d = (await sessionsCol().doc(idHash).get()).data();
+            if (!d || d.scope !== "admin" || typeof d.address !== "string")
+                return null;
+            const expiresAt = num(d.expiresAt);
+            if (expiresAt === undefined || expiresAt <= now)
+                return null;
+            return { idHash, address: d.address, createdAt: num(d.createdAt) ?? 0, expiresAt, via: String(d.via ?? "") };
+        },
+        async endSession(idHash) {
+            const ref = sessionsCol().doc(idHash);
+            await db.runTransaction(async (tx) => {
+                const d = (await tx.get(ref)).data();
+                if (d && d.scope === "admin")
+                    tx.delete(ref);
+            });
+        },
+        async signOutEverywhere() {
+            // The requests first, then the sessions are read: a delivery that ran before the requests were ended wrote its session already, and it goes too; a
+            // delivery after it finds its request delivered (its transaction runs again on the changed document) and writes none.
+            const pending = (await requestsCol().where("scope", "==", "admin").get()).docs.filter((d) => d.data().delivered !== true);
+            for (let i = 0; i < pending.length; i += BATCH) {
+                const b = db.batch();
+                for (const d of pending.slice(i, i + BATCH))
+                    b.set(d.ref, { delivered: true, expiresAt: 0 }, { merge: true });
+                await b.commit();
+            }
+            return deleteAll((await sessionsCol().where("scope", "==", "admin").get()).docs);
+        },
+        async recordLogin(login) {
+            const old = (await loginsCol().where("at", "<", login.at - ADMIN_LOGIN_KEEP_MS).limit(BATCH).get()).docs;
+            const b = db.batch();
+            b.set(loginsCol().doc(`${String(login.at).padStart(15, "0")}-${hex(8)}`), { at: login.at, country: login.country, browser: login.browser, deleteAt: new Date(login.at + ADMIN_LOGIN_KEEP_MS) });
+            for (const d of old)
+                b.delete(d.ref);
+            await b.commit();
+        },
+        async recentLogins(limit) {
+            const n = Math.min(Math.max(Math.floor(Number(limit)) || 0, 0), 50);
+            if (!n)
+                return [];
+            // Newest first; two at the same time come in the order of their ids (the time, then random letters).
+            const docs = (await loginsCol().orderBy("at", "desc").limit(n).get()).docs;
+            return docs.map((d) => {
+                const v = d.data();
+                return { at: num(v.at) ?? 0, country: text(v.country) ?? null, browser: text(v.browser) ?? "Unknown browser" };
+            });
+        },
+        async clean(now) {
+            const old = (await requestsCol().where("expiresAt", "<", now - 2 * 3_600_000).limit(BATCH).get()).docs.filter((d) => d.data().scope === "admin");
+            const ended = (await sessionsCol().where("expiresAt", "<", now).limit(BATCH).get()).docs.filter((d) => d.data().scope === "admin");
+            const logins = (await loginsCol().where("at", "<", now - ADMIN_LOGIN_KEEP_MS).limit(BATCH).get()).docs;
+            await deleteAll([...old, ...ended, ...logins]);
+        },
+    };
+}

package/dist/admin-signin/browser.d.ts

@@ -0,0 +1,4 @@
+/** "Chrome on macOS", "Safari on iOS", "Firefox", or "Unknown browser". At most 40 characters, only from the lists above. */
+export declare function shortBrowser(userAgent: string | null | undefined): string;
+/** The rough country of a request: Cloudflare's two-letter country header, or null (not there, "XX" for unknown, "T1" for Tor, or anything that is not two capital letters). */
+export declare function countryOf(req: Request): string | null;

package/dist/admin-signin/browser.js

@@ -0,0 +1,36 @@
+// What the admin's sign-in list keeps of a browser: a short name made from fixed lists ("Chrome on macOS") and the rough country. The game starter's
+// src/worker/browser.ts, unchanged. It NEVER returns any of the browser's own text, so a hostile browser text cannot put anything in the list, and only
+// this name is kept (never the browser text itself).
+const BROWSERS = [
+    [/\bEdg(?:e|A|iOS)?\//, "Edge"],
+    [/\bOPR\/|\bOpera\b/, "Opera"],
+    [/\bSamsungBrowser\//, "Samsung Internet"],
+    [/\bFirefox\/|\bFxiOS\//, "Firefox"],
+    [/\bChrome\/|\bCriOS\//, "Chrome"],
+    [/\bSafari\//, "Safari"],
+];
+const SYSTEMS = [
+    [/\biPhone\b|\biPad\b|\biPod\b/, "iOS"],
+    [/\bAndroid\b/, "Android"],
+    [/\bCrOS\b/, "ChromeOS"],
+    [/\bWindows\b/, "Windows"],
+    [/\bMac OS X\b|\bMacintosh\b/, "macOS"],
+    [/\bLinux\b|\bX11\b/, "Linux"],
+];
+/** "Chrome on macOS", "Safari on iOS", "Firefox", or "Unknown browser". At most 40 characters, only from the lists above. */
+export function shortBrowser(userAgent) {
+    if (typeof userAgent !== "string" || !userAgent)
+        return "Unknown browser";
+    // Only the start of the text is read: a long text cannot make the matching slow.
+    const ua = userAgent.slice(0, 400);
+    const browser = BROWSERS.find(([re]) => re.test(ua))?.[1];
+    const system = SYSTEMS.find(([re]) => re.test(ua))?.[1];
+    if (!browser && !system)
+        return "Unknown browser";
+    return `${browser ?? "Browser"}${system ? ` on ${system}` : ""}`;
+}
+/** The rough country of a request: Cloudflare's two-letter country header, or null (not there, "XX" for unknown, "T1" for Tor, or anything that is not two capital letters). */
+export function countryOf(req) {
+    const c = req.headers.get("CF-IPCountry");
+    return typeof c === "string" && /^[A-Z]{2}$/.test(c) && c !== "XX" && c !== "T1" ? c : null;
+}