@flayerlabs/gamemode-gate 0.1.0

package/src/sessions.ts

@@ -0,0 +1,155 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isAddress, verifyMessage } from 'viem';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import { formatSessionChallenge } from '@flayerlabs/gamemode-spec/embed';
+
+/**
+ * Proving who a player is, once, and carrying it afterwards.
+ *
+ * A player signs a message with the wallet they are going to buy with; from then on they hold a
+ * token. Two details are load-bearing and both were learned the hard way in the system this
+ * replaces:
+ *
+ * **The message names the page the player is looking at, not the game.** A game runs in an iframe
+ * on flaunch.gg, so a signing prompt naming the game's own origin is one wallets flag as deceptive
+ * — and rightly, because the player is looking at flaunch.gg. The message separately names this
+ * gate's configured origin, which lets the parent refuse a challenge replayed from another gate.
+ *
+ * **The session is a token, never a cookie.** A cross-origin iframe gets partitioned storage, so a
+ * cookie set by the gate is not reliably there on the next request.
+ */
+
+/** Long enough to sign in without hurrying, short enough that a stale prompt stops working. */
+const NONCE_TTL_MS = 2 * 60_000;
+
+/** A round is minutes; a session outliving the day it was made has no purpose. */
+const SESSION_TTL_MS = 12 * 60 * 60_000;
+
+export class NotSignedIn extends Error {
+  constructor(message = 'not signed in') {
+    super(message);
+    this.name = 'NotSignedIn';
+  }
+}
+
+/**
+ * A signed envelope: base64url JSON, then an HMAC of it.
+ *
+ * There is one of these because there used to be two, and both parsed by dot-joining fields and
+ * splitting them apart again. That let an address containing a dot smuggle an extra field into the
+ * body: `challenge('0xabc….Infinity')` produced an expiry of `Infinity`, and `Infinity < now` is
+ * false, so a captured signature could mint fresh sessions forever. JSON has no such ambiguity, and
+ * the shape is checked rather than assumed.
+ */
+interface Envelope {
+  subject: string;
+  expiresAt: number;
+}
+
+export class Sessions {
+  constructor(
+    private readonly secret: string,
+    /** The origin the player is actually looking at — the embedding page, not the game. */
+    private readonly domain: string,
+    /** Exact configured origin of this gate. Never derive this audience from a request header. */
+    private readonly gateOrigin: string,
+    private readonly now: () => number = Date.now,
+  ) {
+    if (!secret || secret.length < 32) {
+      throw new Error('session secret must be at least 32 characters');
+    }
+    try {
+      const gate = new URL(gateOrigin);
+      if ((gate.protocol !== 'https:' && gate.protocol !== 'http:') || gate.origin !== gateOrigin) throw new Error();
+    } catch {
+      throw new Error('gate origin must be an exact http(s) origin');
+    }
+  }
+
+  private sign(value: string): string {
+    return createHmac('sha256', this.secret).update(value).digest('base64url');
+  }
+
+  private seal(envelope: Envelope): string {
+    const body = Buffer.from(JSON.stringify(envelope)).toString('base64url');
+    return `${body}.${this.sign(body)}`;
+  }
+
+  /** Open an envelope, or null. Every field is checked; nothing is inferred from position. */
+  private open(value: string | undefined): Envelope | null {
+    if (!value) return null;
+    const parts = value.split('.');
+    if (parts.length !== 2) return null;
+
+    const [body, mac] = parts as [string, string];
+    if (!this.matches(body, mac)) return null;
+
+    try {
+      const parsed: unknown = JSON.parse(Buffer.from(body, 'base64url').toString());
+      if (typeof parsed !== 'object' || parsed === null) return null;
+      const { subject, expiresAt } = parsed as Record<string, unknown>;
+      if (typeof subject !== 'string' || !subject) return null;
+      // Finite and whole: `Infinity` and `NaN` both slip past a naive `<` comparison.
+      if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) return null;
+      return { subject, expiresAt };
+    } catch {
+      return null;
+    }
+  }
+
+  private matches(value: string, signature: string): boolean {
+    const expected = Buffer.from(this.sign(value));
+    const given = Buffer.from(signature);
+    return expected.length === given.length && timingSafeEqual(expected, given);
+  }
+
+  /**
+   * A challenge to sign.
+   *
+   * Carries its own expiry and signature rather than being stored, so a restart mid-sign-in does
+   * not strand anyone. It is deliberately NOT single-use: doing that needs storage, and the only
+   * party who ever sees the signature is the player's own game, which already holds their session.
+   */
+  challenge(address: string): { nonce: string; message: string } {
+    // Checked before anything is signed: an address is the one field a caller controls, and the
+    // envelope's meaning depends on it being what it claims to be.
+    if (!isAddress(address)) throw new NotSignedIn('that is not a wallet address');
+    const nonce = this.seal({ subject: address.toLowerCase(), expiresAt: this.now() + NONCE_TTL_MS });
+    return { nonce, message: this.messageFor(address, nonce) };
+  }
+
+  private messageFor(address: string, nonce: string): string {
+    return formatSessionChallenge(this.domain, address, this.gateOrigin, nonce);
+  }
+
+  /** Check a signed challenge and issue a session token, or explain why not. */
+  async signIn(address: string, signature: `0x${string}`, nonce: string): Promise<string> {
+    if (!isAddress(address)) throw new NotSignedIn('that is not a wallet address');
+
+    const opened = this.open(nonce);
+    if (!opened) throw new NotSignedIn('that sign-in code is not valid');
+    if (opened.subject !== address.toLowerCase()) throw new NotSignedIn('that sign-in code is for another wallet');
+    if (opened.expiresAt < this.now()) throw new NotSignedIn('that sign-in code has expired, please try again');
+
+    const valid = await verifyMessage({
+      address: address as `0x${string}`,
+      message: this.messageFor(address, nonce),
+      signature,
+    }).catch(() => false);
+    if (!valid) throw new NotSignedIn('that signature does not match the wallet');
+
+    return this.issue(address.toLowerCase());
+  }
+
+  private issue(player: PlayerId): string {
+    return this.seal({ subject: player, expiresAt: this.now() + SESSION_TTL_MS });
+  }
+
+  /** Who is this, or throw. The only way a request gets an identity. */
+  verify(token: string | undefined): PlayerId {
+    const opened = this.open(token);
+    if (!opened) throw new NotSignedIn();
+    if (opened.expiresAt < this.now()) throw new NotSignedIn('your session has expired');
+    return opened.subject;
+  }
+}

package/src/settlement.ts

@@ -0,0 +1,72 @@
+import { parseAbi } from 'viem';
+import type { Pool } from 'pg';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import type { Ledger } from './ledger.js';
+import type { ChainReader } from './chain/discover.js';
+
+/**
+ * Keeping the ledger honest about what was actually spent.
+ *
+ * The obvious design is to watch for a swap and match it back to the authorisation that permitted
+ * it. That turns out to be both harder and less useful than it sounds: the event carries the buyer
+ * and the amount but not the nonce, and a wallet can submit through a relay, so correlating them is
+ * guesswork.
+ *
+ * The contract already keeps the number that matters. `walletSpentWei(poolId, wallet)` is what it
+ * enforces against, so reading it is reading the truth rather than inferring it. No matching, no
+ * event log to replay, and nothing to get subtly wrong.
+ */
+
+const spendGatedAbi = parseAbi([
+  'function walletSpentWei(bytes32 _poolId, address _wallet) view returns (uint256)',
+]);
+
+export class Settlement {
+  constructor(
+    private readonly pool: Pool,
+    private readonly ledger: Ledger,
+    private readonly client: ChainReader,
+    private readonly calculator: `0x${string}`,
+  ) {}
+
+  /**
+   * Bring one round's view of spending up to date with the chain.
+   *
+   * Returns which wallets changed as well as read/failure counts, so live updates can target only
+   * affected players. A read that fails is skipped rather than thrown: one unreachable RPC call
+   * must not stop a round, and the next pass will catch it.
+   */
+  async reconcile(roundId: string): Promise<{ read: number; failed: number; changed: PlayerId[] }> {
+    const round = await this.pool.query<{ pool_id: string }>(`select pool_id from rounds where id = $1`, [
+      roundId,
+    ]);
+    const poolId = round.rows[0]?.pool_id;
+    if (!poolId) return { read: 0, failed: 0, changed: [] };
+
+    const players = await this.ledger.playersIn(roundId);
+    let read = 0;
+    let failed = 0;
+    const changed: PlayerId[] = [];
+
+    for (const player of players) {
+      try {
+        const spent = (await this.client.readContract({
+          address: this.calculator,
+          abi: spendGatedAbi,
+          functionName: 'walletSpentWei',
+          args: [poolId as `0x${string}`, player as `0x${string}`],
+        })) as bigint;
+
+        if (spent > 0n && await this.ledger.recordChainSpend(roundId, player, spent)) changed.push(player);
+        read += 1;
+      } catch {
+        // One unreachable read is not a reason to stop the round, but it is counted. Swallowed
+        // entirely, a chain that has been unreachable all day looks exactly like one where nobody
+        // has spent anything — and the second is a fine reason to keep authorising, while the
+        // first is not.
+        failed += 1;
+      }
+    }
+    return { read, failed, changed };
+  }
+}

package/src/store.ts

@@ -0,0 +1,127 @@
+import type { Pool, PoolClient } from 'pg';
+
+/**
+ * The complete first-release database schema.
+ *
+ * Every table is here rather than beside the code that reads it. Two modules owning parts of one
+ * table is how a schema drifts: one adds a column, the other's migration never runs, and the
+ * failure appears somewhere neither of them looks.
+ */
+export const SCHEMA = `
+create table if not exists rounds (
+  id             text primary key,
+  wei_per_point  numeric(78,0) not null check (wei_per_point > 0),
+  wallet_cap_wei numeric(78,0) not null check (wallet_cap_wei > 0),
+  pool_id        text not null,
+  opens_at       bigint not null,
+  closes_at      bigint not null,
+  books_close_at bigint not null,
+  coin_address   text,
+  coin_name      text not null,
+  coin_symbol    text not null,
+  coin_image_url text,
+  -- The game's own state, opaque to the platform. Written after every command, so a restart
+  -- resumes from here rather than replaying history.
+  state          jsonb not null,
+  -- Commands applied so far. Doubles as the cursor a reconnecting client resumes from.
+  seq            integer not null default 0 check (seq >= 0),
+  constraint rounds_window check (opens_at < closes_at),
+  constraint rounds_books_tail check (books_close_at >= closes_at)
+);
+
+create table if not exists balances (
+  round_id text not null references rounds(id) on delete cascade,
+  player   text not null,
+  points   bigint not null default 0 check (points >= 0),
+  -- What the chain says this wallet has already spent on this pool. The contract keeps this and
+  -- enforces it whatever we believe, so it is the only figure that is actually true.
+  chain_spent_wei numeric(78,0) not null default 0 check (chain_spent_wei >= 0),
+  primary key (round_id, player)
+);
+
+-- One row per authorisation ever issued. Nothing is deleted: a signature that exists in the world
+-- cannot be un-issued, so the ledger records its fate instead of forgetting it.
+create table if not exists claims (
+  nonce         bigint generated always as identity primary key,
+  round_id      text not null references rounds(id) on delete cascade,
+  player        text not null,
+  request_id    varchar(128) not null check (request_id <> ''),
+  requested_wei numeric(78,0) not null check (requested_wei > 0),
+  wei           numeric(78,0) not null check (wei > 0 and wei <= requested_wei),
+  -- Held or released, and nothing else. Whether a swap LANDED is the chain's to say, not ours.
+  status        text not null check (status in ('held', 'released')),
+  deadline      bigint not null,
+  -- Persisted before a payload leaves the gate. Until signing completes, both values are null.
+  signature     text,
+  signer        text,
+  created_at    timestamptz not null default now(),
+  constraint claims_by_request unique (round_id, player, request_id),
+  constraint claims_signature_pair check ((signature is null) = (signer is null))
+);
+
+create index if not exists claims_by_player on claims (round_id, player) where status = 'held';
+
+-- Which game a coin plays. Addresses are chain-local, so the pin is one row per (chain, coin).
+create table if not exists registrations (
+  chain_id    bigint not null check (chain_id > 0),
+  coin        text not null check (coin <> ''),
+  game_id     text not null check (game_id <> ''),
+  gate_origin text not null check (gate_origin <> ''),
+  deploy_id   text not null check (deploy_id <> ''),
+  disabled_at timestamptz,
+  updated_at  timestamptz not null default now(),
+  primary key (chain_id, coin)
+);
+
+-- What actually happened, in order. Not used to rebuild state — the snapshot does that — but it is
+-- the record of why a state looks the way it does, which is what an incident needs.
+create table if not exists commands (
+  round_id text not null references rounds(id) on delete cascade,
+  seq      integer not null check (seq > 0),
+  command  jsonb not null,
+  primary key (round_id, seq)
+);
+`;
+
+const MIGRATION_LOCK = `select pg_advisory_xact_lock(
+  hashtextextended(current_database() || ':' || current_schema() || ':gamemode_schema', 0)
+)`;
+
+/**
+ * Run `fn` inside a transaction, committing on success and rolling back on failure.
+ *
+ * The rollback is itself wrapped, because a connection that has already died throws again on
+ * `rollback` — and an unguarded rollback replaces the useful original error.
+ */
+export async function inTransaction<T>(pool: Pool, fn: (tx: PoolClient) => Promise<T>): Promise<T> {
+  const tx = await pool.connect();
+  try {
+    await tx.query('begin');
+    const result = await fn(tx);
+    await tx.query('commit');
+    return result;
+  } catch (error) {
+    try {
+      await tx.query('rollback');
+    } catch {
+      // Preserve the original error.
+    }
+    throw error;
+  } finally {
+    tx.release();
+  }
+}
+
+/** Create the current schema once, serialising concurrent replica startup in this Postgres schema. */
+export async function migrate(pool: Pool): Promise<void> {
+  await inTransaction(pool, async (tx) => {
+    await tx.query(MIGRATION_LOCK);
+    await tx.query(SCHEMA);
+  });
+}
+
+/**
+ * Postgres hands back `numeric` and `bigint` as strings, because they do not fit a JS number.
+ * Parsing them in one place stops a `Number()` creeping in and silently losing wei precision.
+ */
+export const toBigInt = (value: string | number | null | undefined): bigint => BigInt(value ?? 0);

package/src/turnstile.ts

@@ -0,0 +1,74 @@
+import type { Admit } from './server.js';
+
+const SITEVERIFY = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+const MAX_TOKEN_LENGTH = 2_048;
+const DEFAULT_TIMEOUT_MS = 8_000;
+const FAILURE = { ok: false, reason: 'human verification failed, please try again' } as const;
+
+export interface TurnstileAdmitOptions {
+  secret: string;
+  /** Exact hostnames on which the trusted parent may render the widget. */
+  hostnames: readonly string[];
+  /** The action configured on the widget. */
+  action: string;
+  timeoutMs?: number;
+  /** Test seam for the one external boundary. Production uses global fetch. */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Reference Cloudflare Turnstile policy for the gate's generic admission seam.
+ *
+ * It verifies only session creation. Gameplay and claim policy remain composable operator choices.
+ * Every non-explicit success fails closed, including network, HTTP and malformed-response failures.
+ */
+export function createTurnstileAdmit(options: TurnstileAdmitOptions): Admit {
+  if (!options.secret) throw new RangeError('Turnstile secret is required');
+  if (!options.action) throw new RangeError('Turnstile action is required');
+  if (options.hostnames.length === 0) throw new RangeError('at least one Turnstile hostname is required');
+  const hostnames = new Set(options.hostnames.map((hostname) => hostname.toLowerCase()));
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError('Turnstile timeoutMs must be a positive safe integer');
+  }
+  const verify = options.fetch ?? globalThis.fetch;
+
+  return async (request) => {
+    if (request.at !== 'session') return { ok: true };
+    if (
+      typeof request.evidence !== 'string' ||
+      request.evidence.length === 0 ||
+      request.evidence.length > MAX_TOKEN_LENGTH
+    ) {
+      return FAILURE;
+    }
+
+    const body = new URLSearchParams({
+      secret: options.secret,
+      response: request.evidence,
+      idempotency_key: globalThis.crypto.randomUUID(),
+      ...(request.ip ? { remoteip: request.ip } : {}),
+    });
+    try {
+      const response = await verify(SITEVERIFY, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!response.ok) return FAILURE;
+      const result = (await response.json()) as { success?: unknown; hostname?: unknown; action?: unknown };
+      if (
+        result.success !== true ||
+        typeof result.hostname !== 'string' ||
+        !hostnames.has(result.hostname.toLowerCase()) ||
+        result.action !== options.action
+      ) {
+        return FAILURE;
+      }
+      return { ok: true };
+    } catch {
+      return FAILURE;
+    }
+  };
+}