[abhisek]

Implements the three specs from #32, with the owner decisions recorded in the rewritten specs.

Spec 17: pluggable parent auth

• One generic auth.JWTVerifier checks every provider's tokens. A Preset holds the only vendor knowledge. Presets: supabase (the one real provider) and test (HS256, explicit opt-in, for unit tests, the dev stack and browser E2E). No Clerk code. A new JWKS/OIDC provider is one preset constructor plus one SPA adapter file.
• Accounts are keyed on (auth_provider, auth_subject), never on email. supabase_user_id, the MATHIZ_SUPABASE_* variables and the old boot-config fields are removed (no back-compat: production starts on a fresh database). A set MATHIZ_SUPABASE_* variable stops the server and names its replacement.
• New config: MATHIZ_AUTH_PROVIDER, MATHIZ_AUTH_URL (compulsory for Supabase, must be https), MATHIZ_AUTH_PUBLIC_KEY, MATHIZ_AUTH_HS256_SECRET, MATHIZ_AUTH_AUDIENCE, MATHIZ_AUTH_ALLOW_TEST.
• An unverified email is refused with a 401, because invite acceptance matches on email. Supabase sessions count as verified, and the runbook now requires "Confirm email" ON. An explicit email_verified=false or a missing email is refused.
• The server refuses to start on a database from before this change (the check runs before auto-migrate) and when accounts belong to another provider.
• mathiz auth remap --from X --to Y --map map.csv [--dry-run] switches providers. It is all-or-nothing (no --allow-unmapped), checks every row before writing, and a rerun changes nothing.
• SPA: web/src/auth/ holds one adapter per provider, and each adapter is its own chunk. Parent API calls take a TokenGetter. A 401 is retried once with a new token, then the parent is signed out with a "session ended" notice. A provider key outage is a 503, not a 401, so a provider blip does not sign parents out. The test adapter lets the parent dashboard run in a browser for the first time without an auth provider.
• JWKS fixes found on the way. A failed first fetch now returns its error, so the 30 s retry runs; before, keyfunc built an empty key set and refetched only every 5 minutes. Each failed attempt cancels its refresh goroutine (before, each retry leaked one). Fetches time out after 5 s. Tokens on the JWKS path need a kid.

Spec 18: self-hosted PostgreSQL

• PostgreSQL pool limits (20 open, 10 idle; env overrides). store.Open logs the server version and the effective sslmode, and refuses servers older than 16.
• docker-compose.yml gains a prod profile for one VM: prod-db (postgres:18-alpine, no published port) and prod-app (loopback port for a TLS proxy, MATHIZ_AUTH_ALLOW_TEST blanked). The dev database and CI move to PostgreSQL 18, with the volume layout of the PG 18 image.
• docs/saas.md covers the VM deploy, the 12-hour RPO and RTO, a host cron backup every 12 hours, restore steps and a monthly restore drill. There is no data migration: production starts fresh.

Spec 19: question latency

• Telemetry: q_wait_ms, q_source and q_attempts on the /question canonical line. PostHog gets question_shown {index, waitMs} and question_generation_failed {index}, both anonymous.
• A question a validator rejects as retryable is asked for again, up to 2 more times.
• LLM questions generate without the expedition lock held, so "Sail home", hints and a replacing Start no longer wait on the provider. Quest expeditions stay on the locked path.
• problemgen.Prefetcher (fingerprinted, one held question, generations on its own context) warms Q1 during "Setting sail…" and the next question while the kid reads feedback. The game and the terminal session both use it. MATHIZ_QUESTION_PREFETCH=0 is the off switch.
• On a failed question the SPA keeps the expedition and shows "The map is foggy… 🌫️" with Try again, so no second credit is charged. After 6 s of loading the copy changes to "Still digging… the treasure is deep today ⛏️". The circuit breaker ends the expedition with the normal summary. Game errors carry stable codes.

Verification

• CGO_ENABLED=0 go build ./..., go vet ./... and go test ./... all pass.
• go test -race -count=2 passes on internal/saas, problemgen, screens, llm and cmd.
• The store suite passes on PostgreSQL 16 and 18.
• web: tsc, oxlint and the build all pass.
• Browser E2E (Playwright) on the full stack:
  • Login with a pasted test token, then sign-out, then a forced sign-out with the notice.
  • The Supabase adapter renders its forms and loads only its own chunk.
  • Kid surfaces load no adapter.
  • Q2 appears 74 ms after "Next clue" (a prefetch hit).
  • "Still digging" appears at 6.4 s.
  • Fog, then Try again, recovers with one debit.
  • The breaker ends with the normal summary, with one debit.
• The compose prod profile was booted once: PG 18 data directory, a dump, a restore, and the empty-password refusal.
• Fable reviews ran on the plan, on each complex task and on the whole branch. Every finding is fixed on the branch.

Ops steps after merge

• Production: create .env from .env.example with MATHIZ_AUTH_PROVIDER=supabase and a URL-safe MATHIZ_DB_PASSWORD. Turn on "Confirm email" in Supabase. Then run docker compose --profile prod up -d --build.
• Drop the old mathiz database on the Supabase cluster.
• A local dev database from before this change: recreate it, or drop accounts.supabase_user_id if accounts is empty.

---

Generated by Claude Code

[safedep]

SafeDep Report Summary

No dependency changes detected. Nothing to scan.

View complete scan results →

_{This report is generated by SafeDep GitHub App}

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.