@nano133/nanoterra 0.8.0 → 0.9.0

package/ai/SPEC.md

@@ -2,7 +2,8 @@
 
 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`) and the emotes (`/emotes`, with the wheel). Use only the parts the game needs. It has no network, wallet or Nano code. Read the package README first.
+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.
 
 ## 0. What the owner decides (ask)
 
@@ -12,11 +13,16 @@ looks ladder (`/looks`), held input that does not stick (`/input`), the friends
    in the game starter it is `"character": "nanoterra" | "own"` in `game.config.json` (nothing else reads it).
 3. The quality: `"high"` (toon body and ink outline, 2 draws) or `"low"` (no outline, 1 draw, for slow phones).
 4. How the game moves the character: speed in metres a second, gravity and jump. The package animates; it does not move the object.
-5. Does the game sell looks? If yes, the game is the seller (its own checkout); see step 7.
+5. Does the game sell looks? If yes, the game is the seller; see step 7 (the looks file), step 12 (the player's sign-in) and step 13 (the shop). Ask for the creator's own Nano address (it
+   receives every payment), and whether the game runs on a Cloudflare Worker with D1 (the starter's way) or another server with Firestore or its own database.
 6. The friends list (step 9): Nanoterra's (the default), the game's own, or none. It is the admin's `friends` setting; ask which one the game starts with.
 7. The options menu (step 10): which settings the game can really honour (a game with no music offers no Music slider), and whether the game opens it from its own
    pause menu or shows the kit's gear key.
 
+8. The player's sign-in (step 12), for a game with a server: which ways (a passkey and the three wallet apps by default), the game's DOMAIN for good (a
+   passkey belongs to one domain), the game's frozen passkey SCHEME (the owner approves its texts: they can never change), and whether the sheet offers the
+   spare key (yes by default; "no" for a game for small children).
+
 **Check:** the owner has named the server (yes or no), the source of the character and the quality.
 
 ## 1. Install
@@ -188,7 +194,62 @@ import "@nano133/nanoterra/emotes/style.css";
 the middle; a hold on the key and a slide onto a place plays it; Edit refuses a ninth with "Your wheel is full. Take one off first."; the wheel holds after a
 reload. A walk ends Dance; Clap goes on over the walk. On a keyboard: B opens it, 2 plays the second place, Escape closes it.
 
-## 12. Do not
+## 12. The player's sign-in (a game with a server)
+
+```sh
+npm install @nano133/nanoterra @nano133/signin
+```
+
+1. **The scheme, frozen.** Write it once in one file of the game, with the game's domain in its texts:
+   `export const SCHEME = { input: "<domain> player v1", salt: "<domain>", info: "<domain> player seed v1", versionByte: 1 }`. Add a test with two fixed vectors:
+   `assert.deepEqual(await schemeVector(SCHEME, "<64 hex>"), { seed, address })` (run it once to read the values, write them in, never change them). Never edit
+   the scheme after the first player: a new scheme is a new `versionByte` with new texts. Never take a default from anywhere.
+2. **The store.** D1: add `@nano133/nanoterra/player-signin/d1.sql` to the migrations (on the game starter it keeps every table and session and adds
+   `signin_once`) and `createD1PlayerSignin(env.DB)`. Firestore: `createFirestorePlayerSignin(db)` and a TTL policy on `deleteAt` for the three collections.
+   Another database: a store that passes `playerSigninStoreConformance`.
+3. **The handler.** `createPlayerSignin({ store, siteAddress, limit, visitor, personCheck })`; call `handle(request)` first for every request under `/api/`
+   (null: not its route). Give `limit` a limiter that counts for the whole game (D1), and `visitor` a keyed hash of the IP address. A game whose admin signs in
+   on the same paths (the starter) passes `sharedPaths: true`. Set `domain` once the game has its own domain.
+4. **The player.** Everything that needs the player reads `signin.player(request)` (the shop's and the friends' `player` hook): never an address from the
+   body, and never the admin's login. The game's code exchange makes its session with `signin.signIn(request, address, "nanoterra")`.
+5. **"Delete my data"** calls `signin.forget(player)` with the other stores' `forget`. A cron calls `signin.clean()`.
+6. **The sheet.** `mountPlayerSignin(document.body, { name, scheme: SCHEME, qr, personCheck, onSignedIn })` and the stylesheet; the account key and the
+   shop's "sign in first" call `open()`. On `*.workers.dev` the sheet offers no passkey (it would be lost at the move to the game's own
+   domain); give `mountAdmin` `playerPasskeys: true` so the admin says so. Do not write your own passkey or wallet code, and never store, log or send the seed.
+
+**Check:** on the game's real https address, with a phone (iOS 18 or a recent Android): Make a passkey, see "Keep a spare key", sign in, reload: still
+signed in; sign out, "Use my passkey": the same address. A desktop browser with no PRF shows the passkey last and its plain words. A wallet sign-in works only
+on a public https address (a wallet cannot reach localhost). The tests hold the scheme's vectors.
+
+## 13. The shop (only if the game sells looks)
+
+```ts
+import { createShop } from "@nano133/nanoterra/shop/worker";           // a Worker with D1; else createShopHandler from "@nano133/nanoterra/shop"
+import { mountShop } from "@nano133/nanoterra/shop/panel";
+import "@nano133/nanoterra/shop/style.css";
+```
+
+- The money goes straight from the player's wallet to the creator's address. The server holds **no key**: never add a seed, a private key or a send. The
+  shop reads the ledger and matches a unique, clean amount exactly. Do not copy the starter's `orders`, `match`, `sweep`, `price` or `nodes` files: install them.
+- D1: add `@nano133/nanoterra/shop/d1.sql` to the migrations (a game made from the starter has the tables already: no migration). Firestore:
+  `createFirestoreShop(db)`. Another database: write a `ShopStore` and pass `shopStoreConformance` (each case its own test, `SHOP_CASE_TIMEOUT_MS`).
+- `player(req)` reads the game's own PLAYER sign-in (never the admin's). The shop draws no sign-in: give the panel `signIn()`, which opens the game's
+  sign-in and answers true when a player is signed in.
+- Settings (a Worker): `RECEIVE_ADDRESS` (the creator's address), `TEST_MODE` (`"on"` until the owner says sell), `NODE_API_KEY` (a secret, optional),
+  `TURNSTILE_SITE_KEY` and the secret `TURNSTILE_SECRET` (optional, both). Secrets go in the platform's secret store, never in code or a log.
+- **Test mode stays on until the owner's own address is set AND test mode is off.** In test mode the pay sheet says "TEST MODE: DO NOT PAY", with no QR
+  code, no address and the wallet key off. Never show a pay screen to an address nobody holds the key for without that stamp.
+- Add the cron (`*/10 * * * *`) that calls `shop.scan()`, and give the admin `check: (at) => shop.scan(at)`.
+- Mount the panel with `onOwned(lookId)` (the game adds the look and wears it); `key: false` and `open()` when the game has its own Looks key.
+- Merge `SHOP_CSP` into the game's Content Security Policy with `mergeCsp`; never replace the game's policy.
+- "Delete my data" calls `store.forget(player, now)`; with `waitUntil`, ask the player to try again then.
+- Tests: the shop's money tests are the package's. The game's tests read the game's own looks file and test only the game's own routes and wiring.
+
+**Check:** with `TEST_MODE` on, Buy shows the stamp and no QR code, and the answer of `POST /api/orders` holds no `address` and no `uri`. With the owner's
+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
 
 - 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
@@ -197,3 +258,4 @@ reload. A walk ends Dance; Clap goes on over the walk. On a keyboard: B opens it
   thing gives `hideTail: true` and `hideWings: true`, so a tail or wings do not poke through it.
   The game loads the model and frees it; the character never does.
 - Do not use a look or a record for a game's rules, a score or a payment: it is display only.
+- Do not give a look on anything but a paid order (`"paid"`), and never give one on a sign-in or a ticket alone.

package/dist/admin/panel/dom.d.ts

@@ -1,6 +1,8 @@
 type Attrs = Record<string, string | number | boolean | undefined | ((e: Event) => void)>;
 type Child = Node | string | null | undefined | false;
 export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Attrs, ...children: Child[]): HTMLElementTagNameMap[K];
+/** Takes the keyboard focus out of `within` (to the page), so a game's own keys reach the game again. */
+export declare function releaseFocus(within: Element): void;
 /** "nano_1abc…wxyz" */
 export declare const shortAddress: (a: string) => string;
 export declare function copy(text: string, button: HTMLButtonElement): Promise<void>;

package/dist/admin/panel/dom.js

@@ -18,6 +18,12 @@ export function h(tag, attrs = {}, ...children) {
             el.append(c);
     return el;
 }
+/** Takes the keyboard focus out of `within` (to the page), so a game's own keys reach the game again. */
+export function releaseFocus(within) {
+    const now = document.activeElement;
+    if (now instanceof HTMLElement && within.contains(now))
+        now.blur();
+}
 /** "nano_1abc…wxyz" */
 export const shortAddress = (a) => `${a.slice(0, 10)}…${a.slice(-6)}`;
 export async function copy(text, button) {

package/dist/admin/panel/mount.d.ts

@@ -19,6 +19,9 @@ export type MountOptions = {
     repoHelp?: string;
     /** What the Sign-ins card says about what the game keeps and for how long ("30 days"). Default: only the time, the rough country and a short browser name. */
     loginsNote?: string;
+    /** The game offers its players a passkey (`@nano133/nanoterra/player-signin`): on a preview address (`*.workers.dev`) the banner says that passkeys turn
+     *  on with the game's own domain. */
+    playerPasskeys?: boolean;
     /** The `fetch` to use (default: the page's). */
     fetch?: typeof fetch;
 };

package/dist/admin/panel/mount.js

@@ -4,6 +4,7 @@
 // The page: a top bar (who is signed in, Live or Test mode, the light/dark theme key, Sign out), what is still off (one banner), four numbers (earned, open now, to send back, players;
 // each opens its list), then five tabs: Overview, Cosmetics (the Shelf), Orders, Players and Settings (the Game card, the sign-ins, the facts). Every tab is
 // made once; a new read of the summary fills them again and keeps the chosen tab, the Shelf's draft, a search and the Game card.
+import { PASSKEY_PREVIEW_NOTE, previewHost } from "../../player-signin/host.js";
 import { ApiError, createApi } from "./api.js";
 import { copyKey, h, plural, shortAddress } from "./dom.js";
 import { gameCard } from "./gameCard.js";
@@ -158,8 +159,9 @@ export function mountAdmin(root, options) {
             update(s) {
                 who.replaceChildren(h("span", { class: "who-label" }, "Signed in as"), s.address ? h("span", { class: "who-address" }, h("code", { title: s.address }, shortAddress(s.address)), copyKey(s.address, "Copy your address", icon("copy", 14))) : h("span", {}, "the game's owner"));
                 chips.replaceChildren(h("span", { class: `chip ${s.testMode ? "chip-warn" : "chip-ok"}`, title: s.testMode ? "Payments are not real" : "Payments are real" }, h("span", { class: "chip-dot", "aria-hidden": "true" }), s.testMode ? "Test mode" : "Live"), s.turnstile === undefined ? "" : h("span", { class: `chip ${s.turnstile ? "chip-ok" : "chip-warn"}` }, h("span", { class: "chip-dot", "aria-hidden": "true" }), s.turnstile ? "Bot check on" : "Bot check off"));
-                banner.hidden = !s.warnings.length;
-                banner.replaceChildren(h("div", { class: "banner-icon", "aria-hidden": "true" }, icon("alert", 20)), h("div", {}, h("h2", {}, "Check these"), h("ul", {}, ...s.warnings.map((w) => h("li", {}, w)))));
+                const notes = options.playerPasskeys && previewHost(location.hostname) ? [...s.warnings, PASSKEY_PREVIEW_NOTE] : s.warnings;
+                banner.hidden = !notes.length;
+                banner.replaceChildren(h("div", { class: "banner-icon", "aria-hidden": "true" }, icon("alert", 20)), h("div", {}, h("h2", {}, "Check these"), h("ul", {}, ...notes.map((w) => h("li", {}, w)))));
                 const ownedLooks = s.players.reduce((n, p) => n + p.looks.length, 0);
                 const late = s.totals.paidLate.count;
                 kpis.replaceChildren(kpi("earned", "coin", "Earned", `${s.totals.paid.xno} XNO`, `$${s.totals.paid.usd} · ${plural(s.totals.paid.count, "order")}`, () => go("orders", "paid")), kpi("open", "clock", "Open now", String(s.counts.open), `${s.counts.expired} expired`, () => go("orders", "open")), kpi("late", "back", "To send back", `${s.totals.paidLate.xno} XNO`, late ? `$${s.totals.paidLate.usd} · ${plural(late, "order")}` : "Nothing to send back", () => go("orders", "paid_late"), late > 0), kpi("players", "players", "Players", String(s.players.length), `${plural(ownedLooks, "look")} owned`, () => go("players")));

package/dist/emotes/panel/mount.d.ts

@@ -34,6 +34,11 @@ export type EmotesMountOptions = {
     theme?: "light" | "dark" | "device";
     /** Where the wheel is kept (default: the page's localStorage). null keeps it only for the life of the page. */
     storage?: Pick<Storage, "getItem" | "setItem"> | null;
+    /**
+     * Where the keyboard focus goes when the wheel closes. "game" (the default): out of the key and the wheel, to the page, so Space and the game's
+     * other keys reach the game again (a focused key would take Space and open the wheel again). "key": back to the key, for a page with no keys of its own.
+     */
+    focusAfterClose?: "game" | "key";
 };
 export type MountedEmotes = {
     open(): void;

package/dist/emotes/panel/mount.js

@@ -9,7 +9,7 @@
 //
 // The list is Nanoterra's (each id names one of EMOTES: its name and picture come from the kit), the game's own ({ id, label, icon }), or both. The
 // wheel only calls `onPlay(id)`: the game plays it (Nanoterra's on the kit's character: createEmotes(...).play, from "@nano133/nanoterra/emotes/player").
-import { h } from "../../admin/panel/dom.js";
+import { h, releaseFocus } from "../../admin/panel/dom.js";
 import { icon } from "../../admin/panel/icons.js";
 import { EMOTE_ICONS_URL } from "../icons.js";
 import { EMOTES, emoteOf, isEmote } from "../list.js";
@@ -242,8 +242,12 @@ export function mountEmotes(root, options) {
         layer.hidden = true;
         layer.dataset.open = "false";
         key.setAttribute("aria-expanded", "false");
-        if (focusKey && !key.hidden)
-            key.focus();
+        if (options.focusAfterClose === "key") {
+            if (focusKey && !key.hidden)
+                key.focus();
+        }
+        else
+            releaseFocus(wrap);
     }
     editKey.addEventListener("click", () => {
         edit = !edit;

package/dist/friends/panel/mount.d.ts

@@ -21,6 +21,11 @@ export type FriendsMountOptions = {
     fetch?: typeof fetch;
     /** Asks the player a yes or no question (default: a question in the panel, with a key for each answer; never a browser dialog). */
     confirm?: (question: string) => boolean | Promise<boolean>;
+    /**
+     * Where the keyboard focus goes when the panel closes. "game" (the default): out of the key and the panel, to the page, so Space and the game's
+     * other keys reach the game again (a focused key would take Space and open the panel again). "key": back to the key, for a page with no keys of its own.
+     */
+    focusAfterClose?: "game" | "key";
 };
 export type MountedFriends = {
     /** Sets where the player is (friends see it). Null: no place. */

package/dist/friends/panel/mount.js

@@ -11,7 +11,7 @@
 //
 // The panel is phone first: a sheet from the bottom on a phone held upright, from the side on a wide or sideways screen; every key is 44 px.
 import { ApiError, createApi } from "../../admin/panel/api.js";
-import { h } from "../../admin/panel/dom.js";
+import { h, releaseFocus } from "../../admin/panel/dom.js";
 import { icon } from "../../admin/panel/icons.js";
 import { readWindowMessage, toWindow, whereText, windowUrl } from "./window.js";
 export const FRIENDS_TIMING = { viewOpenMs: 20_000, viewClosedMs: 60_000, pulseMs: 45_000 };
@@ -69,7 +69,10 @@ export function mountFriends(root, options) {
         panel.dataset.open = "false";
         key.setAttribute("aria-expanded", "false");
         onClose();
-        key.focus();
+        if (options.focusAfterClose === "key")
+            key.focus();
+        else
+            releaseFocus(wrap);
     };
     key.addEventListener("click", () => (isOpen ? close() : open()));
     closeKey.addEventListener("click", close);

package/dist/options/panel/mount.d.ts

@@ -11,6 +11,11 @@ export type OptionsMountOptions = {
     onRangeDone?: (key: string, value: number) => void;
     /** Asks the player a yes or no question (default: a question in the panel, with a key for each answer; never a browser dialog). */
     confirm?: (question: string) => boolean | Promise<boolean>;
+    /**
+     * Where the keyboard focus goes when the panel closes. "game" (the default): out of the key and the panel, to the page, so Space and the game's
+     * other keys reach the game again (a focused key would take Space and open the panel again). "key": back to the key, for a page with no keys of its own.
+     */
+    focusAfterClose?: "game" | "key";
 };
 export type MountedOptions = {
     open(): void;

package/dist/options/panel/mount.js

@@ -11,7 +11,7 @@
 // "Reset to defaults" asks in the panel (a question and a key for each answer), never in a browser dialog. Escape answers the question first, then closes.
 // The panel is phone first: a sheet from the bottom on a phone held upright, from the right on a wide or sideways screen; every key is 44 px or more.
 // `key: false` draws no key, for a game that opens the panel from its own pause menu (`open()`).
-import { h } from "../../admin/panel/dom.js";
+import { h, releaseFocus } from "../../admin/panel/dom.js";
 import { icon } from "../../admin/panel/icons.js";
 import { keyLabel } from "../core.js";
 export const TAB_WORDS = { basic: "Basic", advanced: "Advanced" };
@@ -273,8 +273,10 @@ export function mountOptions(root, store, options = {}) {
         panel.dataset.open = scrim.dataset.open = "false";
         key?.setAttribute("aria-expanded", "false");
         options.onClose?.();
-        const back = key ?? (returnTo?.isConnected ? returnTo : null);
-        back?.focus();
+        if (options.focusAfterClose === "key")
+            (key ?? (returnTo?.isConnected ? returnTo : null))?.focus();
+        else
+            releaseFocus(wrap);
     };
     key?.addEventListener("click", () => (isOpen ? close() : open()));
     closeKey.addEventListener("click", close);

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

@@ -0,0 +1,10 @@
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { type PlayerSigninStore } 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 D1PlayerSigninTables = {
+    requests?: string;
+    sessions?: string;
+    once?: string;
+};
+export declare function createD1PlayerSignin(db: D1Like, tables?: D1PlayerSigninTables): PlayerSigninStore;

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

@@ -0,0 +1,108 @@
+// The player sign-in's store for a game on Cloudflare D1. The tables are in ./d1.sql (the package ships it: "@nano133/nanoterra/player-signin/d1.sql");
+// add it to the game's migrations. They are the game starter's own `signin_requests` and `sessions` (so a starter's data carries over: every
+// player stays signed in) and one more, `signin_once`.
+//
+//   import { createD1PlayerSignin } from "@nano133/nanoterra/player-signin/d1";
+//   const store = createD1PlayerSignin(env.DB);
+//
+// It reads and writes ONLY the player's rows (scope = 'play'): a game whose admin signs in through the same tables (the starter's scope 'admin')
+// keeps its admin 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).
+import { 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 createD1PlayerSignin(db, tables = {}) {
+    const T = { requests: tables.requests ?? "signin_requests", sessions: tables.sessions ?? "sessions", once: tables.once ?? "signin_once" };
+    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 WAYS) {
+        stores.set(way, {
+            async create(key, r) {
+                await db
+                    .prepare(`INSERT INTO ${T.requests} (id, rid, way, starter, status, expires_at, nonce, issued_at, label, scope) VALUES (?, ?, ?, ?, 'waiting', ?, ?, ?, ?, 'play')`)
+                    .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 = 'play'`).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 = 'play'`).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 = 'play'`).bind(account, key, way).run()) === 1;
+            },
+        });
+    }
+    const insertSession = (s, afterChange) => {
+        const cols = `INSERT INTO ${T.sessions} (id_hash, address, created_at, expires_at, via, scope)`;
+        return db.prepare(afterChange ? `${cols} SELECT ?, ?, ?, ?, ?, 'play' WHERE changes() = 1` : `${cols} VALUES (?, ?, ?, ?, ?, 'play')`).bind(s.idHash, s.address, s.createdAt, s.expiresAt, s.via);
+    };
+    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 done = await db.batch([
+                db.prepare(`UPDATE ${T.requests} SET delivered = 1 WHERE id = ? AND way = ? AND delivered = 0 AND status = 'signedin' AND scope = 'play'`).bind(key, way),
+                insertSession(session, true),
+            ]);
+            return changes(done[0]) === 1;
+        },
+        async createSession(session) {
+            await insertSession(session, false).run();
+        },
+        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 = 'play'`)
+                .bind(idHash, now)
+                .first();
+            return r ? { idHash: r.id_hash, address: r.address, createdAt: Number(r.created_at), expiresAt: Number(r.expires_at), via: r.via } : null;
+        },
+        async endSession(idHash) {
+            await db.prepare(`DELETE FROM ${T.sessions} WHERE id_hash = ? AND scope = 'play'`).bind(idHash).run();
+        },
+        async useOnce(key, ttlMs, address) {
+            const now = Date.now();
+            // A row past its time may be taken again (its signature's 5 minutes are long over); a live one may not.
+            const res = await db
+                .prepare(`INSERT INTO ${T.once} (key, address, until) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET address = excluded.address, until = excluded.until WHERE ${T.once}.until <= ?`)
+                .bind(key, address, now + ttlMs, now)
+                .run();
+            return changes(res) === 1;
+        },
+        async forget(address) {
+            const done = await db.batch([
+                db.prepare(`DELETE FROM ${T.sessions} WHERE address = ? AND scope = 'play'`).bind(address),
+                db.prepare(`DELETE FROM ${T.requests} WHERE account = ? AND scope = 'play'`).bind(address),
+                db.prepare(`DELETE FROM ${T.once} WHERE address = ?`).bind(address),
+            ]);
+            return done.reduce((n, r) => n + changes(r), 0);
+        },
+        async clean(now) {
+            await db.batch([
+                db.prepare(`DELETE FROM ${T.requests} WHERE expires_at < ? AND scope = 'play'`).bind(now - 2 * 3_600_000),
+                db.prepare(`DELETE FROM ${T.sessions} WHERE expires_at <= ? AND scope = 'play'`).bind(now),
+                db.prepare(`DELETE FROM ${T.once} WHERE until <= ?`).bind(now),
+            ]);
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+import { type PlayerSigninStore } from "../types.js";
+export type PlayerSigninDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface PlayerSigninDocRef {
+    get(): Promise<PlayerSigninDocSnap>;
+}
+export type PlayerSigninQuerySnap = {
+    docs: {
+        id: string;
+        ref: PlayerSigninDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface PlayerSigninQuery {
+    where(field: string, op: "==" | "<" | "<=", value: unknown): PlayerSigninQuery;
+    limit(n: number): PlayerSigninQuery;
+    get(): Promise<PlayerSigninQuerySnap>;
+}
+export interface PlayerSigninCollection extends PlayerSigninQuery {
+    doc(id: string): PlayerSigninDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface PlayerSigninTransaction {
+    get(ref: PlayerSigninDocRef): Promise<PlayerSigninDocSnap>;
+    set(ref: PlayerSigninDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: PlayerSigninDocRef): unknown;
+}
+export interface PlayerSigninBatch {
+    delete(ref: PlayerSigninDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestorePlayerSigninLike {
+    collection(name: string): PlayerSigninCollection;
+    runTransaction<T>(fn: (tx: PlayerSigninTransaction) => Promise<T>): Promise<T>;
+    batch(): PlayerSigninBatch;
+}
+export declare function createFirestorePlayerSignin(db: FirestorePlayerSigninLike, collections?: {
+    requests?: string;
+    sessions?: string;
+    once?: string;
+}): PlayerSigninStore;

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

@@ -0,0 +1,168 @@
+// The player 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 player's documents (scope "play").
+//
+//   import { createFirestorePlayerSignin } from "@nano133/nanoterra/player-signin/firestore";
+//   const store = createFirestorePlayerSignin(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: "play", deleteAt }
+//   sessions/{idHash}       { address, createdAt, expiresAt, via, scope: "play", deleteAt }
+//   signin_once/{key}       { address, until, 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 (Berry Wallet, Nautilus) or the SHA-256 of its nonce (NanChat); `{idHash}` the SHA-256 of the session's token. Every change that reads first is a
+// transaction. Indexes: Firestore's own single-field indexes are enough (`id`, `address`, `account`, `expiresAt`, `until`).
+import { 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);
+function requestOf(d, key, way) {
+    if (!d || d.scope !== "play" || 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 createFirestorePlayerSignin(db, collections = {}) {
+    const requestsCol = () => db.collection(collections.requests ?? "signin_requests");
+    const sessionsCol = () => db.collection(collections.sessions ?? "sessions");
+    const onceCol = () => db.collection(collections.once ?? "signin_once");
+    const sessionData = (s) => ({ address: s.address, createdAt: s.createdAt, expiresAt: s.expiresAt, via: s.via, scope: "play", deleteAt: new Date(s.expiresAt) });
+    const stores = new Map();
+    for (const way of 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: "play",
+                        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 createSession(session) {
+            const ref = sessionsCol().doc(session.idHash);
+            await db.runTransaction(async (tx) => {
+                if ((await tx.get(ref)).exists)
+                    throw new Error("a session with this id exists");
+                tx.set(ref, sessionData(session));
+            });
+        },
+        async session(idHash, now) {
+            const d = (await sessionsCol().doc(idHash).get()).data();
+            if (!d || d.scope !== "play" || 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: 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 === "play")
+                    tx.delete(ref);
+            });
+        },
+        async useOnce(key, ttlMs, address) {
+            const ref = onceCol().doc(key);
+            return db.runTransaction(async (tx) => {
+                const now = Date.now();
+                const d = (await tx.get(ref)).data();
+                if (d && (num(d.until) ?? Infinity) > now)
+                    return false;
+                tx.set(ref, { address, until: now + ttlMs, deleteAt: new Date(now + ttlMs) });
+                return true;
+            });
+        },
+        async forget(address) {
+            const sessions = (await sessionsCol().where("address", "==", address).get()).docs.filter((d) => d.data().scope === "play");
+            const requests = (await requestsCol().where("account", "==", address).get()).docs.filter((d) => d.data().scope === "play");
+            const once = (await onceCol().where("address", "==", address).get()).docs;
+            return deleteAll([...sessions, ...requests, ...once]);
+        },
+        async clean(now) {
+            const old = (await requestsCol().where("expiresAt", "<", now - 2 * 3_600_000).limit(BATCH).get()).docs.filter((d) => d.data().scope === "play");
+            const ended = (await sessionsCol().where("expiresAt", "<=", now).limit(BATCH).get()).docs.filter((d) => d.data().scope === "play");
+            const used = (await onceCol().where("until", "<=", now).limit(BATCH).get()).docs;
+            await deleteAll([...old, ...ended, ...used]);
+        },
+    };
+}

package/dist/player-signin/conformance.d.ts

@@ -0,0 +1,11 @@
+import type { PlayerSigninStore } from "./types.js";
+export type PlayerSigninHarness = {
+    store: PlayerSigninStore;
+    /** Every row the store keeps (requests, sessions, once-only keys) as one text. `forget` must leave none that holds the player's address. */
+    dump(): Promise<string>;
+};
+export type PlayerSigninConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+export declare function playerSigninStoreConformance(make: () => Promise<PlayerSigninHarness>): PlayerSigninConformanceCase[];