@nano133/nanoterra 0.1.0 → 0.3.0

package/dist/admin/conformance.js

@@ -0,0 +1,467 @@
+// The conformance suite: every game that uses the admin handler runs this against its OWN session code and store, in its own tests. It proves
+// the whole chain (the cookie, the session lookup, the guard, the routes), not only the pure guard: a game that reads the wrong cookie, or that
+// forgets to pass its owner, fails here.
+//
+//   import { adminConformance } from "@nano133/nanoterra/admin/conformance";
+//   for (const c of adminConformance(host)) it(c.name, c.run);      // vitest, node:test, any runner
+//
+// `host.request(who, ...)` sends the request as that kind of visitor. The game makes each kind from its own sessions (see `Who`). The suite asks
+// only for statuses and for the words "reason" and "error"; it never reads a cookie.
+import { ORDERS_SHOWN } from "./summary.js";
+const REFUSALS = [
+    { who: "signed_out", status: 401, words: "a visitor who is signed out" },
+    { who: "game_login", status: 401, words: "a login that was made for the game's players" },
+    { who: "game_token_as_admin", status: 401, words: "the token of a player's login put in the admin cookie" },
+    { who: "nanoterra_login", status: 403, reason: "nanoterra", words: "a Nanoterra sign-in (it names an address but proves no key)" },
+    { who: "unknown_via_login", status: 403, words: "an admin login that was made some way the game does not know (it must fail closed)" },
+    { who: "other_wallet", status: 403, reason: "other_address", words: "a wallet that is not the owner's" },
+    { who: "no_address", status: 403, reason: "no_address", words: "anyone, while the game has no owner address" },
+    { who: "expired_login", status: 401, words: "an admin login that the game's own store has expired (made less than a day ago)" },
+    { who: "signed_out_login", status: 401, words: "an admin login that the game's own sign-out has ended" },
+    { who: "old_valid_row", status: 401, words: "an admin login that is more than a day old but still valid in the game's store (only the guard's age check refuses it)" },
+];
+function check(ok, message) {
+    if (!ok)
+        throw new Error(message);
+}
+async function read(res) {
+    const text = await res.text();
+    let json = null;
+    try {
+        const v = JSON.parse(text);
+        if (v && typeof v === "object" && !Array.isArray(v))
+            json = v;
+    }
+    catch {
+        // not JSON
+    }
+    return { status: res.status, text, json };
+}
+/** A refusal carries words and a reason and nothing else: no data of the game. */
+const REFUSAL_KEYS = new Set(["error", "reason", "signedInAs"]);
+/** Words of the game's data that a refusal or an answer to a visitor must never hold. */
+const DATA_WORDS = /"orders"|"players"|"totals"|"counts"|"character"|"signin"|"warnings"/;
+export function adminConformance(host) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run });
+    const good = (extra = {}) => ({ Origin: host.origin, "Content-Type": "application/json", ...extra });
+    const body = (r) => (r.method === "POST" ? "{}" : undefined);
+    const NOT_OWNER = REFUSALS.map((r) => r.who);
+    check(host.routes.length > 0, "the host lists no routes");
+    /**
+     * Sends a request and looks at the HEADERS of the answer: every answer to a request for the admin is `no-store` and has no CORS header, whatever the method and the
+     * status (a preflight answer that allows an origin, or a cached refusal, is a fault). `strict: false` is for paths that the game's own router may answer (a plain 404).
+     */
+    async function send(who, req, strict = true) {
+        const res = await host.request(who, req);
+        let cors = "";
+        res.headers.forEach((v, k) => {
+            if (k.toLowerCase().startsWith("access-control-"))
+                cors = `${k}: ${v}`;
+        });
+        check(cors === "", `${req.method} ${req.path} as ${who}: the answer has a CORS header (${cors})`);
+        if (strict)
+            check((res.headers.get("cache-control") ?? "").includes("no-store"), `${req.method} ${req.path} as ${who}: the answer (${res.status}) is not "Cache-Control: no-store"`);
+        return res;
+    }
+    for (const r of REFUSALS) {
+        add(`every route refuses ${r.words} (${r.status}${r.reason ? `, ${r.reason}` : ""}) and gives it no data`, async () => {
+            for (const route of host.routes) {
+                const got = await read(await send(r.who, { method: route.method, path: route.path, headers: good(), body: body(route) }));
+                const here = `${route.method} ${route.path} as ${r.who}`;
+                check(got.status === r.status, `${here}: expected ${r.status}, got ${got.status}`);
+                if (r.reason)
+                    check(got.json?.reason === r.reason, `${here}: expected reason "${r.reason}", got ${JSON.stringify(got.json?.reason)}`);
+                check(got.json !== null && Object.keys(got.json).every((k) => REFUSAL_KEYS.has(k)), `${here}: a refusal must carry only error, reason and signedInAs, got ${got.text.slice(0, 120)}`);
+            }
+        });
+    }
+    add("OPTIONS and HEAD on every route are refused like any other method, with no CORS answer: no preflight is ever answered for a visitor", async () => {
+        for (const r of REFUSALS) {
+            for (const route of host.routes) {
+                for (const method of ["OPTIONS", "HEAD"]) {
+                    const headers = method === "OPTIONS" ? good({ "Access-Control-Request-Method": "POST", "Access-Control-Request-Headers": "content-type" }) : good();
+                    const got = await send(r.who, { method, path: route.path, headers });
+                    check(got.status === r.status, `${method} ${route.path} as ${r.who}: expected ${r.status}, got ${got.status}`);
+                }
+            }
+        }
+    });
+    add("an unknown path under the base is refused like any admin path (so the routes are not leaked): the same refusal for a visitor, 404 for the owner", async () => {
+        const path = `${host.basePath}/no-such-page`;
+        for (const r of REFUSALS) {
+            const got = await send(r.who, { method: "GET", path });
+            check(got.status === r.status, `GET ${path} as ${r.who}: expected ${r.status}, got ${got.status}`);
+        }
+        const owner = await send("owner", { method: "GET", path });
+        check(owner.status === 404, `GET ${path} as owner: expected 404, got ${owner.status}`);
+    });
+    add("the game's other routes under the base (the ones its own router serves) refuse every visitor who is not the owner, with a refusal that carries no data", async () => {
+        for (const route of host.otherRoutes ?? []) {
+            for (const who of NOT_OWNER) {
+                const got = await read(await send(who, { method: route.method, path: route.path, headers: good(), body: body(route) }, false));
+                const here = `${route.method} ${route.path} as ${who}`;
+                check(got.status === 401 || got.status === 403, `${here}: expected 401 or 403, got ${got.status}`);
+                check(!DATA_WORDS.test(got.text), `${here}: the answer holds the game's data`);
+                check(got.json !== null && Object.keys(got.json).every((k) => REFUSAL_KEYS.has(k)), `${here}: a refusal must carry only error, reason and signedInAs, got ${got.text.slice(0, 120)}`);
+            }
+        }
+    });
+    /** Other spellings of one admin path: other case, a slash, a doubled slash, a percent code, a backslash, a dot segment. */
+    const spellings = (path) => {
+        const last = path.slice(path.lastIndexOf("/") + 1);
+        const base = host.basePath;
+        return [
+            path.toUpperCase(),
+            `${path}/`,
+            path.replace(`/${last}`, `//${last}`),
+            path.slice(0, -1) + `%${path.charCodeAt(path.length - 1).toString(16)}`,
+            path.replace(`/${last}`, `/x/../${last}`),
+            `${base}%2f${last}`,
+            `${base}\\${last}`,
+            `${base}%5c${last}`,
+            `${base.replace(/^\/(\w+)\//, "/$1%2f")}/${last}`,
+            `${base.replace(/^\/(\w)/, (_, c) => `/%${c.charCodeAt(0).toString(16)}`)}/${last}`,
+        ];
+    };
+    add("other spellings of EVERY admin path never open anything for a visitor, with any method", async () => {
+        const seen = new Set();
+        for (const route of host.routes) {
+            for (const path of spellings(route.path)) {
+                if (seen.has(path))
+                    continue;
+                seen.add(path);
+                for (const who of NOT_OWNER) {
+                    for (const method of new Set([route.method, "GET", "POST", "OPTIONS", "HEAD"])) {
+                        const got = await read(await send(who, { method, path, headers: good(), body: body({ method }) }, false));
+                        check([401, 403, 404, 405].includes(got.status), `${method} ${path} as ${who}: expected 401, 403, 404 or 405, got ${got.status}`);
+                        check(!DATA_WORDS.test(got.text), `${method} ${path} as ${who}: the answer holds the game's data`);
+                    }
+                }
+            }
+        }
+    });
+    add("a request from another page never gets a CORS header, and never the data: a foreign Origin (another site, 'null', a sibling subdomain) on every route, with every method, for the owner and for every visitor", async () => {
+        const own = new URL(host.origin);
+        const origins = ["https://evil.example", "null", `${own.protocol}//evil.${own.host}`, `${own.protocol}//${own.host.replace(/^[^.]+\./, "sibling.")}`, `${own.protocol}//${own.host}.evil.example`];
+        const WHO = ["owner", ...NOT_OWNER];
+        for (const route of host.routes) {
+            for (const origin of origins) {
+                for (const who of WHO) {
+                    for (const method of new Set([route.method, "GET", "OPTIONS", "HEAD"])) {
+                        const got = await read(await send(who, { method, path: route.path, headers: { Origin: origin, "Content-Type": "application/json" }, body: body({ method }) }));
+                        const here = `${method} ${route.path} as ${who} with Origin ${origin}`;
+                        check([401, 403, 405].includes(got.status), `${here}: a foreign page must get 401, 403 or 405, got ${got.status}`);
+                        check(!DATA_WORDS.test(got.text), `${here}: the answer holds the game's data`);
+                    }
+                }
+            }
+            // Sec-Fetch-Site says the same: cross-site and same-site (a sibling subdomain has the game's cookies) are not the game's own page.
+            for (const site of ["cross-site", "same-site"]) {
+                const got = await read(await send("owner", { method: route.method, path: route.path, headers: { "Sec-Fetch-Site": site, "Content-Type": "application/json" }, body: body(route) }));
+                check(got.status === 403, `${route.method} ${route.path} as owner with Sec-Fetch-Site ${site}: expected 403, got ${got.status}`);
+            }
+        }
+    });
+    add("an old login that is still valid in the store is refused EVERY time it is used, not only the first: a game must not renew a login on each read", async () => {
+        for (const route of host.routes) {
+            for (const again of [false, true, true]) {
+                const got = await read(await send("old_valid_row", { method: route.method, path: route.path, headers: good(), body: body(route), again }));
+                check(got.status === 401, `${route.method} ${route.path} as old_valid_row${again ? " (the same login again)" : ""}: expected 401, got ${got.status}`);
+            }
+        }
+    });
+    add("a visitor is refused even right after the owner was served on the same URL: an answer is never kept and shown to the next visitor (no cache of answers by URL)", async () => {
+        for (const route of host.routes.filter((r) => r.method === "GET")) {
+            for (const round of [1, 2]) {
+                const served = await send("owner", { method: "GET", path: route.path, headers: good() });
+                check(served.status === 200, `GET ${route.path} as owner: expected 200, got ${served.status}`);
+                await served.text();
+                for (const r of REFUSALS) {
+                    const got = await read(await send(r.who, { method: "GET", path: route.path, headers: good() }));
+                    check(got.status === r.status, `GET ${route.path} as ${r.who} right after the owner was served (round ${round}): expected ${r.status}, got ${got.status}`);
+                    check(!DATA_WORDS.test(got.text), `GET ${route.path} as ${r.who} right after the owner was served: the answer holds the game's data`);
+                }
+            }
+        }
+    });
+    add("(when the host can end a login) a login that the game ended is refused at once, even right after it was used", async () => {
+        if (!host.endLogin)
+            return;
+        for (const route of host.routes.filter((r) => r.method === "GET")) {
+            const first = await send("owner", { method: "GET", path: route.path, headers: good() });
+            check(first.status === 200, `GET ${route.path} as owner: expected 200, got ${first.status}`);
+            await first.text();
+            await host.endLogin("owner");
+            const after = await read(await send("owner", { method: "GET", path: route.path, headers: good(), again: true }));
+            check(after.status === 401, `GET ${route.path} with the same login after the game ended it: expected 401, got ${after.status} (does the game keep sessions in a cache?)`);
+        }
+    });
+    add("(when the admin has Sign out everywhere) the login that used it is refused at once, even though it was used a moment before", async () => {
+        const out = host.routes.find((r) => r.method === "POST" && r.path.endsWith("/signout-all"));
+        if (!out)
+            return;
+        const reads = host.routes.find((r) => r.method === "GET");
+        check((await send("owner", { method: "GET", path: reads.path, headers: good() })).status === 200, "the owner could not read before signing out");
+        const done = await send("owner", { method: "POST", path: out.path, headers: good(), body: "{}" });
+        check(done.status === 200, `POST ${out.path} as owner: expected 200, got ${done.status}`);
+        const after = await send("owner", { method: "GET", path: reads.path, headers: good(), again: true });
+        check(after.status === 401, `GET ${reads.path} with the login that signed out everywhere: expected 401, got ${after.status} (does the game keep sessions in a cache?)`);
+    });
+    add("a player's login token sent in any other place than the game's cookie (a Bearer header, a query parameter, another header) opens nothing", async () => {
+        for (const route of host.routes) {
+            for (const tokenAt of ["bearer", "query", "header"]) {
+                for (const who of ["game_login", "game_token_as_admin"]) {
+                    const got = await read(await send(who, { method: route.method, path: route.path, headers: good(), body: body(route), tokenAt }, false));
+                    const here = `${route.method} ${route.path} as ${who} with the token in ${tokenAt}`;
+                    check(got.status === 401 || got.status === 403, `${here}: expected 401 or 403, got ${got.status}`);
+                    check(!DATA_WORDS.test(got.text), `${here}: the answer holds the game's data`);
+                }
+            }
+        }
+    });
+    add("the owner gets through the guard on every route", async () => {
+        for (const route of host.routes) {
+            const res = await send("owner", { method: route.method, path: route.path, headers: good(), body: body(route) });
+            const got = await read(res);
+            check(![401, 403, 404, 405].includes(got.status) && got.status < 500, `${route.method} ${route.path} as owner: the guard let the owner through, but the status was ${got.status}`);
+        }
+    });
+    add("a POST from another site is refused (403), even with the owner's cookie", async () => {
+        for (const route of host.routes.filter((r) => r.method === "POST")) {
+            const other = await read(await send("owner", { method: "POST", path: route.path, headers: { Origin: "https://evil.example", "Content-Type": "application/json" }, body: "{}" }));
+            check(other.status === 403, `POST ${route.path} with another Origin: expected 403, got ${other.status}`);
+            const fetchSite = await read(await send("owner", { method: "POST", path: route.path, headers: { "Sec-Fetch-Site": "cross-site", "Content-Type": "application/json" }, body: "{}" }));
+            check(fetchSite.status === 403, `POST ${route.path} with no Origin and Sec-Fetch-Site cross-site: expected 403, got ${fetchSite.status}`);
+            const none = await read(await send("owner", { method: "POST", path: route.path, headers: { "Content-Type": "application/json" }, body: "{}" }));
+            check(none.status === 403, `POST ${route.path} with neither Origin nor Sec-Fetch-Site: expected 403, got ${none.status}`);
+        }
+    });
+    add("a method that a route does not have is refused: the guard's answer for a visitor, 405 for the owner", async () => {
+        for (const route of host.routes) {
+            const owner = await read(await send("owner", { method: "DELETE", path: route.path, headers: good() }));
+            check(owner.status === 405, `DELETE ${route.path} as owner: expected 405, got ${owner.status}`);
+            const visitor = await read(await send("signed_out", { method: "DELETE", path: route.path, headers: good() }));
+            check(visitor.status === 401, `DELETE ${route.path} signed out: expected 401, got ${visitor.status}`);
+        }
+    });
+    add("a body that is far too big is refused and changes nothing", async () => {
+        const big = JSON.stringify({ character: "own", pad: "x".repeat(100_000) });
+        for (const route of host.routes.filter((r) => r.method === "POST" && r.path.endsWith("/game"))) {
+            const got = await read(await send("owner", { method: "POST", path: route.path, headers: good(), body: big }));
+            check(got.status === 413 || got.status === 400, `POST ${route.path} with 100 KB: expected 413 or 400, got ${got.status}`);
+        }
+    });
+    return cases;
+}
+const rawOf = (xno) => (BigInt(Math.round(xno * 10_000)) * 10n ** 26n).toString();
+export function adminStoreConformance(make) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run: async () => run(await make()) });
+    const NOW = 1_800_000_000_000;
+    const A = `nano_1${"a".repeat(59)}`;
+    const B = `nano_3${"b".repeat(59)}`;
+    const order = (id, over) => ({ id, player: A, lookId: "mint-cap", usd: "0.25", amountRaw: rawOf(0.25), status: "paid", createdAt: NOW - 1000, expiresAt: NOW + 1000, paidAt: NOW - 500, payer: A, hash: `H${id}`, ...over });
+    add("a new store has no settings of its own", async ({ store }) => {
+        const s = await store.readSettings();
+        check(s.character === undefined && s.signin === undefined, `expected no settings, got ${JSON.stringify(s)}`);
+    });
+    add("a patch saves only what it names; the next patch keeps the rest", async ({ store }) => {
+        await store.saveSettings({ signin: "none" }, NOW);
+        let s = await store.readSettings();
+        check(s.signin === "none" && s.character === undefined, `after signin none: ${JSON.stringify(s)}`);
+        await store.saveSettings({ character: "own" }, NOW + 1);
+        s = await store.readSettings();
+        check(s.signin === "none" && s.character === "own", `after character own: ${JSON.stringify(s)}`);
+        await store.saveSettings({ signin: "exchange", character: "nanoterra" }, NOW + 2);
+        s = await store.readSettings();
+        check(s.signin === "exchange" && s.character === "nanoterra", `after both: ${JSON.stringify(s)}`);
+    });
+    add("an empty patch writes nothing and does not fail", async ({ store }) => {
+        await store.saveSettings({}, NOW);
+        const s = await store.readSettings();
+        check(s.character === undefined && s.signin === undefined, "an empty patch must save nothing");
+    });
+    add("saving changes nothing but the two settings: no order, no owned look, no other meta row", async (h) => {
+        await h.seed({ orders: [order("1", {}), order("2", { status: "open" })], owned: [{ player: A, lookId: "mint-cap", at: NOW }], rate: { value: JSON.stringify({ usd: 1.2, sources: ["x"] }), at: NOW } });
+        const before = await h.snapshot();
+        await h.store.saveSettings({ character: "own", signin: "none" }, NOW + 5);
+        check((await h.snapshot()) === before, "the rows of the game changed after saving the settings");
+    });
+    add("the summary counts the orders by status, reads an open order past its expiry as expired, and totals the money", async ({ store, seed }) => {
+        await seed({
+            orders: [
+                order("a", { status: "paid", usd: "0.25", amountRaw: rawOf(0.25) }),
+                order("b", { status: "paid", usd: "0.50", amountRaw: rawOf(0.5) }),
+                order("c", { status: "paid_late", usd: "1.10", amountRaw: rawOf(0.9) }),
+                order("d", { status: "open", expiresAt: NOW + 1000, paidAt: null, payer: null, hash: null }),
+                order("e", { status: "open", expiresAt: NOW - 1000, paidAt: null, payer: null, hash: null }),
+                order("f", { status: "expired", expiresAt: NOW - 5000, paidAt: null, payer: null, hash: null }),
+            ],
+        });
+        const s = await store.summary(NOW);
+        check(JSON.stringify(s.counts) === JSON.stringify({ open: 1, paid: 2, expired: 2, paid_late: 1 }), `counts: ${JSON.stringify(s.counts)}`);
+        check(JSON.stringify(s.totals.paid) === JSON.stringify({ count: 2, xno: "0.75", usd: "0.75" }), `paid: ${JSON.stringify(s.totals.paid)}`);
+        check(JSON.stringify(s.totals.paidLate) === JSON.stringify({ count: 1, xno: "0.9", usd: "1.10" }), `paid late: ${JSON.stringify(s.totals.paidLate)}`);
+        const e = s.orders.find((o) => o.id === "e");
+        check(e?.status === "expired", `an open order past its expiry reads "expired", got ${e?.status}`);
+        check(s.orders.find((o) => o.id === "d")?.status === "open", "an open order that has not run out stays open");
+        const a = s.orders.find((o) => o.id === "a");
+        check(a.xno === "0.25" && a.usd === "0.25" && a.player === A && a.lookId === "mint-cap" && a.hash === "Ha" && a.payer === A && a.paidAt === NOW - 500, `an order's fields: ${JSON.stringify(a)}`);
+    });
+    add(`the summary lists the newest ${ORDERS_SHOWN} orders, newest first, and still counts them all`, async ({ store, seed }) => {
+        const rows = [];
+        for (let i = 0; i < ORDERS_SHOWN + 5; i++)
+            rows.push(order(`o${String(i).padStart(4, "0")}`, { createdAt: NOW - 100_000 + i, status: "paid", hash: `H${i}` }));
+        await seed({ orders: rows });
+        const s = await store.summary(NOW);
+        check(s.orders.length === ORDERS_SHOWN, `expected ${ORDERS_SHOWN} orders, got ${s.orders.length}`);
+        check(s.orders[0].id === `o${String(ORDERS_SHOWN + 4).padStart(4, "0")}`, `the first order must be the newest, got ${s.orders[0].id}`);
+        check(s.orders.every((o, i, all) => i === 0 || all[i - 1].createdAt >= o.createdAt), "the orders are not newest first");
+        check(s.counts.paid === ORDERS_SHOWN + 5, `the count must be over all orders, got ${s.counts.paid}`);
+        check(s.totals.paid.count === ORDERS_SHOWN + 5, `the total must be over all orders, got ${s.totals.paid.count}`);
+    });
+    add("the summary lists the looks that players own, by player and in the order they were granted", async ({ store, seed }) => {
+        await seed({ owned: [{ player: B, lookId: "royal", at: NOW - 10 }, { player: A, lookId: "sunset", at: NOW - 30 }, { player: A, lookId: "mint-cap", at: NOW - 40 }] });
+        const s = await store.summary(NOW);
+        check(JSON.stringify(s.players) === JSON.stringify([{ player: A, looks: [{ id: "mint-cap", at: NOW - 40 }, { id: "sunset", at: NOW - 30 }] }, { player: B, looks: [{ id: "royal", at: NOW - 10 }] }]), JSON.stringify(s.players));
+    });
+    add("the rate is null when there is none, read when it is good, and null when the row is junk", async ({ store, seed }) => {
+        check((await store.summary(NOW)).rate === null, "no rate row must give null");
+        await seed({ rate: { value: JSON.stringify({ usd: 1.18, sources: ["a", "b"] }), at: NOW - 60 } });
+        check(JSON.stringify((await store.summary(NOW)).rate) === JSON.stringify({ usd: 1.18, sources: ["a", "b"], at: NOW - 60 }), "a good rate row must be read");
+        await seed({ rate: { value: "not json", at: NOW } });
+        check((await store.summary(NOW)).rate === null, "a junk rate row must give null");
+    });
+    // The sign-in list and "sign out everywhere" are optional: a store that has them must pass these cases (a store that has not skips them).
+    add("(when the store lists sign-ins) the last sign-ins come newest first, at most the limit, with only the time, the country and the browser", async (h) => {
+        if (!h.store.recentLogins)
+            return;
+        check(Boolean(h.seedLogins), "a store with recentLogins needs seedLogins in its harness");
+        check((await h.store.recentLogins(10)).length === 0, "a new store lists no sign-ins");
+        const rows = Array.from({ length: 12 }, (_, i) => ({ at: NOW - 1000 * (12 - i), country: i % 3 === 0 ? null : "US", browser: `Chrome on macOS ${i}` }));
+        await h.seedLogins(rows);
+        const got = await h.store.recentLogins(10);
+        check(got.length === 10, `expected 10 sign-ins, got ${got.length}`);
+        check(got.every((l, i, all) => i === 0 || all[i - 1].at >= l.at), "the sign-ins are not newest first");
+        check(got[0].at === NOW - 1000 && got[0].browser === "Chrome on macOS 11", `the first must be the newest: ${JSON.stringify(got[0])}`);
+        check(got.every((l) => Object.keys(l).sort().join() === "at,browser,country"), `a sign-in must carry only at, browser and country: ${JSON.stringify(got[0])}`);
+        check((await h.store.recentLogins(3)).length === 3, "the limit must hold");
+        check((await h.store.recentLogins(0)).length === 0, "a limit of 0 lists none");
+    });
+    add("(when the store can sign out everywhere) it deletes every admin session and no player session, says how many, and changes nothing else", async (h) => {
+        if (!h.store.signOutEverywhere)
+            return;
+        check(Boolean(h.seedSessions && h.sessionCounts), "a store with signOutEverywhere needs seedSessions and sessionCounts in its harness");
+        check(Boolean(h.seedRequests && h.pendingRequests), "a store with signOutEverywhere needs seedRequests and pendingRequests in its harness: the contract must prove that it ends the admin sign-in requests that were not delivered");
+        await h.seed({ orders: [order("1", {}), order("2", { status: "open" })], owned: [{ player: A, lookId: "mint-cap", at: NOW }] });
+        await h.seedSessions({ admin: 3, play: 4 });
+        await h.seedRequests({ admin: 2, game: 3 });
+        const before = await h.snapshot();
+        const n = await h.store.signOutEverywhere();
+        check(n === 3, `expected 3 admin sessions deleted, got ${n}`);
+        const left = await h.sessionCounts();
+        check(left.admin === 0 && left.play === 4, `expected 0 admin and 4 player sessions, got ${JSON.stringify(left)}`);
+        check((await h.snapshot()) === before, "the orders, the owned looks or the meta rows changed");
+        check((await h.store.signOutEverywhere()) === 0, "a second call deletes nothing and says 0");
+        check((await h.sessionCounts()).play === 4, "the player sessions are still there");
+        const p = await h.pendingRequests();
+        check(p.admin === 0, `an admin sign-in request that was started and not delivered must be ended too, ${p.admin} are left (a request signed a moment ago could make a new login)`);
+        check(p.game === 3, `the game's own sign-in requests must be left alone, ${p.game} of 3 are left`);
+    });
+    return cases;
+}
+export function adminSigninConformance(host, options = {}) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run });
+    const SCOPES = ["game", "admin"];
+    const other = (s) => (s === "admin" ? "game" : "admin");
+    const none = (got) => !got.admin && !got.game;
+    const owns = (got, scope) => (scope === "admin" ? got.admin && !got.game : got.game && !got.admin);
+    /** A refused attempt must leave the request as it was: its own browser still signs in, in its own scope, once. This also proves that the signature landed. */
+    async function stillSignsIn(req, scope, after) {
+        const got = await host.finish(req, scope, "own");
+        check(owns(got, scope), `after ${after}, a ${scope} request that was signed no longer signed in its own browser in its own scope: ${JSON.stringify(got)} (a refusal must leave the request as it was; or the signature never landed)`);
+    }
+    add("control: a request signed in its own scope signs in the browser that started it, in that scope only, once", async () => {
+        for (const scope of SCOPES) {
+            const req = await host.start(scope);
+            await host.sign(req);
+            const got = await host.finish(req, scope, "own");
+            check(owns(got, scope), `a ${scope} request finished as ${scope} by its own browser: ${JSON.stringify(got)}`);
+            const again = await host.finish(req, scope, "own");
+            check(none(again), `a ${scope} request must sign in once: the second check gave ${JSON.stringify(again)}`);
+            const stranger = await host.finish(req, scope, "other");
+            check(none(stranger), `a ${scope} request that was already collected must give another browser no login either: ${JSON.stringify(stranger)}`);
+        }
+    });
+    add("a request signs in only the browser that started it: another browser that knows the request signs in nobody, in either scope", async () => {
+        for (const scope of SCOPES) {
+            const req = await host.start(scope);
+            await host.sign(req);
+            const got = await host.finish(req, scope, "other");
+            check(none(got), `a ${scope} request finished in its own scope by ANOTHER browser made a login: ${JSON.stringify(got)}`);
+            await stillSignsIn(req, scope, "another browser asked in the same scope");
+        }
+    });
+    add("a request never makes a login in the OTHER scope: not for the browser that started it, not for another browser, not for retyped credentials; and no login of any kind is made", async () => {
+        for (const scope of SCOPES) {
+            for (const credentials of ["own", "other", "retyped"]) {
+                const req = await host.start(scope);
+                await host.sign(req);
+                const got = await host.finish(req, other(scope), credentials);
+                check(none(got), `a ${scope} request finished as the ${other(scope)} with ${credentials} credentials made a login: ${JSON.stringify(got)}`);
+                await stillSignsIn(req, scope, `an ask as the ${other(scope)} with ${credentials} credentials`);
+            }
+        }
+    });
+    add("(when the admin has Sign out everywhere) a signed admin request makes no login after it, and neither does a waiting one that is signed afterwards; a game request is left alone", async () => {
+        if (!host.signOutEverywhere) {
+            check(!options.signOutEverywhere, "the host has no signOutEverywhere, but the contract was told that the admin has Sign out everywhere");
+            return;
+        }
+        // signed, then signed out everywhere
+        const signed = await host.start("admin");
+        await host.sign(signed);
+        // waiting when signed out everywhere, signed afterwards
+        const waiting = await host.start("admin");
+        // a game request, signed, left alone
+        const game = await host.start("game");
+        await host.sign(game);
+        await host.signOutEverywhere();
+        check(none(await host.finish(signed, "admin", "own")), "a signed admin request that was not yet delivered made a login after Sign out everywhere");
+        try {
+            await host.sign(waiting); // the app may refuse it (the request ended): that is fine
+        }
+        catch {
+            // refused
+        }
+        check(none(await host.finish(waiting, "admin", "own")), "an admin request that was waiting at Sign out everywhere made a login when it was signed afterwards");
+        check(owns(await host.finish(game, "game", "own"), "game"), "Sign out everywhere must leave the game's own sign-in requests alone");
+    });
+    add("(when the host can move its clock) the cross-scope asks are refused after the admin's request life has ended too, inside the game's hour of delivery", async () => {
+        if (!host.advance) {
+            check(!options.advance, "the host has no advance, but the contract was told that the game's clock can be moved");
+            return;
+        }
+        const made = [];
+        for (const scope of SCOPES) {
+            const req = await host.start(scope);
+            await host.sign(req);
+            made.push({ req, scope });
+        }
+        // Ten minutes after the start (the admin's life and its minute of delivery are over, the game's five minutes too), and again at 55 minutes (a game request is still delivered inside its hour).
+        let waited = 0;
+        for (const minutes of [10, 55]) {
+            await host.advance((minutes - waited) * 60_000);
+            waited = minutes;
+            for (const { req, scope } of made) {
+                for (const credentials of ["own", "other", "retyped"]) {
+                    const got = await host.finish(req, other(scope), credentials);
+                    check(none(got), `${minutes} minutes later, a ${scope} request finished as the ${other(scope)} with ${credentials} credentials made a login: ${JSON.stringify(got)}`);
+                }
+            }
+        }
+    });
+    return cases;
+}

package/dist/admin/guard.d.ts

@@ -0,0 +1,38 @@
+/** 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 declare const ADMIN_SESSION_MS: number;
+/** 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 declare const CLOCK_SKEW_MS: number;
+/** 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 declare const OWNER_PATTERN: RegExp;
+/** `ok: true` only when the request may read and change the admin data. */
+export declare function adminAccess(input: AdminAccessInput): AdminAccess;

package/dist/admin/guard.js

@@ -0,0 +1,57 @@
+// 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 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, error, extra = {}) => ({ ok: false, status, error, ...extra });
+const misconfigured = () => 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) {
+    try {
+        return decide(input);
+    }
+    catch {
+        // A getter that throws, a Proxy, anything odd: no.
+        return misconfigured();
+    }
+}
+function decide(input) {
+    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/dist/admin/handler.d.ts

@@ -0,0 +1,63 @@
+import { type AdminSession } from "./guard.js";
+import { type AdminStatus, type AdminStore, type StoreSummary } from "./store.js";
+import { 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>;
+};
+/** The limits of the writes. */
+export declare const ADMIN_LIMITS: {
+    /** A press on a switch. */
+    readonly game: {
+        readonly limit: 30;
+        readonly windowMs: 60000;
+    };
+    /** A payment check. */
+    readonly check: {
+        readonly limit: 20;
+        readonly windowMs: 60000;
+    };
+    /** "Sign out everywhere". */
+    readonly signOutAll: {
+        readonly limit: 5;
+        readonly windowMs: 60000;
+    };
+    /** The biggest body a press can have. */
+    readonly gameBodyMax: 512;
+};
+export declare function createAdminHandler(options: AdminHandlerOptions): AdminHandler;
+/** 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 declare function loadGameSettings(store: Pick<AdminStore, "readSettings">, defaults: GameSettings): Promise<GameState>;