@nano133/nanoterra 0.10.1 → 0.11.0

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;

package/dist/admin-signin/handler.js

@@ -0,0 +1,360 @@
+// The routes of the ADMIN's sign-in, on the Web `Request` and `Response` types (a Worker, Firebase Functions, Node). The game starter's admin sign-in
+// (its src/worker/signin.ts), moved into the package with every check and every signed text as the starter has them; only the paths are new, and the same
+// in every game:
+//
+//   POST {base}/start          the browser starts an admin request: { way, turnstile? } → { way, id, link, walletLink?, code?, expiresAt } and the starter cookie
+//   GET  {base}/nano/:id       Berry Wallet reads the request (no cookie, no Origin)
+//   POST {base}/nano/:id       Berry Wallet posts its signature: 204 with no body when accepted, 401 and the words when refused
+//   POST {base}/nautilus?id=   Nautilus posts its signature: always 200 (Nautilus shows only a 200's words)
+//   POST {base}/nanchat        NanChat's relay server posts the signature (only with `nanchat: true`): always 200, a refusal starts "NOT signed in"
+//   POST {base}/check          the browser asks every 2 seconds: { id, way } → { status: "waiting" | "expired" | "elsewhere" | "used" | "not_owner" | "signedin", address? }
+//   POST {base}/signout        ends this browser's admin login only: { ok: true }
+//
+// `base` is "/api/admin-signin" (ADMIN_SIGNIN_BASE). Berry Wallet and Nautilus sign a text that names the ADMIN: Berry signs the page `${origin}/admin`
+// with NO query (Berry refused "/admin?from=US" with "Sign-in requires a public HTTPS website", device test 2026-10-27), Nautilus signs the label "ADMIN of
+// <host> sign-in ABCD-EFGH from <country>" and shows "Sign in to the ADMIN of <host>. Started <time> UTC from <country>. If you did not start this, do not
+// sign." NanChat is OFF by default and refused with the starter's words: its text must start "Login to <host>" and CANNOT name the ADMIN, so the owner
+// who is asked to sign sees what looks like any sign-in to the game. A game may turn it on (`nanchat: true`); it then signs "Login to <host>" as a
+// player's NanChat sign-in does, and the admin's own checks (the starter cookie, the owner, once) are the same. A request lives 2 minutes, is
+// delivered for one more minute, and works once.
+//
+// Two logins, two cookies: the game's (`session`, the player sign-in's) and the admin's (`admin`; `__Host-admin` on https, HttpOnly, SameSite=Lax, one
+// day), so the game and /admin can have different people signed in at once. The database keeps `adminKey(token)`, the SHA-256 of "admin:" and the token,
+// and a player's session keeps the plain hash: a player's token put in the admin cookie opens nothing, and a starter value copied from the player's cookie
+// finishes no admin request. Only the game's own address (`owner`) makes an admin login. DO NOT CHANGE the checks in this file: they are what makes the
+// admin page the creator's.
+import { answerNanchat, answerNanoSignin, answerNautilus, checkNanchat, checkNanoSignin, checkNautilus, nanchatNonce, nanchatReply, NANO_SIGNIN_ACCEPTED, nanoSigninRefusal, nautilusReply, readNanoSignin, startNanchat, startNanoSignin, startNautilus, validAddress, WalletRefused, } from "@nano133/signin";
+import { ADMIN_SESSION_MS } from "../admin/guard.js";
+import { fail, json, memoryLimiter, readLimited, sameOrigin } from "../admin/http.js";
+import { countryOf, shortBrowser } from "./browser.js";
+import { ADMIN_DELIVER_MS, ADMIN_PAGE, ADMIN_REQUEST_MS, ADMIN_SIGNIN_BASE, ADMIN_SIGNIN_LIMITS, ADMIN_STARTER_MAX_AGE_S, ADMIN_WAYS, NANCHAT_REFUSAL, TOKEN_PATTERN, } 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 const EXAMPLE_ADDRESS = "nano_1111111111111111111111111111111111111111111111111111hifc8npp";
+const hex = (b) => Array.from(b instanceof Uint8Array ? b : new Uint8Array(b), (x) => x.toString(16).padStart(2, "0")).join("");
+const sha256Hex = async (text) => hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+const randomHex = (bytes) => hex(crypto.getRandomValues(new Uint8Array(bytes)));
+/**
+ * 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 const adminKey = (value) => sha256Hex(`admin:${value}`);
+/** Only a space or a tab around a cookie's name or value is dropped (JS trim() also drops Unicode spaces, which would let another name pass for ours). */
+const trimAscii = (s) => s.replace(/^[ \t]+|[ \t]+$/g, "");
+function cookieValue(req, name) {
+    for (const part of (req.headers.get("Cookie") ?? "").split(";")) {
+        const i = part.indexOf("=");
+        if (i > 0 && trimAscii(part.slice(0, i)) === name) {
+            try {
+                return decodeURIComponent(trimAscii(part.slice(i + 1)));
+            }
+            catch {
+                // Not valid percent-coding: not ours.
+            }
+        }
+    }
+    return null;
+}
+const isHttps = (req) => new URL(req.url).protocol === "https:";
+/** A cookie for this site only: on https it gets the __Host- prefix and Secure (the starter's exact form). */
+function cookieHeader(req, name, value, maxAgeSec) {
+    const https = isHttps(req);
+    return `${https ? "__Host-" : ""}${name}=${encodeURIComponent(value)}; Path=/; Max-Age=${maxAgeSec}; HttpOnly; SameSite=Lax${https ? "; Secure" : ""}`;
+}
+/** A cookie's value: on https only the `__Host-` name (a sibling subdomain can set the plain one; it cannot set a `__Host-` one). */
+const readCookie = (req, name) => cookieValue(req, isHttps(req) ? `__Host-${name}` : name);
+/** The limiters live at module level: a Worker makes the sign-in for each request, and a limiter made inside it would forget every call. */
+const fallbackLimit = memoryLimiter();
+const memory = memoryLimiter();
+export function createAdminSignin(options) {
+    const base = options.base ?? ADMIN_SIGNIN_BASE;
+    if (!base.startsWith("/") || base.length < 2 || base.endsWith("/"))
+        throw new Error('a path must start with "/" and not end with "/", like "/api/admin-signin"');
+    const page = options.page ?? ADMIN_PAGE;
+    if (!/^\/[A-Za-z0-9._~\-/]*$/.test(page))
+        throw new Error('the admin page is a path with no query, like "/admin"');
+    const store = options.store;
+    const sessionName = options.cookies?.session ?? "admin";
+    const starterName = options.cookies?.starter ?? "starter-admin";
+    for (const n of [sessionName, starterName])
+        if (!/^[A-Za-z0-9_-]{1,40}$/.test(n))
+            throw new Error("a cookie's name is letters, digits, _ and - only");
+    if (sessionName === starterName)
+        throw new Error("the session cookie and the starter cookie need two names");
+    const owner = options.owner;
+    const now = options.now ?? (() => Date.now());
+    const limit = options.limit ?? fallbackLimit;
+    const siteAddress = owner && validAddress(owner) ? owner : EXAMPLE_ADDRESS;
+    const nanchatOn = options.nanchat === true;
+    const report = (e) => {
+        try {
+            options.onError?.(e);
+        }
+        catch {
+            // nothing more can be done
+        }
+    };
+    const ipOf = (req) => req.headers.get("CF-Connecting-IP") ?? "anyone";
+    const visitorOf = async (req) => (options.visitor ? await options.visitor(req) : ipOf(req));
+    const person = async (token, req) => (options.personCheck ? options.personCheck(token, req) : true);
+    /**
+     * The sign-in options of each wallet app for this request's site: the domain and page come from the address the owner opened (or `domain`). `admin` is
+     * given for a START: the request's life is 2 minutes, and Nautilus's label and line name the admin and the place the request started. Berry Wallet's text
+     * names the admin through its page, for every call (each request this sign-in holds is an admin request), so the wallet's GET and POST get the same text.
+     */
+    function wallets(req, at, admin) {
+        const url = new URL(req.url);
+        const host = options.domain ?? url.host;
+        const origin = `${url.protocol}//${host}`;
+        const clock = { now: () => at };
+        const life = admin ? { ttlMs: ADMIN_REQUEST_MS } : {};
+        const started = new Date(at).toISOString().slice(11, 16);
+        const adminLine = `Sign in to the ADMIN of ${host}. Started ${started} UTC from ${admin?.country ?? "an unknown country"}. If you did not start this, do not sign.`;
+        return {
+            host,
+            berry: { domain: host, uri: `${origin}${page}`, store: store.requests("berry"), ...life, ...clock },
+            nautilus: {
+                site: host,
+                siteAddress,
+                store: store.requests("nautilus"),
+                ...(admin ? { title: `ADMIN of ${host}`, ...(admin.country ? { note: `from ${admin.country}` } : {}), message: adminLine } : {}),
+                ...life,
+                ...clock,
+            },
+            // NanChat's text is "Login to <host> nonce: <nonce>": it has no place for the admin's name.
+            nanchat: { host, store: store.requests("nanchat"), ...life, ...clock },
+            nanchatUrl: `${origin}${base}/nanchat`,
+            requestUrl: (id) => `${origin}${base}/nano/${id}`,
+            nautilusUrl: (id) => `${origin}${base}/nautilus?id=${id}`,
+        };
+    }
+    /** A JSON body of at most 8 KB, or null when it is not one readable object. */
+    async function body(req) {
+        const text = await readLimited(req, ADMIN_SIGNIN_LIMITS.bodyMax);
+        if (text === null)
+            return null;
+        if (!text)
+            return {};
+        try {
+            const v = JSON.parse(text);
+            return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The way a call names; Berry Wallet when it names none. Null for anything else. NanChat is a way even when it is off, so that it is refused with its own words. */
+    const wayOf = (v) => (v === undefined ? "berry" : (ADMIN_WAYS.find((w) => w === v) ?? null));
+    async function start(req, b, at) {
+        const way = wayOf(b.way);
+        if (!way)
+            return fail(400, "That wallet is not one of this game's.");
+        if (!(await limit(`signin|${await visitorOf(req)}`, ADMIN_SIGNIN_LIMITS.signin.limit, ADMIN_SIGNIN_LIMITS.signin.windowMs, at)))
+            return fail(429, "Too many sign-ins. Wait a few minutes.");
+        if (!(await person(b.turnstile, req)))
+            return fail(403, "The person check failed. Try again.");
+        const admin = { country: countryOf(req) };
+        // NanChat cannot name the admin in what it signs (its text must start "Login to <host>"): an admin request through it would look like any sign-in to
+        // the owner who is asked to sign. So it is refused unless the game turned it on.
+        if (way === "nanchat" && !nanchatOn)
+            return fail(400, NANCHAT_REFUSAL);
+        const starter = randomHex(32);
+        const hash = await adminKey(starter);
+        const w = wallets(req, at, admin);
+        let out;
+        if (way === "nautilus") {
+            const s = await startNautilus(w.nautilus, { starter: hash, answerUrl: w.nautilusUrl });
+            out = { way, id: s.id, link: s.link, code: s.code, expiresAt: s.expiresAt };
+        }
+        else if (way === "nanchat") {
+            const s = await startNanchat(w.nanchat, { starter: hash, answerUrl: w.nanchatUrl });
+            out = { way, id: s.id, link: s.link, expiresAt: s.expiresAt };
+        }
+        else {
+            // `label` keeps where the request started ("admin:US"), as the starter wrote it: a starter that reads these rows sees an admin request it knows.
+            const s = await startNanoSignin(w.berry, { starter: hash, requestUrl: w.requestUrl, label: admin.country ? `admin:${admin.country}` : "admin" });
+            out = { way, id: s.id, link: s.link, walletLink: s.walletLink, expiresAt: s.expiresAt };
+        }
+        return json(out, 200, { "Set-Cookie": cookieHeader(req, starterName, starter, ADMIN_STARTER_MAX_AGE_S) });
+    }
+    /**
+     * The browser's check of an admin request. When it is signed and this browser started it ("mine"), a NEW admin session is made, once per request, and
+     * its cookie is set.
+     */
+    async function check(req, b, at) {
+        const way = wayOf(b.way);
+        if (!way)
+            return fail(400, "That wallet is not one of this game's.");
+        if (typeof b.id !== "string")
+            return fail(400, "no request id");
+        const cookie = readCookie(req, starterName);
+        // The starter cookie is what this sign-in made: 32 random bytes as 64 hex characters. A value of any other shape (one with a prefix of the other scope's hashing, for example) is no starter.
+        const starter = cookie && TOKEN_PATTERN.test(cookie) ? await adminKey(cookie) : undefined;
+        // While NanChat is off the admin starts no NanChat request: there is none to deliver.
+        if (way === "nanchat" && !nanchatOn)
+            return json({ status: "expired" });
+        // An admin request is delivered for a minute after it ends.
+        const o = { store: store.requests(way), now: () => at, deliverMs: ADMIN_DELIVER_MS };
+        const r = way === "nautilus" ? await checkNautilus(o, b.id, starter) : way === "nanchat" ? await checkNanchat(o, b.id, starter) : await checkNanoSignin(o, b.id, starter);
+        if (r.status !== "signedin")
+            return json({ status: r.status });
+        if (!r.mine || !r.account)
+            return json({ status: "elsewhere" });
+        // An admin login is for the game's own address only. A wallet that is not it makes no admin login (and does not end the owner's, which is in a cookie
+        // of its own), and the request stays unused.
+        if (r.account !== owner)
+            return json({ status: "not_owner", address: r.account });
+        // Deliver once: a second check of the same request makes no second session. The delivery and the session are ONE step of the store, and the session is
+        // written only when the delivery changed the request. So "Sign out everywhere" cannot run between them: it either ends the request first (nothing is
+        // delivered, no session) or deletes the session after.
+        const token = randomHex(32);
+        const record = { idHash: await adminKey(token), address: r.account, createdAt: at, expiresAt: at + ADMIN_SESSION_MS, via: "wallet" };
+        if (!(await store.deliver(way, r.key ?? b.id, record)))
+            return json({ status: "used" });
+        // The admin's sign-in list: the time, the rough country and a short browser name of THIS browser (the one that started the request and now gets the login). Nothing else.
+        await store.recordLogin({ at, country: countryOf(req), browser: shortBrowser(req.headers.get("User-Agent")) });
+        return json({ status: "signedin", address: r.account }, 200, { "Set-Cookie": cookieHeader(req, sessionName, token, ADMIN_SESSION_MS / 1000) });
+    }
+    /** Berry Wallet's GET and POST. They come from the wallet app, so there is no cookie and no Origin to check. */
+    async function berry(req, id, at) {
+        const w = wallets(req, at);
+        if (req.method === "GET") {
+            const request = await readNanoSignin(w.berry, id, w.requestUrl);
+            return request ? json(request) : json(nanoSigninRefusal("This sign-in expired."), 404);
+        }
+        const b = await body(req);
+        if (!b)
+            return json(nanoSigninRefusal("This answer is not readable."), 401);
+        try {
+            await answerNanoSignin(w.berry, id, b, w.requestUrl);
+            // Berry Wallet shows its success screen only for a 204 with no body.
+            return new Response(null, { status: NANO_SIGNIN_ACCEPTED, headers: { "Cache-Control": "no-store" } });
+        }
+        catch (e) {
+            if (e instanceof WalletRefused)
+                return json(nanoSigninRefusal(e.message), 401);
+            throw e;
+        }
+    }
+    /** Nautilus's answer. It comes from the app: no cookie, no Origin. Nautilus shows the words only with HTTP 200. */
+    async function nautilus(req, at) {
+        const w = wallets(req, at);
+        const b = await body(req);
+        if (!b)
+            return json(nautilusReply(w.host, "That answer could not be read."));
+        try {
+            await answerNautilus(w.nautilus, new URL(req.url).searchParams.get("id") ?? "", b);
+            return json(nautilusReply(w.host));
+        }
+        catch (e) {
+            if (e instanceof WalletRefused)
+                return json(nautilusReply(w.host, e.message));
+            throw e;
+        }
+    }
+    /** NanChat's answer (only while it is on): its relay server posts every one, so the limits are totals and per nonce, never per visitor. Always 200: NanChat shows the words. */
+    async function nanchat(req, at) {
+        const w = wallets(req, at);
+        const refuse = (words) => json(nanchatReply(w.host, words));
+        if (!memory(`${base}|nanchat`, ADMIN_SIGNIN_LIMITS.nanchatRoute.limit, ADMIN_SIGNIN_LIMITS.nanchatRoute.windowMs, at))
+            return refuse("too many sign-ins at once. Wait a minute.");
+        const b = await body(req);
+        if (!b)
+            return refuse("that answer could not be read.");
+        const nonce = nanchatNonce(w.host, b.message);
+        if (nonce && typeof b.account === "string" && typeof b.signature === "string" && /^[0-9A-Fa-f]{128}$/.test(b.signature)) {
+            if (!(await limit("admin-nanchat|all", ADMIN_SIGNIN_LIMITS.nanchatAll.limit, ADMIN_SIGNIN_LIMITS.nanchatAll.windowMs, at)))
+                return refuse("too many sign-ins at once. Wait a few minutes.");
+            if (!(await limit(`admin-nanchat|${nonce}`, ADMIN_SIGNIN_LIMITS.nanchatNonce.limit, ADMIN_SIGNIN_LIMITS.nanchatNonce.windowMs, at)))
+                return refuse(`too many tries for this sign-in. Start again on ${w.host}.`);
+        }
+        try {
+            await answerNanchat(w.nanchat, b);
+            return json(nanchatReply(w.host));
+        }
+        catch (e) {
+            if (e instanceof WalletRefused)
+                return refuse(e.message);
+            throw e;
+        }
+    }
+    async function sessionOf(req, at = now()) {
+        const token = readCookie(req, sessionName);
+        if (!token || !TOKEN_PATTERN.test(token))
+            return null;
+        // The scope is in the store's row (the adapter reads only admin rows) as well as in the hash: the two scopes stay apart in two ways.
+        const s = await store.session(await adminKey(token), at);
+        // Only the two words a login can carry are read; any other is "unknown", never a wallet login (a fail-open map would turn a stray value into a login that opens /admin).
+        return s ? { address: s.address, createdAt: s.createdAt, via: s.via === "wallet" || s.via === "nanoterra" ? s.via : "unknown" } : null;
+    }
+    async function signOut(req) {
+        const token = readCookie(req, sessionName);
+        if (token)
+            await store.endSession(await adminKey(token));
+        return cookieHeader(req, sessionName, "", 0);
+    }
+    async function handle(req) {
+        const url = new URL(req.url);
+        const path = url.pathname;
+        const berryId = path.startsWith(`${base}/nano/`) ? /^[0-9a-f]{32}$/.exec(path.slice(base.length + 6))?.[0] : undefined;
+        const mine = berryId !== undefined || [`${base}/start`, `${base}/check`, `${base}/signout`, `${base}/nautilus`].includes(path) || (nanchatOn && path === `${base}/nanchat`);
+        if (!mine)
+            return null;
+        try {
+            if (options.domain && url.host !== options.domain)
+                return fail(403, `This sign-in belongs to ${options.domain}.`);
+            const at = now();
+            const ip = ipOf(req);
+            // The wallet apps' routes: no cookie and no Origin (an app posts them, not a browser page).
+            if (berryId !== undefined) {
+                if (req.method !== "GET" && req.method !== "POST")
+                    return fail(405, "Not allowed.", {}, { Allow: "GET, POST" });
+                if (!memory(`${base}|wallet|${ip}`, ADMIN_SIGNIN_LIMITS.wallet.limit, ADMIN_SIGNIN_LIMITS.wallet.windowMs, at))
+                    return fail(429, "Too many requests.");
+                return await berry(req, berryId, at);
+            }
+            if (path === `${base}/nautilus`) {
+                if (req.method !== "POST")
+                    return fail(405, "Not allowed.", {}, { Allow: "POST" });
+                // Nautilus shows the words of a refusal only with HTTP 200.
+                if (!memory(`${base}|wallet|${ip}`, ADMIN_SIGNIN_LIMITS.wallet.limit, ADMIN_SIGNIN_LIMITS.wallet.windowMs, at))
+                    return json(nautilusReply(wallets(req, at).host, "Too many requests. Wait a minute."));
+                return await nautilus(req, at);
+            }
+            if (path === `${base}/nanchat`) {
+                if (req.method !== "POST")
+                    return fail(405, "Not allowed.", {}, { Allow: "POST" });
+                return await nanchat(req, at);
+            }
+            // The browser's own calls: a POST from the game's own page.
+            if (req.method !== "POST")
+                return fail(405, "Not allowed.", {}, { Allow: "POST" });
+            if (path === `${base}/check` && !memory(`${base}|poll|${ip}`, ADMIN_SIGNIN_LIMITS.poll.limit, ADMIN_SIGNIN_LIMITS.poll.windowMs, at))
+                return fail(429, "Too many requests. Wait a minute.");
+            if (!sameOrigin(req))
+                return fail(403, "This call must come from the game's own page.");
+            // A sign-out reads no body.
+            if (path === `${base}/signout`)
+                return json({ ok: true }, 200, { "Set-Cookie": await signOut(req) });
+            const b = await body(req);
+            if (!b)
+                return fail(400, "That request is not readable.");
+            if (path === `${base}/check`)
+                return await check(req, b, at);
+            return await start(req, b, at);
+        }
+        catch (e) {
+            report(e);
+            return fail(500, "Something went wrong. Try again.");
+        }
+    }
+    return {
+        base,
+        handle,
+        session: sessionOf,
+        signOut,
+        signOutEverywhere: () => store.signOutEverywhere(),
+        recentLogins: (n) => store.recentLogins(n),
+        clean: (at = now()) => store.clean(at),
+    };
+}

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

@@ -0,0 +1,8 @@
+export { EXAMPLE_ADDRESS, adminKey, createAdminSignin } from "./handler.js";
+export type { AdminSignin, AdminSigninOptions } from "./handler.js";
+export { createMemoryAdminSignin } from "./memory.js";
+export type { MemoryAdminSignin } from "./memory.js";
+export { countryOf, shortBrowser } from "./browser.js";
+export { ADMIN_DELIVER_MS, ADMIN_LOGIN_KEEP_MS, ADMIN_PAGE, ADMIN_REQUEST_MS, ADMIN_SIGNIN_BASE, ADMIN_SIGNIN_LIMITS, ADMIN_STARTER_MAX_AGE_S, ADMIN_WAYS, NANCHAT_REFUSAL, } from "./types.js";
+export type { AdminSessionRecord, AdminSigninSession, AdminSigninStore, AdminWay, RequestStoreLike, SigninRequest } from "./types.js";
+export { ADMIN_SESSION_MS } from "../admin/guard.js";