@nano133/nanoterra 0.10.0 → 0.11.0

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

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

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

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

package/dist/admin-signin/browser.js

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

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

@@ -0,0 +1,11 @@
+import type { AdminSigninStore } from "./types.js";
+export type AdminSigninHarness = {
+    store: AdminSigninStore;
+    /** Every row the store keeps (requests, sessions, the sign-in list) as one text. */
+    dump(): Promise<string>;
+};
+export type AdminSigninConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+export declare function adminSigninStoreConformance(make: () => Promise<AdminSigninHarness>): AdminSigninConformanceCase[];

package/dist/admin-signin/conformance.js

@@ -0,0 +1,190 @@
+// The conformance suite of the admin sign-in's store: a game that writes its own store (another database) runs it, and so proves that its store keeps
+// every rule the package's adapters keep. The package runs it on the memory store, D1 (on SQLite) and Firestore (a fake).
+//
+//   import { adminSigninStoreConformance } from "@nano133/nanoterra/admin-signin/conformance";
+//   for (const c of adminSigninStoreConformance(async () => ({ store: myStore(), dump: () => allMyRowsAsText() }))) it(c.name, c.run);
+//
+// Each case gets a NEW, empty store from `make`. The rules: a request is finished once and delivered once, and a delivery writes its session in the same
+// step; the two wallet apps stay apart; a session lasts until its time; "Sign out everywhere" ends every session and every request not delivered; the
+// sign-in list keeps three things for 30 days. (The whole chain, with the player's sign-in beside it, is `adminSigninConformance` in
+// "@nano133/nanoterra/admin/conformance".)
+import { ADMIN_LOGIN_KEEP_MS } from "./types.js";
+function check(ok, message) {
+    if (!ok)
+        throw new Error(message);
+}
+/** An address the suite can find in any text (a store does not check addresses: the handler does). */
+const who = (n) => `nano_3${n}${"x".repeat(59 - n.length)}`;
+const OWNER = who("own");
+const hex = (n, len = 64) => n.toString(16).padStart(len, "0");
+let serial = 0;
+/** A request as a wallet's start makes it: a fresh id each time. */
+function request(at, extra = {}) {
+    serial += 1;
+    const id = hex(Date.now() * 1000 + serial, 32).slice(-32);
+    return { key: id, r: { id, starter: hex(serial + 7), status: "waiting", expiresAt: at + 2 * 60_000, nonce: hex(serial + 99), issuedAt: at, ...extra } };
+}
+const session = (at, n, via = "wallet") => ({ idHash: hex(1_000_000 + n + serial++), address: OWNER, createdAt: at, expiresAt: at + 86_400_000, via });
+export function adminSigninStoreConformance(make) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run: async () => run(await make(), Date.now()) });
+    add("a request reads back as it was made, by its key and by its browser id, and only for its own wallet app", async ({ store }, now) => {
+        const { key, r } = request(now, { label: "ADMIN of game.test sign-in ABCD-EFGH from US" });
+        await store.requests("nautilus").create(key, r);
+        const back = await store.requests("nautilus").get(key);
+        check(back !== null && back.id === r.id && back.starter === r.starter && back.status === "waiting" && back.expiresAt === r.expiresAt && back.label === r.label && back.nonce === r.nonce && back.issuedAt === r.issuedAt && back.account === undefined, `read back: ${JSON.stringify(back)}`);
+        const found = await store.requests("nautilus").find(r.id);
+        check(found?.key === key && found.request.id === r.id, `find: ${JSON.stringify(found)}`);
+        check((await store.requests("berry").get(key)) === null, "Berry Wallet does not see a Nautilus request");
+        check((await store.requests("berry").find(r.id)) === null, "Berry Wallet does not find a Nautilus request");
+        check((await store.requests("nautilus").get(hex(12345, 32))) === null, "an unknown key is null");
+    });
+    add("NanChat's request (when the game turns NanChat on) is kept under the hash of its nonce and found by the browser's id, for NanChat only", async ({ store }, now) => {
+        const { r } = request(now);
+        const key = hex(424242);
+        await store.requests("nanchat").create(key, { ...r, id: "AbCdEfGhIjKlMnOpQrStUvWx" });
+        check((await store.requests("nanchat").find("AbCdEfGhIjKlMnOpQrStUvWx"))?.key === key, "found by the browser's id");
+        check((await store.requests("berry").find("AbCdEfGhIjKlMnOpQrStUvWx")) === null, "Berry Wallet does not find a NanChat request");
+    });
+    add("a second request with the same key is refused", async ({ store }, now) => {
+        const { key, r } = request(now);
+        await store.requests("berry").create(key, r);
+        let threw = false;
+        try {
+            await store.requests("berry").create(key, { ...r, starter: hex(1) });
+        }
+        catch {
+            threw = true;
+        }
+        check(threw, "the second create throws");
+        check((await store.requests("berry").get(key))?.starter === r.starter, "the first request is unchanged");
+    });
+    add("finish signs a waiting request in once, with its account; a second finish, one on an unknown key, or one by the other wallet app is false", async ({ store }, now) => {
+        const { key, r } = request(now);
+        await store.requests("berry").create(key, r);
+        check(await store.requests("berry").finish(key, OWNER), "the first finish");
+        check(!(await store.requests("berry").finish(key, who("bob"))), "a second finish is false");
+        const back = await store.requests("berry").get(key);
+        check(back?.status === "signedin" && back.account === OWNER, `the account stays the first: ${JSON.stringify(back)}`);
+        check(!(await store.requests("berry").finish(hex(777, 32), OWNER)), "an unknown key");
+        check(!(await store.requests("nautilus").finish(key, OWNER)), "the other wallet app cannot finish it");
+    });
+    add("two finishes at the same moment: exactly one is true", async ({ store }, now) => {
+        const { key, r } = request(now);
+        await store.requests("berry").create(key, r);
+        const both = await Promise.all([store.requests("berry").finish(key, OWNER), store.requests("berry").finish(key, who("bob"))]);
+        check(both.filter(Boolean).length === 1, `results: ${JSON.stringify(both)}`);
+    });
+    add("deliver: false while waiting; then once, with its session; a second delivery writes no session", async ({ store }, now) => {
+        const { key, r } = request(now);
+        await store.requests("berry").create(key, r);
+        const early = session(now, 1);
+        check(!(await store.deliver("berry", key, early)), "a waiting request is not delivered");
+        check((await store.session(early.idHash, now)) === null, "and no session was written");
+        await store.requests("berry").finish(key, OWNER);
+        const s1 = session(now, 2);
+        check(await store.deliver("berry", key, s1), "the first delivery");
+        const read = await store.session(s1.idHash, now);
+        check(read?.address === OWNER && read.via === "wallet" && read.expiresAt === s1.expiresAt && read.createdAt === s1.createdAt && read.idHash === s1.idHash, `the session: ${JSON.stringify(read)}`);
+        const s2 = session(now, 3);
+        check(!(await store.deliver("berry", key, s2)), "a second delivery is false");
+        check((await store.session(s2.idHash, now)) === null, "and wrote no session");
+        check(!(await store.deliver("nautilus", key, session(now, 4))), "the other wallet app cannot deliver it");
+        check(!(await store.deliver("berry", hex(888, 32), session(now, 5))), "an unknown key");
+    });
+    add("two deliveries at the same moment: one is true, and one session is written", async ({ store, dump }, now) => {
+        const { key, r } = request(now);
+        await store.requests("nautilus").create(key, r);
+        await store.requests("nautilus").finish(key, OWNER);
+        const a = session(now, 10);
+        const b = session(now, 11);
+        const both = await Promise.all([store.deliver("nautilus", key, a), store.deliver("nautilus", key, b)]);
+        check(both.filter(Boolean).length === 1, `results: ${JSON.stringify(both)}`);
+        const live = [await store.session(a.idHash, now), await store.session(b.idHash, now)].filter(Boolean);
+        check(live.length === 1, `sessions written: ${live.length} (${(await dump()).slice(0, 300)})`);
+    });
+    add("a session reads while it lasts and not from its end, with the word it was written with; ending it removes it", async ({ store }, now) => {
+        for (const [i, via] of ["wallet", "ticket"].entries()) {
+            const { key, r } = request(now);
+            await store.requests("berry").create(key, r);
+            await store.requests("berry").finish(key, OWNER);
+            const s = session(now, 20 + i, via);
+            await store.deliver("berry", key, s);
+            const read = await store.session(s.idHash, now);
+            check(read?.address === OWNER && read.via === via, `read: ${JSON.stringify(read)} (a store returns the word it holds; the sign-in reads anything but "wallet" and "nanoterra" as "unknown")`);
+            check((await store.session(s.idHash, s.expiresAt)) === null, "not at its end");
+            check((await store.session(s.idHash, s.expiresAt + 1)) === null, "not after it");
+            await store.endSession(s.idHash);
+            check((await store.session(s.idHash, now)) === null, "ended");
+            await store.endSession(s.idHash);
+        }
+        check((await store.session(hex(999), now)) === null, "an unknown hash");
+    });
+    add("Sign out everywhere ends every admin session and says how many; a signed request that was not delivered, and a waiting one, make no login after it", async ({ store }, now) => {
+        const made = [];
+        for (let i = 0; i < 3; i++) {
+            const { key, r } = request(now);
+            await store.requests("berry").create(key, r);
+            await store.requests("berry").finish(key, OWNER);
+            const s = session(now, 30 + i);
+            await store.deliver("berry", key, s);
+            made.push(s);
+        }
+        const signed = request(now);
+        await store.requests("nautilus").create(signed.key, signed.r);
+        await store.requests("nautilus").finish(signed.key, OWNER);
+        const waiting = request(now);
+        await store.requests("berry").create(waiting.key, waiting.r);
+        check((await store.signOutEverywhere()) === 3, "three sessions went");
+        for (const s of made)
+            check((await store.session(s.idHash, now)) === null, "a session is left");
+        check(!(await store.deliver("nautilus", signed.key, session(now, 40))), "a signed request that was not delivered makes a login after Sign out everywhere");
+        const w = await store.requests("berry").get(waiting.key);
+        check(w === null || w.expiresAt <= now, `a waiting request must have ended (its time over), so a wallet's answer is refused: ${JSON.stringify(w)}`);
+        // Even if a wallet's answer were taken, the request is not delivered again.
+        await store.requests("berry").finish(waiting.key, OWNER);
+        check(!(await store.deliver("berry", waiting.key, session(now, 41))), "a request that was waiting at Sign out everywhere makes a login afterwards");
+        check((await store.signOutEverywhere()) === 0, "a second call ends nothing and says 0");
+    });
+    add("the sign-in list: newest first, at most the limit, only the time, the country and the browser; a row older than 30 days goes when the next is written", async ({ store, dump }, now) => {
+        check((await store.recentLogins(10)).length === 0, "a new store lists no sign-ins");
+        await store.recordLogin({ at: now - ADMIN_LOGIN_KEEP_MS - 60_000, country: "FR", browser: "Old" });
+        await store.recordLogin({ at: now - ADMIN_LOGIN_KEEP_MS + 86_400_000, country: "FR", browser: "Kept" });
+        for (let i = 0; i < 12; i++)
+            await store.recordLogin({ at: now - 1000 * (12 - i), country: i % 3 === 0 ? null : "US", browser: `Chrome on macOS ${i}` });
+        const got = await 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" && got[0].country === "US", `the first must be the newest: ${JSON.stringify(got[0])}`);
+        check(got.some((l) => l.country === null), "a sign-in with no country keeps null");
+        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 store.recentLogins(3)).length === 3, "the limit must hold");
+        check((await store.recentLogins(0)).length === 0, "a limit of 0 lists none");
+        const all = await store.recentLogins(50);
+        check(all.length === 13 && all.some((l) => l.browser === "Kept") && !all.some((l) => l.browser === "Old"), `the row of 31 days went, the row of 29 days stayed: ${all.map((l) => l.browser).join(", ")}`);
+        check(!(await dump()).includes("Old"), "the old row is gone from the store");
+    });
+    add("clean deletes requests 2 hours after they ended, ended sessions and sign-in rows past 30 days, and keeps the rest", async ({ store }, now) => {
+        const sessions = [];
+        for (const [i, at] of [now - 2 * 86_400_000, now].entries()) {
+            const { key, r } = request(at);
+            await store.requests("berry").create(key, r);
+            await store.requests("berry").finish(key, OWNER);
+            const s = session(at, 50 + i);
+            await store.deliver("berry", key, s);
+            sessions.push(s);
+        }
+        const old = request(now - 3 * 3_600_000);
+        const fresh = request(now);
+        await store.requests("berry").create(old.key, old.r);
+        await store.requests("berry").create(fresh.key, fresh.r);
+        await store.recordLogin({ at: now - ADMIN_LOGIN_KEEP_MS + 60_000, country: null, browser: "Edge on Windows" });
+        await store.clean(now + 120_000);
+        check((await store.session(sessions[1].idHash, now)) !== null, "the live session stays");
+        check((await store.session(sessions[0].idHash, now - 2 * 86_400_000)) === null, "the ended session went");
+        check((await store.requests("berry").get(old.key)) === null, "the old request went");
+        check((await store.requests("berry").get(fresh.key)) !== null, "the fresh request stays");
+        check((await store.recentLogins(10)).length === 0, "the sign-in row past 30 days went");
+    });
+    return cases;
+}

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

@@ -0,0 +1,62 @@
+import type { AdminLogin } from "../admin/store.js";
+import { type AdminSigninSession, type AdminSigninStore } from "./types.js";
+/** The address that belongs to nobody (its key is all zeros): Nautilus names it while the game has no address of its own. */
+export declare const EXAMPLE_ADDRESS = "nano_1111111111111111111111111111111111111111111111111111hifc8npp";
+export type AdminSigninOptions = {
+    store: AdminSigninStore;
+    /**
+     * The game's own address (the starter's RECEIVE_ADDRESS: "nano_...", lowercase, its checksum checked), or null when none is set. Only this address makes an
+     * admin login: a signature by any other wallet is answered "not_owner" and the request stays unused. Nautilus also NAMES it in its request and in the
+     * text it signs (no key, no payment); with none, the example address.
+     */
+    owner: string | null;
+    /** Where the routes are. Default "/api/admin-signin" (ADMIN_SIGNIN_BASE): keep it, so every page and helper finds the admin's sign-in at the same place. */
+    base?: string;
+    /** The admin page that Berry Wallet signs in to. Default "/admin". A path with no query: Berry refuses a query. */
+    page?: string;
+    /** The game's host exactly as people see it ("mygame.com"). Every signed text names it. Default: the host of each request. When it is set, a call to any other host is refused (403). */
+    domain?: string;
+    /**
+     * Offer NanChat for the admin. Default false: a NanChat start is refused ("NanChat cannot open the admin yet. Use Berry Wallet or Nautilus."). NanChat's
+     * text must start "Login to <host>" and cannot name the ADMIN, which is why it is off: the owner who is asked to sign cannot tell an admin sign-in from a
+     * game sign-in. Turn it on only when the owner accepts that; give the panel the same `nanchat: true`.
+     */
+    nanchat?: boolean;
+    /** The cookies' names. Default { session: "admin", starter: "starter-admin" } (the starter's). On https they get the __Host- prefix. */
+    cookies?: {
+        session?: string;
+        starter?: string;
+    };
+    /** The shared limiter of the starts: false means "too many". Default: a fixed window in this process's memory. */
+    limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+    /** The visitor's key for the limit of the starts: a keyed hash of the IP address, never the address. Default: the CF-Connecting-IP header as it is. */
+    visitor?: (request: Request) => Promise<string>;
+    /** The person check (Turnstile) of a start: true when `token` passes. No hook: no check. */
+    personCheck?: (token: unknown, request: Request) => Promise<boolean>;
+    /** The time now in ms. Default Date.now. */
+    now?: () => number;
+    /** Told about a fault (a store). The visitor gets a plain 500 and never sees it. */
+    onError?: (e: unknown) => void;
+};
+export type AdminSignin = {
+    base: string;
+    /** Answers a route of the admin's sign-in, or null when the request is not one. */
+    handle(request: Request): Promise<Response | null>;
+    /** The ADMIN login of this request (the admin cookie only), or null: give it to `createAdminHandler` as its `session`. Never a player's login. */
+    session(request: Request, now?: number): Promise<AdminSigninSession | null>;
+    /** Ends this request's admin login only and returns the Set-Cookie value that clears the cookie (the game's own login, another person's perhaps, stays). */
+    signOut(request: Request): Promise<string>;
+    /** "Sign out everywhere": every admin login and every admin request not yet delivered. Give it to the admin store (`signOutEverywhere`) when the store has none. */
+    signOutEverywhere(): Promise<number>;
+    /** The last admin sign-ins, newest first. Give it to the admin store (`recentLogins`) when the store has none. */
+    recentLogins(limit: number): Promise<AdminLogin[]>;
+    /** The clean-up (a cron): old admin requests, ended admin sessions, sign-in rows past 30 days. */
+    clean(now?: number): Promise<void>;
+};
+/**
+ * What the database keeps of an admin session or of an admin request's starter: the hash of the value with a prefix. So the SERVER (not only the cookie's
+ * name) keeps the two scopes apart: a token made for the game (the player sign-in keeps its plain hash) does not open /admin even if it is put in the admin
+ * cookie, and a starter value copied from the game's cookie does not finish an admin request.
+ */
+export declare const adminKey: (value: string) => Promise<string>;
+export declare function createAdminSignin(options: AdminSigninOptions): AdminSignin;