open-chess server

A Rust chess server that speaks the Lichess API: the Board, Bot, Challenge and OAuth (PKCE) endpoints, the event, game and move streams, and game export, with Lichess's JSON. Anything written for Lichess talks to it by changing the base URL: a host site's Lichess backend, Lichess Board API apps, and lichess-bot.

It keeps everything in its own Postgres schema (chess): players, API tokens and sessions, challenges, games, moves and clocks, ratings and fair play. People make accounts on it (/signup, /login, /account for tokens), and a host site's players can sign in with the site (see "Plugging into a site" below). Sites and dashboards follow its games through a live feed (GET /api/feed, server-sent events).

Database rights. The role needs to create and write its schema. It may share a database with a host site, but reads nothing of the site's after a one-time import of the site's chess players (CHESS_SITE_SCHEMA).

Lichess client / bot / site ──▶ open-chess × N ──▶ Postgres
           host site ◀── /api/feed ──┘   ▲         chess.*   players, tokens, sessions, games,
                                         │                   challenges, ratings, fair play
                                         └─ LISTEN
fair-play worker × M (Stockfish) ───▶ the same database

Crates

The server is the top of a stack; the lower crates are what a bot (for this server or for lichess.org) reuses.

shakmaty, the usual Rust chess crate, is GPL-3.0, which deny.toml doesn't allow, so cozy-chess handles move generation and the rest is written here.

API

The endpoints (the Lichess API, live game streams, OAuth and scopes, and open-chess's own additions) are in docs/api.md; using the server with Lichess tools and bots is in docs/lichess.md.

Anti-cheat

Bots are allowed and openly marked (title: BOT). For people, these checks apply:

• Separate APIs. Bot accounts can't play through the Board API, and a human account can only become a bot before it has played a game.

• No live feed. The public move stream runs three plies behind live games. Game streams are for the two players only.

• Post-game screening. When a game with a human player ends (20 plies or more), it's queued for the worker (open-chess analyse). Stockfish evaluates every position at multi-PV 3. Each human side then gets:

  • accuracy and ACPL, on Lichess's win-percentage scale;
  • how often their move was the engine's first, or top three, choice (opening, forced moves and decided positions are left out);
  • how even their move times were;
  • whether they spent longer on critical positions (people do);
  • the training-app fingerprint: in the positions where Stockfish and the training app's own engine disagree on the best move, which one the player chose. Honest players choose either or neither; someone copying the app's suggestions chooses the app's move almost every time.

  A screening model folds these into a 0–100 score and decides when a game is flagged (and when the fingerprint alone is enough). The model is data, chess_fairplay::Model as JSON, given in CHESS_FAIRPLAY_MODEL (a file path or the JSON itself). Keep a tuned model private: its numbers tell people what to avoid. Without one the worker uses an untuned example and says so in its log.

• Human review, never automatic bans. Flagged games wait in /api/fairplay/queue. A reviewer's engine verdict marks the account: /api/user then shows tosViolation, and with CHESS_BLOCK_MARKED on the account can't start new games. A clean verdict lifts the mark. The host site decides what happens next: chess.accounts.marked_at and chess.fairplay_reports are there to read.

The score is a screening heuristic, not proof: strong players have accurate games. Tune the model on your own players before relying on it.

Assistance labels. The training app can switch its engine help on during games on this server (never on Lichess, where it's cheating). When it does, it says so: POST /api/board/game/{id}/assist with on=true or false goes into chess.assist_marks, and the game's reports carry declaredAssist. This is ground truth for training the screening model on known assisted and unassisted games; screening itself never relies on it, because a cheating client wouldn't send it.

Scaling

Every request and every clock decision goes through Postgres:

• A move locks its game row, validates and applies the move with chess-core, charges the clock, writes, and sends pg_notify in one transaction.
• The database clock (clock_timestamp()) is the only clock, so replicas never disagree about time used.
• Each replica keeps one LISTEN connection (on Neon's direct host, derived from the pooled one) and passes changes to its own open streams. A move sent to one replica reaches a stream held by another.
• A sweeper on every replica flags clocks, aborts unstarted games and lapses challenges. It claims rows with FOR UPDATE SKIP LOCKED, so replicas don't collide.

So the API scales by adding replicas (HPA on Kubernetes, CHESS_INSTANCES on Cloudflare), and fair play by adding workers. Each player may hold 8 event streams and 40 game streams per replica.

Configuration

Everything is environment (each variable is also a command-line flag: CHESS_PUBLIC_URL is --public-url; open-chess serve --help lists them).

Running

open-chess serve             # the API (runs migrations first); also what `open-chess` alone does
open-chess analyse           # the fair-play worker (and, when idle, the dictionary's photo positions)
open-chess analyse --once    # screen what's waiting, then exit
open-chess migrate           # schema only
open-chess bot create --name stockfish-1800 [--days 365]   # prints the bot's token once
open-chess bot list
open-chess photos export --out DIR [--reviewed-only]      # confirmed photos, for chess-vision-train
open-chess healthcheck       # exit 0 if this machine's server answers /healthz (the image's HEALTHCHECK)

Get it from a release: the binary for Linux, or the image ghcr.io/offenedatenmodellierung/open-chess (built by the Dockerfile from the release's binaries): one image for both roles (Stockfish included), and :slim, distroless with the API and the app but no Stockfish. To deploy:

• Kubernetes: deploy/k8s/chess.yaml (an example).
• Cloudflare: deploy/cloudflare (Containers behind a Worker; an example).

Plugging into a site

The server has its own accounts; a host site plugs in as a client of it, with a secret they share (ESPORTS_SECRET, and ESPORTS_LOGIN=true):

• Signing in. The sign-in page offers "Sign in with ": /auth/esports sends the browser to the site's /chess/sso?return=…&nonce=…, and the site sends it back to /auth/esports/back?a=… with a signed statement of who is signed in there: base64url(json) . base64url(HMAC-SHA256(secret, the first part)), the JSON {"sub": "<the site's player id>", "name", "email", "role", "roles", "nonce", "exp": <Unix seconds>}.
• Tokens for its players. The site's server calls POST /api/esports/token with Authorization: Bearer <secret> and a form (sub, name, email, role, roles, scopes, days or hours, label); the answer is {"token", "username", "scopes", "expires"}. POST /api/esports/revoke (label, optionally sub) revokes the tokens of that name it asked for, e.g. a match's when it ends; GET /api/esports/players lists its players linked here ({"players": [{"sub", "username"}]}).
• Either way the site's player is linked to a player here (made on first use, with a chess account named after them; the site's roles carry over, so its managers review fair play).
• Following games. The site reads GET /api/feed (every game's start, moves and end, with rating changes; resumable), and the public APIs.

A deployment that used to share the site's players (this server's first versions read them from the site's schema) imports them once, with their ids and chess tokens, when this version first starts (CHESS_SITE_SCHEMA).

esports-lab, the (private) application this server was extracted from, is the reference host. Its native chess backend is a Lichess client pointed at this server: its watcher gets both players a short-lived token per game (board:play, challenge:read, challenge:write, named chess match {fixture}) from POST /api/esports/token, and revokes them when the game ends. Fixtures keep backend = 'native', the game id in external_id, and the competition state in the site's tables.

Players play on the site's own board page (#/play/{fixture}), which asks the site for its token (GET /api/me/chess/play/{fixture}) and then talks to this server's Board API directly from the browser ([chess] native_public_url). Any other Board API client works too.

Tests

cargo test -p open-chess-core -p open-chess-proto -p open-chess-client \
           -p open-chess-engine -p open-chess-fairplay -p open-chess-server
# End to end: two replicas on one Postgres, games, clocks, OAuth, bots, fair play
CHESS_TEST_DATABASE_URL=postgres://…?sslmode=disable cargo test -p open-chess-server --test e2e

CI runs the end-to-end suite against a Postgres service with Stockfish installed.