@nano133/nanoterra 0.8.1 → 0.9.3

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

@@ -0,0 +1,116 @@
+/** The wallet apps a player can sign in with, in the order the sheet shows them. */
+export declare const WAYS: readonly ["berry", "nanchat", "nautilus"];
+export type Way = (typeof WAYS)[number];
+/** How a session was made. "wallet": a wallet app's signature. "passkey": a signature by a key in the page (the passkey purse). "nanoterra": the game's own code exchange. */
+export type Via = "wallet" | "passkey" | "nanoterra";
+export declare const VIAS: readonly Via[];
+/** A wallet app's sign-in request, as a store keeps it. The same shape as @nano133/signin's `WalletRequest`. */
+export type SigninRequest = {
+    /** The browser's id for its checks. */
+    id: string;
+    /** The SHA-256 (hex) of the starter cookie of the browser that asked. */
+    starter: string;
+    status: "waiting" | "signedin";
+    /** When it stops taking a signature (ms). */
+    expiresAt: number;
+    /** Nautilus: the label the app shows and signs. */
+    label?: string;
+    /** Berry Wallet: the nonce and when it was issued (ms). */
+    nonce?: string;
+    issuedAt?: number;
+    /** The account that signed, once it is signed. */
+    account?: string;
+};
+/**
+ * The requests of ONE wallet app. The same methods as @nano133/signin's `RequestStore`, so the package's functions take it as it is. `key` is the
+ * request's id for Berry Wallet and Nautilus, and the SHA-256 of the nonce for NanChat (whose answer names only the nonce). `finish` is atomic:
+ * waiting → signed, once; false otherwise.
+ */
+export interface RequestStoreLike {
+    create(key: string, r: SigninRequest): Promise<void>;
+    get(key: string): Promise<SigninRequest | null>;
+    find(id: string): Promise<{
+        key: string;
+        request: SigninRequest;
+    } | null>;
+    finish(key: string, account: string): Promise<boolean>;
+}
+/** A session as a store keeps it. `idHash` is the SHA-256 (hex) of the cookie's token: the token itself is never stored. */
+export type SessionRecord = {
+    idHash: string;
+    address: string;
+    createdAt: number;
+    expiresAt: number;
+    via: Via;
+};
+/** A session as the game reads it. `via` is "unknown" for a word the store holds that is none of VIAS (never read as a wallet). */
+export type PlayerSession = {
+    address: string;
+    createdAt: number;
+    via: Via | "unknown";
+};
+/**
+ * The game's database for the player sign-in. An adapter reads and writes ONLY its three tables or collections (requests, sessions, once-only
+ * keys), and only the PLAYER's rows of them (a game whose admin shares the tables keeps its rows apart: the D1 adapter's `scope` column).
+ * Run `playerSigninStoreConformance` on a store you write yourself.
+ */
+export interface PlayerSigninStore {
+    /** The requests of one wallet app. */
+    requests(way: Way): RequestStoreLike;
+    /**
+     * Delivers a signed request to the browser that started it, ONCE, and writes its session in the same step: true when this call delivered it,
+     * false (and no session written) when it was delivered before, is not signed, or is not known.
+     */
+    deliver(way: Way, key: string, session: SessionRecord): Promise<boolean>;
+    createSession(session: SessionRecord): Promise<void>;
+    /** The session of a token's hash while it lasts (`expiresAt` > now), else null. */
+    session(idHash: string, now: number): Promise<SessionRecord | null>;
+    endSession(idHash: string): Promise<void>;
+    /** Records `key` and answers true; answers false when it is there already. `address` is kept on the row (for `forget`). The passkey route's replay guard. */
+    useOnce(key: string, ttlMs: number, address: string): Promise<boolean>;
+    /** A player's "Delete my data": every session, every signed request and every once-only row of `address`. Returns how many rows went. */
+    forget(address: string): Promise<number>;
+    /** Deletes what nobody needs any more: requests 2 hours after they ended, sessions that ended, once-only rows past their time. */
+    clean(now: number): Promise<void>;
+}
+/** The limits of the routes (calls per window). The two marked "hook" use the game's `limit`; the rest count in this copy's memory. */
+export declare const PLAYER_SIGNIN_LIMITS: {
+    /** A wallet sign-in start or a passkey sign-in, per visitor (hook). */
+    readonly signin: {
+        readonly limit: 20;
+        readonly windowMs: number;
+    };
+    /** The browser's checks (every 2 s), per visitor (memory). */
+    readonly poll: {
+        readonly limit: 90;
+        readonly windowMs: 60000;
+    };
+    /** Berry Wallet's GET and POST and Nautilus's answer, per IP address (memory): the wallet's own phone sends them. */
+    readonly wallet: {
+        readonly limit: 30;
+        readonly windowMs: 60000;
+    };
+    /** NanChat's answers all come from its one relay server: the whole route (memory), the answers of the right shape (hook) and each nonce (hook). */
+    readonly nanchatRoute: {
+        readonly limit: 120;
+        readonly windowMs: 60000;
+    };
+    readonly nanchatAll: {
+        readonly limit: 600;
+        readonly windowMs: number;
+    };
+    readonly nanchatNonce: {
+        readonly limit: 5;
+        readonly windowMs: number;
+    };
+    /** The biggest body the routes read. */
+    readonly bodyMax: 8192;
+};
+/** How long a player's session lasts (the game starter's 30 days). */
+export declare const SESSION_DAYS = 30;
+/** How long the starter cookie lives: a wallet's request must be answered within it. */
+export declare const STARTER_MAX_AGE_S: number;
+/** A token, a starter value: 32 random bytes as 64 hex characters. */
+export declare const TOKEN_PATTERN: RegExp;
+/** A store's word for `via`, as the game reads it. */
+export declare const viaOf: (v: unknown) => Via | "unknown";

package/dist/player-signin/types.js

@@ -0,0 +1,33 @@
+// The PLAYER sign-in of a game: the types, the limits and the store contract. (The admin's sign-in is another thing: "@nano133/nanoterra/admin".)
+//
+// A player is a Nano address. Every way to sign in is a signature from a key the player holds, and the server holds no key:
+//   - a passkey purse: a Nano account made in the browser from the player's passkey (its PRF output), by the game's FROZEN scheme;
+//     the browser signs a short text that names the game, and the server checks the signature (no WebAuthn on the server);
+//   - Berry Wallet (nano-signin-v1), NanChat (nanauth) and Nautilus (nanoauth): the wallet app signs a request that the browser started.
+// The checks are @nano133/signin's. This file names no package: the stores and their adapters work without it.
+/** The wallet apps a player can sign in with, in the order the sheet shows them. */
+export const WAYS = ["berry", "nanchat", "nautilus"];
+export const VIAS = ["wallet", "passkey", "nanoterra"];
+/** The limits of the routes (calls per window). The two marked "hook" use the game's `limit`; the rest count in this copy's memory. */
+export const PLAYER_SIGNIN_LIMITS = {
+    /** A wallet sign-in start or a passkey sign-in, per visitor (hook). */
+    signin: { limit: 20, windowMs: 10 * 60_000 },
+    /** The browser's checks (every 2 s), per visitor (memory). */
+    poll: { limit: 90, windowMs: 60_000 },
+    /** Berry Wallet's GET and POST and Nautilus's answer, per IP address (memory): the wallet's own phone sends them. */
+    wallet: { limit: 30, windowMs: 60_000 },
+    /** NanChat's answers all come from its one relay server: the whole route (memory), the answers of the right shape (hook) and each nonce (hook). */
+    nanchatRoute: { limit: 120, windowMs: 60_000 },
+    nanchatAll: { limit: 600, windowMs: 10 * 60_000 },
+    nanchatNonce: { limit: 5, windowMs: 10 * 60_000 },
+    /** The biggest body the routes read. */
+    bodyMax: 8192,
+};
+/** How long a player's session lasts (the game starter's 30 days). */
+export const SESSION_DAYS = 30;
+/** How long the starter cookie lives: a wallet's request must be answered within it. */
+export const STARTER_MAX_AGE_S = 30 * 60;
+/** A token, a starter value: 32 random bytes as 64 hex characters. */
+export const TOKEN_PATTERN = /^[0-9a-f]{64}$/;
+/** A store's word for `via`, as the game reads it. */
+export const viaOf = (v) => (VIAS.includes(v) ? v : "unknown");

package/dist/shop/adapters/d1.d.ts

@@ -0,0 +1,25 @@
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { type ShopStore } from "../store.js";
+export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
+/** The table names. The defaults are the game starter's. (`hits` is for `d1Limit` only.) */
+export type ShopTables = {
+    orders?: string;
+    owned?: string;
+    meta?: string;
+    hits?: string;
+};
+/**
+ * True while `key` has made at most `limit` calls in this fixed window, counted in D1 (the table `hits`: one count for the whole game, every location).
+ * The game starter's `d1Limit`. Old windows stay until the game deletes them (the starter's cron deletes those older than a day).
+ */
+export declare function d1Limit(db: D1Like, key: string, limit: number, windowMs: number, now?: number, tables?: Pick<ShopTables, "hits">): Promise<boolean>;
+/** The visitor's IP address as Cloudflare saw it (CF-Connecting-IP); an IPv6 address by its /64 (one home network). "local" when there is none. */
+export declare function visitorIp(req: Request): string;
+/**
+ * The visitor's key: a hash of a random salt (made once per game and kept in `meta` as "salt") and the IP address, never the address itself. The game
+ * starter's `visitorKey`: the same salt row, so the keys stay the same after a switch.
+ */
+export declare function visitorKey(db: D1Like, req: Request, tables?: Pick<ShopTables, "meta">): Promise<string>;
+export declare function createD1Shop(db: D1Like, options?: {
+    tables?: ShopTables;
+}): ShopStore;

package/dist/shop/adapters/d1.js

@@ -0,0 +1,200 @@
+// The shop store for a game on Cloudflare D1, on the game starter's own tables (migrations/0001_init.sql): `orders`, `owned` and `meta`. The package
+// ships the same tables as "@nano133/nanoterra/shop/d1.sql" (CREATE ... IF NOT EXISTS) for a new game; the starter has them already, so it switches with
+// no migration and keeps every order and owned look.
+//
+//   import { createD1Shop } from "@nano133/nanoterra/shop/d1";
+//   const store = createD1Shop(env.DB);
+//
+// It reads and writes ONLY those three tables (in `meta`, only the keys "rate" and "scan"). The table names can be changed (`tables`), but the admin's
+// D1 store ("@nano133/nanoterra/admin/d1") reads the starter's names: keep them unless the game has its own admin store.
+//
+// The money rules are in the statements themselves: `amount_lock` and `hash` are UNIQUE (no two held orders ask for one amount, one payment pays one
+// order), the payment and the grant are ONE batch (a D1 transaction), and the scan's claim is one upsert that only one caller in a gap can win.
+import { parseRate } from "../../admin/summary.js";
+import { paidStatus } from "../orders.js";
+import { FORGOTTEN } from "../store.js";
+const STATUSES = ["open", "paid", "expired", "paid_late"];
+const orderOf = (r) => ({
+    id: r.id,
+    player: r.player,
+    lookId: r.look_id,
+    usd: r.usd,
+    rate: Number(r.rate),
+    amount: r.amount,
+    amountLock: r.amount_lock ?? null,
+    status: STATUSES.includes(r.status) ? r.status : "expired",
+    createdAt: Number(r.created_at),
+    expiresAt: Number(r.expires_at),
+    holdUntil: Number(r.hold_until),
+    hash: r.hash ?? null,
+    payer: r.payer ?? null,
+    paidAt: r.paid_at === null || r.paid_at === undefined ? null : Number(r.paid_at),
+    visitor: r.visitor ?? null,
+});
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const changes = (res) => Number(res?.meta?.changes ?? 0);
+const isUnique = (e) => /UNIQUE/i.test(String(e?.message ?? e));
+/** D1 takes at most 100 bound values in one statement. */
+const CHUNK = 90;
+const tableName = (v, fallback) => {
+    const name = v ?? fallback;
+    if (!NAME.test(name))
+        throw new Error(`the table name "${name}" must be plain (letters, digits and _)`);
+    return name;
+};
+async function sha256Hex(text) {
+    const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * True while `key` has made at most `limit` calls in this fixed window, counted in D1 (the table `hits`: one count for the whole game, every location).
+ * The game starter's `d1Limit`. Old windows stay until the game deletes them (the starter's cron deletes those older than a day).
+ */
+export async function d1Limit(db, key, limit, windowMs, now = Date.now(), tables = {}) {
+    const hits = tableName(tables.hits, "hits");
+    const win = Math.floor(now / windowMs);
+    const row = await db.prepare(`INSERT INTO ${hits} (key, win, count) VALUES (?, ?, 1) ON CONFLICT (key, win) DO UPDATE SET count = count + 1 RETURNING count`).bind(key, win).first();
+    return Number(row?.count ?? 1) <= limit;
+}
+/** The visitor's IP address as Cloudflare saw it (CF-Connecting-IP); an IPv6 address by its /64 (one home network). "local" when there is none. */
+export function visitorIp(req) {
+    const ip = req.headers.get("CF-Connecting-IP") ?? "local";
+    return ip.includes(":") ? ip.split(":").slice(0, 4).join(":") + "::/64" : ip;
+}
+/**
+ * The visitor's key: a hash of a random salt (made once per game and kept in `meta` as "salt") and the IP address, never the address itself. The game
+ * starter's `visitorKey`: the same salt row, so the keys stay the same after a switch.
+ */
+export async function visitorKey(db, req, tables = {}) {
+    const meta = tableName(tables.meta, "meta");
+    let row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first();
+    if (!row) {
+        const fresh = Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (x) => x.toString(16).padStart(2, "0")).join("");
+        await db.prepare(`INSERT OR IGNORE INTO ${meta} (key, value, at) VALUES ('salt', ?, ?)`).bind(fresh, Date.now()).run();
+        row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first();
+    }
+    return (await sha256Hex(`${row.value}|${visitorIp(req)}`)).slice(0, 32);
+}
+export function createD1Shop(db, options = {}) {
+    const T = { orders: tableName(options.tables?.orders, "orders"), owned: tableName(options.tables?.owned, "owned"), meta: tableName(options.tables?.meta, "meta") };
+    const COLS = "id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, hash, payer, paid_at, visitor";
+    async function inChunks(sql, values, col) {
+        const out = new Set();
+        for (let i = 0; i < values.length; i += CHUNK) {
+            const part = values.slice(i, i + CHUNK);
+            const rows = (await db.prepare(sql(part.map(() => "?").join(", "))).bind(...part).all()).results;
+            for (const r of rows)
+                out.add(r[col]);
+        }
+        return out;
+    }
+    const tidy = async (now) => {
+        await db.batch([
+            db.prepare(`UPDATE ${T.orders} SET status = 'expired' WHERE status = 'open' AND expires_at < ?`).bind(now),
+            db.prepare(`UPDATE ${T.orders} SET amount_lock = NULL WHERE amount_lock IS NOT NULL AND hold_until < ?`).bind(now),
+        ]);
+    };
+    const waiting = async (player) => db.prepare(`SELECT COUNT(*) AS n, MAX(hold_until) AS until FROM ${T.orders} WHERE player = ? AND amount_lock IS NOT NULL`).bind(player).first();
+    return {
+        tidy,
+        heldAmounts: (amounts) => inChunks((m) => `SELECT amount_lock FROM ${T.orders} WHERE amount_lock IN (${m})`, amounts, "amount_lock"),
+        async insert(o) {
+            try {
+                await db
+                    .prepare(`INSERT INTO ${T.orders} (id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, visitor) VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?)`)
+                    .bind(o.id, o.player, o.lookId, o.usd, o.rate, o.amount, o.amount, o.createdAt, o.expiresAt, o.holdUntil, o.visitor)
+                    .run();
+                return true;
+            }
+            catch (e) {
+                // Another order took this amount since the read. Any other failure stops.
+                if (isUnique(e))
+                    return false;
+                throw e;
+            }
+        },
+        async order(id) {
+            const r = await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE id = ?`).bind(id).first();
+            return r ? orderOf(r) : null;
+        },
+        async openOrder(player, lookId, until) {
+            const r = await db
+                .prepare(`SELECT ${COLS} FROM ${T.orders} WHERE player = ? AND look_id = ? AND status = 'open' AND expires_at > ? ORDER BY created_at DESC LIMIT 1`)
+                .bind(player, lookId, until)
+                .first();
+            return r ? orderOf(r) : null;
+        },
+        async countOpen(player, now) {
+            const r = await db.prepare(`SELECT COUNT(*) AS n FROM ${T.orders} WHERE player = ? AND status = 'open' AND expires_at > ?`).bind(player, now).first();
+            return Number(r?.n ?? 0);
+        },
+        async owns(player, lookId) {
+            return Boolean(await db.prepare(`SELECT 1 AS one FROM ${T.owned} WHERE player = ? AND look_id = ?`).bind(player, lookId).first());
+        },
+        async owned(player) {
+            return (await db.prepare(`SELECT look_id FROM ${T.owned} WHERE player = ? ORDER BY granted_at, look_id`).bind(player).all()).results.map((r) => r.look_id);
+        },
+        async held() {
+            return (await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE amount_lock IS NOT NULL`).all()).results.map(orderOf);
+        },
+        usedHashes: (hashes) => inChunks((m) => `SELECT hash FROM ${T.orders} WHERE hash IN (${m})`, hashes, "hash"),
+        async settle(order, pay, now) {
+            const status = paidStatus(order, pay.seenMs);
+            try {
+                const [update] = await db.batch([
+                    db
+                        .prepare(`UPDATE ${T.orders} SET status = ?, hash = ?, payer = ?, paid_at = ?, amount_lock = NULL WHERE id = ? AND status IN ('open', 'expired') AND amount_lock IS NOT NULL`)
+                        .bind(status, pay.hash, pay.payer, pay.seenMs, order.id),
+                    db
+                        .prepare(`INSERT OR IGNORE INTO ${T.owned} (player, look_id, order_id, granted_at) SELECT player, look_id, id, ? FROM ${T.orders} WHERE id = ? AND status = 'paid' AND hash = ?`)
+                        .bind(now, order.id, pay.hash),
+                ]);
+                return changes(update) === 1 ? status : "taken";
+            }
+            catch (e) {
+                if (isUnique(e))
+                    return "used";
+                throw e;
+            }
+        },
+        async claimScan(now, gapMs) {
+            const r = await db
+                .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('scan', '', ?) ON CONFLICT (key) DO UPDATE SET at = excluded.at WHERE ${T.meta}.at <= ?`)
+                .bind(now, now - gapMs)
+                .run();
+            return changes(r) === 1;
+        },
+        async readRate() {
+            const r = await db.prepare(`SELECT value, at FROM ${T.meta} WHERE key = 'rate'`).first();
+            return r ? parseRate(r.value, Number(r.at)) : null;
+        },
+        async saveRate(rate) {
+            await db
+                .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('rate', ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, at = excluded.at`)
+                .bind(JSON.stringify({ usd: rate.usd, sources: rate.sources }), rate.at)
+                .run();
+        },
+        async forget(player, now) {
+            await tidy(now);
+            const w = await waiting(player);
+            if (Number(w?.n ?? 0) > 0)
+                return { deleted: 0, kept: 0, waitUntil: Number(w.until) };
+            // One batch, and each statement holds the money gate again: an order made meanwhile stops every one of them.
+            const gate = `NOT EXISTS (SELECT 1 FROM ${T.orders} WHERE player = ?1 AND amount_lock IS NOT NULL)`;
+            const done = await db.batch([
+                db.prepare(`DELETE FROM ${T.owned} WHERE player = ?1 AND ${gate}`).bind(player),
+                db.prepare(`DELETE FROM ${T.orders} WHERE player = ?1 AND hash IS NULL AND amount_lock IS NULL AND ${gate}`).bind(player),
+                // A paid order keeps no payer; a paid-late one keeps it: the creator sends that payment back by hand.
+                db.prepare(`UPDATE ${T.orders} SET payer = ?2 WHERE payer = ?1 AND status = 'paid' AND ${gate}`).bind(player, FORGOTTEN),
+                db.prepare(`UPDATE ${T.orders} SET player = ?2, visitor = NULL WHERE player = ?1 AND hash IS NOT NULL AND ${gate}`).bind(player, FORGOTTEN),
+            ]);
+            const [owned, orders, , kept] = done.map(changes);
+            if (owned + orders + kept === 0) {
+                const again = await waiting(player);
+                if (Number(again?.n ?? 0) > 0)
+                    return { deleted: 0, kept: 0, waitUntil: Number(again.until) };
+            }
+            return { deleted: owned + orders, kept, waitUntil: null };
+        },
+    };
+}

package/dist/shop/adapters/firestore.d.ts

@@ -0,0 +1,53 @@
+import { type ShopStore } from "../store.js";
+export type ShopDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface ShopDocRef {
+    get(): Promise<ShopDocSnap>;
+}
+export type ShopQuerySnap = {
+    docs: {
+        id: string;
+        ref: ShopDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface ShopQuery {
+    where(field: string, op: "==" | "<", value: unknown): ShopQuery;
+    limit(n: number): ShopQuery;
+    get(): Promise<ShopQuerySnap>;
+}
+export interface ShopCollection extends ShopQuery {
+    doc(id: string): ShopDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface ShopTransaction {
+    get(ref: ShopDocRef): Promise<ShopDocSnap>;
+    set(ref: ShopDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: ShopDocRef): unknown;
+}
+export interface ShopBatch {
+    set(ref: ShopDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: ShopDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestoreShopLike {
+    collection(name: string): ShopCollection;
+    runTransaction<T>(fn: (tx: ShopTransaction) => Promise<T>): Promise<T>;
+    batch(): ShopBatch;
+}
+export type ShopCollections = {
+    orders?: string;
+    owned?: string;
+    meta?: string;
+    amounts?: string;
+    hashes?: string;
+};
+/** The most documents one query reads: a small game's orders of one player, or its held amounts. */
+export declare const FIRESTORE_SHOP_SCAN = 2000;
+export declare function createFirestoreShop(db: FirestoreShopLike, collections?: ShopCollections): ShopStore;