@diffenderfer-games/hub-contract 0.0.0-stage → 2.0.0-next.0

package/src/manifest/controls.ts

@@ -0,0 +1,42 @@
+/**
+ * `game.controls`: the gamepad-to-keyboard map zero-config games use, so a
+ * controller or arcade stick works in a game that never calls
+ * `hub.input.define()` (docs/hub.md "Mapping controls per game").
+ */
+import { z } from 'zod';
+import { SEAT_LIMITS } from '../limits';
+
+/** A `KeyboardEvent.code`, such as `ArrowUp`, `Space`, `KeyZ` or `ShiftLeft`. */
+export const KeyCode = z.string().regex(/^[A-Za-z0-9]{1,32}$/, 'must be a KeyboardEvent.code such as ArrowUp, Space or KeyZ');
+
+/** A standard-gamepad button index, `"0"` to `"19"`. */
+export const ButtonIndex = z.string().regex(/^(?:1?[0-9])$/, 'must be a gamepad button index 0-19');
+
+/** One player's map. Unset directions and buttons keep the defaults. */
+export const ControlMap = z.strictObject({
+  /** Key pressed for stick/d-pad up. Default `ArrowUp`. */
+  up: KeyCode.optional(),
+  /** Key pressed for stick/d-pad down. Default `ArrowDown`. */
+  down: KeyCode.optional(),
+  /** Key pressed for stick/d-pad left. Default `ArrowLeft`. */
+  left: KeyCode.optional(),
+  /** Key pressed for stick/d-pad right. Default `ArrowRight`. */
+  right: KeyCode.optional(),
+  /**
+   * Button index → key. Defaults: `0` Space, `1` Enter, `2` KeyZ, `3` KeyX,
+   * `8` Escape, `9` Enter.
+   */
+  buttons: z.record(ButtonIndex, KeyCode).optional(),
+});
+
+/** A gamepad-to-keyboard map. */
+export type ControlMap = z.infer<typeof ControlMap>;
+
+/** `game.controls`: one map for every pad, or one per player in `players`. */
+export const GameControls = ControlMap.extend({
+  /** Per-player maps, by gamepad order; pads past the end use the first. Overrides the shared map. */
+  players: z.array(ControlMap).min(1).max(SEAT_LIMITS.maxSeats).optional(),
+});
+
+/** `game.controls`. */
+export type GameControls = z.infer<typeof GameControls>;

package/src/manifest/fields.ts

@@ -0,0 +1,89 @@
+/**
+ * Field rules shared by several parts of the `game.*` manifest. Each rule is
+ * defined once here.
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS, SEAT_LIMITS } from '../limits';
+
+/**
+ * A non-empty string with no leading or trailing whitespace. Used for fields
+ * the hub reads verbatim (commands, paths, titles), where stray spaces are a
+ * mistake rather than something the hub would trim away.
+ */
+export const Trimmed = z.string().regex(/^\S(?:[\s\S]*\S)?$/, 'must be non-empty, with no leading or trailing spaces');
+
+/** A label the hub trims and shows to players, at most `max` characters. */
+export function trimmedText(max: number) {
+  return z.string().trim().min(1).max(max);
+}
+
+/**
+ * A URL suffix relative to `/<slug>/` that invites and Join open, such as
+ * `?lobby=1` or `play/online`. Not absolute, no `..`, no `//`.
+ */
+export const LobbySuffix = z
+  .string()
+  .trim()
+  .regex(new RegExp(`^[A-Za-z0-9_./?=&#%-]{0,${MANIFEST_LIMITS.lobbyMax}}$`), 'may only use letters, digits and _ . / ? = & # % -')
+  .refine((s) => !s.startsWith('/') && !s.includes('..') && !s.includes('//'), 'must be a relative URL suffix (no leading /, no .., no //)');
+
+/**
+ * A `[min, max]` player range: whole numbers, `lowest <= min <= max <= 8`.
+ *
+ * @param lowest - the smallest `min` allowed (1 for multiplayer, 2 for races)
+ */
+export function playerRange(lowest: number) {
+  const seatCount = z.number().int().min(lowest).max(SEAT_LIMITS.maxSeats);
+  return z.tuple([seatCount, seatCount]).refine(([min, max]) => min <= max, `must be [min, max] with ${lowest} <= min <= max <= ${SEAT_LIMITS.maxSeats}`);
+}
+
+/**
+ * An optional block that may also be written as `false` ("off"). `false`
+ * parses to `undefined`, the same as leaving the field out.
+ *
+ * (A `z.union` with `z.literal(false)` would work too, but it hides the
+ * block's own field errors behind a bare "Invalid input".)
+ */
+export function orFalse<T extends z.ZodType>(block: T) {
+  return z.preprocess((v: false | z.input<T>) => (v === false ? undefined : v), block.optional()).optional();
+}
+
+/** True when no two items share a `key`. */
+export function hasUniqueKeys(items: readonly { readonly key: string }[]): boolean {
+  return new Set(items.map((i) => i.key)).size === items.length;
+}
+
+/** The placeholders a `build` or `start` command may use. */
+export const COMMAND_PLACEHOLDERS = ['PORT', 'GAME_PATH', 'GAME_SLUG'] as const;
+
+const PLACEHOLDER = /\{\{(\w+)\}\}/g;
+const KNOWN_PLACEHOLDERS: ReadonlySet<string> = new Set(COMMAND_PLACEHOLDERS);
+
+/**
+ * A shell command the host runs in the app folder. It may use the
+ * placeholders `{{PORT}}`, `{{GAME_PATH}}` and `{{GAME_SLUG}}`; any other
+ * `{{NAME}}` fails the build.
+ */
+export const Command = Trimmed.refine(
+  (cmd) => [...cmd.matchAll(PLACEHOLDER)].every((m) => KNOWN_PLACEHOLDERS.has(m[1] ?? '')),
+  `may only use the placeholders ${COMMAND_PLACEHOLDERS.map((p) => `{{${p}}}`).join(', ')}`,
+);
+
+/** True when a relative path names something strictly inside its folder. */
+function staysInside(path: string): boolean {
+  let depth = 0;
+  for (const part of path.split(/[\\/]/)) {
+    if (part === '..') {
+      depth -= 1;
+      if (depth < 0) {
+        return false;
+      }
+    } else if (part !== '' && part !== '.') {
+      depth += 1;
+    }
+  }
+  return depth > 0;
+}
+
+/** A file path relative to the app folder that stays inside it, e.g. `cover.png`. */
+export const AppFilePath = Trimmed.refine(staysInside, 'must be a file inside the app folder');

package/src/manifest/game.ts

@@ -0,0 +1,132 @@
+/**
+ * The `game` block of an app's `package.json`: how the host builds, serves
+ * and shows the game (HANDOFF.md "The game block").
+ *
+ * This is the **strict** authoring schema `hub-doctor` runs in a game: a
+ * mistake fails the parse. The host stays lenient at boot (a bad field falls
+ * back to its default with a warning), so one typo never takes a game down.
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS } from '../limits';
+import { GameChanges } from './changes';
+import { GameControls } from './controls';
+import { AppFilePath, Command, Trimmed, orFalse } from './fields';
+import { GameLeaderboardDecls } from './leaderboards';
+import { GameMultiplayer, StaticGameMultiplayer } from './multiplayer';
+import { GameRace } from './race';
+
+/** The corner the injected hub menu button sits in. Default `top-left`. */
+export const MenuPosition = z.enum(['top-left', 'top-right', 'bottom-left', 'bottom-right']);
+
+/** A menu button corner. */
+export type MenuPosition = z.infer<typeof MenuPosition>;
+
+/** Pixels to push the menu button away from its corner, 0 to 600. */
+const OffsetPx = z.number().int().min(0).max(MANIFEST_LIMITS.menuOffsetMax);
+
+/** The menu offset as the host sends it: both axes, in px. */
+export const MenuOffsetXY = z.strictObject({
+  /** Inward from the left or right edge, px. */
+  x: OffsetPx,
+  /** Down from a top corner or up from a bottom one, px. */
+  y: OffsetPx,
+});
+
+/**
+ * `game.menuOffset`: how far to push the menu button away from its corner so
+ * it clears the game's own bars. A number moves it vertically only.
+ */
+export const MenuOffset = z.union([OffsetPx, MenuOffsetXY.partial()]);
+
+/** Fields both app types share. */
+const commonFields = {
+  /** Shown on the catalog card and in the menu. */
+  title: Trimmed,
+  /** Catalog, search and link-preview text. Falls back to `package.json` `description`. */
+  description: Trimmed.optional(),
+  /**
+   * Credit shown on the tile, e.g. `"Mason & Phil"` (split into authors for the
+   * catalog filter). Falls back to `package.json` `author`.
+   */
+  author: z.string().trim().min(1).optional(),
+  /** Runs at boot when the source changed. May use `{{PORT}}`, `{{GAME_PATH}}`, `{{GAME_SLUG}}`. */
+  build: Command.optional(),
+  /** Tile and preview image, relative to the project root (not `serveDir`); must stay inside it. */
+  image: AppFilePath.optional(),
+  /** `true` leaves the app out of the catalog entirely. */
+  hidden: z.boolean().optional(),
+  /** `false` opts out of the injected hub menu and SDK. */
+  hub: z.boolean().optional(),
+  /** `false` opts out of the PWA install tags and service worker. */
+  pwa: z.boolean().optional(),
+  /** The corner the hub menu button sits in. Default `top-left`. */
+  menuPosition: MenuPosition.optional(),
+  /** Push the menu button away from its corner, px: a number (vertical) or `{ x, y }`. */
+  menuOffset: MenuOffset.optional(),
+  /** `true` opts into the shared daily challenges (`hub.daily.define(...)`). */
+  dailyChallenges: z.boolean().optional(),
+  /** Boards to create up front, so they show before the first score. */
+  leaderboards: GameLeaderboardDecls.optional(),
+  /** The gamepad-to-keyboard map for games that never call `hub.input.define()`. */
+  controls: GameControls.optional(),
+  /** Turns a single-player game into a race target; `true` for all defaults, `false` for off. */
+  race: GameRace,
+  /** Player-facing "What's new" notes, one per change, newest last. Keep it updated. */
+  changes: GameChanges.optional(),
+};
+
+/** A static app: the build emits a folder the host serves. */
+export const StaticGame = z.strictObject({
+  /** `static`: no running process. */
+  type: z.literal('static'),
+  /** The folder served at `/<slug>/`; must exist after `build`. */
+  serveDir: Trimmed,
+  /** Makes the game an online invite/join target (`hub-rooms` only); `false` for off. */
+  multiplayer: orFalse(StaticGameMultiplayer),
+  ...commonFields,
+});
+
+/** A process app: the host runs a long-lived server and proxies to it. */
+export const ProcessGame = z.strictObject({
+  /** `process`: the host starts `start` and proxies `/<slug>/` to it. */
+  type: z.literal('process'),
+  /** The long-lived server command; must listen on the assigned port (`{{PORT}}` or `PORT`). */
+  start: Command,
+  /** The path the host polls until it answers below 500. Default `/`. */
+  healthPath: Trimmed.startsWith('/').optional(),
+  /** Makes the game an online invite/join target; `false` for off. */
+  multiplayer: orFalse(GameMultiplayer),
+  ...commonFields,
+});
+
+/** The `game` block of a game's `package.json`. */
+export const GameManifest = z.discriminatedUnion('type', [StaticGame, ProcessGame]);
+
+/** A parsed `game` block (defaults applied). */
+export type GameManifest = z.output<typeof GameManifest>;
+
+/** The `game` block as a game writes it. */
+export type GameManifestInput = z.input<typeof GameManifest>;
+
+/** A game's `package.json`: the `game` block plus the npm fields the host falls back to. */
+export const GamePackageJson = z.looseObject({
+  /** The npm name; the title fallback. */
+  name: z.string().optional(),
+  /** The description fallback. */
+  description: z.string().optional(),
+  /** The author fallback: npm's string or `{ name }` form. */
+  author: z.union([z.string(), z.looseObject({ name: z.string().optional() })]).optional(),
+  /** How the host treats the app. */
+  game: GameManifest,
+});
+
+/**
+ * The host repo's own `game` block: only its "What's new" notes (shown as
+ * "diffenderfer.games"). It is not an app, so it has no `type`.
+ */
+export const HostManifest = z.strictObject({
+  /** The host's display name. */
+  title: Trimmed.optional(),
+  /** The host's own notes (menu, friends, home page). */
+  changes: GameChanges.optional(),
+});

package/src/manifest/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `package.json` `game.*` manifest and the injected `window.__HUB__`
+ * config.
+ */
+export * from './changes';
+export * from './controls';
+export { AppFilePath, COMMAND_PLACEHOLDERS, Command, LobbySuffix } from './fields';
+export * from './game';
+export * from './inject';
+export * from './leaderboards';
+export * from './multiplayer';
+export * from './race';

package/src/manifest/inject.ts

@@ -0,0 +1,31 @@
+/**
+ * `window.__HUB__`: the small config object the host writes into every page
+ * it injects (game pages, and the catalog page). The SDK and the menu read it
+ * to find the game's slug, the API base and the menu placement.
+ *
+ * The same inline script may also set `window.__hubDailyDeep` (a
+ * `?daily=YYYY-MM-DD` deep link captured before game code runs) and
+ * `window.__hubInstall` (the PWA install prompt); those are not part of this
+ * object.
+ */
+import { z } from 'zod';
+import { Slug } from '../common';
+import { GameControls } from './controls';
+import { MenuOffsetXY, MenuPosition } from './game';
+
+/** The injected `window.__HUB__` config. */
+export const HubInject = z.strictObject({
+  /** The game's slug. Missing on the catalog page. */
+  slug: Slug.optional(),
+  /** Where the REST API lives. Always `/_api` today. */
+  apiBase: z.literal('/_api'),
+  /** The menu button's corner (from `game.menuPosition`). Missing on the catalog page. */
+  menu: MenuPosition.optional(),
+  /** The menu button's offset from its corner (from `game.menuOffset`); only sent when not 0,0. */
+  menuOffset: MenuOffsetXY.optional(),
+  /** The game's `game.controls`, as written; only sent when set. */
+  controls: GameControls.optional(),
+});
+
+/** The injected `window.__HUB__` config. */
+export type HubInject = z.infer<typeof HubInject>;

package/src/manifest/leaderboards.ts

@@ -0,0 +1,29 @@
+/**
+ * `game.leaderboards`: boards declared up front, so they show on the catalog
+ * before the first score.
+ */
+import { z } from 'zod';
+import { SortDir } from '../api/leaderboards';
+import { Key } from '../common';
+import { MANIFEST_LIMITS } from '../limits';
+import { Trimmed, hasUniqueKeys } from './fields';
+
+/** One declared leaderboard. */
+export const LeaderboardDecl = z.strictObject({
+  /** The board key `hub.submitScore(key, score)` uses: letters, digits and `_ . : -`, 1 to 64. */
+  key: Key,
+  /** What players see, at most 80 characters. Defaults to the key. */
+  title: Trimmed.max(MANIFEST_LIMITS.leaderboardTitleMax).optional(),
+  /** Which scores rank first. Default `desc`. */
+  sort: SortDir.default('desc'),
+  /** List players whose best is 0. Default `false`. */
+  showZeros: z.boolean().optional(),
+  /**
+   * `server`: only the game's own server may submit (trusted multiplayer
+   * results); the client endpoint refuses. Default `client`.
+   */
+  source: z.enum(['client', 'server']).default('client'),
+});
+
+/** `game.leaderboards`: unique keys. */
+export const GameLeaderboardDecls = z.array(LeaderboardDecl).refine(hasUniqueKeys, 'leaderboard keys must be unique');

package/src/manifest/multiplayer.ts

@@ -0,0 +1,71 @@
+/**
+ * `game.multiplayer`: the opt-in that makes a game an online invite/join
+ * target (docs/multiplayer.md §7).
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/**
+ * How players connect: `hub-rooms` (the hub relays room messages) or
+ * `own-server` (a process app runs its own game server; process apps only).
+ */
+export const Transport = z.enum(['hub-rooms', 'own-server']);
+
+/** A mode key: letters, digits, `_` or `-`, 1 to 32 characters. */
+export const ModeKey = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, 'must be 1-32 letters, digits, _ or -');
+
+/** A game mode players can be invited into. */
+export const MultiplayerMode = z.strictObject({
+  /** Sent with invites and launches as `mode`. */
+  key: ModeKey,
+  /** What players see. Defaults to the key. */
+  title: trimmedText(MANIFEST_LIMITS.modeTitleMax).optional(),
+  /** `[min, max]` players for this mode, within 1..8. Defaults to the game's. */
+  players: playerRange(1).optional(),
+});
+
+/**
+ * A soften-list word this game's chat may keep (e.g. `shot` for a pool game):
+ * one lowercase word of 2 to 20 letters. Reject-list words never pass.
+ */
+export const ChatAllowWord = z.string().trim().toLowerCase().regex(/^[a-z]{2,20}$/, 'must be a single word of 2-20 letters');
+
+/** The `game.multiplayer` block. */
+export const GameMultiplayer = z.strictObject({
+  /** URL suffix invites and Join open, relative to `/<slug>/`. Default `''` (the game's root). */
+  lobby: LobbySuffix.default(''),
+  /** `[min, max]` players, within 1..8. Default `[2, 8]`. */
+  players: playerRange(1).default([2, 8]),
+  /**
+   * `hub-rooms` or `own-server`. Default: `own-server` for process apps,
+   * `hub-rooms` for static apps (which cannot use `own-server`).
+   */
+  transport: Transport.optional(),
+  /** Friends can invite each other into this game. Default `true`. */
+  invites: z.boolean().default(true),
+  /** Friends can join a game in progress. Default `true`. */
+  join: z.boolean().default(true),
+  /** Friends can watch. Default `false`. */
+  spectate: z.boolean().default(false),
+  /** Offer quick match. Default `false`. */
+  quickMatch: z.boolean().default(false),
+  /** Modes players can be invited into (at most 16, unique keys). */
+  modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, 'mode keys must be unique').default([]),
+  /**
+   * Extra quick-chat phrases for this game (at most 24, each at most 40
+   * characters). Checked by the content filter at boot; failing ones are dropped.
+   */
+  quickChat: z.array(trimmedText(MANIFEST_LIMITS.quickChatTextMax)).max(MANIFEST_LIMITS.quickChatMax).default([]),
+  /** Soften-list words this game's chat may keep (at most 20). */
+  chatAllow: z.array(ChatAllowWord).max(MANIFEST_LIMITS.chatAllowMax).default([]),
+});
+
+/** A normalised `game.multiplayer` block. */
+export type GameMultiplayer = z.output<typeof GameMultiplayer>;
+
+/** `game.multiplayer` for a static app: `own-server` needs a process app. */
+export const StaticGameMultiplayer = GameMultiplayer.refine((multiplayer) => multiplayer.transport !== 'own-server', {
+  message: 'own-server needs a process app; static apps use hub-rooms',
+  path: ['transport'],
+});

package/src/manifest/race.ts

@@ -0,0 +1,93 @@
+/**
+ * `game.race`: the opt-in that turns a single-player game into a race target
+ * (docs/multiplayer.md §14, docs/plans/race.md §5).
+ */
+import { z } from 'zod';
+import { RaceKey, RaceParamValue as RaceValue } from '../api/mp/races';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/** A race param value. */
+type RaceValue = z.infer<typeof RaceValue>;
+
+const RaceTitle = trimmedText(MANIFEST_LIMITS.raceTitleMax);
+
+/** One choice of a race param: a bare value, or a value with a title. */
+export const RaceOption = z.union([
+  RaceValue,
+  z.strictObject({
+    /** The value the game receives in `r.params[key]`. */
+    value: RaceValue,
+    /** What the creator sees. Defaults to the value. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+  }),
+]);
+
+/** The value of an option, bare or titled. */
+function optionValue(option: z.output<typeof RaceOption>): RaceValue {
+  return typeof option === 'object' ? option.value : option;
+}
+
+/** A choice the race creator makes. The server only accepts declared values. */
+export const RaceParam = z
+  .strictObject({
+    /** The key the game reads, `r.params[key]`. */
+    key: RaceKey,
+    /** What the creator sees. Defaults to the key. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+    /** The choices, 1 to 12. */
+    options: z.array(RaceOption).min(1).max(MANIFEST_LIMITS.raceOptionsMax),
+    /** The preselected value; one of the options' values. Defaults to the first. */
+    default: RaceValue.optional(),
+  })
+  .refine((p) => p.default === undefined || p.options.some((option) => optionValue(option) === p.default), {
+    message: 'default must be one of the option values',
+    path: ['default'],
+  });
+
+/** How the live race HUD and the race history show a stat. */
+export const RaceStatFormat = z.enum(['int', 'percent', 'time', 'bool', 'color']);
+
+/** A value of {@link RaceStatFormat}. */
+export type RaceStatFormat = z.infer<typeof RaceStatFormat>;
+
+/** A stat the live race HUD and the race history show. */
+export const RaceStat = z.strictObject({
+  /** The key the game sends in `hub.race.status({ [key]: value })`. */
+  key: RaceKey,
+  /** The column label. Defaults to the key. Checked like quick-chat text. */
+  title: RaceTitle.optional(),
+  /** `int` (default), `percent`, `time` (ms), `bool` or `color` (`#rrggbb`). */
+  format: RaceStatFormat.default('int'),
+});
+
+/** The `game.race` object form. */
+export const RaceBlock = z.strictObject({
+  /** URL suffix race invites and Join open, relative to `/<slug>/`. Default `?race=lobby`. */
+  lobby: LobbySuffix.default('?race=lobby'),
+  /** `[min, max]` racers, within 2..8. Default `[2, 2]`. */
+  players: playerRange(2).default([2, 2]),
+  /** What the creator picks (at most 6, unique keys). */
+  params: z.array(RaceParam).max(MANIFEST_LIMITS.raceParamsMax).refine(hasUniqueKeys, 'param keys must be unique').default([]),
+  /** What the live HUD and the history show (at most 8, unique keys; the HUD shows the first 3). */
+  stats: z.array(RaceStat).max(MANIFEST_LIMITS.raceStatsMax).refine(hasUniqueKeys, 'stat keys must be unique').default([]),
+  /**
+   * The earliest a finish may count after the go, in ms (0 to 600000). A
+   * sooner finish is held until then. Default: the hub's `raceMinFinishMs`.
+   */
+  minMs: z.number().int().min(0).max(MANIFEST_LIMITS.raceMinMsMax).optional(),
+});
+
+/** A normalised `game.race` block. */
+export type RaceBlock = z.output<typeof RaceBlock>;
+
+/**
+ * `game.race`: an object, `true` for all defaults (no params, no stats), or
+ * `false` for off. `true` parses to the object form, `false` to `undefined`.
+ */
+export const GameRace = z
+  .preprocess((v: boolean | z.input<typeof RaceBlock>) => (v === true ? {} : v === false ? undefined : v), RaceBlock.optional())
+  .optional();
+
+/** `game.race` as a game writes it. */
+export type GameRaceInput = z.input<typeof GameRace>;

package/src/middleware.ts

@@ -0,0 +1,47 @@
+/**
+ * Middleware **defs** for the public API (plan §6.1). A def is a contract
+ * only: a name, the context it provides and its dependencies. It holds no
+ * code, so it is safe in a published package; the server binds the real
+ * implementation. Each endpoint's guards are part of its declaration, which
+ * lets tests check rules such as "every social endpoint requires an active
+ * account" (plan §10.3).
+ */
+import { ctx, middleware } from '@ayepi/core';
+import { Slug } from './common';
+import type { SessionUser } from './entities';
+
+/**
+ * Resolves the `hub_session` cookie (the user, or `null`) and the anonymous
+ * `hub_cid` client id. Every endpoint has it.
+ */
+export const session = middleware('session', {
+  provides: ctx<{ user: SessionUser | null; clientId: string }>(),
+  doc: { security: { cookieAuth: { type: 'apiKey', in: 'cookie', name: 'hub_session' } } },
+});
+
+/** Signed in, as a guest or an account. Otherwise 401 `signed_out`. */
+export const requireUser = middleware('requireUser', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [session],
+});
+
+/**
+ * Signed in and not suspended. Otherwise 401 `signed_out` or 403
+ * `suspended`. Every social, multiplayer, race and trade endpoint has it.
+ */
+export const requireActive = middleware('requireActive', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireUser],
+});
+
+/** Active and a claimed account (not a guest). Otherwise 403 `claim_required`. */
+export const requireClaimed = middleware('requireClaimed', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireActive],
+});
+
+/**
+ * Owns the `:slug` path segment and checks it names a known game.
+ * Otherwise 404 "No such game".
+ */
+export const game = middleware.loader('slug', Slug, { requires: [session] });

package/src/realtime/define.ts

@@ -0,0 +1,52 @@
+/**
+ * Definers for socket ops and events (plan §5.2). One declaration per op or
+ * event feeds the server (validation), the runtime and test clients (types)
+ * and the generated op/event tables.
+ */
+import type { z } from 'zod';
+import type { ErrorCode } from '../errors';
+
+/** A client → server op on `/_ws`: its input, its ack and the codes it can fail with. */
+export interface OpDef<D extends z.ZodType = z.ZodType, A extends z.ZodType = z.ZodType> {
+  /** The op's input (`d` in `{t:'op', id, op, d}`). */
+  readonly d: D;
+  /** The success ack's payload (`d` in `{t:'ack', ok:true, d}`). */
+  readonly ack: A;
+  /** Error codes this op can fail with, beyond the envelope's own (see `ENVELOPE_ERRORS`). */
+  readonly errors: readonly ErrorCode[];
+  /**
+   * The refusal a malformed `d` gets (status 400), when the hub names it
+   * (`bad_stats`, `bad_patch`). Without it the refusal is `bad_request`
+   * with the first validation message.
+   */
+  readonly invalid?: { readonly code: ErrorCode; readonly error: string };
+  /** One line for the generated op table. */
+  readonly doc: string;
+}
+
+/** A server → client event on `/_ws`. */
+export interface EventDef<D extends z.ZodType = z.ZodType> {
+  /** The payload (`d` in `{t:'ev', ev, d}`). */
+  readonly d: D;
+  /** One line for the generated event table. */
+  readonly doc: string;
+}
+
+/** Declare an op (identity at runtime; keeps the literal types). */
+export function op<const D extends z.ZodType, const A extends z.ZodType>(def: OpDef<D, A>): OpDef<D, A> {
+  return def;
+}
+
+/** Declare an event (identity at runtime; keeps the literal types). */
+export function event<const D extends z.ZodType>(def: EventDef<D>): EventDef<D> {
+  return def;
+}
+
+/** The input type of an op. */
+export type OpInput<O extends OpDef> = z.input<O['d']>;
+
+/** The ack payload type of an op. */
+export type OpAck<O extends OpDef> = z.output<O['ack']>;
+
+/** The payload type of an event. */
+export type EventData<E extends EventDef> = z.output<E['d']>;

package/src/realtime/envelope.ts

@@ -0,0 +1,67 @@
+/**
+ * The legacy `/_ws` envelope (multiplayer-impl.md §4.2), unchanged since v1
+ * and kept indefinitely (plan D6):
+ *
+ * ```
+ * client → server  {t:'op',  id, op, d}
+ * server → client  {t:'ack', id, ok:true,  d}
+ *                  {t:'ack', id, ok:false, err: ErrorBody}
+ *                  {t:'ev',  ev, d}
+ * ```
+ */
+import { z } from 'zod';
+import { Json } from '../common';
+import { ErrorBody, type ErrorCode } from '../errors';
+
+/** A client's op frame. `id` is the client's own counter, echoed in the ack. */
+export const OpFrame = z.object({
+  t: z.literal('op'),
+  id: z.number(),
+  op: z.string(),
+  d: Json.optional(),
+});
+
+/** An op frame. */
+export type OpFrame = z.infer<typeof OpFrame>;
+
+/** A successful ack. */
+export const OkAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(true), d: Json });
+
+/** A failed ack. */
+export const ErrAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(false), err: ErrorBody });
+
+/** An ack frame: the server's answer to one op. */
+export const AckFrame = z.discriminatedUnion('ok', [OkAckFrame, ErrAckFrame]);
+
+/** An ack frame. */
+export type AckFrame = z.infer<typeof AckFrame>;
+
+/** A server-pushed event frame. */
+export const EvFrame = z.object({ t: z.literal('ev'), ev: z.string(), d: Json });
+
+/** An event frame. */
+export type EvFrame = z.infer<typeof EvFrame>;
+
+/** Any frame the server sends. */
+export const ServerFrame = z.union([AckFrame, EvFrame]);
+
+/** Close codes the client understands. */
+export const CloseCode = {
+  /** Service restart: reconnect quietly. */
+  restart: 1012,
+  /** The account is suspended. */
+  suspended: 4003,
+  /** Too many sockets for this user or IP. */
+  tooMany: 4029,
+  /** A frame that wasn't a valid op. */
+  badMessage: 4400,
+} as const;
+
+/**
+ * Codes any op can fail with, raised by the envelope rather than the op:
+ * the per-socket rate limit, an unknown op name, and ops sent before `hello`.
+ */
+export const ENVELOPE_ERRORS: readonly ErrorCode[] = ['rate_limited', 'unknown_op', 'hello_required'];
+
+/** Ops the server accepts before `hello`. */
+export const PRE_HELLO_OPS: readonly string[] = ['hello', 'ping'];