brainwave/docs/superpowers/plans/2026-08-21-security-audit-fixes.md

# Security Audit Fixes Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Fix all vulnerabilities confirmed by the 2026-08-21 full-codebase security audit (5 confirmed ≥8/10 confidence + 6 sub-threshold verified findings).

**Architecture:** Three clusters. (A) Session security: JWTs gain a `tv` (token version) claim; `requireAuth` revalidates the user against SQLite on every request (deleted accounts, demoted roles, password-rotation revocation); logout blacklists until real `exp`. (B) AI cost control: wire the existing-but-dead quota helpers into every provider call path and cap attacker-controlled prompt sizes. (C) Bootstrap & hygiene: make the setup wizard the only admin bootstrap, stop register-time auto-admin, sanitize admin user listings, bound result schemas, enforce view-only share mode server-side, pin SSH host keys in CI.

**Tech Stack:** Express 5, better-sqlite3 (sync), jsonwebtoken 9, zod 3, vitest 4, Gitea Actions.

**Spec:** Security audit report delivered in this session (2026-08-21). Findings referenced below as Vuln N / sub-threshold N.

## Global Constraints

- Do not alter lines containing redacted numeric literals in `userRepo.ts` (`storageQuotaBytes ?? …`) and `migrations.ts` (`storage_quota_bytes … DEFAULT`) — edit around them.
- Keep HTTP response shapes of AI endpoints unchanged (`{ data, usageTokens }` payloads stay) so the frontend needs no changes.
- Tests run with `cd backend && npx vitest run`; vitest.setup stubs `JWT_SECRET`, `DB_PATH=:memory:`; `getDb()` runs full migrations on first use.
- No git commits — user has not requested them; leave changes in working tree.
- Existing deployments upgrade transparently; all users are logged out once by the new `tv` claim (accepted, noted in final report).

---

### Task 1: Token versioning + DB revalidation (Vuln 3, Vuln 4, sub-threshold 1)

**Files:**
- Modify: `backend/src/db/migrations.ts` (add column)
- Modify: `backend/src/utils/tokens.ts` (JwtPayload.tv)
- Modify: `backend/src/repositories/userRepo.ts` (token_version plumbing)
- Modify: `backend/src/middleware/auth.ts` (revalidation)
- Modify: `backend/src/services/authService.ts` (sign with tv, bump on password events)
- Modify: `backend/src/routes/setup.ts` (sign with tv)
- Modify: `backend/src/routes/auth.ts` (logout uses decoded exp)
- Modify: `backend/src/utils/tokenBlacklist.ts` (purge expired rows at init)
- Test: `backend/src/utils/tokens.test.ts` (update payload fixtures), `backend/src/middleware/auth.test.ts` (new)

**Interfaces:**
- Produces: `JwtPayload { userId, email, displayName, role, tv }`; `DbUser.token_version: number`; `UpdateUserData.tokenVersion?: number`.

- [ ] **Step 1: Write failing tests** (`auth.test.ts`): valid token passes and `req.user.role` comes from DB; deleted user → 401; tv mismatch → 401. Update `tokens.test.ts` payload fixtures to include `tv: 0` (type error until implemented = failing).
- [ ] **Step 2: Run** `npx vitest run src/middleware/auth.test.ts src/utils/tokens.test.ts` → FAIL (missing tv / column).
- [ ] **Step 3: Implement** per code in execution notes: migration guard block; `token_version INTEGER NOT NULL DEFAULT 0`; JwtPayload gains required `tv`; requireAuth loads user via `getUserById`, 401 on missing user, 401 on `user.token_version !== payload.tv`, rebuilds `req.user` from the DB row; changePassword/resetPassword bump tokenVersion; logout blacklists `(decoded.exp ?? now+86400)*1000`; initCache purges expired rows before loading.
- [ ] **Step 4: Run** → PASS.
- [ ] **Step 5: Full suite** `npx vitest run` → PASS.

### Task 2: Setup-gated bootstrap, no register auto-admin, enumeration-safe register, last-admin guard (sub-threshold 2, 3, 4)

**Files:**
- Modify: `backend/src/routes/setup.ts` (status + POST gate on countAdmins)
- Modify: `backend/src/routes/auth.ts` (drop isFirstUser; last-admin self-delete guard)
- Modify: `backend/src/services/authService.ts` (register signature, role always 'user', duplicate → generic success after timing-equalized hash)
- Modify: `backend/src/db/migrations.ts` (remove auto-promote block)
- Modify: `backend/src/repositories/userRepo.ts` (remove dead promoteFirstUserToAdmin)
- Test: `backend/src/services/authService.test.ts` (new)

- [ ] **Step 1: Failing tests**: duplicate-email register resolves `{ message }` with no token; fresh register returns token with role 'user'; both take ~equal time (hash-before-check asserted structurally, not by timing).
- [ ] **Step 2: Run** → FAIL.
- [ ] **Step 3: Implement**: setup status/gate switch to `countAdmins() > 0`; register drops isFirstUser param, hashes password before duplicate check, returns `{ message: 'Check your inbox…' }` on duplicates; `DELETE /api/auth/me` refuses when `role==='admin' && countAdmins()<=1`; migrations/userRepo promotion code deleted.
- [ ] **Step 4: Run** → PASS. **Step 5: Full suite** → PASS.

### Task 3: AI quota enforcement + prompt size caps (Vuln 1, Vuln 2)

**Files:**
- Modify: `backend/src/utils/aiQuota.ts` (add enforceDailyAiQuota throwing AppError 429)
- Create: `backend/src/validators/gradeSchemas.ts` (schema with serialized-size superRefine caps), `backend/src/validators/aiSchemas.ts` (hintSchema moved + cap)
- Modify: `backend/src/routes/ai.ts`, `backend/src/routes/grade.ts`, `backend/src/routes/results.ts` (enforce before provider call; recordDailyAiUsage after, using returned usageTokens)
- Test: `backend/src/utils/aiQuota.test.ts`, `backend/src/validators/gradeSchemas.test.ts`

**Interfaces:**
- Consumes: `recordDailyAiUsage(userId, getUtcDateKey(), tokens)`; services' existing `AiUsageResult.usageTokens`.
- Produces: `enforceDailyAiQuota(userId): void` (throws `AppError(429)`).

- [ ] **Step 1: Failing tests**: quota throws 429 when used ≥ limit; passes under limit; passes when limit unset ("0"/absent → null → unlimited). Grade schema rejects question JSON > 8000 chars / answer > 4000 chars.
- [ ] **Step 2: Run** → FAIL. **Step 3: Implement. Step 4: Run → PASS. Step 5: Full suite → PASS.**

### Task 4: Admin user DTO + result schema bounds (sub-threshold 5, 6)

**Files:**
- Modify: `backend/src/repositories/userRepo.ts` (`SafeUser`, explicit SELECT columns in listUsers)
- Modify: `backend/src/validators/resultSchemas.ts` (finite/int/min/max bounds, title ≤300)
- Test: `backend/src/validators/resultSchemas.test.ts`, repo test for sanitized listing

- [ ] **Step 1: Failing tests**: listUsers never includes password_hash/verify_token/reset_token/reset_expires keys; schema rejects negative counts, non-integers, huge floats, oversized titles.
- [ ] **Step 2–5:** implement → PASS → full suite PASS.

### Task 5: View-only share clone block (Vuln 5)

**Files:**
- Modify: `backend/src/routes/share.ts`
- Test: `backend/src/routes/share.test.ts`

- [ ] Export pure `canClone(shareMode?: string | null): boolean` ('view' → false; 'clone'/null/undefined → true). Failing test first, then guard `if (!canClone(source.share_mode)) throw new AppError(403, 'This exam is shared as view-only and cannot be saved')` before `cloneExam`. PASS + full suite.

### Task 6: CI SSH host-key pinning (sub-threshold 7)

**Files:** Modify `.gitea/workflows/deploy.yml`

- [ ] Replace keyscan step: write `${{ vars.SSH_HOST_PUBLIC_KEY }}` via env-indirection into known_hosts; hard-fail with setup instructions when unset. Validate YAML parses.

### Task 7: Verification

- [ ] `cd backend && npx tsc --noEmit && npx vitest run` — all green.
- [ ] `cd frontend && npm run build` (or tsc -b) — typecheck green (no frontend changes expected).
- [ ] Ultracode adversarial review workflow over the full diff; fix anything CONFIRMED.
- [ ] Final report mapping each finding → fix → evidence.