@nano133/nanoterra 0.8.1 → 0.9.0

package/dist/player-signin/adapters/d1.js

@@ -0,0 +1,108 @@
+// The player sign-in's store for a game on Cloudflare D1. The tables are in ./d1.sql (the package ships it: "@nano133/nanoterra/player-signin/d1.sql");
+// add it to the game's migrations. They are the game starter's own `signin_requests` and `sessions` (so a starter's data carries over: every
+// player stays signed in) and one more, `signin_once`.
+//
+//   import { createD1PlayerSignin } from "@nano133/nanoterra/player-signin/d1";
+//   const store = createD1PlayerSignin(env.DB);
+//
+// It reads and writes ONLY the player's rows (scope = 'play'): a game whose admin signs in through the same tables (the starter's scope 'admin')
+// keeps its admin rows, and this adapter never reads, delivers, ends or deletes one. D1 has no transaction that reads and then writes, so each change
+// is ONE statement that holds its own check, and a delivery and its session are one batch (the session is written only when the delivery changed a row).
+import { WAYS } from "../types.js";
+const toRequest = (r) => ({
+    id: r.rid ?? r.id,
+    starter: r.starter,
+    status: r.status === "signedin" ? "signedin" : "waiting",
+    expiresAt: Number(r.expires_at),
+    ...(r.label ? { label: r.label } : {}),
+    ...(r.nonce ? { nonce: r.nonce } : {}),
+    ...(r.issued_at ? { issuedAt: Number(r.issued_at) } : {}),
+    ...(r.account ? { account: r.account } : {}),
+});
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+const changes = (res) => Number(res?.meta?.changes ?? 0);
+export function createD1PlayerSignin(db, tables = {}) {
+    const T = { requests: tables.requests ?? "signin_requests", sessions: tables.sessions ?? "sessions", once: tables.once ?? "signin_once" };
+    for (const n of Object.values(T))
+        if (!NAME.test(n))
+            throw new Error(`not a table name: ${n}`);
+    const COLS = "id, rid, starter, status, expires_at, nonce, issued_at, label, account";
+    const stores = new Map();
+    for (const way of WAYS) {
+        stores.set(way, {
+            async create(key, r) {
+                await db
+                    .prepare(`INSERT INTO ${T.requests} (id, rid, way, starter, status, expires_at, nonce, issued_at, label, scope) VALUES (?, ?, ?, ?, 'waiting', ?, ?, ?, ?, 'play')`)
+                    .bind(key, r.id, way, r.starter, r.expiresAt, r.nonce ?? null, r.issuedAt ?? null, r.label ?? null)
+                    .run();
+            },
+            async get(key) {
+                const r = await db.prepare(`SELECT ${COLS} FROM ${T.requests} WHERE id = ? AND way = ? AND scope = 'play'`).bind(key, way).first();
+                return r ? toRequest(r) : null;
+            },
+            async find(id) {
+                const r = await db.prepare(`SELECT ${COLS} FROM ${T.requests} WHERE rid = ? AND way = ? AND scope = 'play'`).bind(id, way).first();
+                return r ? { key: r.id, request: toRequest(r) } : null;
+            },
+            async finish(key, account) {
+                return changes(await db.prepare(`UPDATE ${T.requests} SET status = 'signedin', account = ? WHERE id = ? AND way = ? AND status = 'waiting' AND scope = 'play'`).bind(account, key, way).run()) === 1;
+            },
+        });
+    }
+    const insertSession = (s, afterChange) => {
+        const cols = `INSERT INTO ${T.sessions} (id_hash, address, created_at, expires_at, via, scope)`;
+        return db.prepare(afterChange ? `${cols} SELECT ?, ?, ?, ?, ?, 'play' WHERE changes() = 1` : `${cols} VALUES (?, ?, ?, ?, ?, 'play')`).bind(s.idHash, s.address, s.createdAt, s.expiresAt, s.via);
+    };
+    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 done = await db.batch([
+                db.prepare(`UPDATE ${T.requests} SET delivered = 1 WHERE id = ? AND way = ? AND delivered = 0 AND status = 'signedin' AND scope = 'play'`).bind(key, way),
+                insertSession(session, true),
+            ]);
+            return changes(done[0]) === 1;
+        },
+        async createSession(session) {
+            await insertSession(session, false).run();
+        },
+        async session(idHash, now) {
+            const r = await db
+                .prepare(`SELECT id_hash, address, created_at, expires_at, via FROM ${T.sessions} WHERE id_hash = ? AND expires_at > ? AND scope = 'play'`)
+                .bind(idHash, now)
+                .first();
+            return r ? { idHash: r.id_hash, address: r.address, createdAt: Number(r.created_at), expiresAt: Number(r.expires_at), via: r.via } : null;
+        },
+        async endSession(idHash) {
+            await db.prepare(`DELETE FROM ${T.sessions} WHERE id_hash = ? AND scope = 'play'`).bind(idHash).run();
+        },
+        async useOnce(key, ttlMs, address) {
+            const now = Date.now();
+            // A row past its time may be taken again (its signature's 5 minutes are long over); a live one may not.
+            const res = await db
+                .prepare(`INSERT INTO ${T.once} (key, address, until) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET address = excluded.address, until = excluded.until WHERE ${T.once}.until <= ?`)
+                .bind(key, address, now + ttlMs, now)
+                .run();
+            return changes(res) === 1;
+        },
+        async forget(address) {
+            const done = await db.batch([
+                db.prepare(`DELETE FROM ${T.sessions} WHERE address = ? AND scope = 'play'`).bind(address),
+                db.prepare(`DELETE FROM ${T.requests} WHERE account = ? AND scope = 'play'`).bind(address),
+                db.prepare(`DELETE FROM ${T.once} WHERE address = ?`).bind(address),
+            ]);
+            return done.reduce((n, r) => n + changes(r), 0);
+        },
+        async clean(now) {
+            await db.batch([
+                db.prepare(`DELETE FROM ${T.requests} WHERE expires_at < ? AND scope = 'play'`).bind(now - 2 * 3_600_000),
+                db.prepare(`DELETE FROM ${T.sessions} WHERE expires_at <= ? AND scope = 'play'`).bind(now),
+                db.prepare(`DELETE FROM ${T.once} WHERE until <= ?`).bind(now),
+            ]);
+        },
+    };
+}

package/dist/player-signin/adapters/firestore.d.ts

@@ -0,0 +1,45 @@
+import { type PlayerSigninStore } from "../types.js";
+export type PlayerSigninDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface PlayerSigninDocRef {
+    get(): Promise<PlayerSigninDocSnap>;
+}
+export type PlayerSigninQuerySnap = {
+    docs: {
+        id: string;
+        ref: PlayerSigninDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface PlayerSigninQuery {
+    where(field: string, op: "==" | "<" | "<=", value: unknown): PlayerSigninQuery;
+    limit(n: number): PlayerSigninQuery;
+    get(): Promise<PlayerSigninQuerySnap>;
+}
+export interface PlayerSigninCollection extends PlayerSigninQuery {
+    doc(id: string): PlayerSigninDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface PlayerSigninTransaction {
+    get(ref: PlayerSigninDocRef): Promise<PlayerSigninDocSnap>;
+    set(ref: PlayerSigninDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: PlayerSigninDocRef): unknown;
+}
+export interface PlayerSigninBatch {
+    delete(ref: PlayerSigninDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestorePlayerSigninLike {
+    collection(name: string): PlayerSigninCollection;
+    runTransaction<T>(fn: (tx: PlayerSigninTransaction) => Promise<T>): Promise<T>;
+    batch(): PlayerSigninBatch;
+}
+export declare function createFirestorePlayerSignin(db: FirestorePlayerSigninLike, collections?: {
+    requests?: string;
+    sessions?: string;
+    once?: string;
+}): PlayerSigninStore;

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

@@ -0,0 +1,168 @@
+// The player 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 player's documents (scope "play").
+//
+//   import { createFirestorePlayerSignin } from "@nano133/nanoterra/player-signin/firestore";
+//   const store = createFirestorePlayerSignin(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: "play", deleteAt }
+//   sessions/{idHash}       { address, createdAt, expiresAt, via, scope: "play", deleteAt }
+//   signin_once/{key}       { address, until, 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 (Berry Wallet, Nautilus) or the SHA-256 of its nonce (NanChat); `{idHash}` the SHA-256 of the session's token. Every change that reads first is a
+// transaction. Indexes: Firestore's own single-field indexes are enough (`id`, `address`, `account`, `expiresAt`, `until`).
+import { 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);
+function requestOf(d, key, way) {
+    if (!d || d.scope !== "play" || 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 createFirestorePlayerSignin(db, collections = {}) {
+    const requestsCol = () => db.collection(collections.requests ?? "signin_requests");
+    const sessionsCol = () => db.collection(collections.sessions ?? "sessions");
+    const onceCol = () => db.collection(collections.once ?? "signin_once");
+    const sessionData = (s) => ({ address: s.address, createdAt: s.createdAt, expiresAt: s.expiresAt, via: s.via, scope: "play", deleteAt: new Date(s.expiresAt) });
+    const stores = new Map();
+    for (const way of 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: "play",
+                        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 createSession(session) {
+            const ref = sessionsCol().doc(session.idHash);
+            await db.runTransaction(async (tx) => {
+                if ((await tx.get(ref)).exists)
+                    throw new Error("a session with this id exists");
+                tx.set(ref, sessionData(session));
+            });
+        },
+        async session(idHash, now) {
+            const d = (await sessionsCol().doc(idHash).get()).data();
+            if (!d || d.scope !== "play" || 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: 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 === "play")
+                    tx.delete(ref);
+            });
+        },
+        async useOnce(key, ttlMs, address) {
+            const ref = onceCol().doc(key);
+            return db.runTransaction(async (tx) => {
+                const now = Date.now();
+                const d = (await tx.get(ref)).data();
+                if (d && (num(d.until) ?? Infinity) > now)
+                    return false;
+                tx.set(ref, { address, until: now + ttlMs, deleteAt: new Date(now + ttlMs) });
+                return true;
+            });
+        },
+        async forget(address) {
+            const sessions = (await sessionsCol().where("address", "==", address).get()).docs.filter((d) => d.data().scope === "play");
+            const requests = (await requestsCol().where("account", "==", address).get()).docs.filter((d) => d.data().scope === "play");
+            const once = (await onceCol().where("address", "==", address).get()).docs;
+            return deleteAll([...sessions, ...requests, ...once]);
+        },
+        async clean(now) {
+            const old = (await requestsCol().where("expiresAt", "<", now - 2 * 3_600_000).limit(BATCH).get()).docs.filter((d) => d.data().scope === "play");
+            const ended = (await sessionsCol().where("expiresAt", "<=", now).limit(BATCH).get()).docs.filter((d) => d.data().scope === "play");
+            const used = (await onceCol().where("until", "<=", now).limit(BATCH).get()).docs;
+            await deleteAll([...old, ...ended, ...used]);
+        },
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { PlayerSigninStore } from "./types.js";
+export type PlayerSigninHarness = {
+    store: PlayerSigninStore;
+    /** Every row the store keeps (requests, sessions, once-only keys) as one text. `forget` must leave none that holds the player's address. */
+    dump(): Promise<string>;
+};
+export type PlayerSigninConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+export declare function playerSigninStoreConformance(make: () => Promise<PlayerSigninHarness>): PlayerSigninConformanceCase[];

package/dist/player-signin/conformance.js

@@ -0,0 +1,160 @@
+// The conformance suite of the player 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, and the emulator).
+//
+//   import { playerSigninStoreConformance } from "@nano133/nanoterra/player-signin/conformance";
+//   for (const c of playerSigninStoreConformance(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 ways stay apart; a session lasts until its time; a once-only key counts once; "forget" leaves nothing of the player's.
+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 ANN = who("ann");
+const BOB = who("bob");
+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 + 5 * 60_000, nonce: hex(serial + 99), issuedAt: at, ...extra } };
+}
+const session = (address, at, n, via = "wallet") => ({ idHash: hex(1_000_000 + n + serial++), address, createdAt: at, expiresAt: at + 30 * 86_400_000, via });
+export function playerSigninStoreConformance(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 way", async ({ store }, now) => {
+        const { key, r } = request(now, { label: "game.test sign-in ABCD-EFGH" });
+        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)}`);
+        for (const other of ["berry", "nanchat"]) {
+            check((await store.requests(other).get(key)) === null, `${other} does not see a nautilus request`);
+            check((await store.requests(other).find(r.id)) === null, `${other} 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 is kept under the hash of its nonce and found by the browser's id", 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");
+    });
+    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, or one on an unknown key, is false", async ({ store }, now) => {
+        const { key, r } = request(now);
+        await store.requests("berry").create(key, r);
+        check(await store.requests("berry").finish(key, ANN), "the first finish");
+        check(!(await store.requests("berry").finish(key, BOB)), "a second finish is false");
+        const back = await store.requests("berry").get(key);
+        check(back?.status === "signedin" && back.account === ANN, `the account stays the first: ${JSON.stringify(back)}`);
+        check(!(await store.requests("berry").finish(hex(777, 32), ANN)), "an unknown key");
+        check(!(await store.requests("nautilus").finish(key, ANN)), "another way 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, ANN), store.requests("berry").finish(key, 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(ANN, 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, ANN);
+        const s1 = session(ANN, now, 2);
+        check(await store.deliver("berry", key, s1), "the first delivery");
+        const read = await store.session(s1.idHash, now);
+        check(read?.address === ANN && read.via === "wallet" && read.expiresAt === s1.expiresAt && read.createdAt === s1.createdAt, `the session: ${JSON.stringify(read)}`);
+        const s2 = session(ANN, 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(ANN, now, 4))), "another way cannot deliver it");
+        check(!(await store.deliver("berry", hex(888, 32), session(ANN, 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, ANN);
+        const a = session(ANN, now, 10);
+        const b = session(ANN, 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, with its `via`, and not from its end; ending it removes it", async ({ store }, now) => {
+        const s = session(BOB, now, 20, "passkey");
+        await store.createSession(s);
+        const read = await store.session(s.idHash, now);
+        check(read?.address === BOB && read.via === "passkey" && read.idHash === s.idHash, `read: ${JSON.stringify(read)}`);
+        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");
+        check((await store.session(hex(999), now)) === null, "an unknown id");
+        await store.endSession(s.idHash);
+        check((await store.session(s.idHash, now)) === null, "ended");
+        await store.endSession(s.idHash);
+    });
+    add("a once-only key counts once; another key counts; two at the same moment: one", async ({ store }, now) => {
+        const k = hex(now);
+        check(await store.useOnce(k, 600_000, ANN), "the first use");
+        check(!(await store.useOnce(k, 600_000, BOB)), "the second use");
+        check(await store.useOnce(hex(now + 1), 600_000, ANN), "another key");
+        const k2 = hex(now + 2);
+        const both = await Promise.all([store.useOnce(k2, 600_000, ANN), store.useOnce(k2, 600_000, ANN)]);
+        check(both.filter(Boolean).length === 1, `two at once: ${JSON.stringify(both)}`);
+    });
+    add("forget leaves nothing of the player's (sessions, signed requests, once-only keys) and every row of another player", async ({ store, dump }, now) => {
+        for (const [address, n] of [[ANN, 30], [BOB, 40]]) {
+            await store.createSession(session(address, now, n, "passkey"));
+            const { key, r } = request(now);
+            await store.requests("berry").create(key, r);
+            await store.requests("berry").finish(key, address);
+            await store.deliver("berry", key, session(address, now, n + 1));
+            await store.useOnce(hex(now + n), 600_000, address);
+        }
+        const before = await dump();
+        check(before.includes(ANN) && before.includes(BOB), "both players are in the store");
+        const gone = await store.forget(ANN);
+        check(gone >= 4, `rows that went: ${gone}`);
+        const after = await dump();
+        check(!after.includes(ANN), `the player is left in the store: ${after.slice(0, 400)}`);
+        check(after.split(BOB).length - 1 >= 4, "the other player's rows stay");
+        check((await store.forget(ANN)) === 0, "a second forget finds nothing");
+    });
+    add("clean deletes ended sessions and requests 2 hours after they ended, and keeps the rest", async ({ store }, now) => {
+        const ended = { ...session(ANN, now - 40 * 86_400_000, 50), expiresAt: now - 1 };
+        const live = session(ANN, now, 51);
+        await store.createSession(ended);
+        await store.createSession(live);
+        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.clean(now);
+        check((await store.session(live.idHash, now)) !== null, "the live session stays");
+        check((await store.session(ended.idHash, now - 2)) === 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");
+    });
+    return cases;
+}

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

@@ -0,0 +1,64 @@
+import { type PlayerSession, type PlayerSigninStore, type Via, type Way } 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 PlayerSigninOptions = {
+    store: PlayerSigninStore;
+    /**
+     * A Nano address of the game's own (the starter's RECEIVE_ADDRESS). Nautilus only NAMES it in its request and in the text it signs: no key, no
+     * payment. Null or none: the example address.
+     */
+    siteAddress?: string | null;
+    /** Where the sign-in routes are. Default "/api/signin". */
+    base?: string;
+    /** The sign-out route. Default "/api/signout". */
+    signOutPath?: string;
+    /** The wallet apps the game offers, in the sheet's order. Default all three: ["berry", "nanchat", "nautilus"]. An empty list offers none. */
+    ways?: readonly Way[];
+    /** The passkey route. Default true. */
+    passkey?: boolean;
+    /**
+     * The game's host exactly as players see it ("mygame.com", with a port when it has one). 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;
+    /** True when the game's admin signs in on the same paths (the starter's `scope: "admin"`): its calls answer null. Default false. */
+    sharedPaths?: boolean;
+    /** The cookies' names. Default { session: "session", starter: "starter" } (the starter's). On https they get the __Host- prefix. */
+    cookies?: {
+        session?: string;
+        starter?: string;
+    };
+    /** How long a session lasts, in days. Default 30. */
+    sessionDays?: number;
+    /** The shared limiter (sign-in starts, passkey sign-ins, NanChat's totals): false means "too many". Default: a fixed window in this copy's memory. */
+    limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+    /** The visitor's key for the limits: 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 and a passkey sign-in: 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 player gets a plain 500 and never sees it. */
+    onError?: (e: unknown) => void;
+};
+export type PlayerSignin = {
+    base: string;
+    /** Answers a sign-in route, or null when the request is not one (or is the admin's, with `sharedPaths`). */
+    handle(request: Request): Promise<Response | null>;
+    /** The signed-in player of this request (their Nano address), or null. The shop's and the friends' `player` hook. Never the admin's login. */
+    player(request: Request): Promise<string | null>;
+    /** The session of this request: the address, when it was made and how. */
+    session(request: Request): Promise<PlayerSession | null>;
+    /** Makes a new session for `address` (the game's own code exchange: via "nanoterra") and returns the Set-Cookie value to send. */
+    signIn(request: Request, address: string, via: Via): Promise<string>;
+    /** Ends this request's session and returns the Set-Cookie value that clears the cookie. */
+    signOut(request: Request): Promise<string>;
+    /** "Delete my data": every session and sign-in row of the player. Returns how many rows went. */
+    forget(player: string): Promise<number>;
+    /** The clean-up (a cron): old requests, ended sessions, used once-only keys. */
+    clean(now?: number): Promise<void>;
+};
+export declare function sha256Hex(text: string): Promise<string>;
+/** A cookie for this site only: on https it gets the __Host- prefix and Secure (the starter's exact form). */
+export declare function cookieHeader(req: Request, name: string, value: string, maxAgeSec: number): string;
+export declare function createPlayerSignin(options: PlayerSigninOptions): PlayerSignin;