@flayerlabs/gamemode-gate 0.7.1 → 0.8.0

package/src/join-ticket-ledger.ts

@@ -0,0 +1,325 @@
+import { randomUUID } from 'node:crypto';
+import type { Pool, PoolClient } from 'pg';
+import { isAddress } from 'viem';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import type { PlayerJoinTicket } from '@flayerlabs/gamemode-spec/live';
+import { issuePlayerJoinTicket, readPlayerJoinTicket } from './player-join-tickets.js';
+import { inTransaction } from './store.js';
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const RATE_WINDOW_MS = 60_000;
+const LIST_LIMIT = 100;
+
+/** Enough for a player whose connection keeps dropping; far too few to farm seats with. */
+export const DEFAULT_MAX_JOIN_TICKETS_PER_MINUTE = 20;
+
+/**
+ * Where a ticket is in its life.
+ *
+ * `issued` is waiting to be presented. `expired` was never presented in time. `consumed` is a seat
+ * the game server accepted and has not given back. `released` is finished, by the server's word.
+ */
+export type JoinTicketStatus = 'issued' | 'expired' | 'consumed' | 'released';
+
+export interface JoinTicketRecord {
+  jti: string;
+  roundId: string;
+  player: PlayerId;
+  audience: string;
+  issuedAt: number;
+  expiresAt: number;
+  consumedAt: number | null;
+  releasedAt: number | null;
+  status: JoinTicketStatus;
+}
+
+/** How freely one wallet may be handed tickets. The gate operator's choice, per game. */
+export interface JoinTicketPolicy {
+  /**
+   * The most tickets one wallet may hold open in a round: issued and unexpired, or consumed and not
+   * yet released. Omitted, there is no limit.
+   *
+   * Set it only if your game server releases every seat it consumes, and releases them all when it
+   * restarts. A server that consumes and never releases locks its own players out for the round.
+   */
+  maxOpenPerPlayer?: number;
+  /** Tickets one wallet may be issued in a round in any minute. Defaults to twenty. */
+  maxIssuedPerMinutePerPlayer?: number;
+}
+
+export type JoinTicketIssueRefusal = 'ticket.rate_limited' | 'ticket.seat_open';
+
+export type JoinTicketIssueResult =
+  | { ok: true; ticket: PlayerJoinTicket }
+  | { ok: false; refuse: JoinTicketIssueRefusal };
+
+export type JoinTicketConsumeRefusal =
+  | 'ticket.invalid'
+  | 'ticket.no_such_round'
+  | 'ticket.wrong_audience'
+  | 'ticket.expired'
+  | 'ticket.already_consumed'
+  | 'ticket.released';
+
+/** The seat a server just accepted, and any other seats the same wallet still holds. */
+export interface JoinTicketConsumption {
+  ticket: JoinTicketRecord;
+  /**
+   * Other consumed, unreleased tickets for this wallet in this round, oldest first.
+   *
+   * A reconnecting player arrives before the server has noticed the old socket died. Close these
+   * connections and release them, and the wallet holds one seat.
+   */
+  otherOpen: string[];
+}
+
+export type JoinTicketConsumeResult =
+  | ({ ok: true } & JoinTicketConsumption)
+  | { ok: false; refuse: JoinTicketConsumeRefusal };
+
+/** Exactly one selector: one ticket, one wallet's tickets, or every ticket in the round. */
+export type JoinTicketReleaseSelector = { jti: string } | { player: PlayerId } | { all: true };
+
+export type JoinTicketReleaseResult =
+  | { ok: true; released: string[] }
+  | { ok: false; refuse: 'ticket.invalid' | 'ticket.no_such_round' };
+
+export interface JoinTicketCounts {
+  /** Every ticket this wallet has been issued in the round. */
+  issued: number;
+  /** Seats the game server consumed and has not released. */
+  open: number;
+}
+
+interface IssueInput {
+  awardToken: string;
+  roundId: string;
+  player: PlayerId;
+  audience: string;
+  closesAt: number;
+  now: number;
+}
+
+interface StoredTicket {
+  jti: string;
+  round_id: string;
+  player: string;
+  audience: string;
+  issued_at: string;
+  expires_at: string;
+  consumed_at: string | null;
+  released_at: string | null;
+}
+
+const COLUMNS = 'jti, round_id, player, audience, issued_at, expires_at, consumed_at, released_at';
+
+function statusOf(row: StoredTicket, now: number): JoinTicketStatus {
+  if (row.released_at !== null) return 'released';
+  if (row.consumed_at !== null) return 'consumed';
+  return Number(row.expires_at) > now ? 'issued' : 'expired';
+}
+
+const record = (row: StoredTicket, now: number): JoinTicketRecord => ({
+  jti: row.jti,
+  roundId: row.round_id,
+  player: row.player,
+  audience: row.audience,
+  issuedAt: Number(row.issued_at),
+  expiresAt: Number(row.expires_at),
+  consumedAt: row.consumed_at === null ? null : Number(row.consumed_at),
+  releasedAt: row.released_at === null ? null : Number(row.released_at),
+  status: statusOf(row, now),
+});
+
+function positiveInteger(value: number | undefined, name: string): number | null {
+  if (value === undefined) return null;
+  if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  return value;
+}
+
+/**
+ * The gate's record of every join ticket it signs, and what became of each.
+ *
+ * A ticket by itself is a stateless MAC: the gate that signed it cannot say how many a wallet
+ * holds, and every game server has to keep its own replay cache to stop one being presented twice.
+ * Writing each ticket down moves both jobs here. Issue is rationed per wallet, consume succeeds
+ * exactly once, and release is how the server that owns the connection says the seat is free.
+ *
+ * Scoped by game in every statement, so another game's round reads as no such round.
+ */
+export class JoinTickets {
+  private readonly maxOpenPerPlayer: number | null;
+  private readonly maxIssuedPerMinutePerPlayer: number;
+
+  constructor(
+    private readonly pool: Pool,
+    private readonly gameId: string,
+    policy: JoinTicketPolicy = {},
+  ) {
+    this.maxOpenPerPlayer = positiveInteger(policy.maxOpenPerPlayer, 'tickets.maxOpenPerPlayer');
+    this.maxIssuedPerMinutePerPlayer =
+      positiveInteger(policy.maxIssuedPerMinutePerPlayer, 'tickets.maxIssuedPerMinutePerPlayer') ??
+      DEFAULT_MAX_JOIN_TICKETS_PER_MINUTE;
+  }
+
+  /** Sign a ticket and write it down, or refuse a wallet that already holds too many. */
+  async issue(input: IssueInput): Promise<JoinTicketIssueResult> {
+    const player = input.player.toLowerCase();
+    const jti = randomUUID();
+    // Signed before the transaction: it is pure, and its bounds checks should fail before a lock.
+    const ticket = issuePlayerJoinTicket({ ...input, player, gameId: this.gameId, jti });
+
+    return inTransaction(this.pool, async (tx) => {
+      // Two requests from one wallet must not both read "under the limit" and both insert.
+      await lockPlayer(tx, input.roundId, player);
+      const counts = await tx.query<{ recent: string; open: string }>(
+        `select count(*) filter (where issued_at > $3)::text as recent,
+                count(*) filter (
+                  where released_at is null and (consumed_at is not null or expires_at > $4)
+                )::text as open
+         from join_tickets where round_id = $1 and player = $2`,
+        [input.roundId, player, input.now - RATE_WINDOW_MS, input.now],
+      );
+      const { recent, open } = counts.rows[0]!;
+      if (Number(recent) >= this.maxIssuedPerMinutePerPlayer) return { ok: false, refuse: 'ticket.rate_limited' };
+      if (this.maxOpenPerPlayer !== null && Number(open) >= this.maxOpenPerPlayer) {
+        return { ok: false, refuse: 'ticket.seat_open' };
+      }
+      await tx.query(
+        `insert into join_tickets (jti, round_id, player, audience, issued_at, expires_at)
+         values ($1, $2, $3, $4, $5, $6)`,
+        [jti, input.roundId, player, input.audience, input.now, ticket.expiresAt],
+      );
+      return { ok: true, ticket };
+    });
+  }
+
+  /**
+   * Accept a ticket a browser presented, exactly once.
+   *
+   * The gate verifies the MAC, the round, the audience and the expiry, so a game server in any
+   * language can admit a player with one request and no cryptography of its own.
+   */
+  async consume(
+    input: { awardToken: string; roundId: string; ticket: unknown; audience?: unknown },
+    now = Date.now(),
+  ): Promise<JoinTicketConsumeResult> {
+    if (typeof input.roundId !== 'string' || !IDENTIFIER.test(input.roundId)) {
+      return { ok: false, refuse: 'ticket.invalid' };
+    }
+    if (input.audience !== undefined && typeof input.audience !== 'string') {
+      return { ok: false, refuse: 'ticket.invalid' };
+    }
+    const claims = readPlayerJoinTicket(input.ticket, input.awardToken);
+    if (!claims || claims.gameId !== this.gameId) return { ok: false, refuse: 'ticket.invalid' };
+    if (!(await this.roundExists(input.roundId))) return { ok: false, refuse: 'ticket.no_such_round' };
+    if (claims.roundId !== input.roundId) return { ok: false, refuse: 'ticket.invalid' };
+    // A ticket minted for one server must not seat a player on another that shares the gate.
+    if (input.audience !== undefined && input.audience !== claims.audience) {
+      return { ok: false, refuse: 'ticket.wrong_audience' };
+    }
+
+    const updated = await this.pool.query<StoredTicket>(
+      `update join_tickets set consumed_at = $3
+       where jti = $1 and round_id = $2 and consumed_at is null and released_at is null and expires_at > $3
+       returning ${COLUMNS}`,
+      [claims.jti, input.roundId, now],
+    );
+    const row = updated.rows[0];
+    if (!row) {
+      const existing = await this.pool.query<StoredTicket>(
+        `select ${COLUMNS} from join_tickets where jti = $1 and round_id = $2`,
+        [claims.jti, input.roundId],
+      );
+      const found = existing.rows[0];
+      // A valid MAC with no row was signed by something other than this ledger.
+      if (!found) return { ok: false, refuse: 'ticket.invalid' };
+      if (found.released_at !== null) return { ok: false, refuse: 'ticket.released' };
+      if (found.consumed_at !== null) return { ok: false, refuse: 'ticket.already_consumed' };
+      return { ok: false, refuse: 'ticket.expired' };
+    }
+
+    const others = await this.pool.query<{ jti: string }>(
+      `select jti from join_tickets
+       where round_id = $1 and player = $2 and jti <> $3 and consumed_at is not null and released_at is null
+       order by consumed_at, jti`,
+      [input.roundId, row.player, row.jti],
+    );
+    return { ok: true, ticket: record(row, now), otherOpen: others.rows.map((other) => other.jti) };
+  }
+
+  /**
+   * Give seats back. Releasing an unpresented ticket voids it.
+   *
+   * Idempotent: a ticket already released is not released again and is not an error, so a server
+   * can call this from every code path that ends a connection.
+   */
+  async release(roundId: string, selector: unknown, now = Date.now()): Promise<JoinTicketReleaseResult> {
+    const parsed = parseSelector(selector);
+    if (typeof roundId !== 'string' || !IDENTIFIER.test(roundId) || !parsed) {
+      return { ok: false, refuse: 'ticket.invalid' };
+    }
+    if (!(await this.roundExists(roundId))) return { ok: false, refuse: 'ticket.no_such_round' };
+
+    const [filter, value] =
+      'jti' in parsed
+        ? ['and jti = $3', parsed.jti]
+        : 'player' in parsed
+          ? ['and player = $3', parsed.player.toLowerCase()]
+          : ['', null];
+    const released = await this.pool.query<{ jti: string }>(
+      `update join_tickets set released_at = $2
+       where round_id = $1 and released_at is null ${filter}
+       returning jti`,
+      value === null ? [roundId, now] : [roundId, now, value],
+    );
+    return { ok: true, released: released.rows.map((row) => row.jti) };
+  }
+
+  /** One wallet's most recent tickets in a round, newest first. Null for a round this game does not own. */
+  async list(roundId: string, player: string, now = Date.now()): Promise<JoinTicketRecord[] | null> {
+    if (!(await this.roundExists(roundId))) return null;
+    const rows = await this.pool.query<StoredTicket>(
+      `select ${COLUMNS} from join_tickets
+       where round_id = $1 and player = $2
+       order by issued_at desc, jti
+       limit ${LIST_LIMIT}`,
+      [roundId, player.toLowerCase()],
+    );
+    return rows.rows.map((row) => record(row, now));
+  }
+
+  async counts(roundId: string, player: string): Promise<JoinTicketCounts> {
+    const result = await this.pool.query<{ issued: string; open: string }>(
+      `select count(*)::text as issued,
+              count(*) filter (where consumed_at is not null and released_at is null)::text as open
+       from join_tickets where round_id = $1 and player = $2`,
+      [roundId, player.toLowerCase()],
+    );
+    return { issued: Number(result.rows[0]!.issued), open: Number(result.rows[0]!.open) };
+  }
+
+  private async roundExists(roundId: string): Promise<boolean> {
+    const round = await this.pool.query(
+      `select 1 from rounds where id = $1 and game_id = $2 and score_authority = 'external-server'`,
+      [roundId, this.gameId],
+    );
+    return round.rows.length > 0;
+  }
+}
+
+function lockPlayer(tx: PoolClient, roundId: string, player: string): Promise<unknown> {
+  return tx.query(`select pg_advisory_xact_lock(hashtextextended($1, 0))`, [`gamemode_join_ticket:${roundId}:${player}`]);
+}
+
+function parseSelector(value: unknown): JoinTicketReleaseSelector | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const { jti, player, all } = value as Record<string, unknown>;
+  // Exactly one, so a body that names a ticket and also says "all" cannot empty a round by accident.
+  if ([jti, player, all].filter((entry) => entry !== undefined).length !== 1) return null;
+  if (jti !== undefined) return typeof jti === 'string' && IDENTIFIER.test(jti) ? { jti } : null;
+  if (player !== undefined) {
+    return typeof player === 'string' && isAddress(player, { strict: false }) ? { player } : null;
+  }
+  return all === true ? { all: true } : null;
+}

package/src/main.ts

@@ -4,7 +4,13 @@ import { createPublicClient, http, isAddress, parseAbi, type PublicClient } from
 import type { FastifyInstance } from 'fastify';
 import type { GameModule } from '@flayerlabs/gamemode-spec';
 import type { SpendToken } from '@flayerlabs/gamemode-spec/live';
-import { createGate, type AnnouncedSpendToken, type GateAnnouncement, type PriceFor } from './server.js';
+import {
+  MAX_TRUSTED_PROXY_HOPS,
+  createGate,
+  type AnnouncedSpendToken,
+  type GateAnnouncement,
+  type PriceFor,
+} from './server.js';
 import { Ledger } from './ledger.js';
 import { Claims } from './claims.js';
 import { Sessions } from './sessions.js';
@@ -16,6 +22,13 @@ import { resolveEconomy } from './economy.js';
 import { deploymentFor, type GateDeployment } from './chain/chains.js';
 import { assertSecureConfig } from './chain/secure.js';
 import { RegistryPrices } from './chain/registry-prices.js';
+import {
+  isTurnstileTestingSecret,
+  resolveTurnstileEnv,
+  turnstileAdmission,
+  type TurnstileConfig,
+} from './turnstile.js';
+import { composeAdmit, createRateLimitAdmit } from './admission.js';
 
 /**
  * A production gate from an environment, assembled and checked.
@@ -68,6 +81,12 @@ export interface ResolvedGateConfig {
   pairedTokenCapHeadroomPercent: number;
   /** May lift the gate early or rotate the signer on-chain. Defaults to the signing key's address. */
   settler: `0x${string}` | null;
+  /** Reverse proxies between the internet and this process; decides whose address a request has. */
+  trustedProxyHops: number;
+  /** The Turnstile widget that guards sign-in, or null when sign-in needs no evidence. */
+  turnstile: TurnstileConfig | null;
+  /** Sign-ins one address may make in a minute. Zero is no limit. */
+  sessionsPerIpPerMinute: number;
 }
 
 export interface SpendTokenPricing {
@@ -180,6 +199,15 @@ function address(env: Env, name: string): `0x${string}` | null {
  *                            would otherwise quote; tokens neither here nor approved on the
  *                            manager's PairedTokenRegistry are refused.
  *   PAIRED_TOKEN_CAP_HEADROOM_PERCENT  default 25; headroom on caps sized for registry-priced pairings
+ *   TRUSTED_PROXY_HOPS       default 0; reverse proxies in front of the gate (2 on Railway, 3 with
+ *                            a CDN in front of that). Decides the address admission policy sees.
+ *   SESSIONS_PER_IP_PER_MINUTE  sign-ins one address may make in a minute. Default 30 when
+ *                            TRUSTED_PROXY_HOPS is set, otherwise 0 (no limit): until the gate is
+ *                            told its proxies it cannot tell one player's address from another's.
+ *   TURNSTILE_SITE_KEY       optional; with TURNSTILE_SECRET, sign-in requires a Turnstile token
+ *   TURNSTILE_SECRET         optional; set together with TURNSTILE_SITE_KEY or not at all
+ *   TURNSTILE_ACTION         default game-session
+ *   TURNSTILE_HOSTNAMES      default the host of SIGN_IN_DOMAIN; comma-separated
  */
 export function resolveGateEnv(env: Env): ResolvedGateConfig {
   const chainId = Number(required(env, 'CHAIN_ID'));
@@ -237,13 +265,19 @@ export function resolveGateEnv(env: Env): ResolvedGateConfig {
     );
   if (allowedOrigins.length === 0) throw new Error('ALLOWED_ORIGINS names no origins');
 
+  const signInDomain = required(env, 'SIGN_IN_DOMAIN');
+  const trustedProxyHops = integer(env, 'TRUSTED_PROXY_HOPS', 0);
+  if (trustedProxyHops > MAX_TRUSTED_PROXY_HOPS) {
+    throw new Error(`TRUSTED_PROXY_HOPS must be at most ${MAX_TRUSTED_PROXY_HOPS}`);
+  }
+
   return {
     chainId,
     rpcUrl: required(env, 'RPC_URL'),
     signerPrivateKey: signerPrivateKey as `0x${string}`,
     databaseUrl: required(env, 'DATABASE_URL'),
     sessionSecret: required(env, 'SESSION_SECRET'),
-    signInDomain: required(env, 'SIGN_IN_DOMAIN'),
+    signInDomain,
     gateOrigin: required(env, 'GATE_ORIGIN'),
     allowedOrigins,
     port: integer(env, 'PORT', 8790),
@@ -263,6 +297,9 @@ export function resolveGateEnv(env: Env): ResolvedGateConfig {
     spendTokens: spendTokens(env),
     pairedTokenCapHeadroomPercent: integer(env, 'PAIRED_TOKEN_CAP_HEADROOM_PERCENT', 25),
     settler: address(env, 'SETTLER'),
+    trustedProxyHops,
+    turnstile: resolveTurnstileEnv(env, signInDomain),
+    sessionsPerIpPerMinute: integer(env, 'SESSIONS_PER_IP_PER_MINUTE', trustedProxyHops > 0 ? 30 : 0),
   };
 }
 
@@ -399,6 +436,20 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
   const signer = new PayloadSigner(config.signerPrivateKey, config.chainId, config.deployment.spendGatedCalculator);
   const settler = config.settler ?? signer.address;
 
+  const turnstile = config.turnstile ? turnstileAdmission(config.turnstile) : null;
+  if (config.turnstile && isTurnstileTestingSecret(config.turnstile.secret)) {
+    // Loud because it is silent otherwise: the widget renders and every caller passes.
+    console.warn('TURNSTILE_SECRET is a Cloudflare testing secret: sign-in is not protected');
+  }
+  // The rate limit first: a caller over budget is refused before a Turnstile token is spent on them.
+  const rateLimit =
+    config.sessionsPerIpPerMinute > 0
+      ? createRateLimitAdmit({
+          limits: { session: { perIp: { max: config.sessionsPerIpPerMinute, windowMs: 60_000 } } },
+        })
+      : undefined;
+  const admit = rateLimit || turnstile ? composeAdmit(rateLimit, turnstile?.admit) : undefined;
+
   const announce = (): GateAnnouncement => ({
     chainId: config.chainId,
     contracts: {
@@ -420,6 +471,7 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     accepting: true,
     publicLaunchesOpen: true,
     privateLaunches: false,
+    ...(turnstile ? { admission: turnstile.admission } : {}),
   });
 
   const app = createGate({
@@ -448,6 +500,8 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     }),
     settlement: new Settlement(pool, ledger, client, config.deployment.spendGatedCalculator),
     allowedOrigins: config.allowedOrigins,
+    trustedProxyHops: config.trustedProxyHops,
+    ...(admit ? { admit } : {}),
     announce,
     readiness: createGateReadiness({ origin: config.gateOrigin, chainId: config.chainId,
       positionManager: config.deployment.positionManager, signer, pool, client }),

package/src/player-join-tickets.ts

@@ -31,6 +31,8 @@ interface IssuePlayerJoinTicketOptions extends VerifyPlayerJoinTicketOptions {
   player: PlayerId;
   closesAt: number;
   now: number;
+  /** The ticket's unique ID, when the caller has already written it down. Random when omitted. */
+  jti?: string;
 }
 
 interface TicketBody extends VerifiedPlayerJoin {
@@ -66,6 +68,7 @@ export function issuePlayerJoinTicket(options: IssuePlayerJoinTicketOptions): Pl
   if (!Number.isSafeInteger(options.closesAt) || options.closesAt <= now) {
     throw new RangeError('the round must still be open');
   }
+  if (options.jti !== undefined && !ID.test(options.jti)) throw new RangeError('jti must be a valid identifier');
   const expiresAt = Math.min(now + PLAYER_JOIN_TICKET_TTL_MS, options.closesAt);
   const claims: TicketBody = {
     v: 1,
@@ -76,29 +79,27 @@ export function issuePlayerJoinTicket(options: IssuePlayerJoinTicketOptions): Pl
     audience: options.audience,
     issuedAt: now,
     expiresAt,
-    jti: randomUUID(),
+    jti: options.jti ?? randomUUID(),
   };
   const body = Buffer.from(JSON.stringify(claims)).toString('base64url');
   return { ticket: `gmj1.${body}.${mac(body, options.awardToken)}`, expiresAt };
 }
 
-/** Verify an opaque browser join ticket before binding a socket to its wallet. */
-export function verifyPlayerJoinTicket(
-  ticket: unknown,
-  options: VerifyPlayerJoinTicketOptions,
-): VerifiedPlayerJoin | null {
-  if (
-    options.awardToken.length < 32 ||
-    typeof ticket !== 'string' ||
-    ticket.length === 0 ||
-    ticket.length > MAX_TICKET_LENGTH
-  ) {
+/**
+ * Check a ticket's MAC and shape, and nothing about when or where it is being presented.
+ *
+ * For the gate's own ledger, which then decides freshness and scope from the row it wrote. A
+ * game server must use {@link verifyPlayerJoinTicket}: a ticket that only passes this is authentic,
+ * not acceptable.
+ */
+export function readPlayerJoinTicket(ticket: unknown, awardToken: string): VerifiedPlayerJoin | null {
+  if (awardToken.length < 32 || typeof ticket !== 'string' || ticket.length === 0 || ticket.length > MAX_TICKET_LENGTH) {
     return null;
   }
   const parts = ticket.split('.');
   if (parts.length !== 3 || parts[0] !== 'gmj1') return null;
   const [, body, signature] = parts as [string, string, string];
-  if (!body || !signature || !matches(body, signature, options.awardToken)) return null;
+  if (!body || !signature || !matches(body, signature, awardToken)) return null;
 
   let value: Record<string, unknown>;
   try {
@@ -109,7 +110,6 @@ export function verifyPlayerJoinTicket(
     return null;
   }
 
-  const now = Date.now();
   if (
     value.v !== 1 ||
     value.kind !== 'player-join' ||
@@ -128,11 +128,6 @@ export function verifyPlayerJoinTicket(
     !Number.isSafeInteger(value.expiresAt) ||
     typeof value.jti !== 'string' ||
     !ID.test(value.jti) ||
-    value.gameId !== options.gameId ||
-    value.roundId !== options.roundId ||
-    value.audience !== options.audience ||
-    value.issuedAt > now + CLOCK_SKEW_MS ||
-    value.expiresAt <= now ||
     value.expiresAt <= value.issuedAt ||
     value.expiresAt - value.issuedAt > PLAYER_JOIN_TICKET_TTL_MS
   ) {
@@ -149,3 +144,23 @@ export function verifyPlayerJoinTicket(
     jti: value.jti,
   };
 }
+
+/** Verify an opaque browser join ticket before binding a socket to its wallet. */
+export function verifyPlayerJoinTicket(
+  ticket: unknown,
+  options: VerifyPlayerJoinTicketOptions,
+): VerifiedPlayerJoin | null {
+  const claims = readPlayerJoinTicket(ticket, options.awardToken);
+  const now = Date.now();
+  if (
+    !claims ||
+    claims.gameId !== options.gameId ||
+    claims.roundId !== options.roundId ||
+    claims.audience !== options.audience ||
+    claims.issuedAt > now + CLOCK_SKEW_MS ||
+    claims.expiresAt <= now
+  ) {
+    return null;
+  }
+  return claims;
+}