@pithy-sh/multiplayer 0.1.0

package/src/game/patterns/wageringTable.ts

@@ -0,0 +1,193 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MultiplayerInvalidTransitionError } from "../../error/errors";
+import type { LedgerEffect } from "../effects";
+import type { GameContext, GameModel } from "../model";
+
+/**
+ * The **wagering-table** pattern — the base helper for banked casino games: a persistent table where
+ * players place bets on a random event, and the house is the counterparty. Craps, roulette, sic bo.
+ *
+ * The helper owns the wagering plumbing that every such game shares: the **bet book** (tracking pending
+ * bets), the ledger **holds** placed when a bet lands, and the **settlement** (release/capture/credit) when
+ * a bet resolves — plus the persistent-table lifecycle (it never ends on a round; leaving returns a
+ * player's open bets). A game built on it supplies only the game-specific parts: what a valid bet is, who
+ * may trigger the random event, and how that event decides each pending bet. It never touches a hold ref or
+ * a ledger effect directly.
+ *
+ * Use it with `mode: "table"` and pair it with `@pithy-sh/ledger`.
+ */
+
+/** A bet the helper is holding: the player, the ledger hold `ref`, the staked `amount`, and game-specific `data`. */
+export interface PendingBet {
+  userId: string;
+  ref: string;
+  amount: number;
+  data: unknown;
+}
+
+/** A game's decision on a pending bet after a random event: won `payout`, lost, or pushed (stake returned). */
+export interface BetDecision {
+  ref: string;
+  result: "win" | "lose" | "push";
+  payout: number;
+}
+
+export interface WageringTableSpec<Config, Round, BetInput> {
+  /** The game's `kind` — its registry key. */
+  kind: string;
+  /** The game's config schema (the `rules` block). */
+  config: z.ZodType<Config>;
+  /** The schema for the round-specific state (a craps come-out/point, a roulette between-spins). */
+  round: z.ZodType<Round>;
+  /** The schema for a bet's input (the body of a `bet` action). */
+  bet: z.ZodType<BetInput>;
+  minPlayers?: number;
+  maxPlayers?: number;
+  /** The ledger currency bets are held and paid in. */
+  currency: (config: Config) => string;
+  /** The initial round state. */
+  startRound: (ctx: GameContext<Config>) => Round;
+  /** Validate a bet against the round and the player's existing bets; return the stake to hold plus `data` to store with it. Throw on illegal. */
+  placeBet: (
+    ctx: GameContext<Config>,
+    round: Round,
+    playerId: string,
+    bet: BetInput,
+    bets: readonly PendingBet[],
+  ) => { amount: number; data: unknown };
+  /** The member allowed to trigger the random event now (a shooter), or null to allow anyone. */
+  eventDriver?: (ctx: GameContext<Config>, round: Round) => string | null;
+  /** Run the random event (roll, spin): advance the round and decide each pending bet. The helper settles them. */
+  runEvent: (
+    ctx: GameContext<Config>,
+    round: Round,
+    bets: readonly PendingBet[],
+  ) => { round: Round; decisions: BetDecision[] };
+  /** Optional view of the round; the helper adds the bet book around it. */
+  view?: (ctx: GameContext<Config>, round: Round, viewerId: string) => unknown;
+}
+
+type TableState<Round> = { round: Round; bets: PendingBet[]; betSeq: number; lastDecisions: BetDecision[] };
+
+/** Build a {@link GameModel} for a banked wagering table from its {@link WageringTableSpec}. */
+export function wageringTable<Config, Round, BetInput>(
+  spec: WageringTableSpec<Config, Round, BetInput>,
+): GameModel<Config, TableState<Round>> {
+  const PendingBetSchema = z
+    .object({
+      userId: z.string().describe("The player who placed the bet."),
+      ref: z.string().describe("The ledger hold ref."),
+      amount: z.number().int().describe("The staked amount."),
+      data: z.unknown().describe("Game-specific bet data."),
+    })
+    .describe("A pending bet holding a stake.");
+  const state = z
+    .object({
+      round: spec.round.describe("The round-specific state."),
+      bets: z.array(PendingBetSchema).describe("Pending bets, each holding its stake."),
+      betSeq: z.number().int().describe("A monotonic counter making each bet's hold ref unique."),
+      lastDecisions: z
+        .array(z.object({ ref: z.string(), result: z.enum(["win", "lose", "push"]), payout: z.number() }))
+        .describe("How the last event decided each bet."),
+    })
+    .describe(`The ${spec.kind} table's state — the round, the bet book, and the last event's decisions.`);
+  const action = z
+    .discriminatedUnion("kind", [
+      z
+        .object({ kind: z.literal("bet").describe("Place a bet."), bet: spec.bet.describe("The bet.") })
+        .describe("Place a bet."),
+      z
+        .object({ kind: z.literal("event").describe("Trigger the random event (roll/spin).") })
+        .describe("Trigger the event."),
+    ])
+    .describe("A wagering-table action — place a bet, or trigger the event.");
+
+  return {
+    kind: spec.kind,
+    config: spec.config,
+    state,
+    minPlayers: spec.minPlayers ?? 1,
+    maxPlayers: spec.maxPlayers,
+
+    init: (ctx) => ({ round: spec.startRound(ctx), bets: [], betSeq: 0, lastDecisions: [] }),
+
+    apply(ctx, current, playerId, rawAction) {
+      const parsed = action.parse(rawAction);
+
+      if (parsed.kind === "bet") {
+        const { amount, data } = spec.placeBet(ctx, current.round, playerId, parsed.bet as BetInput, current.bets);
+        const ref = `${ctx.sessionId}:bet:${current.betSeq}`;
+        const effects: LedgerEffect[] = [
+          { op: "hold", userId: playerId, currency: spec.currency(ctx.config), amount, ref },
+        ];
+        return {
+          state: {
+            ...current,
+            betSeq: current.betSeq + 1,
+            bets: [...current.bets, { userId: playerId, ref, amount, data }],
+          },
+          effects,
+        };
+      }
+
+      // An event — check the driver (shooter), then run it and settle the decided bets.
+      const driver = spec.eventDriver?.(ctx, current.round);
+      if (driver !== undefined && driver !== null && driver !== playerId) {
+        throw new MultiplayerInvalidTransitionError({
+          message: "It is not your turn to trigger the event.",
+          detail: `${playerId} is not the driver (${driver}).`,
+        });
+      }
+      const { round, decisions } = spec.runEvent(ctx, current.round, current.bets);
+      const decided = new Map(decisions.map((d) => [d.ref, d]));
+      const currency = spec.currency(ctx.config);
+      const effects: LedgerEffect[] = [];
+      for (const bet of current.bets) {
+        const decision = decided.get(bet.ref);
+        if (!decision) continue; // no decision — the bet carries to the next event
+        if (decision.result === "lose") {
+          effects.push({ op: "capture", ref: bet.ref });
+        } else {
+          effects.push({ op: "release", ref: bet.ref }); // win or push: return the stake
+          if (decision.result === "win" && decision.payout > 0) {
+            effects.push({
+              op: "credit",
+              userId: bet.userId,
+              currency,
+              amount: decision.payout,
+              ref: `${bet.ref}:win`,
+              memo: `${spec.kind} win`,
+            });
+          }
+        }
+      }
+      const bets = current.bets.filter((b) => !decided.has(b.ref));
+      return { state: { round, bets, betSeq: current.betSeq, lastDecisions: decisions }, effects };
+    },
+
+    isComplete: () => false, // a table runs until closed or emptied (the session's table lifecycle)
+    resolve: () => ({ outcome: { scores: {}, winnerUserId: null, draw: false } }),
+
+    onLeave(_ctx, current, playerId) {
+      // Return the leaver's held stakes and drop their bets.
+      const effects: LedgerEffect[] = current.bets
+        .filter((b) => b.userId === playerId)
+        .map((b) => ({ op: "release", ref: b.ref }));
+      return { state: { ...current, bets: current.bets.filter((b) => b.userId !== playerId) }, effects };
+    },
+
+    redact(ctx, current, viewerId) {
+      const driver = spec.eventDriver?.(ctx, current.round) ?? null;
+      return {
+        ...(spec.view ? { round: spec.view(ctx, current.round, viewerId) } : { round: current.round }),
+        driver,
+        yourTurnToTrigger: driver === null || driver === viewerId,
+        bets: current.bets.map((b) => ({ userId: b.userId, amount: b.amount, data: b.data })),
+        lastDecisions: current.lastDecisions,
+      };
+    },
+  };
+}

package/src/game/random.ts

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * Server-authoritative randomness for game models — the primitive a house cannot let a client control.
+ *
+ * A session mints a random **seed** at creation (128 bits of `crypto.getRandomValues`) and stores it. From
+ * that seed a **deterministic** stream of draws is derived: given the seed and a cursor, every value is
+ * fixed and reproducible. The Durable Object advances the cursor as a model draws and persists it, so the
+ * stream never repeats and survives hibernation.
+ *
+ * Determinism is what makes it **provably fair**. The seed's SHA-256 hash is committed up front (shown to
+ * every player before a single die is rolled) and the seed itself is revealed when the session ends. An
+ * auditor hashes the revealed seed to check it against the commitment, then replays this exact algorithm to
+ * verify every roll — so the house cannot have chosen or re-rolled an outcome. It is also why models must
+ * draw randomness only in `init`/`apply` (the transitions the DO persists), never in `resolve`/`redact`.
+ */
+export interface RandomSource {
+  /** The next draw as a float in [0, 1). */
+  next(): number;
+  /** The next draw as an integer in [minInclusive, maxInclusive] — a die is `int(1, 6)`. */
+  int(minInclusive: number, maxInclusive: number): number;
+  /** The next draw as a uniformly-chosen element of `items`. */
+  pick<T>(items: readonly T[]): T;
+}
+
+/** The persisted RNG state: the seed, its committed hash, and how many values have been drawn. */
+export const RngState = z
+  .object({
+    seed: z
+      .string()
+      .describe(
+        "The session's random seed (hex). Secret until the session is terminal, then revealed for verification.",
+      ),
+    seedHash: z
+      .string()
+      .describe("SHA-256 of the seed (hex) — the fairness commitment, shown to players before any draw."),
+    cursor: z
+      .number()
+      .int()
+      .describe("How many values have been drawn from the stream. Advances as models draw; persisted by the DO."),
+  })
+  .describe("A session's provably-fair RNG state — seed, its commitment, and the stream position.");
+export type RngState = z.infer<typeof RngState>;
+
+/** Derive a 32-bit numeric base from the hex seed (an xmur3-style string hash). */
+function seedToBase(seed: string): number {
+  let h = 1779033703 ^ seed.length;
+  for (let i = 0; i < seed.length; i++) {
+    h = Math.imul(h ^ seed.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  return h >>> 0;
+}
+
+/** A counter-based draw: a deterministic float in [0, 1) for a given base and counter (a splitmix32 mix). */
+function draw(base: number, counter: number): number {
+  let t = (base + Math.imul(counter, 0x9e3779b9)) >>> 0;
+  t ^= t >>> 15;
+  t = Math.imul(t, 0x2c1b3c6d) >>> 0;
+  t ^= t >>> 12;
+  t = Math.imul(t, 0x297a2d39) >>> 0;
+  t ^= t >>> 15;
+  return (t >>> 0) / 4294967296;
+}
+
+/** Bytes → lowercase hex. */
+function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+/**
+ * Mint a fresh RNG state: 128 crypto-random bits of seed, its SHA-256 commitment, cursor at zero. Async
+ * because the hash is (`crypto.subtle.digest`); called once, at session creation.
+ */
+export async function createRngState(): Promise<RngState> {
+  const seedBytes = crypto.getRandomValues(new Uint8Array(16));
+  const seed = toHex(seedBytes);
+  const digest = await crypto.subtle.digest("SHA-256", seedBytes);
+  return { seed, seedHash: toHex(new Uint8Array(digest)), cursor: 0 };
+}
+
+/**
+ * A {@link RandomSource} over an RNG state, plus `spent()` — the cursor after the draws taken, which the DO
+ * reads back to persist. The source is a closure over a local cursor; nothing mutates the passed state.
+ */
+export function randomSource(state: RngState): RandomSource & { spent(): number } {
+  const base = seedToBase(state.seed);
+  let cursor = state.cursor;
+  const next = () => draw(base, cursor++);
+  return {
+    next,
+    int: (min, max) => min + Math.floor(next() * (max - min + 1)),
+    pick: (items) => items[Math.floor(next() * items.length)] as (typeof items)[number],
+    spent: () => cursor,
+  };
+}

package/src/http/guard.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The one route guard: every multiplayer route requires an authenticated player.
+ *
+ * It depends on the core `AuthContext` seam and nothing else — `@pithy-sh/auth` populates `c.var.auth`,
+ * and multiplayer never reaches into its internals (CLAUDE.md §HTTP). Without auth installed `c.var.auth`
+ * is null and every route is denied, which is the correct failure: membership binds to an authenticated
+ * user id, so a session with no stable player identity cannot exist. There is no public multiplayer
+ * surface, because there is no such thing as an anonymous member of an authoritative session.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/http/routes.ts

@@ -0,0 +1,254 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DurableObjectNamespace, DurableObjectStub } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { ErrorPayload } from "@pithy-sh/core/src/error/payload";
+import { InternalError, PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import { type ResolvedGame, resolveGame } from "../config/config";
+import { MultiplayerGameNotFoundError, MultiplayerSessionNotFoundError } from "../error/errors";
+// Type-only, so it erases: the DO module imports `cloudflare:workers` and must never land on the value
+// import graph the adopter's `pithy.config.ts` pulls in. The two constants both sides need live in the
+// pure `session/protocol` module for the same reason (#172).
+import type { MultiplayerSession } from "../session/durableObject";
+import { RPC_ERROR_PREFIX, USER_HEADER } from "../session/protocol";
+import type { GameSnapshot } from "../session/state";
+import { requireAuth } from "./guard";
+import { MultiplayerGameParams, MultiplayerSessionParams } from "./schemas";
+
+/**
+ * The multiplayer routes, their declared verification strategies, and what they accept. Every route is
+ * `bearer | session` — gated by {@link requireAuth} — because membership binds to an authenticated user id
+ * and there is no public session surface:
+ *
+ * | Method | Path                             | Strategy          | Validates                       |
+ * |--------|----------------------------------|-------------------|---------------------------------|
+ * | POST   | /multiplayer/games/:game         | bearer \| session | param `MultiplayerGameParams`    |
+ * | POST   | /multiplayer/sessions/:id/join   | bearer \| session | param `MultiplayerSessionParams` |
+ * | POST   | /multiplayer/sessions/:id/action | bearer \| session | param `MultiplayerSessionParams` |
+ * | POST   | /multiplayer/sessions/:id/leave  | bearer \| session | param `MultiplayerSessionParams` |
+ * | POST   | /multiplayer/sessions/:id/close  | bearer \| session | param `MultiplayerSessionParams` |
+ * | GET    | /multiplayer/sessions/:id/result | bearer \| session | param `MultiplayerSessionParams` |
+ * | GET    | /multiplayer/sessions/:id/socket | bearer \| session | param `MultiplayerSessionParams` |
+ * | GET    | /multiplayer/sessions/:id        | bearer \| session | param `MultiplayerSessionParams` |
+ *
+ * Validators run **after** {@link requireAuth}, so an unauthenticated caller is still denied 401 whatever it
+ * sends. The param schemas bound a segment's shape only: resolving a game key stays in the handler (an
+ * unknown game is still a 404), and judging a session id stays in {@link sessionStub} (an unparseable id is
+ * still a 404).
+ *
+ * **No route declares a json schema, including the one route that reads a body.** An action is whatever the
+ * game's model defines — a commit for a commit-reveal game, a cell for a sequential grid — and the route
+ * forwards its JSON body untouched to the model, which is the only thing that knows its shape. There is no
+ * shape for this capability to impose, and a `zValidator("json", …)` would still change what a caller may
+ * send: it rejects an empty body under a JSON content-type with a 400, where a body-less action legitimately
+ * reaches a model that takes no payload today. So the body is read off the raw request instead, with
+ * the same "unreadable body means no payload" fallback — the model, not multiplayer, decides what is legal.
+ * The join, leave, and close routes read no body at all, so validating one on them would only 400 the
+ * body-less request their clients already send.
+ *
+ * The authenticated user id comes from the core `AuthContext` seam (`c.var.auth.userId`) and is passed to the
+ * Durable Object on every call — the DO never trusts a client-supplied id. The WebSocket upgrade is forwarded
+ * to the DO with that id set on {@link USER_HEADER}, a server-set header the DO trusts.
+ */
+export interface MultiplayerRoutesOptions {
+  /** The games, validated against their models at assembly (each carries parsed `rules`). */
+  games: readonly ResolvedGame[];
+  basePath?: string;
+}
+
+/** The `SESSIONS` Durable Object namespace binding, typed to the session class. */
+type SessionsNamespace = DurableObjectNamespace<MultiplayerSession>;
+
+/**
+ * The authenticated player's id. `requireAuth` runs before every handler, so `c.var.auth` is set — this
+ * reads it defensively (throwing rather than asserting non-null) so a misordered middleware surfaces as a
+ * clear error, never a crash.
+ */
+function userId(c: Context<PithyHonoEnv>): string {
+  const auth = c.var.auth;
+  if (!auth) {
+    throw new InternalError({ detail: "requireAuth() must run before a multiplayer handler reads the user id." });
+  }
+  return auth.userId;
+}
+
+/** Read the `SESSIONS` binding off the env, or fail with a configuration error naming the missing binding. */
+function sessionsBinding(c: Context<PithyHonoEnv>): SessionsNamespace {
+  const binding = (c.env as Record<string, unknown>).SESSIONS as SessionsNamespace | undefined;
+  if (!binding) {
+    throw new InternalError({
+      message: "Multiplayer is not configured.",
+      action: "Bind a Durable Object namespace named SESSIONS in wrangler.jsonc.",
+      detail: "The multiplayer capability requires a `SESSIONS` durable_object binding; none was present on env.",
+    });
+  }
+  return binding;
+}
+
+/**
+ * Run a Durable Object RPC call, reviving a `PithyError` the DO threw.
+ *
+ * A `PithyError` thrown inside a DO does not cross the RPC boundary as itself — the runtime strips it to a
+ * bare Error. So the DO's `guard` encodes the payload as JSON into the Error message behind
+ * {@link RPC_ERROR_PREFIX} (a message is the one thing the boundary preserves), and this decodes it back
+ * into a real `PithyError` so `pithyErrorHandler` maps it to the same status and body a direct throw would
+ * — a `not_a_member` commit stays a 403, not a 500. Anything else propagates untouched (and 500s, correctly).
+ */
+async function callSession<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof PithyError) throw error;
+    const message = (error as { message?: unknown } | null)?.message;
+    if (typeof message === "string" && message.startsWith(RPC_ERROR_PREFIX)) {
+      try {
+        const parsed = ErrorPayload.safeParse(JSON.parse(message.slice(RPC_ERROR_PREFIX.length)));
+        if (parsed.success) throw new PithyError(parsed.data, { cause: error });
+      } catch (reviveError) {
+        // A revived PithyError is the intended result — rethrow it. Only a genuinely malformed envelope
+        // (JSON.parse failure) falls through to the original error below, rather than a 500 from here.
+        if (reviveError instanceof PithyError) throw reviveError;
+      }
+    }
+    throw error;
+  }
+}
+
+/** Resolve a session stub from a path id, mapping an unparseable id to a 404 rather than a 500. */
+function sessionStub(namespace: SessionsNamespace, rawId: string): DurableObjectStub<MultiplayerSession> {
+  let id: ReturnType<SessionsNamespace["idFromString"]>;
+  try {
+    id = namespace.idFromString(rawId);
+  } catch (cause) {
+    throw new MultiplayerSessionNotFoundError({ detail: `"${rawId}" is not a valid session id.` }, { cause });
+  }
+  return namespace.get(id);
+}
+
+/** Build the config snapshot the DO stores from a validated game — nullable fields normalized for storage. */
+function snapshot(game: ResolvedGame): GameSnapshot {
+  return {
+    key: game.key,
+    kind: game.kind,
+    mode: game.mode,
+    players: game.players,
+    turnTimeoutMs: game.turnTimeoutMs ?? null,
+    leaderboard: game.leaderboard ?? null,
+    rules: game.rules,
+  };
+}
+
+export function registerMultiplayerRoutes(options: MultiplayerRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/multiplayer";
+  const { games } = options;
+
+  return (app) => {
+    // Create a session for a configured game. The creator is its first member.
+    app.post(
+      `${base}/games/:game`,
+      requireAuth(),
+      zValidator("param", MultiplayerGameParams, validationHook),
+      async (c) => {
+        const gameKey = c.req.valid("param").game;
+        const game = resolveGame(games, gameKey);
+        if (!game) throw new MultiplayerGameNotFoundError({ detail: `No game "${gameKey}" is configured.` });
+
+        const namespace = sessionsBinding(c);
+        const id = namespace.newUniqueId();
+        const stub = namespace.get(id);
+        const view = await callSession(() => stub.create(snapshot(game), userId(c)));
+        return c.json(view, 201);
+      },
+    );
+
+    app.post(
+      `${base}/sessions/:id/join`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        const view = await callSession(() => stub.join(userId(c)));
+        return c.json(view, 200);
+      },
+    );
+
+    app.post(
+      `${base}/sessions/:id/action`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        // The action payload is the one thing this capability does not shape — it belongs to the game's
+        // model (see the docblock), so it is read raw and forwarded. Read off `c.req.raw` rather than
+        // declared as a json validator so a body-less action still reaches a model that takes no payload,
+        // instead of becoming a 400.
+        const body = await c.req.raw.json().catch(() => undefined);
+        const view = await callSession(() => stub.action(userId(c), body));
+        return c.json(view, 200);
+      },
+    );
+
+    // Table mode: take or leave a seat, or close the table. Neither reads a body.
+    app.post(
+      `${base}/sessions/:id/leave`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        return c.json(await callSession(() => stub.leave(userId(c))), 200);
+      },
+    );
+
+    app.post(
+      `${base}/sessions/:id/close`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        return c.json(await callSession(() => stub.close(userId(c))), 200);
+      },
+    );
+
+    app.get(
+      `${base}/sessions/:id/result`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        const result = await callSession(() => stub.result());
+        if (!result) throw new MultiplayerSessionNotFoundError({ detail: "The session has no terminal result yet." });
+        return c.json(result, 200);
+      },
+    );
+
+    // The WebSocket upgrade — forwarded to the DO with the authenticated id set on the trusted header. The
+    // DO answers a non-upgrade request with 426, so the check lives there, once.
+    app.get(
+      `${base}/sessions/:id/socket`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        const forwarded = new Request(c.req.raw);
+        forwarded.headers.set(USER_HEADER, userId(c));
+        return stub.fetch(forwarded) as unknown as Response;
+      },
+    );
+
+    // Registered last so `/sessions/:id/*` static suffixes above are matched first.
+    app.get(
+      `${base}/sessions/:id`,
+      requireAuth(),
+      zValidator("param", MultiplayerSessionParams, validationHook),
+      async (c) => {
+        const stub = sessionStub(sessionsBinding(c), c.req.valid("param").id);
+        const view = await callSession(() => stub.view(userId(c)));
+        return c.json(view, 200);
+      },
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The HTTP-boundary shapes for the multiplayer routes. Declared on the route line with
+ * `zValidator(target, Schema, validationHook)`, so a malformed segment is a `validation/invalid_input` 400
+ * before any handler runs, never an unbounded string handed to a config lookup or a Durable Object id parse.
+ *
+ * Both are **param** schemas, and both are shape checks rather than existence checks. Resolving a game key
+ * against the configured games stays in the handler (an unknown game is still a `multiplayer/game_not_found`
+ * 404), and deciding whether a session id names a real Durable Object stays in `idFromString` (an unparseable
+ * id is still a `multiplayer/session_not_found` 404).
+ *
+ * There is deliberately no body schema here. The one route that reads a body — `POST /sessions/:id/action` —
+ * forwards it untouched to the game's model, which is the only thing that knows an action's shape; see the
+ * routes docblock.
+ */
+
+/**
+ * A game key is a URL path segment, so it is lowercase, digits, and dashes — the same shape
+ * `MultiplayerGame.key` enforces at config assembly. A key that cannot be configured cannot resolve, so
+ * bounding the segment here rejects it a step earlier without narrowing what already works.
+ */
+const GAME_KEY = /^[a-z0-9][a-z0-9-]*$/;
+
+export const MultiplayerGameParams = z
+  .object({
+    game: z
+      .string()
+      .max(64)
+      .regex(GAME_KEY, "A game key is lowercase, digits, and dashes — it is a URL path segment.")
+      .describe("The configured game a session is created for. Resolved against the games in the handler."),
+  })
+  .describe("The path params of a game-scoped multiplayer route.");
+export type MultiplayerGameParams = z.output<typeof MultiplayerGameParams>;
+
+export const MultiplayerSessionParams = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe(
+        "The session's Durable Object id. Bounded, not parsed: a real id is 64 hex characters, but the id a client sent is judged by `idFromString`, which answers an unparseable one with a 404. A hex regex here would make that a 400 and leave the handler's catch unreachable.",
+      ),
+  })
+  .describe("The path params of a session-scoped multiplayer route.");
+export type MultiplayerSessionParams = z.output<typeof MultiplayerSessionParams>;