# Totenschloss Repository hosted on Twig: A chat server over the Deadlock data lake. Ask questions in plain English and get answers from read-only DuckDB queries against the DuckLake catalog at `data.deadlock-api.com`. Every lookup behind a reply is one click away under its "See the data" link. Stack: Zig server (std.http), DuckDB via its C API (in-memory, one database per request), vanilla JavaScript and CSS frontend embedded into the binary. The build links DuckDB and libstdc++ statically, so the result is one self-contained binary; only the system libc is dynamic, which DuckDB needs to load its `ducklake` and `httpfs` extensions. ## Run locally ```sh mise install # Zig 0.14.1, plus DuckDB 2.0.0 via the postinstall hook mise run run # PORT defaults to 8080 ``` `mise.toml` pins the toolchain. The `postinstall` hook runs `scripts/fetch-duckdb.sh`, which downloads the DuckDB static archives and the libstdc++ archive into `vendor/duckdb/` (skipped if already present); nothing has to be installed system-wide. Tasks: `build`, `test`, `run`, `fetch-duckdb`, `docker`. Builds target the baseline x86-64 CPU by default, so a binary built on a new machine still runs on an older host. Override with `-Dcpu=native` only for a binary that stays on this machine. Open http://localhost:8080. Without an API key the chat is disabled, but `/sql` still works: ``` /sql SELECT hero_id, count(*) AS games FROM lake.match_player_latest WHERE match_id BETWEEN 105000000 AND 105100000 GROUP BY ALL ORDER BY games DESC /tables # list lake tables and columns ``` Tests: `mise run test`. ## Configuration Local values go in `.env` (git-ignored); `mise` loads it for every task. The full list of variables, with defaults and what each one is for, is in [docs/DEPLOY.md](docs/DEPLOY.md#environment). ### Login and invites Set `ADMIN_PASSWORD` (and optionally `ADMIN_USERNAME`, default `admin`) to turn on login. Without it the site stays open to anyone, which is fine for a local trial. The admin signs in with those environment values. Admins can open **Invites**, create a single-use invite, and share the resulting `/signup?invite=…` link. The recipient picks a username and a password and is signed in. Accounts and invites are stored in `storage/auth.json`; passwords are PBKDF2 hashes with a random salt, and invite codes are stored only as SHA-256 hashes. Sessions are in memory, so a restart signs everyone out but keeps the accounts. ## Security User text is never spliced into SQL. Anything that reaches DuckDB goes through these layers: 1. **Parser check.** `json_serialize_sql` turns the query into an AST. It must be exactly one `SELECT` (or set operation). `sql_guard.zig` rejects anything else. 2. **Table and function rules.** Base tables must come from `lake`. Table functions (`read_csv`, `glob`, URL literals in `FROM`, ...) are rejected, and `getenv` and similar scalar functions are denied by name. 3. **Statement kind.** DuckDB's own prepared-statement type must be `SELECT`. 4. **Session lockdown.** The catalog is attached `READ_ONLY`. Local filesystem access is disabled, and configuration is locked (`lock_configuration`) before any query runs. Remote reads stay on because the lake's data files are HTTPS. 5. **Limits.** One private in-memory DuckDB per request, 1 GB memory cap, 30 s query timeout, 45 s per answer, 200 rows returned to the UI (50 to the model), at most 4 concurrent chats. `lake.match_player` is hundreds of GB, so scans of it must filter `start_time` or `match_id` (or be a metadata aggregate such as `count(*)`); other shapes are rejected before DuckDB starts downloading data files. The model only sees the schema and results it asks for. The API key is read once at startup and never sent to the browser. Web requests must also pass the login check when `ADMIN_PASSWORD` is set. Sessions use a random 256-bit token in an `HttpOnly`, `SameSite=Lax` cookie; state-changing requests reject cross-site origins. Password checks use PBKDF2's deliberate cost, so brute-force attempts are expensive. ## Deploy See [docs/DEPLOY.md](docs/DEPLOY.md) for once and Docker deployment, and for configuring login and invites. ## Docker (summary) ```sh docker build -t totenschloss . docker run --rm -p 8080:80 --env-file .env -v totenschloss-data:/storage totenschloss ``` The image meets the once requirements: - serves HTTP on port 80 (`PORT=80`) - `GET /up` returns `200 ok` - persistent data in `/storage` (the volume is included in backups) - no `SECRET_KEY_BASE`, SMTP or hostname configuration needed; pass `INFERENCE_API_KEY` (or `ANTHROPIC_API_KEY`) and `ADMIN_PASSWORD` through `--env-file`; `.env` is never copied into the image ## Layout ``` .twig.toml Twig view configuration (tabs, presentation, scripts) src/main.zig entry point and startup src/server.zig HTTP routes, admission control, chat and auth endpoints src/auth.zig accounts, invites, password hashing and sessions src/chat.zig agent loop: model <-> describe_tables / run_sql tools src/llm.zig Anthropic Messages API client (tool use) src/session.zig per-request DuckDB session: attach, lockdown, timeout, results src/sql_guard.zig AST-based query guard and its tests src/duckdb.zig DuckDB C API wrapper src/web/ index.html, app.js, style.css (embedded at build time) ```