@flayerlabs/gamemode-gate 0.7.1 → 0.8.0

package/src/admission.ts

@@ -0,0 +1,273 @@
+import type { Admission, AdmissionRequest, Admit } from './server.js';
+
+type Checkpoint = AdmissionRequest['at'];
+
+const TOO_MANY: Admission = { ok: false, reason: 'too many tries, wait a minute' };
+const SUSPICIOUS: Admission = { ok: false, reason: 'you cannot play from this network' };
+
+/** IPv4 arriving over a dual-stack socket is the same caller as the bare IPv4 address. */
+export function normaliseIp(ip: string): string {
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip);
+  return (mapped ? mapped[1]! : ip).toLowerCase();
+}
+
+/**
+ * Run several admission policies as one. The first refusal is the answer.
+ *
+ * In order, so put the cheap local checks first: a rate limit that refuses saves the Turnstile
+ * round trip behind it, and a spent Turnstile token is not wasted on a caller already over budget.
+ */
+export function composeAdmit(...policies: readonly (Admit | undefined)[]): Admit {
+  const active = policies.filter((policy): policy is Admit => policy !== undefined);
+  return async (request) => {
+    for (const policy of active) {
+      const admission = await policy(request);
+      if (!admission.ok) return admission;
+    }
+    return { ok: true };
+  };
+}
+
+/** At most `max` requests in any `windowMs`, approximately: two adjacent windows are weighed. */
+export interface Rate {
+  max: number;
+  windowMs: number;
+}
+
+export interface CheckpointLimits {
+  /** Skipped when the caller's address is unknown. */
+  perIp?: Rate;
+  /** Skipped at `session`, where nobody has proved who they are yet. */
+  perPlayer?: Rate;
+}
+
+export type RateLimits = Partial<Record<Checkpoint, CheckpointLimits>>;
+
+export interface RateLimitAdmitOptions {
+  limits: RateLimits;
+  /** Most distinct callers remembered at once. Bounds memory under rotating addresses. */
+  maxKeys?: number;
+  /** Test seam. */
+  now?: () => number;
+}
+
+/**
+ * Budgets generous enough for a household or an office behind one address, and far too small to
+ * farm sessions or tickets with. Gameplay and claims have no default: only the game knows its
+ * cadence, and a false refusal on a claim costs a player a purchase.
+ */
+export const DEFAULT_RATE_LIMITS: RateLimits = {
+  session: { perIp: { max: 30, windowMs: 60_000 } },
+  ticket: { perIp: { max: 60, windowMs: 60_000 } },
+};
+
+const DEFAULT_MAX_KEYS = 100_000;
+
+interface Bucket {
+  /** The start of the current fixed window. */
+  start: number;
+  count: number;
+  /** What the previous window ended with, weighed in by how much of it still overlaps. */
+  previous: number;
+}
+
+function assertRate(rate: Rate | undefined, name: string): void {
+  if (rate === undefined) return;
+  if (!Number.isSafeInteger(rate.max) || rate.max <= 0) throw new RangeError(`${name}.max must be a positive safe integer`);
+  if (!Number.isSafeInteger(rate.windowMs) || rate.windowMs <= 0) {
+    throw new RangeError(`${name}.windowMs must be a positive safe integer`);
+  }
+}
+
+/**
+ * A request budget per address and per wallet, kept in this process.
+ *
+ * In memory because a gate is one process per game: there is no second replica for a caller to
+ * spread across, and a budget that survives a restart is not worth a database write on every
+ * action. The budget is spent only by admitted requests, so a caller refused by an earlier policy
+ * in {@link composeAdmit} does not burn it.
+ *
+ * Needs the real caller address. Behind a proxy, set `trustedProxyHops` first: otherwise every
+ * player shares the proxy's address and one budget.
+ */
+export function createRateLimitAdmit(options: RateLimitAdmitOptions): Admit {
+  for (const [at, limits] of Object.entries(options.limits)) {
+    assertRate(limits?.perIp, `limits.${at}.perIp`);
+    assertRate(limits?.perPlayer, `limits.${at}.perPlayer`);
+  }
+  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+  if (!Number.isSafeInteger(maxKeys) || maxKeys <= 0) throw new RangeError('maxKeys must be a positive safe integer');
+  const now = options.now ?? Date.now;
+  const buckets = new Map<string, Bucket>();
+
+  /** Whether one more request fits, without spending it. */
+  const fits = (key: string, rate: Rate, at: number): boolean => {
+    const bucket = buckets.get(key);
+    if (!bucket) return true;
+    const elapsed = at - bucket.start;
+    if (elapsed >= 2 * rate.windowMs) return true;
+    const [current, previous] = elapsed >= rate.windowMs ? [0, bucket.count] : [bucket.count, bucket.previous];
+    const into = elapsed % rate.windowMs;
+    return current + previous * (1 - into / rate.windowMs) < rate.max;
+  };
+
+  const spend = (key: string, rate: Rate, at: number): void => {
+    const bucket = buckets.get(key);
+    const elapsed = bucket ? at - bucket.start : Infinity;
+    if (!bucket || elapsed >= 2 * rate.windowMs) {
+      buckets.delete(key);
+      if (buckets.size >= maxKeys) buckets.delete(buckets.keys().next().value as string);
+      buckets.set(key, { start: at, count: 1, previous: 0 });
+    } else if (elapsed >= rate.windowMs) {
+      bucket.previous = bucket.count;
+      bucket.count = 1;
+      bucket.start += rate.windowMs;
+    } else {
+      bucket.count += 1;
+    }
+  };
+
+  return (request) => {
+    const limits = options.limits[request.at];
+    if (!limits) return { ok: true };
+    const at = now();
+    const checks: [string, Rate][] = [];
+    if (limits.perIp && request.ip) checks.push([`${request.at}:ip:${normaliseIp(request.ip)}`, limits.perIp]);
+    if (limits.perPlayer && request.player) {
+      checks.push([`${request.at}:player:${request.player.toLowerCase()}`, limits.perPlayer]);
+    }
+    // All budgets are checked before any is spent, so a refusal by one does not drain another.
+    if (checks.some(([key, rate]) => !fits(key, rate, at))) return TOO_MANY;
+    for (const [key, rate] of checks) spend(key, rate, at);
+    return { ok: true };
+  };
+}
+
+/** What a reputation provider says about an address. Absent fields mean "not known to be". */
+export interface IpVerdict {
+  vpn?: boolean;
+  proxy?: boolean;
+  tor?: boolean;
+  /** A privacy relay such as iCloud Private Relay. Ordinary people use these. */
+  relay?: boolean;
+  /** A datacentre or cloud address. */
+  hosting?: boolean;
+}
+
+export type IpLookup = (ip: string, signal: AbortSignal) => Promise<IpVerdict>;
+
+export interface IpReputationAdmitOptions {
+  /** Your provider. The gate ships no default: every provider needs an account only you have. */
+  lookup: IpLookup;
+  /** Which checkpoints consult the provider. Defaults to `session` only. */
+  at?: readonly Checkpoint[];
+  /**
+   * Whether a verdict is a refusal. Defaults to VPN, proxy, Tor or hosting. Relays are admitted by
+   * default, because refusing them refuses every Safari user with Private Relay on.
+   */
+  refuse?: (verdict: IpVerdict) => boolean;
+  /** How long a verdict is reused. Defaults to one hour. */
+  cacheMs?: number;
+  /** Defaults to 2,000. */
+  timeoutMs?: number;
+  /** Most addresses remembered at once. Defaults to 50,000. */
+  maxCached?: number;
+  /**
+   * What to do when the provider fails or times out. Defaults to admitting: an outage at a third
+   * party should not close your game. Set true only if a lockout is cheaper for you than a bot.
+   */
+  failClosed?: boolean;
+  /** Test seam. */
+  now?: () => number;
+}
+
+const defaultRefuse = (verdict: IpVerdict): boolean =>
+  verdict.vpn === true || verdict.proxy === true || verdict.tor === true || verdict.hosting === true;
+
+/**
+ * Refuse callers whose address a reputation provider calls anonymising.
+ *
+ * A seam, not a detector. Proxy and VPN detection is a paid data product with false positives, and
+ * which of them a game can live with is the operator's call. Whatever the provider, one lookup is
+ * made per address per `cacheMs`, and concurrent requests from one address share it.
+ */
+export function createIpReputationAdmit(options: IpReputationAdmitOptions): Admit {
+  const checkpoints = new Set<Checkpoint>(options.at ?? ['session']);
+  const refuse = options.refuse ?? defaultRefuse;
+  const cacheMs = options.cacheMs ?? 60 * 60_000;
+  const timeoutMs = options.timeoutMs ?? 2_000;
+  const maxCached = options.maxCached ?? 50_000;
+  for (const [name, value] of [['cacheMs', cacheMs], ['timeoutMs', timeoutMs], ['maxCached', maxCached]] as const) {
+    if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  const now = options.now ?? Date.now;
+  const cache = new Map<string, { refused: boolean; until: number }>();
+  const inFlight = new Map<string, Promise<boolean | null>>();
+
+  const ask = async (ip: string): Promise<boolean | null> => {
+    try {
+      const refused = refuse(await options.lookup(ip, AbortSignal.timeout(timeoutMs)));
+      cache.delete(ip);
+      if (cache.size >= maxCached) cache.delete(cache.keys().next().value as string);
+      cache.set(ip, { refused, until: now() + cacheMs });
+      return refused;
+    } catch {
+      // Not cached: the next request asks again rather than inheriting an outage.
+      return null;
+    }
+  };
+
+  return async (request) => {
+    if (!checkpoints.has(request.at) || !request.ip) return { ok: true };
+    const ip = normaliseIp(request.ip);
+    const cached = cache.get(ip);
+    let refused: boolean | null;
+    if (cached && cached.until > now()) {
+      refused = cached.refused;
+    } else {
+      let pending = inFlight.get(ip);
+      if (!pending) {
+        pending = ask(ip).finally(() => inFlight.delete(ip));
+        inFlight.set(ip, pending);
+      }
+      refused = await pending;
+    }
+    if (refused === null) return options.failClosed ? SUSPICIOUS : { ok: true };
+    return refused ? SUSPICIOUS : { ok: true };
+  };
+}
+
+export interface IpinfoPrivacyOptions {
+  /** An IPinfo token on a plan that includes privacy detection. */
+  token: string;
+  /** Test seam. */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * A reference {@link IpLookup} for IPinfo's privacy detection endpoint.
+ *
+ * Here to show the shape of an adapter, and because it is one HTTP call. Check the response
+ * against your own IPinfo plan before relying on it: this library has no IPinfo account and does
+ * not test against the live service.
+ */
+export function ipinfoPrivacyLookup(options: IpinfoPrivacyOptions): IpLookup {
+  if (!options.token) throw new RangeError('IPinfo token is required');
+  const request = options.fetch ?? globalThis.fetch;
+  return async (ip, signal) => {
+    const response = await request(`https://ipinfo.io/${encodeURIComponent(ip)}/privacy`, {
+      headers: { authorization: `Bearer ${options.token}`, accept: 'application/json' },
+      signal,
+    });
+    if (!response.ok) throw new Error(`IPinfo answered ${response.status}`);
+    const body = (await response.json()) as Record<string, unknown>;
+    if (typeof body !== 'object' || body === null) throw new Error('IPinfo answered with something other than an object');
+    return {
+      vpn: body.vpn === true,
+      proxy: body.proxy === true,
+      tor: body.tor === true,
+      relay: body.relay === true,
+      hosting: body.hosting === true,
+    };
+  };
+}

package/src/chain/secure.ts

@@ -1,4 +1,5 @@
 import { keccak256, parseAbi, toHex, type PublicClient } from 'viem';
+import { spendAuthorisationTypedData } from '@flayerlabs/gamemode-spec/embed';
 import type { FlaunchVariant } from './chains.js';
 
 /**
@@ -25,8 +26,56 @@ const wiringAbi = parseAbi([
   'function registeredCalculators(address) view returns (bool)',
   'function hasRole(bytes32 role, address account) view returns (bool)',
   'function approvedRouters(address) view returns (bool)',
+  'function eip712Domain() view returns (bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt, uint256[] extensions)',
 ]);
 
+/**
+ * The EIP-712 domain this gate signs under, read off the typed-data builder so the two can never
+ * disagree. A calculator whose on-chain domain differs (the version-1 generation, say) rejects every
+ * authorisation this gate mints as `InvalidSigner` — at claim time, in a round that will not come
+ * back — so boot refuses it here instead.
+ */
+const SIGNING_DOMAIN = spendAuthorisationTypedData(
+  { buyer: `0x${'00'.repeat(20)}`, poolId: `0x${'00'.repeat(32)}`, deadline: 0n, spendCeilingWei: 0n },
+  1,
+  `0x${'00'.repeat(20)}`,
+).domain;
+
+/** What the calculator says its own EIP-712 domain is, or why it could not be read. */
+export type CalculatorDomain = { ok: true; name: string; version: string } | { ok: false; reason: string };
+
+/**
+ * Does this calculator verify signatures under the domain this gate signs?
+ *
+ * Reads `eip712Domain()` (EIP-5267) and compares name and version with the typed data the gate's
+ * signer produces. Same shape as {@link checkPositionManagerWiring}: a verdict with a reason the
+ * operator can act on, because the fix is one env var (`SPEND_GATED_CALCULATOR`), not a redeploy.
+ */
+export async function checkCalculatorDomain(
+  client: Pick<PublicClient, 'readContract'>,
+  calculator: `0x${string}`,
+): Promise<CalculatorDomain> {
+  let name: string;
+  let version: string;
+  try {
+    const domain = (await client.readContract({ address: calculator, abi: wiringAbi, functionName: 'eip712Domain' })) as readonly unknown[];
+    name = String(domain[1]);
+    version = String(domain[2]);
+  } catch {
+    return { ok: false, reason: `${calculator} does not answer eip712Domain() — is it a SpendGatedSignerFeeCalculator?` };
+  }
+  if (name !== SIGNING_DOMAIN.name || version !== SIGNING_DOMAIN.version) {
+    return {
+      ok: false,
+      reason:
+        `SPEND_GATED_CALCULATOR ${calculator} verifies "${name}" version ${version}, but this gate signs ` +
+        `"${SIGNING_DOMAIN.name}" version ${SIGNING_DOMAIN.version}; every authorisation it minted would be refused as ` +
+        'InvalidSigner. Point SPEND_GATED_CALCULATOR at the calculator generation this SDK pairs with',
+    };
+  }
+  return { ok: true, name, version };
+}
+
 export interface SecureConfig {
   chainId: number;
   signerPrivateKey: string;
@@ -65,6 +114,9 @@ export async function assertSecureConfig(client: PublicClient, config: SecureCon
     throw new Error(`SPEND_GATED_CALCULATOR ${config.spendGatedCalculator} holds no code on chain ${chainId}`);
   }
 
+  const domain = await checkCalculatorDomain(client, config.spendGatedCalculator);
+  if (!domain.ok) throw new Error(domain.reason);
+
   if (config.positionManager) await assertWiring(client, config);
 }
 

package/src/index.ts

@@ -2,6 +2,7 @@
 export {
   Claims,
   DEFAULT_SETTLEMENT_TAIL_MS,
+  MAX_TRUSTED_PROXY_HOPS,
   Room,
   Sessions,
   createGate,
@@ -9,6 +10,7 @@ export {
 } from './server.js';
 export type {
   Admission,
+  AdmissionAnnouncement,
   AdmissionRequest,
   Admit,
   AnnouncedSpendToken,
@@ -19,8 +21,27 @@ export type {
   PriceFor,
   VerifiedLaunch,
 } from './server.js';
-export { createTurnstileAdmit } from './turnstile.js';
-export type { TurnstileAdmitOptions } from './turnstile.js';
+export {
+  DEFAULT_RATE_LIMITS,
+  composeAdmit,
+  createIpReputationAdmit,
+  createRateLimitAdmit,
+  ipinfoPrivacyLookup,
+} from './admission.js';
+export type {
+  CheckpointLimits,
+  IpLookup,
+  IpReputationAdmitOptions,
+  IpVerdict,
+  IpinfoPrivacyOptions,
+  Rate,
+  RateLimitAdmitOptions,
+  RateLimits,
+} from './admission.js';
+export { IpBlocks, MAX_IP_BLOCKS } from './ip-blocks.js';
+export type { IpBlock, IpBlockRefusal, IpBlockResult } from './ip-blocks.js';
+export { createTurnstileAdmit, isTurnstileTestingSecret, resolveTurnstileEnv, turnstileAdmission } from './turnstile.js';
+export type { TurnstileAdmitOptions, TurnstileConfig } from './turnstile.js';
 
 export { Ledger } from './ledger.js';
 export type { Authorisation, Quote } from './ledger.js';
@@ -57,6 +78,17 @@ export type {
   GameServerPlayerStanding,
 } from './game-server-awards.js';
 export { PLAYER_JOIN_TICKET_TTL_MS, verifyPlayerJoinTicket } from './player-join-tickets.js';
+export { DEFAULT_MAX_JOIN_TICKETS_PER_MINUTE } from './join-ticket-ledger.js';
+export type {
+  JoinTicketConsumeRefusal,
+  JoinTicketConsumption,
+  JoinTicketCounts,
+  JoinTicketIssueRefusal,
+  JoinTicketPolicy,
+  JoinTicketRecord,
+  JoinTicketReleaseSelector,
+  JoinTicketStatus,
+} from './join-ticket-ledger.js';
 export type { VerifiedPlayerJoin, VerifyPlayerJoinTicketOptions } from './player-join-tickets.js';
 
 /**

package/src/ip-blocks.ts

@@ -0,0 +1,154 @@
+import { BlockList, isIP } from 'node:net';
+import type { Pool } from 'pg';
+import { normaliseIp } from './admission.js';
+
+/** A list longer than this is a job for a firewall in front of the gate, not a table inside it. */
+export const MAX_IP_BLOCKS = 10_000;
+const MAX_REASON_LENGTH = 200;
+const DEFAULT_REFRESH_MS = 30_000;
+
+export interface IpBlock {
+  /** Canonical network, such as `203.0.113.0/24` or `2001:db8::/32`. A single address is a /32 or /128. */
+  cidr: string;
+  /** An operator's note. Never shown to the player. */
+  reason: string | null;
+  createdAt: number;
+  /** Milliseconds, or null for a block that stays until it is removed. */
+  expiresAt: number | null;
+}
+
+export type IpBlockRefusal = 'ip_block.invalid' | 'ip_block.limit_exceeded';
+
+export type IpBlockResult = { ok: true; block: IpBlock } | { ok: false; refuse: IpBlockRefusal };
+
+interface StoredBlock {
+  cidr: string;
+  reason: string | null;
+  created_at: string;
+  expires_at: string | null;
+}
+
+const block = (row: StoredBlock): IpBlock => ({
+  cidr: row.cidr,
+  reason: row.reason,
+  createdAt: Number(row.created_at),
+  expiresAt: row.expires_at === null ? null : Number(row.expires_at),
+});
+
+/** An address or a network in CIDR form, or null. Host bits are allowed here and cleared on write. */
+function parseCidr(value: unknown): { address: string; prefix: number; family: 4 | 6 } | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 64) return null;
+  const [address, prefixText, ...rest] = value.trim().split('/');
+  if (!address || rest.length > 0) return null;
+  const family = isIP(address);
+  if (family !== 4 && family !== 6) return null;
+  const widest = family === 4 ? 32 : 128;
+  if (prefixText === undefined) return { address, prefix: widest, family };
+  if (!/^\d{1,3}$/.test(prefixText)) return null;
+  const prefix = Number(prefixText);
+  // /0 would block every caller. That is turning the gate off, and not what a block list is for.
+  if (prefix < 1 || prefix > widest) return null;
+  return { address, prefix, family };
+}
+
+/**
+ * Addresses and networks this gate refuses, kept in Postgres and matched in memory.
+ *
+ * The table is the record; the in-memory list is what a request is checked against, because an
+ * admission check runs on every action and a query per action is not affordable. The list is
+ * rebuilt after every write through this instance and at most every `refreshMs` otherwise, so a
+ * block written by another process takes effect within that interval.
+ */
+export class IpBlocks {
+  private matcher = new BlockList();
+  private loadedAt = -Infinity;
+  private loading: Promise<void> | null = null;
+
+  constructor(
+    private readonly pool: Pool,
+    private readonly refreshMs = DEFAULT_REFRESH_MS,
+  ) {}
+
+  /** Whether an address is blocked. Loads the list on first use and refreshes it when stale. */
+  async blocks(ip: string | null, now = Date.now()): Promise<boolean> {
+    if (!ip) return false;
+    if (this.loadedAt === -Infinity) await this.reload(now);
+    // A stale list is refreshed behind the request: the answer is at most one interval old.
+    else if (now - this.loadedAt >= this.refreshMs) void this.reload(now).catch(() => undefined);
+    const address = normaliseIp(ip);
+    const family = isIP(address);
+    if (family !== 4 && family !== 6) return false;
+    return this.matcher.check(address, family === 4 ? 'ipv4' : 'ipv6');
+  }
+
+  /** Block an address or network. Blocking it again updates the reason and expiry. */
+  async add(input: { cidr?: unknown; reason?: unknown; expiresAt?: unknown }, now = Date.now()): Promise<IpBlockResult> {
+    const parsed = parseCidr(input?.cidr);
+    const reason = input?.reason ?? null;
+    const expiresAt = input?.expiresAt ?? null;
+    if (
+      !parsed ||
+      (reason !== null && (typeof reason !== 'string' || reason.length > MAX_REASON_LENGTH)) ||
+      (expiresAt !== null && (!Number.isSafeInteger(expiresAt) || (expiresAt as number) <= now))
+    ) {
+      return { ok: false, refuse: 'ip_block.invalid' };
+    }
+    const result = await this.pool.query<StoredBlock>(
+      `insert into ip_blocks (cidr, reason, created_at, expires_at)
+       select network(set_masklen($1::inet, $2)), $3, $4, $5
+       where (select count(*) from ip_blocks) < $6
+          or exists (select 1 from ip_blocks where cidr = network(set_masklen($1::inet, $2)))
+       on conflict (cidr) do update set reason = excluded.reason, expires_at = excluded.expires_at
+       returning cidr::text, reason, created_at, expires_at`,
+      [parsed.address, parsed.prefix, reason, now, expiresAt, MAX_IP_BLOCKS],
+    );
+    const row = result.rows[0];
+    if (!row) return { ok: false, refuse: 'ip_block.limit_exceeded' };
+    await this.reload(now);
+    return { ok: true, block: block(row) };
+  }
+
+  /** Remove a block. True if there was one. */
+  async remove(cidr: unknown, now = Date.now()): Promise<boolean | null> {
+    const parsed = parseCidr(cidr);
+    if (!parsed) return null;
+    const result = await this.pool.query(
+      'delete from ip_blocks where cidr = network(set_masklen($1::inet, $2))',
+      [parsed.address, parsed.prefix],
+    );
+    await this.reload(now);
+    return (result.rowCount ?? 0) > 0;
+  }
+
+  /** Every block still in force, newest first. */
+  async list(now = Date.now()): Promise<IpBlock[]> {
+    const result = await this.pool.query<StoredBlock>(
+      `select cidr::text, reason, created_at, expires_at from ip_blocks
+       where expires_at is null or expires_at > $1
+       order by created_at desc, cidr`,
+      [now],
+    );
+    return result.rows.map(block);
+  }
+
+  private reload(now: number): Promise<void> {
+    this.loading ??= (async () => {
+      try {
+        // Expired rows are cleared here rather than by a timer: a gate nobody calls has no work to do.
+        await this.pool.query('delete from ip_blocks where expires_at is not null and expires_at <= $1', [now]);
+        const rows = await this.pool.query<{ address: string; prefix: number; family: number }>(
+          'select host(cidr) as address, masklen(cidr) as prefix, family(cidr) as family from ip_blocks',
+        );
+        const next = new BlockList();
+        for (const row of rows.rows) {
+          next.addSubnet(row.address, Number(row.prefix), Number(row.family) === 4 ? 'ipv4' : 'ipv6');
+        }
+        this.matcher = next;
+        this.loadedAt = now;
+      } finally {
+        this.loading = null;
+      }
+    })();
+    return this.loading;
+  }
+}