@flayerlabs/gamemode-gate 0.1.0 → 0.2.0

package/src/economy.ts

@@ -53,7 +53,7 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
   if (!Number.isFinite(usdPerEth) || usdPerEth <= 0) {
     return { ok: false, problem: 'the ETH price must be a positive number', suggestedPointsPerDollar: pointsPerDollar };
   }
-  if (!Number.isFinite(maxPointsPerPlayer) || maxPointsPerPlayer <= 0) {
+  if (!Number.isSafeInteger(maxPointsPerPlayer) || maxPointsPerPlayer <= 0) {
     return {
       ok: false,
       problem: 'the game says a player can earn at most 0 points, so there is nothing to pay',

package/src/game-registry.ts

@@ -1,8 +1,8 @@
 import Fastify, { type FastifyInstance } from 'fastify';
 import cors from '@fastify/cors';
-import { createHash, timingSafeEqual } from 'node:crypto';
 import type { Pool } from 'pg';
 import { isAddress } from 'viem';
+import { hasBearerToken } from './bearer.js';
 import {
   InvalidRegistration,
   RegistrationConflict,
@@ -19,12 +19,6 @@ export interface GameRegistryOptions {
   writerToken: string;
 }
 
-const authorised = (header: string | undefined, token: string): boolean => {
-  const supplied = header?.startsWith('Bearer ') ? header.slice('Bearer '.length) : '';
-  const digest = (value: string): Buffer => createHash('sha256').update(value).digest();
-  return timingSafeEqual(digest(supplied), digest(token));
-};
-
 const routeChainId = (value: string): number | null => {
   if (!/^[1-9][0-9]*$/.test(value)) return null;
   const parsed = Number(value);
@@ -35,7 +29,7 @@ const internalRoute = (
   request: { headers: { authorization?: string | undefined }; params: unknown },
   token: string,
 ) => {
-  if (!authorised(request.headers.authorization, token)) {
+  if (!hasBearerToken(request.headers.authorization, token)) {
     return { ok: false as const, status: 401 as const, message: 'registry writer authentication failed' };
   }
   const { chainId: rawChainId, coin } = request.params as { chainId: string; coin: string };

package/src/game-server-awards.ts

@@ -0,0 +1,199 @@
+import type { Pool } from 'pg';
+import { isAddress } from 'viem';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import { inTransaction } from './store.js';
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** The JSON body a trusted creator server sends to the gate. */
+export interface GameServerAwardRequest {
+  eventId: string;
+  player: PlayerId;
+  points: number;
+}
+
+/** The durable receipt returned for a new award or an identical retry. */
+export interface GameServerAwardReceipt extends GameServerAwardRequest {
+  roundId: string;
+  totalPoints: number;
+}
+
+export type GameServerAwardRefusal =
+  | 'award.invalid'
+  | 'award.no_such_round'
+  | 'award.wrong_authority'
+  | 'award.not_open_yet'
+  | 'award.window_closed'
+  | 'award.event_mismatch'
+  | 'award.limit_exceeded';
+
+export type GameServerAwardResult =
+  | { ok: true; created: boolean; award: GameServerAwardReceipt }
+  | { ok: false; refuse: GameServerAwardRefusal };
+
+interface GameServerAwardInput extends GameServerAwardRequest {
+  roundId: string;
+}
+
+interface StoredAward {
+  round_id: string;
+  event_id: string;
+  player: string;
+  points: string;
+  total_points: string;
+}
+
+/** A result that must roll back any setup writes before it reaches the caller. */
+class RollbackResult extends Error {
+  constructor(readonly result: GameServerAwardResult) {
+    super('game server award did not commit');
+  }
+}
+
+const receipt = (row: StoredAward): GameServerAwardReceipt => ({
+  roundId: row.round_id,
+  eventId: row.event_id,
+  player: row.player,
+  points: Number(row.points),
+  totalPoints: Number(row.total_points),
+});
+
+const matches = (stored: GameServerAwardReceipt, input: GameServerAwardInput): boolean =>
+  stored.roundId === input.roundId &&
+  stored.eventId === input.eventId &&
+  stored.player === input.player &&
+  stored.points === input.points;
+
+const replay = (stored: GameServerAwardReceipt, input: GameServerAwardInput): GameServerAwardResult =>
+  matches(stored, input)
+    ? { ok: true, created: false, award: stored }
+    : { ok: false, refuse: 'award.event_mismatch' };
+
+/**
+ * Credit events from one trusted creator game server.
+ *
+ * The event receipt and balance move in one transaction. A stable event id makes retries safe,
+ * while the adopted round fixes the wallet, time and reward ceilings this module enforces.
+ */
+export class GameServerAwards {
+  constructor(
+    private readonly pool: Pool,
+    private readonly gameId: string,
+  ) {}
+
+  async record(candidate: GameServerAwardInput): Promise<GameServerAwardResult> {
+    if (
+      !candidate ||
+      typeof candidate.roundId !== 'string' ||
+      !IDENTIFIER.test(candidate.roundId) ||
+      typeof candidate.eventId !== 'string' ||
+      !IDENTIFIER.test(candidate.eventId) ||
+      typeof candidate.player !== 'string' ||
+      !isAddress(candidate.player, { strict: false }) ||
+      !Number.isSafeInteger(candidate.points) ||
+      candidate.points <= 0
+    ) {
+      return { ok: false, refuse: 'award.invalid' };
+    }
+
+    const input = { ...candidate, player: candidate.player.toLowerCase() };
+    const receivedAt = Date.now();
+
+    try {
+      return await inTransaction(this.pool, async (tx) => {
+        const prior = await tx.query<StoredAward>(
+          `select awards.round_id, awards.event_id, awards.player,
+                  awards.points::text, awards.total_points::text
+           from award_events awards
+           join rounds on rounds.id = awards.round_id
+           where awards.round_id = $1 and awards.event_id = $2 and rounds.game_id = $3`,
+          [input.roundId, input.eventId, this.gameId],
+        );
+        if (prior.rows[0]) return replay(receipt(prior.rows[0]), input);
+
+        const round = await tx.query<{
+          opens_at: string;
+          closes_at: string;
+          max_points_per_player: string;
+          score_authority: 'rules' | 'external-server';
+          game_id: string;
+        }>(
+          `select opens_at, closes_at, max_points_per_player, score_authority, game_id
+           from rounds where id = $1`,
+          [input.roundId],
+        );
+        const terms = round.rows[0];
+        if (!terms || terms.game_id !== this.gameId) {
+          return { ok: false, refuse: 'award.no_such_round' } as const;
+        }
+        if (terms.score_authority !== 'external-server') {
+          return { ok: false, refuse: 'award.wrong_authority' } as const;
+        }
+
+        // Reserve the event id before checking the balance. A concurrent retry waits on this
+        // unique row and then reads the first request's receipt. Without that ordering, it could
+        // see the first request's new balance and incorrectly fail the reward ceiling check.
+        const inserted = await tx.query<StoredAward>(
+          `insert into award_events (round_id, event_id, player, points, total_points)
+           values ($1, $2, $3, $4, $4)
+           on conflict (round_id, event_id) do nothing
+           returning round_id, event_id, player, points::text, total_points::text`,
+          [input.roundId, input.eventId, input.player, input.points],
+        );
+        if (!inserted.rows[0]) {
+          const concurrent = await tx.query<StoredAward>(
+            `select round_id, event_id, player, points::text, total_points::text
+             from award_events where round_id = $1 and event_id = $2`,
+            [input.roundId, input.eventId],
+          );
+          const stored = concurrent.rows[0];
+          if (!stored) throw new Error(`${input.roundId}: award conflict disappeared`);
+          throw new RollbackResult(replay(receipt(stored), input));
+        }
+
+        // Establish idempotency before checking the clock. A retry may arrive after closesAt while
+        // the original request is still committing; it must recover that result, not lose it.
+        if (receivedAt < Number(terms.opens_at)) {
+          throw new RollbackResult({ ok: false, refuse: 'award.not_open_yet' });
+        }
+        if (receivedAt >= Number(terms.closes_at)) {
+          throw new RollbackResult({ ok: false, refuse: 'award.window_closed' });
+        }
+
+        // A claim locks the same row. Creating it before locking means a first award and first claim
+        // cannot both pass through a missing row without seeing each other.
+        await tx.query(
+          `insert into balances (round_id, player, points) values ($1, $2, 0)
+           on conflict (round_id, player) do nothing`,
+          [input.roundId, input.player],
+        );
+        const balance = await tx.query<{ points: string }>(
+          `select points::text from balances where round_id = $1 and player = $2 for update`,
+          [input.roundId, input.player],
+        );
+        const total = BigInt(balance.rows[0]?.points ?? '0') + BigInt(input.points);
+        if (total > BigInt(terms.max_points_per_player)) {
+          throw new RollbackResult({ ok: false, refuse: 'award.limit_exceeded' });
+        }
+
+        await tx.query(`update balances set points = $3 where round_id = $1 and player = $2`, [
+          input.roundId,
+          input.player,
+          total.toString(),
+        ]);
+        await tx.query(
+          `update award_events set total_points = $3 where round_id = $1 and event_id = $2`,
+          [input.roundId, input.eventId, total.toString()],
+        );
+        return {
+          ok: true,
+          created: true,
+          award: { ...input, totalPoints: Number(total) },
+        };
+      });
+    } catch (error) {
+      if (error instanceof RollbackResult) return error.result;
+      throw error;
+    }
+  }
+}

package/src/index.ts

@@ -5,13 +5,16 @@ export {
   Room,
   Sessions,
   createGate,
+  createGameServerGate,
 } from './server.js';
 export type {
   Admission,
   AdmissionRequest,
   Admit,
   ConfigForLaunch,
+  GameServerGateOptions,
   GateOptions,
+  MaxPointsForLaunch,
   VerifiedLaunch,
 } from './server.js';
 export { createTurnstileAdmit } from './turnstile.js';
@@ -43,3 +46,8 @@ export {
 export type { Registration, SecurityProfile } from './registry.js';
 export { createGameRegistry } from './game-registry.js';
 export type { GameRegistryOptions } from './game-registry.js';
+export type {
+  GameServerAwardReceipt,
+  GameServerAwardRefusal,
+  GameServerAwardRequest,
+} from './game-server-awards.js';

package/src/ledger.ts

@@ -87,16 +87,6 @@ export class Ledger {
     await migrate(this.pool);
   }
 
-  /** Credit points. Called once per award the game emits. */
-  async award(roundId: string, player: PlayerId, points: number): Promise<void> {
-    if (points <= 0) return;
-    await this.pool.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`,
-      [roundId, player, Math.floor(points)],
-    );
-  }
-
   /**
    * Authorise up to `upToWei`, or refuse.
    *

package/src/room.ts

@@ -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.
@@ -39,6 +40,8 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     readonly window: RoundWindow,
     readonly launch: LaunchContext,
     readonly weiPerPoint: bigint,
+    readonly maxPointsPerPlayer: number,
+    readonly scoreAuthority: ScoreAuthority,
     private seq: number,
   ) {}
 
@@ -52,6 +55,8 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       window: RoundWindow;
       weiPerPoint: bigint;
       walletCapWei: bigint;
+      maxPointsPerPlayer: number;
+      scoreAuthority: ScoreAuthority;
       poolId: string;
       booksCloseAt?: number;
       launch?: {
@@ -66,6 +71,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,
@@ -80,13 +88,17 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     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, 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, 0)`,
       [
         round.id,
+        game.id,
         round.weiPerPoint.toString(),
         round.walletCapWei.toString(),
+        round.maxPointsPerPlayer,
+        round.scoreAuthority,
         round.poolId,
         round.window.opensAt,
         round.window.closesAt,
@@ -98,7 +110,18 @@ 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,
+      round.weiPerPoint,
+      round.maxPointsPerPlayer,
+      round.scoreAuthority,
+      0,
+    );
   }
 
   /** Pick up a round that already exists. Returns null if there is no such round. */
@@ -119,14 +142,19 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       coin_symbol: string;
       coin_image_url: string | null;
       wei_per_point: string;
+      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,
+              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({
@@ -147,6 +175,8 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       window,
       launch,
       toBigInt(row.wei_per_point),
+      Number(row.max_points_per_player),
+      row.score_authority,
       row.seq,
     );
   }
@@ -200,6 +230,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 +249,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.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.maxPointsPerPlayer],
         );
+        if (credited.rowCount !== 1) {
+          throw new Error(`${this.game.id}: awards exceeded the declared maximum for ${award.player}`);
+        }
       }
     });
   }

package/src/server.ts

@@ -6,13 +6,15 @@ import type { Command, GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
 import { isRefusal } from '@flayerlabs/gamemode-spec';
 import type { PresenceState } 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';
 
 /**
  * The gate's door.
@@ -26,9 +28,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 +66,24 @@ 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;
+}
+
 /** 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. */
@@ -131,8 +138,83 @@ 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;
+}
+
+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 { gameId, maxPointsPerPlayer: _maximum, awardToken, ...base } = options;
+  return createGateRuntime(
+    { ...base, game: gameServerModule(gameId), config },
+    'external-server',
+    { token: awardToken, awards: new GameServerAwards(options.pool, gameId) },
+  );
+}
+
+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 +256,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
@@ -246,6 +332,8 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
         window: { opensAt: launch.opensAt, closesAt: launch.closesAt },
         weiPerPoint: economy.economy.weiPerPoint,
         walletCapWei: launch.walletCapWei,
+        maxPointsPerPlayer,
+        scoreAuthority,
         poolId: launch.poolId,
         booksCloseAt: launch.closesAt + settlementTailMs,
         launch: {
@@ -381,6 +469,33 @@ export function createGate<Config, State, Event, Action, PublicView, PlayerView>
       .send(adopted.room.launch);
   });
 
+  if (awardEndpoint) {
+    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);
+    });
+  }
+
   app.get('/rounds/:id', async (request, reply) => {
     const id = (request.params as { id: string }).id;
     const room = await roomFor(id);
@@ -396,6 +511,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 +551,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 {