@flayerlabs/gamemode-gate 0.1.0 → 0.3.0

package/src/registry.ts

@@ -1,5 +1,9 @@
 import type { Pool } from 'pg';
-import type { GameRegistration } from '@flayerlabs/gamemode-spec/embed';
+import {
+  parseGameServerOrigins,
+  type GameRegistration,
+  type GameSecurityProfile,
+} from '@flayerlabs/gamemode-spec/embed';
 
 /**
  * Which game a coin plays, and everything the page embedding it needs to know.
@@ -15,10 +19,7 @@ export type Registration = GameRegistration;
  * Semantic fields, never CSP text: a policy assembled by string concatenation somewhere else is a
  * policy someone can inject into.
  */
-export interface SecurityProfile {
-  kind: 'game';
-  connect: { https: string; wss: string };
-}
+export type SecurityProfile = GameSecurityProfile;
 
 export class InvalidRegistration extends Error {
   constructor(message: string) {
@@ -96,16 +97,32 @@ export function gateOrigin(value: unknown): string {
   return url.origin;
 }
 
+/** Validate the reviewed origins a creator-owned authoritative game server may use. */
+export function gameServerOrigins(value: unknown): readonly string[] {
+  const origins = parseGameServerOrigins(value);
+  if (origins === null) {
+    throw new InvalidRegistration('game server origins must be at most four distinct public HTTPS origins');
+  }
+  return origins;
+}
+
 /** The profile for a registration. The websocket address is derived, never supplied separately. */
-export function securityProfile(registration: Pick<Registration, 'gateOrigin'>): SecurityProfile {
+export function securityProfile(
+  registration: Pick<Registration, 'gateOrigin' | 'gameServerOrigins'>,
+): SecurityProfile {
   // Revalidated here on purpose: this is the value that leaves for another system, and checking it
   // at the boundary costs nothing.
   const origin = gateOrigin(registration.gateOrigin);
+  const servers = gameServerOrigins(registration.gameServerOrigins);
   return {
     kind: 'game',
     // Same host, same port, different scheme. Deriving it means the two can never name different
     // servers, which a second hand-entered field eventually would.
-    connect: { https: origin, wss: `wss://${new URL(origin).host}` },
+    connect: {
+      https: origin,
+      wss: `wss://${new URL(origin).host}`,
+      ...(servers.length === 0 ? {} : { gameServerOrigins: servers }),
+    },
   };
 }
 
@@ -136,12 +153,14 @@ export function checkRegistration(entry: Registration): Registration {
   if (typeof entry?.coin !== 'string' || !ADDRESS.test(entry.coin)) {
     throw new InvalidRegistration('coin must be a wallet address');
   }
+  const servers = gameServerOrigins(entry.gameServerOrigins);
   return {
     chainId: chainId(entry.chainId),
     coin: entry.coin.toLowerCase(),
     gameId: id(entry.gameId, 'game'),
     deployId: deployId(entry.deployId),
     gateOrigin: gateOrigin(entry.gateOrigin),
+    ...(servers.length === 0 ? {} : { gameServerOrigins: servers }),
   };
 }
 
@@ -150,16 +169,19 @@ export function checkRegistration(entry: Registration): Registration {
  */
 export async function pinGameRegistration(pool: Pool, entry: Registration): Promise<Registration> {
   const checked = checkRegistration(entry);
+  const servers = checked.gameServerOrigins ?? [];
   const result = await pool.query(
-    `insert into registrations (chain_id, coin, game_id, gate_origin, deploy_id) values ($1, $2, $3, $4, $5)
+    `insert into registrations (chain_id, coin, game_id, gate_origin, deploy_id, game_server_origins)
+     values ($1, $2, $3, $4, $5, $6)
      on conflict (chain_id, coin) do update set
        updated_at = registrations.updated_at
      where registrations.disabled_at is null
        and registrations.game_id = excluded.game_id
        and registrations.gate_origin = excluded.gate_origin
        and registrations.deploy_id = excluded.deploy_id
+       and registrations.game_server_origins = excluded.game_server_origins
      returning coin`,
-    [checked.chainId, checked.coin, checked.gameId, checked.gateOrigin, checked.deployId],
+    [checked.chainId, checked.coin, checked.gameId, checked.gateOrigin, checked.deployId, servers],
   );
   if (result.rows.length === 0) throw new RegistrationConflict();
   return checked;
@@ -180,8 +202,9 @@ export async function resolveGameRegistration(
     game_id: string;
     gate_origin: string;
     deploy_id: string;
+    game_server_origins: string[];
   }>(
-    `select chain_id::text, coin, game_id, gate_origin, deploy_id
+    `select chain_id::text, coin, game_id, gate_origin, deploy_id, game_server_origins
      from registrations where chain_id = $1 and coin = $2 and disabled_at is null`,
     [checkedChainId, coin.toLowerCase()],
   );
@@ -193,6 +216,7 @@ export async function resolveGameRegistration(
         gameId: row.game_id,
         gateOrigin: row.gate_origin,
         deployId: row.deploy_id,
+        gameServerOrigins: row.game_server_origins,
       })
     : null;
 }

package/src/room.ts

@@ -1,7 +1,7 @@
 import type { Pool } from 'pg';
 import { Round } from '@flayerlabs/gamemode-spec/round';
 import type { Award, Command, Decision, GameModule, PlayerId, Refusal, RoundWindow } from '@flayerlabs/gamemode-spec';
-import type { LaunchContext } from '@flayerlabs/gamemode-spec/live';
+import type { LaunchContext, RoundTerms } from '@flayerlabs/gamemode-spec/live';
 import { isRefusal } from '@flayerlabs/gamemode-spec';
 import { inTransaction, toBigInt } from './store.js';
 
@@ -13,6 +13,7 @@ import { inTransaction, toBigInt } from './store.js';
  * them. Excluding it from the type is better than checking for it: the mistake stops compiling.
  */
 type PlayerCommand<Action> = Exclude<Command<Action>, { kind: 'wake' }>;
+export type ScoreAuthority = 'rules' | 'external-server';
 
 /**
  * A round, made durable.
@@ -38,7 +39,8 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     private round: Round<Config, State, Event, Action, PublicView, PlayerView>,
     readonly window: RoundWindow,
     readonly launch: LaunchContext,
-    readonly weiPerPoint: bigint,
+    readonly terms: RoundTerms,
+    readonly scoreAuthority: ScoreAuthority,
     private seq: number,
   ) {}
 
@@ -52,6 +54,10 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       window: RoundWindow;
       weiPerPoint: bigint;
       walletCapWei: bigint;
+      pointsPerDollar: number;
+      usdPerEth: number;
+      maxPointsPerPlayer: number;
+      scoreAuthority: ScoreAuthority;
       poolId: string;
       booksCloseAt?: number;
       launch?: {
@@ -66,6 +72,9 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     if (!Number.isSafeInteger(booksCloseAt) || booksCloseAt < round.window.closesAt) {
       throw new RangeError('booksCloseAt must be a safe timestamp at or after closesAt');
     }
+    if (!Number.isSafeInteger(round.maxPointsPerPlayer) || round.maxPointsPerPlayer <= 0) {
+      throw new RangeError('maxPointsPerPlayer must be a positive safe integer');
+    }
     const launch = Object.freeze({
       roundId: round.id,
       poolId: round.poolId,
@@ -77,16 +86,30 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       closesAt: round.window.closesAt,
       booksCloseAt,
     });
+    const terms: RoundTerms = Object.freeze({
+      maxPointsPerPlayer: round.maxPointsPerPlayer,
+      walletCapWei: round.walletCapWei,
+      weiPerPoint: round.weiPerPoint,
+      pointsPerDollar: round.pointsPerDollar,
+      usdPerEth: round.usdPerEth,
+    });
     const started = Round.start(game, round.config, round.seed, round.window);
     await pool.query(
       `insert into rounds (
-         id, wei_per_point, wallet_cap_wei, pool_id, opens_at, closes_at, books_close_at,
+         id, game_id, wei_per_point, wallet_cap_wei, points_per_dollar, usd_per_eth,
+         max_points_per_player, score_authority,
+         pool_id, opens_at, closes_at, books_close_at,
          coin_address, coin_name, coin_symbol, coin_image_url, state, seq
-       ) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, 0)`,
+       ) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, 0)`,
       [
         round.id,
+        game.id,
         round.weiPerPoint.toString(),
         round.walletCapWei.toString(),
+        round.pointsPerDollar,
+        round.usdPerEth,
+        round.maxPointsPerPlayer,
+        round.scoreAuthority,
         round.poolId,
         round.window.opensAt,
         round.window.closesAt,
@@ -98,7 +121,17 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
         serialise(game.id, started.snapshot()),
       ],
     );
-    return new Room(pool, game, round.id, started, round.window, launch, round.weiPerPoint, 0);
+    return new Room(
+      pool,
+      game,
+      round.id,
+      started,
+      round.window,
+      launch,
+      terms,
+      round.scoreAuthority,
+      0,
+    );
   }
 
   /** Pick up a round that already exists. Returns null if there is no such round. */
@@ -119,14 +152,23 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       coin_symbol: string;
       coin_image_url: string | null;
       wei_per_point: string;
+      wallet_cap_wei: string;
+      points_per_dollar: number;
+      usd_per_eth: number;
+      max_points_per_player: string;
+      score_authority: ScoreAuthority;
+      game_id: string;
     }>(
       `select state, seq, pool_id, opens_at, closes_at, books_close_at, wei_per_point,
+              wallet_cap_wei, points_per_dollar, usd_per_eth,
+              max_points_per_player, score_authority, game_id,
               coin_address, coin_name, coin_symbol, coin_image_url
        from rounds where id = $1`,
       [id],
     );
     const row = result.rows[0];
     if (!row) return null;
+    if (row.game_id !== game.id) return null;
 
     const window = { opensAt: Number(row.opens_at), closesAt: Number(row.closes_at) };
     const launch = Object.freeze({
@@ -139,6 +181,13 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       ...window,
       booksCloseAt: Number(row.books_close_at),
     });
+    const terms: RoundTerms = Object.freeze({
+      maxPointsPerPlayer: Number(row.max_points_per_player),
+      walletCapWei: toBigInt(row.wallet_cap_wei),
+      weiPerPoint: toBigInt(row.wei_per_point),
+      pointsPerDollar: Number(row.points_per_dollar),
+      usdPerEth: Number(row.usd_per_eth),
+    });
     return new Room(
       pool,
       game,
@@ -146,7 +195,8 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       Round.resume(game, row.state, window),
       window,
       launch,
-      toBigInt(row.wei_per_point),
+      terms,
+      row.score_authority,
       row.seq,
     );
   }
@@ -200,6 +250,9 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
    * is meant to be one writer per round; this is what makes a broken assumption loud.
    */
   private async commit(seq: number, command: Command<Action>, state: State, awards: Award[]): Promise<void> {
+    if (awards.length > 0 && this.scoreAuthority !== 'rules') {
+      throw new Error(`${this.id}: rules cannot award points for an externally scored round`);
+    }
     await inTransaction(this.pool, async (tx) => {
       const updated = await tx.query(
         `update rounds set state = $2, seq = $3 where id = $1 and seq = $4`,
@@ -216,11 +269,19 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       for (const award of awards) {
         // Same transaction as the state that earned them. Points credited without the state that
         // justifies them, or the reverse, is a ledger nobody can reconcile.
-        await tx.query(
+        const points = Math.floor(award.points);
+        if (points > this.terms.maxPointsPerPlayer) {
+          throw new Error(`${this.game.id}: awards exceeded the declared maximum for ${award.player}`);
+        }
+        const credited = await tx.query(
           `insert into balances (round_id, player, points) values ($1, $2, $3)
-           on conflict (round_id, player) do update set points = balances.points + excluded.points`,
-          [this.id, award.player, Math.floor(award.points)],
+           on conflict (round_id, player) do update set points = balances.points + excluded.points
+           where balances.points + excluded.points <= $4`,
+          [this.id, award.player, points, this.terms.maxPointsPerPlayer],
         );
+        if (credited.rowCount !== 1) {
+          throw new Error(`${this.game.id}: awards exceeded the declared maximum for ${award.player}`);
+        }
       }
     });
   }

package/src/server.ts

@@ -4,15 +4,25 @@ import cors from '@fastify/cors';
 import type { Pool } from 'pg';
 import type { Command, GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
 import { isRefusal } from '@flayerlabs/gamemode-spec';
-import type { PresenceState } from '@flayerlabs/gamemode-spec/live';
+import type {
+  EconomyBalance,
+  PresenceState,
+  RoundTerms,
+  WireEconomyBalance,
+  WireRoundTerms,
+} from '@flayerlabs/gamemode-spec/live';
 import { isReactionId, LIVE_PROTOCOL_VERSION } from '@flayerlabs/gamemode-spec/live';
-import { Room } from './room.js';
+import { Room, type ScoreAuthority } from './room.js';
 import { CLAIM_AUTHORIZATION_TTL_MS, Claims, isClaimAmount, isClaimRequestId } from './claims.js';
 import { NotSignedIn, Sessions } from './sessions.js';
 import type { Discovery, Launch, PoolKey } from './chain/discover.js';
 import type { Settlement } from './settlement.js';
 import { resolveEconomy } from './economy.js';
 import { encodeHookData } from './chain/signer.js';
+import { hasBearerToken } from './bearer.js';
+import { GameServerAwards, type GameServerAwardRequest } from './game-server-awards.js';
+import { issuePlayerJoinTicket } from './player-join-tickets.js';
+import { gameServerOrigins } from './registry.js';
 
 /**
  * The gate's door.
@@ -26,9 +36,8 @@ import { encodeHookData } from './chain/signer.js';
  * that size would be guessing at the shape of a problem nobody has.
  */
 
-interface GateBaseOptions<Config, State, Event, Action, PublicView, PlayerView> {
+interface GateBaseOptions {
   pool: Pool;
-  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>;
   sessions: Sessions;
   claims: Claims;
   /** How many points a dollar buys. The only economic number anyone sets by hand. */
@@ -65,18 +74,26 @@ interface GateBaseOptions<Config, State, Event, Action, PublicView, PlayerView>
 export type VerifiedLaunch = Readonly<Omit<Launch, 'poolKey'>> & { readonly poolKey: Readonly<PoolKey> };
 export type ConfigForLaunch<Config> = (launch: VerifiedLaunch) => Promise<Config>;
 
-export type GateOptions<Config, State, Event, Action, PublicView, PlayerView> = GateBaseOptions<
-  Config,
-  State,
-  Event,
-  Action,
-  PublicView,
-  PlayerView
-> & {
+export type GateOptions<Config, State, Event, Action, PublicView, PlayerView> = GateBaseOptions & {
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>;
   /** A static serialisable config, or a factory resolved once after each launch is verified. */
   config: Config | ConfigForLaunch<Config>;
 };
 
+export type MaxPointsForLaunch = (launch: VerifiedLaunch) => Promise<number>;
+
+/** Run a gate beside a creator-owned authoritative game server. */
+export interface GameServerGateOptions extends GateBaseOptions {
+  /** Stable game identifier used to protect durable room state from a different game module. */
+  gameId: string;
+  /** The most one wallet can earn in a round, or a value resolved once for each verified launch. */
+  maxPointsPerPlayer: number | MaxPointsForLaunch;
+  /** Dedicated server-to-server token. Never expose it to browser game code. */
+  awardToken: string;
+  /** Reviewed HTTPS origins that may receive player join tickets. The gate origin is always allowed. */
+  gameServerOrigins?: readonly string[];
+}
+
 /** Where an admission check is being made. Enough to tell a sign-in from a spend. */
 export interface AdmissionRequest {
   /** `session` on sign-in, `action` on gameplay, `claim` when allowance is about to be committed. */
@@ -105,6 +122,25 @@ const ADMIT_ALL: Admit = () => ({ ok: true });
 /** What the socket says, which is only the truth when nothing is proxying in front of the gate. */
 const ipOf = (request: FastifyRequest): string | null => request.ip || null;
 
+/** Wei has no JSON form, so terms cross as decimal strings, exactly as the economy balance does. */
+const wireTerms = (terms: RoundTerms): WireRoundTerms => ({
+  maxPointsPerPlayer: terms.maxPointsPerPlayer,
+  walletCapWei: terms.walletCapWei.toString(),
+  weiPerPoint: terms.weiPerPoint.toString(),
+  pointsPerDollar: terms.pointsPerDollar,
+  usdPerEth: terms.usdPerEth,
+});
+
+/** The same encoding for the per-player balance, wherever it leaves the process. */
+const wireEconomy = (balance: EconomyBalance): WireEconomyBalance => ({
+  weiPerPoint: balance.weiPerPoint.toString(),
+  earnedWei: balance.earnedWei.toString(),
+  heldWei: balance.heldWei.toString(),
+  spentWei: balance.spentWei.toString(),
+  availableWei: balance.availableWei.toString(),
+  holdExpiresAt: balance.holdExpiresAt,
+});
+
 /** How often each open room is nudged so a deadline nobody is watching still fires. */
 const TICK_MS = 250;
 
@@ -131,8 +167,85 @@ type AdoptionResult<Config, State, Event, Action, PublicView, PlayerView> =
   | { ok: true; room: Room<Config, State, Event, Action, PublicView, PlayerView>; created: boolean }
   | { ok: false; status: 409 | 503; message: string };
 
+interface AwardEndpoint {
+  token: string;
+  awards: GameServerAwards;
+  ticketAudiences: ReadonlySet<string>;
+}
+
+interface GameServerConfig {
+  maxPointsPerPlayer: number;
+}
+
+type GameServerState = Record<string, never>;
+type GameServerEvent = never;
+type GameServerAction = never;
+type GameServerPublicView = Record<string, never>;
+type GameServerPlayerView = Record<string, never>;
+
+const GAME_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+function gameServerModule(
+  id: string,
+): GameModule<
+  GameServerConfig,
+  GameServerState,
+  GameServerEvent,
+  GameServerAction,
+  GameServerPublicView,
+  GameServerPlayerView
+> {
+  return {
+    id,
+    parseAction: () => null,
+    initRound: () => ({}),
+    decide: (_state, command) => {
+      if (command.kind === 'action') return { refuse: 'gameplay.external' };
+      return { events: [] };
+    },
+    evolve: (state) => state,
+    publicView: () => ({}),
+    playerView: () => ({}),
+    nextWakeAt: () => null,
+    rewardBounds: (config) => ({ maxPointsPerPlayer: config.maxPointsPerPlayer }),
+  };
+}
+
 export function createGate<Config, State, Event, Action, PublicView, PlayerView>(
   options: GateOptions<Config, State, Event, Action, PublicView, PlayerView>,
+): FastifyInstance {
+  return createGateRuntime(options, 'rules');
+}
+
+export function createGameServerGate(options: GameServerGateOptions): FastifyInstance {
+  if (typeof options.gameId !== 'string' || !GAME_ID.test(options.gameId)) {
+    throw new RangeError('gameId must be a valid identifier');
+  }
+  if (typeof options.awardToken !== 'string' || options.awardToken.length < 32) {
+    throw new RangeError('awardToken must be at least 32 characters');
+  }
+
+  const maximum = options.maxPointsPerPlayer;
+  if (typeof maximum !== 'function' && (!Number.isSafeInteger(maximum) || maximum <= 0)) {
+    throw new RangeError('maxPointsPerPlayer must be a positive safe integer');
+  }
+  const config: GameServerConfig | ConfigForLaunch<GameServerConfig> =
+    typeof maximum === 'function'
+      ? async (launch) => ({ maxPointsPerPlayer: await maximum(launch) })
+      : { maxPointsPerPlayer: maximum };
+  const ticketAudiences = new Set([options.sessions.origin, ...gameServerOrigins(options.gameServerOrigins)]);
+  const { gameId, maxPointsPerPlayer: _maximum, awardToken, gameServerOrigins: _origins, ...base } = options;
+  return createGateRuntime(
+    { ...base, game: gameServerModule(gameId), config },
+    'external-server',
+    { token: awardToken, awards: new GameServerAwards(options.pool, gameId), ticketAudiences },
+  );
+}
+
+function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>(
+  options: GateOptions<Config, State, Event, Action, PublicView, PlayerView>,
+  scoreAuthority: ScoreAuthority,
+  awardEndpoint?: AwardEndpoint,
 ): FastifyInstance {
   const { pool, game, sessions, claims, discovery, settlement } = options;
   const admit = options.admit ?? ADMIT_ALL;
@@ -174,6 +287,10 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
     const existing = rooms.get(id);
     if (existing) return existing;
     const loaded = await Room.load(pool, game, id);
+    if (loaded && loaded.scoreAuthority !== scoreAuthority) {
+      app.log.error(`${id}: round belongs to ${loaded.scoreAuthority}, not ${scoreAuthority}`);
+      return null;
+    }
     // A durable row is history after its books close, not permission to resurrect an active
     // ticker and market stream every time somebody refreshes an old coin page. It still gets one
     // bounded catch-up through closesAt: a restart spanning the whole tail must not strand final
@@ -245,7 +362,11 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
         seed: Number(BigInt(launch.poolId) % 2147483647n),
         window: { opensAt: launch.opensAt, closesAt: launch.closesAt },
         weiPerPoint: economy.economy.weiPerPoint,
+        pointsPerDollar: economy.economy.pointsPerDollar,
+        usdPerEth: economy.economy.usdPerEth,
         walletCapWei: launch.walletCapWei,
+        maxPointsPerPlayer,
+        scoreAuthority,
         poolId: launch.poolId,
         booksCloseAt: launch.closesAt + settlementTailMs,
         launch: {
@@ -381,6 +502,89 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
       .send(adopted.room.launch);
   });
 
+  if (awardEndpoint) {
+    app.post('/rounds/:id/join-ticket', async (request, reply) => {
+      const who = player(request);
+      const id = (request.params as { id: string }).id;
+      const room = await roomFor(id);
+      if (!room) return reply.code(404).send({ message: 'that game is not running' });
+      const now = Date.now();
+      if (now >= room.window.closesAt) {
+        return reply.code(409).send({ message: 'that game has ended' });
+      }
+      const requested = (request.body as { audience?: unknown } | null)?.audience;
+      const audience = requested === undefined ? sessions.origin : requested;
+      if (typeof audience !== 'string' || !awardEndpoint.ticketAudiences.has(audience)) {
+        return reply.code(400).send({ message: 'that game server is not registered' });
+      }
+      return issuePlayerJoinTicket({
+        awardToken: awardEndpoint.token,
+        player: who,
+        gameId: game.id,
+        roundId: id,
+        audience,
+        closesAt: room.window.closesAt,
+        now,
+      });
+    });
+
+    app.post('/internal/rounds/:id/awards', async (request, reply) => {
+      if (!hasBearerToken(request.headers.authorization, awardEndpoint.token)) {
+        return reply.code(401).send({ message: 'game server authentication failed' });
+      }
+      const body = (request.body ?? {}) as Partial<GameServerAwardRequest>;
+      const result = await awardEndpoint.awards.record({
+        roundId: (request.params as { id: string }).id,
+        eventId: body.eventId as string,
+        player: body.player as PlayerId,
+        points: body.points as number,
+      });
+      if (!result.ok) {
+        const status =
+          result.refuse === 'award.invalid'
+            ? 400
+            : result.refuse === 'award.no_such_round' || result.refuse === 'award.wrong_authority'
+              ? 404
+              : 409;
+        return reply.code(status).send({ refuse: result.refuse });
+      }
+
+      announcePlayer(result.award.roundId, result.award.player);
+      return reply.code(result.created ? 201 : 200).send(result.award);
+    });
+
+    /**
+     * What one wallet has earned, so a game server can refuse a seat before the player sits in it.
+     *
+     * Advisory, and deliberately so. The award route still enforces the ceiling inside the
+     * transaction that moves the balance, so a caller that stops handling `award.limit_exceeded`
+     * because it checked here first has moved the check out of the only place it is atomic.
+     *
+     * Never routed through `roomFor`: that resurrects rooms, advances game state and returns
+     * nothing once the books close — none of which a read should do.
+     */
+    app.get('/internal/rounds/:id/players/:player', async (request, reply) => {
+      if (!hasBearerToken(request.headers.authorization, awardEndpoint.token)) {
+        return reply.code(401).send({ message: 'game server authentication failed' });
+      }
+      const params = request.params as { id: string; player: string };
+      const result = await awardEndpoint.awards.pointsFor({
+        roundId: params.id,
+        player: params.player as PlayerId,
+      });
+      if (!result.ok) {
+        return reply.code(result.refuse === 'award.invalid' ? 400 : 404).send({ refuse: result.refuse });
+      }
+
+      // `heldWei` moves on its own when an authorisation expires, so this answer is only true at the
+      // moment it is read. Points are monotone; the wei beside them are not.
+      const balance = await claims.economyBalance(result.standing.roundId, result.standing.player);
+      return reply
+        .header('cache-control', 'no-store')
+        .send({ ...result.standing, economy: wireEconomy(balance) });
+    });
+  }
+
   app.get('/rounds/:id', async (request, reply) => {
     const id = (request.params as { id: string }).id;
     const room = await roomFor(id);
@@ -388,7 +592,12 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
     const before = room.sequence();
     await room.tick(Date.now());
     if (room.sequence() !== before) announce(id);
-    return { sequence: room.sequence(), view: room.publicView(), launch: room.launch };
+    return {
+      sequence: room.sequence(),
+      view: room.publicView(),
+      launch: room.launch,
+      terms: wireTerms(room.terms),
+    };
   });
 
   app.post('/rounds/:id/join', async (request, reply) => {
@@ -396,6 +605,10 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
     if (!room) return reply.code(404).send({ message: 'that game is not running' });
 
     const id = (request.params as { id: string }).id;
+    if (scoreAuthority === 'external-server') {
+      player(request);
+      return { joined: true };
+    }
     const before = room.sequence();
     const result = await room.apply({
       kind: 'join',
@@ -432,6 +645,8 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
   app.post('/rounds/:id/claim', async (request, reply) => {
     const id = (request.params as { id: string }).id;
     const who = player(request);
+    const room = await roomFor(id);
+    if (!room) return reply.code(404).send({ message: 'that game is not running' });
     const { maxSpendWei, requestId } = request.body as { maxSpendWei?: string; requestId?: unknown };
     let upTo: bigint;
     try {
@@ -558,21 +773,14 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
       const balance = viewer
         ? await claims.economyBalance(id, viewer)
         : {
-            weiPerPoint: room.weiPerPoint,
+            weiPerPoint: room.terms.weiPerPoint,
             earnedWei: 0n,
             heldWei: 0n,
             spentWei: 0n,
             availableWei: 0n,
             holdExpiresAt: null,
           };
-      const economy = {
-        weiPerPoint: balance.weiPerPoint.toString(),
-        earnedWei: balance.earnedWei.toString(),
-        heldWei: balance.heldWei.toString(),
-        spentWei: balance.spentWei.toString(),
-        availableWei: balance.availableWei.toString(),
-        holdExpiresAt: balance.holdExpiresAt,
-      };
+      const economy = wireEconomy(balance);
       return {
         v: LIVE_PROTOCOL_VERSION,
         type: 'snapshot',
@@ -581,6 +789,7 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
         view: room.publicView(),
         you: viewer ? room.playerView(viewer) : null,
         economy,
+        terms: wireTerms(room.terms),
         launch: room.launch,
         presence: presence(id),
       };

package/src/sessions.ts

@@ -66,6 +66,11 @@ export class Sessions {
     }
   }
 
+  /** Exact configured gate origin, used as the default audience for a co-located game server. */
+  get origin(): string {
+    return this.gateOrigin;
+  }
+
   private sign(value: string): string {
     return createHmac('sha256', this.secret).update(value).digest('base64url');
   }