@nano133/nanoterra 0.1.0 → 0.2.0

package/src/admin/guard.ts

@@ -0,0 +1,86 @@
+// The admin guard: who may open a game's /admin. ONE pure function: no cookie, no database, no clock of its own. The game reads its own admin
+// session and passes it in; the answer is "yes" or a refusal with a status and a reason.
+//
+// DO NOT LOOSEN THIS. It is the game starter's `adminGuard` (src/worker/admin.ts), with the same five checks in the same order, and it may only
+// refuse MORE than the starter does, never less (a test runs both over a grid of inputs and proves it). Deny by default: anything this function
+// does not understand is a refusal, and a fault inside it is a refusal too.
+
+/** An admin login a game has found for this request: the address that signed, when the login was made (ms), and how it was made. */
+export type AdminSession = {
+  address: string;
+  createdAt: number;
+  /** "wallet" is a signature made with the address's key. Anything else (a sign-in from Nanoterra names an address but proves no key) never opens /admin. */
+  via: string;
+};
+
+export type AdminAccessInput = {
+  /** The game's own address, in the form "nano_" and 60 characters, lowercase. A host passes null when none is set (or the example address is). */
+  owner: string | null | undefined;
+  /** The admin login of this request, or null when there is none. It must be the ADMIN login: a login made for the game's players is not one. */
+  session: AdminSession | null | undefined;
+  /** The time now, in ms. */
+  now: number;
+  /** How old an admin login may be, in ms. At most one day: a bigger number is cut to one day, never allowed. */
+  maxAgeMs?: number;
+};
+
+/** Why a visitor was refused: the status to send and a word a page can act on. */
+export type AdminRefusal = {
+  ok: false;
+  status: 401 | 403;
+  error: string;
+  /** "no_address": the game has no real owner address yet. "nanoterra": a Nanoterra sign-in names an address but proves no key. "other_address": a wallet that is not the owner's. "misconfigured": the host passed a value the guard cannot trust. */
+  reason?: "no_address" | "nanoterra" | "other_address" | "misconfigured";
+  /** For "other_address": the address that is signed in (the page says "you are signed in as ..."). */
+  signedInAs?: string;
+};
+export type AdminAccess = { ok: true } | AdminRefusal;
+
+/** An admin login counts for one day; then the owner signs in again. */
+export const ADMIN_SESSION_MS = 24 * 60 * 60_000;
+/** A login made in the future by this much or more is not believed (clocks of two servers differ by seconds, not by minutes). */
+export const CLOCK_SKEW_MS = 5 * 60_000;
+
+/** A Nano address as a page writes it: "nano_", then 60 characters of the Nano alphabet, the first one a 1 or a 3. The guard checks the shape; the host checks the checksum when it reads its setting. */
+export const OWNER_PATTERN = /^nano_[13][13-9a-km-uw-z]{59}$/;
+
+const refuse = (status: 401 | 403, error: string, extra: Partial<AdminRefusal> = {}): AdminRefusal => ({ ok: false, status, error, ...extra });
+const misconfigured = (): AdminRefusal => refuse(403, "The admin page is not set up correctly. Nobody can open it until it is.", { reason: "misconfigured" });
+
+/** `ok: true` only when the request may read and change the admin data. */
+export function adminAccess(input: AdminAccessInput): AdminAccess {
+  try {
+    return decide(input);
+  } catch {
+    // A getter that throws, a Proxy, anything odd: no.
+    return misconfigured();
+  }
+}
+
+function decide(input: AdminAccessInput): AdminAccess {
+  const { owner, session, now, maxAgeMs } = input;
+  if (typeof now !== "number" || !Number.isFinite(now)) return misconfigured();
+  let max = ADMIN_SESSION_MS;
+  if (maxAgeMs !== undefined) {
+    // A limit the host set must be a real, positive number. A wrong one is a refusal, not the default: the host meant something shorter.
+    if (typeof maxAgeMs !== "number" || !Number.isFinite(maxAgeMs) || maxAgeMs <= 0) return misconfigured();
+    max = Math.min(maxAgeMs, ADMIN_SESSION_MS);
+  }
+
+  // 1. The game has a real owner address.
+  if (typeof owner !== "string" || !OWNER_PATTERN.test(owner)) {
+    return refuse(403, "Set the game's own Nano address first. Only that address can open this page.", { reason: "no_address" });
+  }
+  // 2. There is an admin login.
+  if (!session || typeof session !== "object") return refuse(401, "Sign in with your Nano address.");
+  const { address, createdAt, via } = session;
+  if (typeof address !== "string" || typeof via !== "string" || typeof createdAt !== "number") return refuse(401, "Sign in with your Nano address.");
+  // 3. It was made with a wallet signature. A sign-in from Nanoterra names an address but proves no key.
+  if (via !== "wallet") return refuse(403, "Sign in with your Nano wallet to open this page.", { reason: "nanoterra" });
+  // 4. It is the owner's address (the same text, no other form).
+  if (address !== owner) return refuse(403, "Only the game's own address can open this page.", { reason: "other_address", signedInAs: address });
+  // 5. It is not older than the limit (one day at most), and not from the future.
+  const age = now - createdAt;
+  if (!(age >= -CLOCK_SKEW_MS && age <= max)) return refuse(401, "Sign in again: an admin sign-in counts for one day.");
+  return { ok: true };
+}

package/src/admin/handler.ts

@@ -0,0 +1,200 @@
+// The admin handler: the routes of /admin on the Web `Request` and `Response` types, so it fits a Worker, Firebase Functions and Node.
+//
+//   GET  {base}/summary   the numbers: status, orders, the looks that players own
+//   GET  {base}/game      the two switches
+//   POST {base}/game      a press: { character } or { signin } (only the two known words)
+//   POST {base}/check     the payment check, when the game gives one
+//
+// EVERY request under the base goes through `adminAccess` first, before the route is even looked up: a visitor who is not the owner gets 401 or 403
+// for any path, a real one or not, and learns nothing about the routes. The handler sets no CORS header. A POST must come from the game's own page.
+
+import { adminAccess, type AdminAccess, type AdminSession } from "./guard.js";
+import { fail, foreignOrigin, json, memoryLimiter, readLimited, sameOrigin } from "./http.js";
+import { ADMIN_LOGINS_SHOWN, type AdminLogin, type AdminOrder, type AdminPlayer, type AdminStatus, type AdminStore, type AdminSummary, type StoreSummary } from "./store.js";
+import { mergeSettings, parsePatch, type GameSettings, type GameState } from "./switches.js";
+
+export type AdminRoute = { method: "GET" | "POST"; path: string };
+
+export type AdminHandlerOptions = {
+  /** The game's database. */
+  store: AdminStore;
+  /** What a switch is while /admin has not set it: the game's own words (game.config.json in the starter). */
+  defaults: GameSettings;
+  /** The game's own address ("nano_...", lowercase, its checksum already checked by the host), or null when none is set. */
+  owner: string | null;
+  /** The admin login of this request, or null. It reads the ADMIN cookie only (a login made for the game's players is not one). */
+  session: (req: Request, now: number) => Promise<AdminSession | null>;
+  /** The Status card: what only the game knows. It gets the numbers of the store too, for a warning that depends on them ("2 payments came late"). Default: the owner's address and nothing else. */
+  status?: (now: number, summary: StoreSummary) => Promise<AdminStatus> | AdminStatus;
+  /** What a look is called, for the orders. Default: its id. */
+  lookName?: (id: string) => string | undefined;
+  /** The payment check (POST check). Its answer is sent as `scan`. With none given, the route does not exist. */
+  check?: (now: number) => Promise<unknown>;
+  /** Where the routes are. Default "/api/admin". */
+  basePath?: string;
+  /** How old an admin login may be, in ms: one day at most (a bigger number is cut to one day). */
+  maxAgeMs?: number;
+  /** A limiter for the writes: false means "too many". Default: a fixed window in memory, one bucket for the whole admin (only the owner gets this far). */
+  limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+  /** The time now in ms. Default Date.now. */
+  now?: () => number;
+  /** Told about a fault in the store or in a callback. The visitor gets a plain 500 and never sees the fault. */
+  onError?: (e: unknown) => void;
+};
+
+export type AdminHandler = {
+  /** Every route, so that a test can walk them (see "@nano133/nanoterra/admin/conformance"). */
+  routes: readonly AdminRoute[];
+  basePath: string;
+  /** The answer for a request under the base path, or null when the request is not for the admin (the game goes on with its own routes). */
+  handle(req: Request): Promise<Response | null>;
+};
+
+/** A browser name as the list shows it: words ("Chrome on macOS"). Anything else a store gives (a raw browser text, an address) is shown as "Unknown browser". */
+const BROWSER_NAME = /^[A-Za-z][A-Za-z ]{0,39}$/;
+
+/** The limits of the writes. */
+export const ADMIN_LIMITS = {
+  /** A press on a switch. */
+  game: { limit: 30, windowMs: 60_000 },
+  /** A payment check. */
+  check: { limit: 20, windowMs: 60_000 },
+  /** "Sign out everywhere". */
+  signOutAll: { limit: 5, windowMs: 60_000 },
+  /** The biggest body a press can have. */
+  gameBodyMax: 512,
+} as const;
+
+/**
+ * Whether a request path could be read as under the admin base by anything: in any case, with backslashes for slashes, doubled slashes, and percent codes (decoded again and
+ * again, a code at a time, so one bad code does not stop the rest). Used ONLY to decide that a request is the admin's, so that the guard answers it. A path that is still
+ * changing after ten decodings is not an honest path: it is the admin's too (the guard refuses it). The route match later is exact on the parsed path.
+ */
+function readsAsBase(raw: string, base: string): boolean {
+  let p = raw;
+  for (let i = 0; i < 10; i++) {
+    const plain = p.toLowerCase().replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+    if (plain === base || plain.startsWith(`${base}/`)) return true;
+    const decoded = p.replace(/%([0-9a-f]{2})/gi, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+    if (decoded === p) return false;
+    p = decoded;
+  }
+  return true;
+}
+
+/** The default limiter lives at module level: a Worker makes a handler for each request, and a limiter made inside it would forget every press. */
+const sharedLimit = memoryLimiter();
+
+export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
+  const base = (options.basePath ?? "/api/admin").toLowerCase();
+  if (!base.startsWith("/") || base.length < 2 || base.endsWith("/")) throw new Error('basePath must start with "/" and not end with "/", like "/api/admin"');
+  const now = options.now ?? (() => Date.now());
+  const limit = options.limit ?? sharedLimit;
+  /** The key of a limit: the base path and the owner come first, so two games in one process never share a count. */
+  const lkey = (name: string) => `${base}|${options.owner ?? ""}|${name}`;
+  const routes: AdminRoute[] = [
+    { method: "GET", path: `${base}/summary` },
+    { method: "GET", path: `${base}/game` },
+    { method: "POST", path: `${base}/game` },
+    ...(options.check ? [{ method: "POST" as const, path: `${base}/check` }] : []),
+    ...(options.store.signOutEverywhere ? [{ method: "POST" as const, path: `${base}/signout-all` }] : []),
+  ];
+
+  const settings = async (): Promise<GameState> => mergeSettings(await options.store.readSettings(), options.defaults);
+
+  async function summary(at: number): Promise<AdminSummary> {
+    const s = await options.store.summary(at);
+    const status = options.status ? await options.status(at, s) : { address: options.owner, testMode: false, warnings: [] as string[] };
+    const name = (id: string) => options.lookName?.(id) ?? id;
+    const orders: AdminOrder[] = s.orders.map((o) => ({ ...o, look: name(o.lookId) }));
+    const players: AdminPlayer[] = s.players.map((p) => ({ player: p.player, looks: p.looks.map((l) => ({ id: l.id, name: name(l.id), at: l.at })) }));
+    const out: AdminSummary = { ...status, counts: s.counts, totals: s.totals, rate: s.rate, orders, players, canCheck: Boolean(options.check) };
+    if (options.store.recentLogins) {
+      // Only the three things of a sign-in go out, whatever the store gave (a store that returns an address or a browser text by mistake does not show it).
+      const rows = await options.store.recentLogins(ADMIN_LOGINS_SHOWN);
+      out.logins = rows.slice(0, ADMIN_LOGINS_SHOWN).map((l): AdminLogin => ({ at: Number(l.at), country: typeof l.country === "string" && /^[A-Z]{2}$/.test(l.country) ? l.country : null, browser: typeof l.browser === "string" && BROWSER_NAME.test(l.browser) ? l.browser : "Unknown browser" }));
+    }
+    if (options.store.signOutEverywhere) out.canSignOutEverywhere = true;
+    return out;
+  }
+
+  /** Tells the game about a fault. A fault in the game's own `onError` is not the visitor's business: it is swallowed. */
+  const report = (e: unknown): void => {
+    try {
+      options.onError?.(e);
+    } catch {
+      // nothing more can be done
+    }
+  };
+
+  async function handle(req: Request): Promise<Response | null> {
+    const url = new URL(req.url);
+    if (!readsAsBase(url.pathname, base)) return null;
+    try {
+      const at = now();
+      // 1. The guard, before anything else.
+      let session: AdminSession | null;
+      try {
+        session = await options.session(req, at);
+      } catch (e) {
+        report(e);
+        // The game could not read its sessions: nobody is let in.
+        return fail(503, "The game's server could not check your sign-in. Try again.");
+      }
+      const access: AdminAccess = adminAccess({ owner: options.owner, session, now: at, maxAgeMs: options.maxAgeMs });
+      if (!access.ok) {
+        const { status, error, reason, signedInAs } = access;
+        return fail(status, error, { ...(reason ? { reason } : {}), ...(signedInAs ? { signedInAs } : {}) });
+      }
+      // 2. The route: an exact path (as the handler lists it), else 404 or 405.
+      const exact = url.pathname;
+      const known = routes.filter((r) => r.path === exact);
+      if (!known.length) return fail(404, "No such admin page.");
+      const route = known.find((r) => r.method === req.method);
+      if (!route) return fail(405, "Not allowed.", {}, { Allow: known.map((r) => r.method).join(", ") });
+      // 3. The call must come from the game's own page: a write must say so (Origin, or Sec-Fetch-Site same-origin); a read must not say it comes from another page.
+      if (route.method === "POST" ? !sameOrigin(req) : foreignOrigin(req)) return fail(403, "This call must come from the game's own page.");
+
+      if (route.method === "GET" && route.path === `${base}/summary`) return json(await summary(at));
+      if (route.method === "GET") return json(await settings());
+      if (route.path === `${base}/game`) {
+        if (!(await limit(lkey("admin-game"), ADMIN_LIMITS.game.limit, ADMIN_LIMITS.game.windowMs, at))) return fail(429, "Too many presses. Wait a minute.");
+        const text = await readLimited(req, ADMIN_LIMITS.gameBodyMax);
+        if (text === null) return fail(413, "That is too much to send.");
+        let body: unknown;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          return fail(400, "Send JSON.");
+        }
+        const parsed = parsePatch(body);
+        if (!parsed.ok) return fail(400, parsed.error);
+        await options.store.saveSettings(parsed.patch, at);
+        return json(await settings());
+      }
+      if (route.path === `${base}/signout-all`) {
+        if (!(await limit(lkey("admin-signout-all"), ADMIN_LIMITS.signOutAll.limit, ADMIN_LIMITS.signOutAll.windowMs, at))) return fail(429, "Too many tries. Wait a minute.");
+        const n = await options.store.signOutEverywhere!();
+        return json({ ok: true, signedOut: n });
+      }
+      // POST check
+      if (!(await limit(lkey("admin-check"), ADMIN_LIMITS.check.limit, ADMIN_LIMITS.check.windowMs, at))) return fail(429, "Too many checks. Wait a minute.");
+      const scan = await options.check!(at);
+      return json({ scan, summary: await summary(now()) });
+    } catch (e) {
+      report(e);
+      return fail(500, "The game's server could not do that. Nothing was changed that you can see here.");
+    }
+  }
+
+  return { routes, basePath: options.basePath ?? "/api/admin", handle };
+}
+
+/** The settings as the game's own routes need them (the listing file, the character): the stored words, or the game's defaults. A fault in the store gives the defaults. */
+export async function loadGameSettings(store: Pick<AdminStore, "readSettings">, defaults: GameSettings): Promise<GameState> {
+  try {
+    return mergeSettings(await store.readSettings(), defaults);
+  } catch {
+    return mergeSettings({}, defaults);
+  }
+}

package/src/admin/http.ts

@@ -0,0 +1,74 @@
+// Small helpers for the handler. Web APIs only (they run in Workers, Firebase Functions and Node).
+
+export function json(data: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...headers },
+  });
+}
+
+export const fail = (status: number, error: string, extra: Record<string, unknown> = {}, headers: Record<string, string> = {}): Response => json({ error, ...extra }, status, headers);
+
+/**
+ * True when the browser says the request comes from this game's own pages. A call that changes something must pass this, so another site
+ * cannot make the owner's browser do it. The browser sets Origin on a POST; a request with no Origin must say Sec-Fetch-Site: same-origin.
+ */
+export function sameOrigin(req: Request): boolean {
+  const origin = req.headers.get("Origin");
+  if (origin !== null) return origin === new URL(req.url).origin;
+  return req.headers.get("Sec-Fetch-Site") === "same-origin";
+}
+
+/**
+ * True when the browser says a request did NOT come from this game's own pages: an Origin that is not the game's (any value, "null" too), or Sec-Fetch-Site "cross-site" or
+ * "same-site" (a sibling subdomain is same-site and has the game's cookies). A request with neither header (a command-line tool; a browser's own address bar says "none") is not foreign.
+ * The admin API is called only by its own page, so a read that is foreign is refused too: whatever CORS headers the game's router might add, the answer is not for another page.
+ */
+export function foreignOrigin(req: Request): boolean {
+  const origin = req.headers.get("Origin");
+  if (origin !== null && origin !== new URL(req.url).origin) return true;
+  const site = req.headers.get("Sec-Fetch-Site");
+  return site === "cross-site" || site === "same-site";
+}
+
+/** The text of a body of at most `max` bytes, or null when it is bigger. It stops reading at the limit: a body with no length cannot fill the memory. */
+export async function readLimited(req: Request, max: number): Promise<string | null> {
+  const declared = req.headers.get("Content-Length");
+  if (declared !== null && (!/^\d+$/.test(declared) || Number(declared) > max)) return null;
+  if (!req.body) return "";
+  const reader = req.body.getReader();
+  const parts: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > max) {
+      await reader.cancel().catch(() => undefined);
+      return null;
+    }
+    parts.push(value);
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const p of parts) {
+    all.set(p, at);
+    at += p.byteLength;
+  }
+  return new TextDecoder().decode(all);
+}
+
+/** A fixed-window limiter in memory. True while `key` has made at most `limit` calls in this window. Each copy of a server counts for itself. */
+export function memoryLimiter(): (key: string, limit: number, windowMs: number, now: number) => boolean {
+  const hits = new Map<string, { count: number; until: number }>();
+  return (key, limit, windowMs, now) => {
+    const hit = hits.get(key);
+    if (!hit || hit.until <= now) {
+      if (hits.size > 1000) for (const [k, v] of hits) if (v.until <= now) hits.delete(k);
+      hits.set(key, { count: 1, until: now + windowMs });
+      return true;
+    }
+    hit.count += 1;
+    return hit.count <= limit;
+  };
+}

package/src/admin/index.ts

@@ -0,0 +1,21 @@
+// "@nano133/nanoterra/admin": the admin of a game, in the package. No Three.js, no database, no cookie: the game gives a session and a store.
+//
+//   adminAccess            the guard: one pure function, who may open /admin
+//   createAdminHandler     the routes, on Request and Response
+//   loadGameSettings       the two switches for the game's own routes
+//   createMemoryStore      a store in memory, for tests
+//   (the conformance suite is its own path: "@nano133/nanoterra/admin/conformance"; the adapters are "/admin/d1" and "/admin/firestore")
+
+export { ADMIN_SESSION_MS, CLOCK_SKEW_MS, OWNER_PATTERN, adminAccess } from "./guard.js";
+export type { AdminAccess, AdminAccessInput, AdminRefusal, AdminSession } from "./guard.js";
+export { ADMIN_LIMITS, createAdminHandler, loadGameSettings } from "./handler.js";
+export type { AdminHandler, AdminHandlerOptions, AdminRoute } from "./handler.js";
+export { createMemoryStore } from "./memory.js";
+export type { MemoryStore } from "./memory.js";
+export { ADMIN_LOGINS_SHOWN } from "./store.js";
+export type { AdminLogin, AdminOrder, AdminPlayer, AdminStatus, AdminStore, AdminSummary, Money, OrderStatus, StoreSummary } from "./store.js";
+export { ORDERS_SHOWN, moneyOf, parseRate, shapeOrders, shapePlayers, statusOf, summarize } from "./summary.js";
+export type { OrderRow } from "./summary.js";
+export { RAW_PER_XNO, xnoText } from "./amount.js";
+export { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, REVIEW_LINK, REVIEW_NOTE, SWITCHES, isCharacter, isSignin, isSigninChoice, mergeSettings, parsePatch, pressOf, signinOn, stateOf } from "./switches.js";
+export type { Character, GamePatch, GameSettings, GameState, Signin, SwitchId } from "./switches.js";

package/src/admin/memory.ts

@@ -0,0 +1,59 @@
+// A store in memory, for tests (and for a game's first try). Nothing is kept after the process ends. It builds its summary with the same code as the
+// real adapters (./summary.ts), so it is the reference for what a summary says.
+
+import { summarize, type OrderRow } from "./summary.js";
+import type { AdminLogin, AdminStore, StoreSummary } from "./store.js";
+import type { GamePatch } from "./switches.js";
+
+export type MemoryStore = AdminStore & {
+  /** The rows as an adapter would keep them in its meta table. */
+  readonly rows: Map<string, string>;
+  /** How many writes were made. */
+  writes: number;
+  orders: OrderRow[];
+  owned: { player: string; lookId: string; at: number }[];
+  rate: StoreSummary["rate"];
+  /** The admin sign-ins and the count of admin sessions, when the store was made with `logins: true`. */
+  logins: (AdminLogin & Record<string, unknown>)[];
+  adminSessions: number;
+  playSessions: number;
+  /** Admin sign-in requests started and not delivered, and the game's own: "sign out everywhere" ends the first and leaves the second. */
+  pendingAdminRequests: number;
+  pendingGameRequests: number;
+};
+
+export function createMemoryStore(seed: { orders?: OrderRow[]; owned?: { player: string; lookId: string; at: number }[]; rate?: StoreSummary["rate"]; logins?: boolean } = {}): MemoryStore {
+  const store: MemoryStore = {
+    rows: new Map(),
+    writes: 0,
+    orders: seed.orders ?? [],
+    owned: seed.owned ?? [],
+    rate: seed.rate ?? null,
+    logins: [],
+    adminSessions: 0,
+    playSessions: 0,
+    pendingAdminRequests: 0,
+    pendingGameRequests: 0,
+    async readSettings() {
+      return { character: store.rows.get("setting:character"), signin: store.rows.get("setting:signin") };
+    },
+    async saveSettings(patch: GamePatch) {
+      if (patch.character) store.rows.set("setting:character", patch.character);
+      if (patch.signin) store.rows.set("setting:signin", patch.signin);
+      store.writes++;
+    },
+    async summary(now: number): Promise<StoreSummary> {
+      return summarize(store.orders, store.owned, store.rate, now);
+    },
+  };
+  if (seed.logins) {
+    store.recentLogins = async (limit: number) => [...store.logins].sort((a, b) => b.at - a.at).slice(0, limit);
+    store.signOutEverywhere = async () => {
+      const n = store.adminSessions;
+      store.adminSessions = 0;
+      store.pendingAdminRequests = 0;
+      return n;
+    };
+  }
+  return store;
+}

package/src/admin/panel/api.ts

@@ -0,0 +1,37 @@
+// Calls to the game's own server. Cookies stay on this site; nothing goes to another server.
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public body: Record<string, unknown> = {},
+  ) {
+    super(message);
+  }
+}
+
+export type Api = {
+  get<T>(path: string): Promise<T>;
+  post<T>(path: string, body?: unknown): Promise<T>;
+};
+
+/** The calls of the admin: `base` is where the routes are ("/api/admin"), `send` is `fetch` (a test gives its own). */
+export function createApi(base: string, send: typeof fetch = (...a) => fetch(...a)): Api {
+  async function call<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const res = await send(`${base}${path}`, { credentials: "same-origin", ...init, headers: { "Content-Type": "application/json", ...(init.headers ?? {}) } });
+    const text = await res.text();
+    let body: Record<string, unknown> = {};
+    try {
+      const v: unknown = text ? JSON.parse(text) : {};
+      if (v && typeof v === "object") body = v as Record<string, unknown>;
+    } catch {
+      body = {};
+    }
+    if (!res.ok) throw new ApiError(res.status, typeof body.error === "string" ? body.error : `The server answered ${res.status}. Try again.`, body);
+    return body as T;
+  }
+  return {
+    get: (path) => call(path),
+    post: (path, body = {}) => call(path, { method: "POST", body: JSON.stringify(body) }),
+  };
+}

package/src/admin/panel/dom.ts

@@ -0,0 +1,31 @@
+// A tiny helper to build page elements without innerHTML (safe for any text, and fine under a strict CSP). The panel runs in a browser.
+
+type Attrs = Record<string, string | number | boolean | undefined | ((e: Event) => void)>;
+type Child = Node | string | null | undefined | false;
+
+export function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Attrs = {}, ...children: Child[]): HTMLElementTagNameMap[K] {
+  const el = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === false) continue;
+    if (typeof v === "function") el.addEventListener(k.replace(/^on/, ""), v);
+    else if (k === "class") el.className = String(v);
+    else if (v === true) el.setAttribute(k, "");
+    else el.setAttribute(k, String(v));
+  }
+  for (const c of children) if (c !== null && c !== undefined && c !== false) el.append(c);
+  return el;
+}
+
+/** "nano_1abc…wxyz" */
+export const shortAddress = (a: string): string => `${a.slice(0, 10)}…${a.slice(-6)}`;
+
+export async function copy(text: string, button: HTMLButtonElement): Promise<void> {
+  const was = button.textContent;
+  try {
+    await navigator.clipboard.writeText(text);
+    button.textContent = "Copied";
+  } catch {
+    button.textContent = "Copy failed";
+  }
+  setTimeout(() => (button.textContent = was), 1500);
+}

package/src/admin/panel/gameCard.ts

@@ -0,0 +1,63 @@
+// The "Game" card of /admin: two switches, "Players use their Nanoterra character" and "Players can sign in with Nanoterra". A press saves at once
+// (POST {api}/game, behind the same admin guard as every admin call) and the game reads the setting at run time, so the creator pushes and deploys
+// nothing. The words are in ../switches.ts. The card changes ONLY these two settings: never a look, a price or an order.
+
+import { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, REVIEW_LINK, REVIEW_NOTE, SWITCHES, pressOf, signinOn, stateOf, type GameState, type SwitchId } from "../switches.js";
+import { ApiError, type Api } from "./api.js";
+import { h } from "./dom.js";
+
+/** The card for the settings `initial`. It keeps its own state: a press shows "Saving…", then "Saved." or the server's words. `defaultsFile` is where the game's defaults are written ("game.config.json"). */
+export function gameCard(api: Api, initial: GameState, defaultsFile = "the game's own settings"): HTMLElement {
+  let state = initial;
+  const rows = new Map<SwitchId, { button: HTMLButtonElement; sentence: HTMLElement; status: HTMLElement }>();
+  /** Under the character switch: it works only through sign-in, so it says so, and says what a player gets while sign-in is Off. */
+  const needs = h("p", { class: "fine switch-needs" });
+  const card = h("section", { class: "admin-card game-card", "aria-labelledby": "game-title" }, h("h2", { id: "game-title" }, "Game"));
+  card.append(h("p", { class: "fine" }, `Two choices about your game. A press saves at once: you push nothing and deploy nothing. They start from ${defaultsFile}, and a press here wins.`));
+
+  const draw = () => {
+    for (const [id, row] of rows) {
+      const on = stateOf(id, state);
+      row.button.setAttribute("aria-checked", on ? "true" : "false");
+      row.button.classList.toggle("switch-on", on);
+      row.button.querySelector(".switch-word")!.textContent = on ? "On" : "Off";
+      row.sentence.textContent = on ? SWITCHES[id].on : SWITCHES[id].off;
+    }
+    needs.hidden = !stateOf("character", state);
+    needs.textContent = signinOn(state.signin) ? CHARACTER_NEEDS_SIGNIN : CHARACTER_SIGNIN_OFF;
+  };
+
+  const press = async (id: SwitchId) => {
+    const row = rows.get(id)!;
+    row.button.disabled = true;
+    row.status.textContent = "Saving…";
+    try {
+      state = await api.post<GameState>("/game", pressOf(id, state));
+      row.status.textContent = "Saved.";
+      draw();
+    } catch (e) {
+      row.status.textContent = e instanceof ApiError ? e.message : "The game's server did not answer. Nothing was changed.";
+    } finally {
+      row.button.disabled = false;
+    }
+  };
+
+  for (const id of ["character", "signin"] as const) {
+    const label = h("span", { class: "switch-title", id: `switch-${id}-label` }, SWITCHES[id].title);
+    const button = h(
+      "button",
+      { class: "switch", type: "button", role: "switch", "aria-checked": "false", "aria-labelledby": `switch-${id}-label`, "aria-describedby": `switch-${id}-note` },
+      h("span", { class: "switch-word" }, "Off"),
+      h("span", { class: "switch-knob", "aria-hidden": "true" }),
+    );
+    const sentence = h("p", { class: "switch-note", id: `switch-${id}-note` });
+    const status = h("span", { class: "fine", role: "status", "aria-live": "polite" });
+    button.addEventListener("click", () => void press(id));
+    rows.set(id, { button, sentence, status });
+    card.append(h("div", { class: "switch-row" }, h("div", { class: "switch-head" }, label, button), sentence, id === "character" ? needs : null, status));
+    // The sign-in word is part of the listing file: Nanoterra's review decides what Nanoterra shows. This page cannot see that review.
+    if (id === "signin") card.append(h("p", { class: "fine switch-review" }, REVIEW_NOTE, " ", h("a", { href: REVIEW_LINK, target: "_blank", rel: "noopener noreferrer" }, "Open the launch page")));
+  }
+  draw();
+  return card;
+}

package/src/admin/panel/index.ts

@@ -0,0 +1,18 @@
+// "@nano133/nanoterra/admin/panel": the admin page of a game, drawn in the browser into one element. Plain DOM, no framework, no Three.js.
+//
+//   import { mountAdmin } from "@nano133/nanoterra/admin/panel";
+//   import "@nano133/nanoterra/admin/style.css";
+//   mountAdmin(document.getElementById("admin")!, { looks, signIn, signOut });
+//
+// The server part is "@nano133/nanoterra/admin" (the guard and the handler): it must not load this one.
+
+export { mountAdmin } from "./mount.js";
+export type { MountedAdmin, MountOptions } from "./mount.js";
+export { ApiError, createApi } from "./api.js";
+export type { Api } from "./api.js";
+export { gameCard } from "./gameCard.js";
+export { lookPicture, shelfView } from "./shelf.js";
+export { DEFAULT_LOGINS_NOTE, signinsCard } from "./signins.js";
+export type { ShelfData } from "./shelf.js";
+export { aiPrompt, centsOf, changeText, ownedIds, shelfStats, soldText } from "./shelfData.js";
+export type { LookStats, ShelfOrder, ShelfPlayer } from "./shelfData.js";