@nano133/nanoterra 0.8.1 → 0.9.3

package/src/player-signin/scheme.ts

@@ -0,0 +1,32 @@
+// The game's passkey SCHEME: the texts that turn a passkey's secret (its PRF output) into the player's Nano account. It is the game's own, and it is
+// FROZEN: a player's looks belong to the address these exact texts give.
+//
+//   PRF input = UTF-8 scheme.input
+//   seed      = HKDF-SHA-256(ikm = the PRF output, salt = UTF-8 scheme.salt, info = UTF-8 scheme.info, 32 bytes)
+//   account   = the seed as 64 hex characters, account 0
+//
+// Write it one time, in one file of the game, and test it with fixed vectors (`schemeVector`): a PRF output, its seed, its address. A change of one
+// character gives every player another account (and so no looks). A new scheme is a new `versionByte` with new texts, never an edit. The kit offers
+// no default on purpose: a default in a library could change under the game.
+
+import { seedFromPrf, type PasskeyScheme } from "@nano133/signin/passkey";
+import { purseAddress } from "@nano133/signin/purse";
+import { checkScheme } from "./scheme-check.js";
+
+export type { PasskeyScheme };
+export { checkScheme };
+
+const bytesOf = (prfHex: string) => {
+  if (!/^[0-9a-fA-F]{64}$/.test(prfHex)) throw new Error("a PRF output is 64 hex characters (32 bytes)");
+  return Uint8Array.from(prfHex.match(/../g)!.map((b) => parseInt(b, 16)));
+};
+
+/**
+ * One fixed vector of a scheme: the seed and the address that a PRF output gives. For the game's own test, which must never change:
+ *
+ *   assert.deepEqual(await schemeVector(SCHEME, "0102…1f20"), { seed: "A3D5…", address: "nano_14kj…" });
+ */
+export async function schemeVector(scheme: PasskeyScheme, prfHex: string): Promise<{ seed: string; address: string }> {
+  const seed = await seedFromPrf(bytesOf(prfHex), checkScheme(scheme));
+  return { seed, address: purseAddress(seed) };
+}

package/src/player-signin/types.ts

@@ -0,0 +1,103 @@
+// The PLAYER sign-in of a game: the types, the limits and the store contract. (The admin's sign-in is another thing: "@nano133/nanoterra/admin".)
+//
+// A player is a Nano address. Every way to sign in is a signature from a key the player holds, and the server holds no key:
+//   - a passkey purse: a Nano account made in the browser from the player's passkey (its PRF output), by the game's FROZEN scheme;
+//     the browser signs a short text that names the game, and the server checks the signature (no WebAuthn on the server);
+//   - Berry Wallet (nano-signin-v1), NanChat (nanauth) and Nautilus (nanoauth): the wallet app signs a request that the browser started.
+// The checks are @nano133/signin's. This file names no package: the stores and their adapters work without it.
+
+/** The wallet apps a player can sign in with, in the order the sheet shows them. */
+export const WAYS = ["berry", "nanchat", "nautilus"] as const;
+export type Way = (typeof WAYS)[number];
+
+/** How a session was made. "wallet": a wallet app's signature. "passkey": a signature by a key in the page (the passkey purse). "nanoterra": the game's own code exchange. */
+export type Via = "wallet" | "passkey" | "nanoterra";
+export const VIAS: readonly Via[] = ["wallet", "passkey", "nanoterra"];
+
+/** A wallet app's sign-in request, as a store keeps it. The same shape as @nano133/signin's `WalletRequest`. */
+export type SigninRequest = {
+  /** The browser's id for its checks. */
+  id: string;
+  /** The SHA-256 (hex) of the starter cookie of the browser that asked. */
+  starter: string;
+  status: "waiting" | "signedin";
+  /** When it stops taking a signature (ms). */
+  expiresAt: number;
+  /** Nautilus: the label the app shows and signs. */
+  label?: string;
+  /** Berry Wallet: the nonce and when it was issued (ms). */
+  nonce?: string;
+  issuedAt?: number;
+  /** The account that signed, once it is signed. */
+  account?: string;
+};
+
+/**
+ * The requests of ONE wallet app. The same methods as @nano133/signin's `RequestStore`, so the package's functions take it as it is. `key` is the
+ * request's id for Berry Wallet and Nautilus, and the SHA-256 of the nonce for NanChat (whose answer names only the nonce). `finish` is atomic:
+ * waiting → signed, once; false otherwise.
+ */
+export interface RequestStoreLike {
+  create(key: string, r: SigninRequest): Promise<void>;
+  get(key: string): Promise<SigninRequest | null>;
+  find(id: string): Promise<{ key: string; request: SigninRequest } | null>;
+  finish(key: string, account: string): Promise<boolean>;
+}
+
+/** A session as a store keeps it. `idHash` is the SHA-256 (hex) of the cookie's token: the token itself is never stored. */
+export type SessionRecord = { idHash: string; address: string; createdAt: number; expiresAt: number; via: Via };
+
+/** A session as the game reads it. `via` is "unknown" for a word the store holds that is none of VIAS (never read as a wallet). */
+export type PlayerSession = { address: string; createdAt: number; via: Via | "unknown" };
+
+/**
+ * The game's database for the player sign-in. An adapter reads and writes ONLY its three tables or collections (requests, sessions, once-only
+ * keys), and only the PLAYER's rows of them (a game whose admin shares the tables keeps its rows apart: the D1 adapter's `scope` column).
+ * Run `playerSigninStoreConformance` on a store you write yourself.
+ */
+export interface PlayerSigninStore {
+  /** The requests of one wallet app. */
+  requests(way: Way): RequestStoreLike;
+  /**
+   * Delivers a signed request to the browser that started it, ONCE, and writes its session in the same step: true when this call delivered it,
+   * false (and no session written) when it was delivered before, is not signed, or is not known.
+   */
+  deliver(way: Way, key: string, session: SessionRecord): Promise<boolean>;
+  createSession(session: SessionRecord): Promise<void>;
+  /** The session of a token's hash while it lasts (`expiresAt` > now), else null. */
+  session(idHash: string, now: number): Promise<SessionRecord | null>;
+  endSession(idHash: string): Promise<void>;
+  /** Records `key` and answers true; answers false when it is there already. `address` is kept on the row (for `forget`). The passkey route's replay guard. */
+  useOnce(key: string, ttlMs: number, address: string): Promise<boolean>;
+  /** A player's "Delete my data": every session, every signed request and every once-only row of `address`. Returns how many rows went. */
+  forget(address: string): Promise<number>;
+  /** Deletes what nobody needs any more: requests 2 hours after they ended, sessions that ended, once-only rows past their time. */
+  clean(now: number): Promise<void>;
+}
+
+/** The limits of the routes (calls per window). The two marked "hook" use the game's `limit`; the rest count in this copy's memory. */
+export const PLAYER_SIGNIN_LIMITS = {
+  /** A wallet sign-in start or a passkey sign-in, per visitor (hook). */
+  signin: { limit: 20, windowMs: 10 * 60_000 },
+  /** The browser's checks (every 2 s), per visitor (memory). */
+  poll: { limit: 90, windowMs: 60_000 },
+  /** Berry Wallet's GET and POST and Nautilus's answer, per IP address (memory): the wallet's own phone sends them. */
+  wallet: { limit: 30, windowMs: 60_000 },
+  /** NanChat's answers all come from its one relay server: the whole route (memory), the answers of the right shape (hook) and each nonce (hook). */
+  nanchatRoute: { limit: 120, windowMs: 60_000 },
+  nanchatAll: { limit: 600, windowMs: 10 * 60_000 },
+  nanchatNonce: { limit: 5, windowMs: 10 * 60_000 },
+  /** The biggest body the routes read. */
+  bodyMax: 8192,
+} as const;
+
+/** How long a player's session lasts (the game starter's 30 days). */
+export const SESSION_DAYS = 30;
+/** How long the starter cookie lives: a wallet's request must be answered within it. */
+export const STARTER_MAX_AGE_S = 30 * 60;
+
+/** A token, a starter value: 32 random bytes as 64 hex characters. */
+export const TOKEN_PATTERN = /^[0-9a-f]{64}$/;
+
+/** A store's word for `via`, as the game reads it. */
+export const viaOf = (v: unknown): Via | "unknown" => (VIAS.includes(v as Via) ? (v as Via) : "unknown");

package/src/shop/adapters/d1.sql

@@ -0,0 +1,52 @@
+-- The shop tables of "@nano133/nanoterra/shop/d1": the game starter's own (migrations/0001_init.sql), column for column. A new game adds this file to its
+-- migrations (for example migrations/0002_shop.sql) and runs `wrangler d1 migrations apply`. A game made from the starter has these tables already:
+-- it needs no migration (and IF NOT EXISTS makes this file a no-op there). The store reads and writes only the first three tables; `d1Limit` the fourth.
+-- Times are milliseconds since 1970 (Date.now()). Amounts are raw, as text (1 XNO = 10^30 raw).
+
+-- One row per order (a player asked to buy a look).
+CREATE TABLE IF NOT EXISTS orders (
+  id TEXT PRIMARY KEY,               -- 24 hex characters
+  player TEXT NOT NULL,              -- the signed-in player's id (the starter's: the nano_ address)
+  look_id TEXT NOT NULL,
+  usd TEXT NOT NULL,                 -- the price in US dollars when the order was made: "0.25"
+  rate REAL NOT NULL,                -- dollars per XNO that turned the price into XNO
+  amount TEXT NOT NULL,              -- the exact amount to pay, a clean amount (at most 4 decimals of XNO)
+  -- The reservation: equal to `amount` while a payment of it may still be matched to this order, NULL
+  -- after. UNIQUE, so no two held orders ever ask for the same amount (NULLs never collide).
+  amount_lock TEXT UNIQUE,
+  status TEXT NOT NULL DEFAULT 'open', -- open | paid | expired | paid_late
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL,       -- the order takes a payment until then
+  hold_until INTEGER NOT NULL,       -- the amount stays reserved until then (late payments are still seen)
+  hash TEXT UNIQUE,                  -- the paying send block: one payment pays one order, once
+  payer TEXT,                        -- the account that sent it
+  paid_at INTEGER,                   -- when the node first saw that send
+  visitor TEXT                       -- a keyed hash of the buyer's IP address (limits, never the address)
+);
+CREATE INDEX IF NOT EXISTS orders_by_status ON orders (status, expires_at);
+CREATE INDEX IF NOT EXISTS orders_by_player ON orders (player, look_id, status);
+
+-- The looks each player owns. One row per player and look: a second grant changes nothing.
+CREATE TABLE IF NOT EXISTS owned (
+  player TEXT NOT NULL,
+  look_id TEXT NOT NULL,
+  order_id TEXT NOT NULL,
+  granted_at INTEGER NOT NULL,
+  PRIMARY KEY (player, look_id)
+);
+
+-- Small shared values. The shop keeps "rate" (the last good XNO price, JSON { usd, sources }), "scan" (the time of the last payment scan) and "salt" (`visitorKey`).
+-- The admin keeps its settings here too ("setting:character" and the rest).
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  at INTEGER NOT NULL
+);
+
+-- Rate-limit counters (`d1Limit`): one row per key and time window. The game deletes old windows (the starter's cron: those older than a day).
+CREATE TABLE IF NOT EXISTS hits (
+  key TEXT NOT NULL,
+  win INTEGER NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (key, win)
+);

package/src/shop/adapters/d1.ts

@@ -0,0 +1,245 @@
+// The shop store for a game on Cloudflare D1, on the game starter's own tables (migrations/0001_init.sql): `orders`, `owned` and `meta`. The package
+// ships the same tables as "@nano133/nanoterra/shop/d1.sql" (CREATE ... IF NOT EXISTS) for a new game; the starter has them already, so it switches with
+// no migration and keeps every order and owned look.
+//
+//   import { createD1Shop } from "@nano133/nanoterra/shop/d1";
+//   const store = createD1Shop(env.DB);
+//
+// It reads and writes ONLY those three tables (in `meta`, only the keys "rate" and "scan"). The table names can be changed (`tables`), but the admin's
+// D1 store ("@nano133/nanoterra/admin/d1") reads the starter's names: keep them unless the game has its own admin store.
+//
+// The money rules are in the statements themselves: `amount_lock` and `hash` are UNIQUE (no two held orders ask for one amount, one payment pays one
+// order), the payment and the grant are ONE batch (a D1 transaction), and the scan's claim is one upsert that only one caller in a gap can win.
+
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { parseRate } from "../../admin/summary.js";
+import { paidStatus } from "../orders.js";
+import { FORGOTTEN, type ForgetResult, type OrderStatus, type Settled, type ShopOrder, type ShopStore } from "../store.js";
+
+export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
+
+/** The table names. The defaults are the game starter's. (`hits` is for `d1Limit` only.) */
+export type ShopTables = { orders?: string; owned?: string; meta?: string; hits?: string };
+
+type Row = {
+  id: string;
+  player: string;
+  look_id: string;
+  usd: string;
+  rate: number;
+  amount: string;
+  amount_lock: string | null;
+  status: string;
+  created_at: number;
+  expires_at: number;
+  hold_until: number;
+  hash: string | null;
+  payer: string | null;
+  paid_at: number | null;
+  visitor: string | null;
+};
+
+const STATUSES: readonly OrderStatus[] = ["open", "paid", "expired", "paid_late"];
+
+const orderOf = (r: Row): ShopOrder => ({
+  id: r.id,
+  player: r.player,
+  lookId: r.look_id,
+  usd: r.usd,
+  rate: Number(r.rate),
+  amount: r.amount,
+  amountLock: r.amount_lock ?? null,
+  status: (STATUSES as readonly string[]).includes(r.status) ? (r.status as OrderStatus) : "expired",
+  createdAt: Number(r.created_at),
+  expiresAt: Number(r.expires_at),
+  holdUntil: Number(r.hold_until),
+  hash: r.hash ?? null,
+  payer: r.payer ?? null,
+  paidAt: r.paid_at === null || r.paid_at === undefined ? null : Number(r.paid_at),
+  visitor: r.visitor ?? null,
+});
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const changes = (res: unknown): number => Number((res as { meta?: { changes?: number } } | undefined)?.meta?.changes ?? 0);
+const isUnique = (e: unknown) => /UNIQUE/i.test(String((e as Error)?.message ?? e));
+/** D1 takes at most 100 bound values in one statement. */
+const CHUNK = 90;
+
+const tableName = (v: string | undefined, fallback: string): string => {
+  const name = v ?? fallback;
+  if (!NAME.test(name)) throw new Error(`the table name "${name}" must be plain (letters, digits and _)`);
+  return name;
+};
+
+async function sha256Hex(text: string): Promise<string> {
+  const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * True while `key` has made at most `limit` calls in this fixed window, counted in D1 (the table `hits`: one count for the whole game, every location).
+ * The game starter's `d1Limit`. Old windows stay until the game deletes them (the starter's cron deletes those older than a day).
+ */
+export async function d1Limit(db: D1Like, key: string, limit: number, windowMs: number, now = Date.now(), tables: Pick<ShopTables, "hits"> = {}): Promise<boolean> {
+  const hits = tableName(tables.hits, "hits");
+  const win = Math.floor(now / windowMs);
+  const row = await db.prepare(`INSERT INTO ${hits} (key, win, count) VALUES (?, ?, 1) ON CONFLICT (key, win) DO UPDATE SET count = count + 1 RETURNING count`).bind(key, win).first<{ count: number }>();
+  return Number(row?.count ?? 1) <= limit;
+}
+
+/** The visitor's IP address as Cloudflare saw it (CF-Connecting-IP); an IPv6 address by its /64 (one home network). "local" when there is none. */
+export function visitorIp(req: Request): string {
+  const ip = req.headers.get("CF-Connecting-IP") ?? "local";
+  return ip.includes(":") ? ip.split(":").slice(0, 4).join(":") + "::/64" : ip;
+}
+
+/**
+ * The visitor's key: a hash of a random salt (made once per game and kept in `meta` as "salt") and the IP address, never the address itself. The game
+ * starter's `visitorKey`: the same salt row, so the keys stay the same after a switch.
+ */
+export async function visitorKey(db: D1Like, req: Request, tables: Pick<ShopTables, "meta"> = {}): Promise<string> {
+  const meta = tableName(tables.meta, "meta");
+  let row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first<{ value: string }>();
+  if (!row) {
+    const fresh = Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (x) => x.toString(16).padStart(2, "0")).join("");
+    await db.prepare(`INSERT OR IGNORE INTO ${meta} (key, value, at) VALUES ('salt', ?, ?)`).bind(fresh, Date.now()).run();
+    row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first<{ value: string }>();
+  }
+  return (await sha256Hex(`${row!.value}|${visitorIp(req)}`)).slice(0, 32);
+}
+
+export function createD1Shop(db: D1Like, options: { tables?: ShopTables } = {}): ShopStore {
+  const T = { orders: tableName(options.tables?.orders, "orders"), owned: tableName(options.tables?.owned, "owned"), meta: tableName(options.tables?.meta, "meta") };
+  const COLS = "id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, hash, payer, paid_at, visitor";
+
+  async function inChunks(sql: (marks: string) => string, values: readonly string[], col: string): Promise<Set<string>> {
+    const out = new Set<string>();
+    for (let i = 0; i < values.length; i += CHUNK) {
+      const part = values.slice(i, i + CHUNK);
+      const rows = (await db.prepare(sql(part.map(() => "?").join(", "))).bind(...part).all<Record<string, string>>()).results;
+      for (const r of rows) out.add(r[col]);
+    }
+    return out;
+  }
+
+  const tidy = async (now: number) => {
+    await db.batch([
+      db.prepare(`UPDATE ${T.orders} SET status = 'expired' WHERE status = 'open' AND expires_at < ?`).bind(now),
+      db.prepare(`UPDATE ${T.orders} SET amount_lock = NULL WHERE amount_lock IS NOT NULL AND hold_until < ?`).bind(now),
+    ]);
+  };
+
+  const waiting = async (player: string) =>
+    db.prepare(`SELECT COUNT(*) AS n, MAX(hold_until) AS until FROM ${T.orders} WHERE player = ? AND amount_lock IS NOT NULL`).bind(player).first<{ n: number; until: number | null }>();
+
+  return {
+    tidy,
+
+    heldAmounts: (amounts) => inChunks((m) => `SELECT amount_lock FROM ${T.orders} WHERE amount_lock IN (${m})`, amounts, "amount_lock"),
+
+    async insert(o) {
+      try {
+        await db
+          .prepare(`INSERT INTO ${T.orders} (id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, visitor) VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?)`)
+          .bind(o.id, o.player, o.lookId, o.usd, o.rate, o.amount, o.amount, o.createdAt, o.expiresAt, o.holdUntil, o.visitor)
+          .run();
+        return true;
+      } catch (e) {
+        // Another order took this amount since the read. Any other failure stops.
+        if (isUnique(e)) return false;
+        throw e;
+      }
+    },
+
+    async order(id) {
+      const r = await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE id = ?`).bind(id).first<Row>();
+      return r ? orderOf(r) : null;
+    },
+
+    async openOrder(player, lookId, until) {
+      const r = await db
+        .prepare(`SELECT ${COLS} FROM ${T.orders} WHERE player = ? AND look_id = ? AND status = 'open' AND expires_at > ? ORDER BY created_at DESC LIMIT 1`)
+        .bind(player, lookId, until)
+        .first<Row>();
+      return r ? orderOf(r) : null;
+    },
+
+    async countOpen(player, now) {
+      const r = await db.prepare(`SELECT COUNT(*) AS n FROM ${T.orders} WHERE player = ? AND status = 'open' AND expires_at > ?`).bind(player, now).first<{ n: number }>();
+      return Number(r?.n ?? 0);
+    },
+
+    async owns(player, lookId) {
+      return Boolean(await db.prepare(`SELECT 1 AS one FROM ${T.owned} WHERE player = ? AND look_id = ?`).bind(player, lookId).first());
+    },
+
+    async owned(player) {
+      return (await db.prepare(`SELECT look_id FROM ${T.owned} WHERE player = ? ORDER BY granted_at, look_id`).bind(player).all<{ look_id: string }>()).results.map((r) => r.look_id);
+    },
+
+    async held() {
+      return (await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE amount_lock IS NOT NULL`).all<Row>()).results.map(orderOf);
+    },
+
+    usedHashes: (hashes) => inChunks((m) => `SELECT hash FROM ${T.orders} WHERE hash IN (${m})`, hashes, "hash"),
+
+    async settle(order, pay, now): Promise<Settled> {
+      const status = paidStatus(order, pay.seenMs);
+      try {
+        const [update] = await db.batch([
+          db
+            .prepare(`UPDATE ${T.orders} SET status = ?, hash = ?, payer = ?, paid_at = ?, amount_lock = NULL WHERE id = ? AND status IN ('open', 'expired') AND amount_lock IS NOT NULL`)
+            .bind(status, pay.hash, pay.payer, pay.seenMs, order.id),
+          db
+            .prepare(`INSERT OR IGNORE INTO ${T.owned} (player, look_id, order_id, granted_at) SELECT player, look_id, id, ? FROM ${T.orders} WHERE id = ? AND status = 'paid' AND hash = ?`)
+            .bind(now, order.id, pay.hash),
+        ]);
+        return changes(update) === 1 ? status : "taken";
+      } catch (e) {
+        if (isUnique(e)) return "used";
+        throw e;
+      }
+    },
+
+    async claimScan(now, gapMs) {
+      const r = await db
+        .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('scan', '', ?) ON CONFLICT (key) DO UPDATE SET at = excluded.at WHERE ${T.meta}.at <= ?`)
+        .bind(now, now - gapMs)
+        .run();
+      return changes(r) === 1;
+    },
+
+    async readRate() {
+      const r = await db.prepare(`SELECT value, at FROM ${T.meta} WHERE key = 'rate'`).first<{ value: string; at: number }>();
+      return r ? parseRate(r.value, Number(r.at)) : null;
+    },
+
+    async saveRate(rate) {
+      await db
+        .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('rate', ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, at = excluded.at`)
+        .bind(JSON.stringify({ usd: rate.usd, sources: rate.sources }), rate.at)
+        .run();
+    },
+
+    async forget(player, now): Promise<ForgetResult> {
+      await tidy(now);
+      const w = await waiting(player);
+      if (Number(w?.n ?? 0) > 0) return { deleted: 0, kept: 0, waitUntil: Number(w!.until) };
+      // One batch, and each statement holds the money gate again: an order made meanwhile stops every one of them.
+      const gate = `NOT EXISTS (SELECT 1 FROM ${T.orders} WHERE player = ?1 AND amount_lock IS NOT NULL)`;
+      const done = await db.batch([
+        db.prepare(`DELETE FROM ${T.owned} WHERE player = ?1 AND ${gate}`).bind(player),
+        db.prepare(`DELETE FROM ${T.orders} WHERE player = ?1 AND hash IS NULL AND amount_lock IS NULL AND ${gate}`).bind(player),
+        // A paid order keeps no payer; a paid-late one keeps it: the creator sends that payment back by hand.
+        db.prepare(`UPDATE ${T.orders} SET payer = ?2 WHERE payer = ?1 AND status = 'paid' AND ${gate}`).bind(player, FORGOTTEN),
+        db.prepare(`UPDATE ${T.orders} SET player = ?2, visitor = NULL WHERE player = ?1 AND hash IS NOT NULL AND ${gate}`).bind(player, FORGOTTEN),
+      ]);
+      const [owned, orders, , kept] = done.map(changes);
+      if (owned + orders + kept === 0) {
+        const again = await waiting(player);
+        if (Number(again?.n ?? 0) > 0) return { deleted: 0, kept: 0, waitUntil: Number(again!.until) };
+      }
+      return { deleted: owned + orders, kept, waitUntil: null };
+    },
+  };
+}