# Phase 9 — Production hardening

**Goal:** make the app safe and stable to expose to strangers on the internet: config via
environment, resource limits on everything user-controlled, and a single-service production
build.

## Decisions

| Question | Answer |
|---|---|
| Database | **Decide at start of this phase.** SQLite on a persistent disk (zero code change, but Render disks require the ~$7/mo starter tier) vs Postgres (free/cheap managed options, better resume talking point, needs SQLAlchemy URL + migration tweaks). Revisit with current Render pricing. |

**Ask before implementing:** the database choice above, and target monthly budget (drives
Render tier: free tier sleeps after idle + has no persistent disk).

## Configuration

- [ ] All config via env vars with sane local defaults: `DATABASE_URL`, `SECRET_KEY`
      (sessions + API-key encryption), `MULTI_USER`, `CORS_ORIGINS`, demo-key vars (Phase 8),
      port/host. Document each in `backend/.env.example`.
- [ ] Fail fast on missing `SECRET_KEY` when `MULTI_USER=true`.

## Abuse & resource limits

- [ ] **quickjs limits**: per-execution time limit and memory limit on the scripting engine
      (`scripting/engine.py`) — user-submitted JS must not be able to hang or OOM the server.
- [ ] Rate limiting on expensive endpoints (turn generation, script run, auth) — per-user and
      per-IP (e.g. `slowapi`).
- [ ] Request size limits (script source length, memory/story-card text lengths, action text).
- [ ] Cap per-user row counts (adventures, scenarios, scripts, story cards) with friendly errors.
- [ ] Audit debug router (`routers/debug.py`) and `/docs`: admin-only or disabled when
      `MULTI_USER=true` — debug log may contain other users' prompts.

## Production serving

- [ ] Single service: FastAPI serves the built SPA (fallback already exists) — verify the Docker
      image from Phase 7 is production-ready (no `--reload`, multiple workers or async-safe
      single worker; check SQLite + multiple workers interaction before choosing).
- [ ] CORS locked to the deployed origin (moot if same-origin single service — verify).
- [ ] Security headers middleware; cookies `Secure` + `SameSite`.
- [ ] Streaming (SSE) works behind Render's proxy — verify no buffering issues.
- [ ] Structured logging; scrub API keys from all logs and the debug page.

## Database (after decision)

- [ ] If Postgres: swap `DATABASE_URL`, verify JSON-blob columns (embeddings) and
      `migrations.py` work; test full play loop.
- [ ] If SQLite-on-disk: confirm WAL mode + single-worker (or serialized writes) is acceptable.
- [ ] Backup story: platform DB backups (Postgres) or a scheduled dump of the disk (SQLite).

## Exit criteria

Running the production Docker image locally with `MULTI_USER=true`: a hostile user cannot hang
the server with a `while(true)` script, cannot see another user's data or the debug log, gets
rate-limited instead of burning the demo key, and the app streams turns normally the whole time.

### Verified 2026-07-07 (uvicorn, `MULTI_USER=1`, fresh SQLite DB, curl)

- **Fail-fast secret:** `import app.main` with `MULTI_USER=1` and no `AIDND_SECRET_KEY` raises
  the RuntimeError as designed (won't boot).
- **`while(true)` script:** `POST /api/scripts/{id}/test` on an `input_js` infinite loop returns
  `InternalError: interrupted` (engine time limit) — server stays responsive afterward.
- **Cross-user isolation:** guest B sees `[]` for scripts, gets 404 on guest A's script id;
  guest A keeps its own row. No leakage.
- **Debug log:** `GET /api/debug/requests` → 403 in multi-user mode.
- **Rate limiting:** 12 rapid `POST /api/auth/register` → 429 after the 10th (auth scope, 10/300s).
- **Body size:** 3 MB body to `POST /api/scenarios` → 413 (limit 2 MB) via BodySizeLimitMiddleware.
- **Security headers:** CSP, `x-frame-options: DENY`, `x-content-type-options: nosniff`,
  `referrer-policy: same-origin` on every response — including the SSE stream.
- **Docs disabled:** Swagger UI and OpenAPI schema not served (`/docs`, `/openapi.json` fall
  through to the SPA `index.html`; no `swagger-ui`, no API schema exposed).
- **SSE streaming:** `POST /api/adventures/{id}/actions` streams `text/event-stream` with
  `x-accel-buffering: no`, chunked, incremental events — the pure-ASGI middlewares don't buffer.
  (No LLM key configured here, so it streams the "No model configured" error event; a *live*
  provider turn through this path was verified end-to-end in Phase 8.)

All Phase 9 exit criteria met.

### Postgres path verified 2026-07-07 (real Neon, PostgreSQL 18.4)

Pointed the backend at a live Neon `DATABASE_URL` (pooled, `sslmode=require&channel_binding=require`):

- **Driver/URL:** `postgres://`/`postgresql://` normalized to `postgresql+psycopg://`; raw
  psycopg3 connect succeeds.
- **Bootstrap:** fresh DB → `create_all` builds all 11 tables and stamps `schema_version = 23`
  (= `LATEST_VERSION`); the SQLite-only migrations 2–23 are correctly skipped on a fresh DB.
- **Embedding column:** `memories.embedding` is Postgres `json`; a float list round-trips
  intact (`[0.1, 0.2, 0.3, -0.4]` back as a `list`).
- **ORM CRUD:** user → scenario → adventure → memory create/read/delete with FK cascades works.
- **HTTP round-trip (multi-user, TestClient):** guest bootstrap → register → me → create
  scenario → list → settings → delete, all 200/201/204 against Neon.

Remaining Phase 10 step: the Docker production image specifically (build + run the container).