@nano133/nanoterra 0.1.0 → 0.3.0

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

@@ -0,0 +1,40 @@
+import type { AdminStore } from "../store.js";
+export interface FirestoreDocLike {
+    get(): Promise<{
+        exists: boolean;
+        data(): Record<string, unknown> | undefined;
+    }>;
+}
+export interface FirestoreQueryLike {
+    orderBy(field: string, direction?: "asc" | "desc"): FirestoreQueryLike;
+    limit(n: number): FirestoreQueryLike;
+    get(): Promise<{
+        docs: {
+            id: string;
+            data(): Record<string, unknown>;
+        }[];
+    }>;
+}
+export interface FirestoreCollectionLike extends FirestoreQueryLike {
+    doc(id: string): FirestoreDocLike;
+}
+export interface FirestoreBatchLike {
+    set(doc: FirestoreDocLike, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestoreLike {
+    collection(name: string): FirestoreCollectionLike;
+    batch(): FirestoreBatchLike;
+}
+export declare const FIRESTORE_SCAN_LIMIT = 5000;
+export declare const FIRESTORE_KEYS: {
+    readonly character: "setting:character";
+    readonly signin: "setting:signin";
+};
+export declare function createFirestoreStore(db: FirestoreLike, collections?: {
+    meta?: string;
+    orders?: string;
+    owned?: string;
+}): AdminStore;

package/dist/admin/adapters/firestore.js

@@ -0,0 +1,53 @@
+// The admin 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 writes ONLY the two settings; everything else it does is a read.
+//
+// The data model (the names a game must have; only the three collection names can be changed):
+//   meta/{key}          { value: string, at: number }          keys "setting:character", "setting:signin", "rate" (value is JSON { usd, sources })
+//   orders/{id}         { player, lookId, usd, amount, status, createdAt, expiresAt, paidAt, payer, hash }   `amount` is the raw amount as text
+//   owned/{player__lookId}  { player, lookId, orderId, grantedAt }
+//
+// The summary reads the newest 5000 orders (the counts and the totals are over those) and every owned look: for a small game. A big game should keep running totals.
+import { parseRate, summarize } from "../summary.js";
+export const FIRESTORE_SCAN_LIMIT = 5000;
+export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin" };
+const text = (v, fallback = "") => (typeof v === "string" ? v : fallback);
+const num = (v, fallback = 0) => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+const orNull = (v) => (typeof v === "string" ? v : null);
+export function createFirestoreStore(db, collections = {}) {
+    const meta = collections.meta ?? "meta";
+    const orders = collections.orders ?? "orders";
+    const owned = collections.owned ?? "owned";
+    const valueOf = async (key) => {
+        const snap = await db.collection(meta).doc(key).get();
+        return snap.exists ? snap.data() : undefined;
+    };
+    return {
+        async readSettings() {
+            const [character, signin] = await Promise.all([valueOf(FIRESTORE_KEYS.character), valueOf(FIRESTORE_KEYS.signin)]);
+            return { character: character?.value, signin: signin?.value };
+        },
+        async saveSettings(patch, now) {
+            const batch = db.batch();
+            let n = 0;
+            if (patch.character)
+                (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.character), { value: patch.character, at: now }), n++);
+            if (patch.signin)
+                (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.signin), { value: patch.signin, at: now }), n++);
+            if (n)
+                await batch.commit();
+        },
+        async summary(now) {
+            const [orderDocs, ownedDocs, rate] = await Promise.all([
+                db.collection(orders).orderBy("createdAt", "desc").limit(FIRESTORE_SCAN_LIMIT).get(),
+                db.collection(owned).get(),
+                valueOf("rate"),
+            ]);
+            const rows = orderDocs.docs.map((d) => {
+                const o = d.data();
+                return { id: d.id, player: text(o.player), lookId: text(o.lookId), usd: text(o.usd, "0"), amountRaw: text(o.amount, "0"), status: text(o.status, "open"), createdAt: num(o.createdAt), expiresAt: num(o.expiresAt), paidAt: typeof o.paidAt === "number" ? o.paidAt : null, payer: orNull(o.payer), hash: orNull(o.hash) };
+            });
+            const list = ownedDocs.docs.map((d) => ({ player: text(d.data().player), lookId: text(d.data().lookId), at: num(d.data().grantedAt) }));
+            return summarize(rows, list, parseRate(rate?.value, rate?.at), now);
+        },
+    };
+}

package/dist/admin/amount.d.ts

@@ -0,0 +1,5 @@
+export declare const RAW_PER_XNO: bigint;
+/** A raw amount as XNO with every significant digit: "0.2512". Throws on text that is not a whole number. */
+export declare function xnoText(raw: string): string;
+/** A raw amount that can be added: digits only, at most 39 of them. Anything else is not counted (a bad row must not break the summary). */
+export declare const isRawText: (s: unknown) => s is string;

package/dist/admin/amount.js

@@ -0,0 +1,11 @@
+// Nano amounts for the summary. 1 XNO is 10^30 raw, more than a JavaScript number holds exactly, so amounts are decimal strings and the sums are BigInt.
+export const RAW_PER_XNO = 10n ** 30n;
+/** A raw amount as XNO with every significant digit: "0.2512". Throws on text that is not a whole number. */
+export function xnoText(raw) {
+    const n = BigInt(raw);
+    const whole = n / RAW_PER_XNO;
+    const frac = (n % RAW_PER_XNO).toString().padStart(30, "0").replace(/0+$/, "");
+    return frac ? `${whole}.${frac}` : `${whole}`;
+}
+/** A raw amount that can be added: digits only, at most 39 of them. Anything else is not counted (a bad row must not break the summary). */
+export const isRawText = (s) => typeof s === "string" && /^[0-9]{1,39}$/.test(s);

package/dist/admin/conformance.d.ts

@@ -0,0 +1,132 @@
+import type { AdminRoute } from "./handler.js";
+import type { AdminStore } from "./store.js";
+import { type OrderRow } from "./summary.js";
+/**
+ * The kinds of visitor the game must be able to make:
+ *  - signed_out            no cookie at all
+ *  - game_login            a valid login made for the game's PLAYERS (the owner's own address, even), in the game's own cookie: it is not an admin login
+ *  - game_token_as_admin   the token of that same player login, put in the ADMIN cookie. The game must keep the two scopes apart in its store, not only in the cookie names
+ *  - nanoterra_login       an admin-scope login whose `via` is "nanoterra" (a sign-in from Nanoterra), for the owner's address
+ *  - unknown_via_login     an admin-scope login of the owner's whose `via` is a word the game does not know (like "ticket", or an empty one): it must fail closed
+ *  - other_wallet          a wallet login for an address that is not the owner's
+ *  - no_address            a wallet login while the game has NO owner address set (the game runs with none)
+ *  - expired_login         a wallet login of the owner's, made LESS than a day ago, that the game's own store has already expired (its own life is shorter than a day, or it ended).
+ *                          The guard's age check cannot refuse it, so only the game's store does: a game whose session code ignores its own expiry fails here
+ *  - signed_out_login      a wallet login of the owner's, made just now, that the game's own sign-out route has ended. A game that still reads it fails here
+ *  - old_valid_row         a wallet login of the owner's made more than one day ago whose stored row is STILL valid, so only the guard's own age check can refuse it. The suite sends it
+ *                          TWICE (the second time with `again: true`, the same login): a game that renews the creation time on every read fails here
+ *  - owner                 a wallet login of the owner's, made just now
+ */
+export type Who = "signed_out" | "game_login" | "game_token_as_admin" | "nanoterra_login" | "unknown_via_login" | "other_wallet" | "no_address" | "expired_login" | "signed_out_login" | "old_valid_row" | "owner";
+export type ConformanceRequest = {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: string;
+    /** True when the suite wants the SAME login as the last request of this kind (do not make a new one): a host must support it, or a session that renews itself on each read is not caught. */
+    again?: boolean;
+    /**
+     * Set when the suite wants the login token of this kind sent in a place that is NOT the game's cookie, with NO cookie: "bearer" (`Authorization: Bearer <token>`), "query" (the token in the
+     * query as `token`, `t` and `access_token`) or "header" (`X-Auth-Token: <token>`). A host must support it, or a game that also reads a player's token from one of these places is not caught.
+     */
+    tokenAt?: "bearer" | "query" | "header";
+};
+export type ConformanceHost = {
+    /** The handler's `routes`. */
+    routes: readonly AdminRoute[];
+    /** The handler's `basePath`. */
+    basePath: string;
+    /** The game's own origin, like "https://game.example": the suite sends it as the Origin of a good POST. */
+    origin: string;
+    /**
+     * Other routes that the game's OWN router serves under the base path (an old route, a debug route, a route kept for an old page): `{ method, path }`. The suite sends each
+     * as every kind of visitor who is not the owner and requires a refusal: a route that the game's router answers BEFORE the handler, with no guard, must show up here.
+     * List every one you know of; the suite cannot find the ones your router hides from it.
+     */
+    otherRoutes?: readonly {
+        method: string;
+        path: string;
+    }[];
+    request(who: Who, req: ConformanceRequest): Promise<Response>;
+    /** Optional but recommended. Ends the login of the last request of this kind with the game's OWN sign-out (the real route): the suite then uses the same login again and requires a refusal. */
+    endLogin?(who: Who): Promise<void>;
+};
+export type ConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+export declare function adminConformance(host: ConformanceHost): ConformanceCase[];
+/** What a test gives to run the store contract: the store, and a way to put rows in the game's database the way the game's own code does (the store has no write for them). */
+export type StoreHarness = {
+    store: AdminStore;
+    seed(data: {
+        orders?: OrderRow[];
+        owned?: {
+            player: string;
+            lookId: string;
+            at: number;
+        }[];
+        rate?: {
+            value: string;
+            at: number;
+        };
+    }): Promise<void>;
+    /** Every row that the store could change by mistake, as one text: the orders, the owned looks and the meta rows that are NOT the two settings. Same rows, same text. */
+    snapshot(): Promise<string>;
+    /** Only for a store with `recentLogins` and `signOutEverywhere`: put admin sign-ins in the game's database (the store only reads them). */
+    seedLogins?(rows: {
+        at: number;
+        country: string | null;
+        browser: string;
+    }[]): Promise<void>;
+    /** Put this many admin sessions and this many player sessions in the game's database. */
+    seedSessions?(n: {
+        admin: number;
+        play: number;
+    }): Promise<void>;
+    /** How many admin sessions and how many player sessions the game's database holds now. */
+    sessionCounts?(): Promise<{
+        admin: number;
+        play: number;
+    }>;
+    /** Put this many admin sign-in requests and this many game sign-in requests that were started and NOT delivered in the game's database. */
+    seedRequests?(n: {
+        admin: number;
+        game: number;
+    }): Promise<void>;
+    /** How many admin and game sign-in requests are still not delivered. */
+    pendingRequests?(): Promise<{
+        admin: number;
+        game: number;
+    }>;
+};
+export declare function adminStoreConformance(make: () => Promise<StoreHarness>): ConformanceCase[];
+export type SigninScope = "game" | "admin";
+export type SigninHost = {
+    /** Starts a sign-in request for this scope in a NEW browser, and returns a handle (the host keeps that browser's credentials in it). */
+    start(scope: SigninScope): Promise<unknown>;
+    /** The owner's wallet signs the request (what the wallet app does). It MUST throw when the answer was refused: a signature that did not land is a fault of the test, never a pass. */
+    sign(request: unknown): Promise<void>;
+    /**
+     * The browser asks to finish the request AS `as` (the scope the check is made for), and says which logins it ended with.
+     *  - "own": the browser that started it, with its own credentials;
+     *  - "other": a different browser with no credentials of this request;
+     *  - "retyped": the browser that started it, presenting its credentials as the OTHER scope would read them (the cookie copied to the other scope's name; a value that the other
+     *    scope's hashing would match: the game's best attempt at a forged credential). It differs from "own" only when `as` is not the scope the request started for.
+     */
+    finish(request: unknown, as: SigninScope, credentials: "own" | "other" | "retyped"): Promise<{
+        admin: boolean;
+        game: boolean;
+    }>;
+    /** Optional, but pass `{ signOutEverywhere: true }` to the contract when your admin has "Sign out everywhere". Signs out everywhere (from a fresh admin login of the owner). */
+    signOutEverywhere?(): Promise<void>;
+    /**
+     * Optional, recommended (pass `{ advance: true }` to the contract when the host has it: a host that then has none fails). Moves the game's clock forward by `ms` for every later call. The contract then repeats the cross-scope asks after the admin's window has ended, inside the
+     * game's hour of delivery: a scope check that only works while a request is fresh fails here. The contract runs this case last.
+     */
+    advance?(ms: number): Promise<void>;
+};
+export declare function adminSigninConformance(host: SigninHost, options?: {
+    signOutEverywhere?: boolean;
+    advance?: boolean;
+}): ConformanceCase[];