nas-tools/specs/sprint-02-auth-hardening.md

# Sprint 02 — Auth Hardening

**Depends on:** S00, S01 (need stable environment to test auth changes against)
**Duration:** ~10h
**Goal:** Add Pydantic validation to raw-JSON endpoints, bind passkey challenges to sessions, gate sensitive log endpoints behind admin role, fix fragile cross-module patterns.

---

## S02.1 — Add max_length to LoginRequest

- **Files:** `dashboard/backend/routers/auth.py:22-25`
- **Estimate:** 0.5h
- **Done means:** `LoginRequest` has `max_length=128` on username, `max_length=1024` on password. Requests exceeding limits get 422 with clear field error.
- **Verify by:**
  1. `curl -X POST /api/auth/login -d '{"username":"'$(python -c 'print("a"*200)')'","password":"test"}'` → 422, error mentions max_length
  2. Normal login with valid credentials → 200
- **Risk:** None. Pydantic validation happens before password hashing.

- [ ] S02.1 — Add max_length to LoginRequest

## S02.2 — Add Pydantic models to RBAC override endpoints

- **Files:** `dashboard/backend/routers/auth.py:242-259,303-326`
- **Estimate:** 2h
- **Done means:** `rbac_set_override` and `rbac_update_role` use Pydantic models (`RbacOverrideRequest`, `RbacUpdateRoleRequest`) instead of `await request.json()`. Unknown fields are rejected. Existing RBAC functionality unchanged.
- **Verify by:**
  1. Send valid override payload → 200, override saved
  2. Send payload with unknown field `sidebar_links` → 422 validation error
  3. Send payload missing required `pages` field → 422
  4. Existing RBAC tests pass (`test_rbac.py`, `test_auth_flow.py`)
- **Risk:** Audit frontend `Settings.svelte` to confirm it only sends expected fields.

- [ ] S02.2 — Add Pydantic models to RBAC override endpoints

## S02.3 — Add Pydantic models to passkey endpoints

- **Files:** `dashboard/backend/routers/passkey.py:78,127,188`
- **Estimate:** 2h
- **Done means:** `register_verify`, `login_verify`, `delete` use Pydantic models matching WebAuthn payload structure. Malformed payloads get 422 instead of 500.
- **Verify by:**
  1. Send valid WebAuthn registration payload → 200
  2. Send malformed payload (missing `response` field) → 422 with field-level error
  3. Existing passkey tests pass (`test_passkey.py`)
- **Risk:** WebAuthn payloads have specific structure — cross-reference with the `webauthn` library's expected types.

- [ ] S02.3 — Add Pydantic models to passkey endpoints

## S02.4 — Bind passkey challenges to sessions

- **Files:** `dashboard/backend/routers/passkey.py:29-55`
- **Estimate:** 1.5h
- **Done means:** Passkey challenges are stored keyed by a session-bound identifier (not globally). `_get_challenge` only returns the challenge if the session matches.
- **Verify by:**
  1. User A requests challenge → challenge stored with user A's session ID
  2. User B (different session) tries to verify with user A's challenge → 400 "invalid challenge"
  3. User A verifies with own challenge → success
  4. Existing passkey tests pass
- **Risk:** Need session identifier for unauthenticated users during login flow. Use server-generated `challenge_id` returned in options, required in verify — simplest and stateless.

- [ ] S02.4 — Bind passkey challenges to sessions

## S02.5 — Gate audit log endpoint behind admin role

- **Files:** `dashboard/backend/routers/system.py:82-116`
- **Estimate:** 1h
- **Done means:** `/api/system/audit-log` requires admin role. Non-admin users get 403. Log collection unchanged.
- **Verify by:**
  1. Admin user requests audit log → 200, entries returned
  2. Non-admin user requests audit log → 403
- **Risk:** Frontend Security page must handle 403 gracefully if current user isn't admin.

- [ ] S02.5 — Gate audit log endpoint behind admin role

## S02.6 — Gate security log endpoint behind admin role

- **Files:** `dashboard/backend/routers/security.py:198`
- **Estimate:** 1h
- **Done means:** `/api/security/logs` requires admin role. Non-admin users get 403.
- **Verify by:**
  1. Admin user requests security logs → 200
  2. Non-admin user requests security logs → 403
- **Risk:** Same as S02.5 — frontend must handle 403 gracefully.

- [ ] S02.6 — Gate security log endpoint behind admin role

## S02.7 — Fix fragile opc_db.json.dumps() pattern

- **Files:** `dashboard/backend/services/agent_executor.py:273,307`
- **Estimate:** 0.5h
- **Done means:** `agent_executor.py` imports `json` directly and uses `json.dumps()` instead of `opc_db.json.dumps()`.
- **Verify by:**
  1. `grep "opc_db.json" dashboard/backend/services/agent_executor.py` → no match
  2. OPC task creation and agent execution still work end-to-end
- **Risk:** None — pure refactor.

- [ ] S02.7 — Fix fragile opc_db.json.dumps() pattern

## S02.8 — Add COOKIE_SECURE startup warning

- **Files:** `dashboard/backend/auth_service.py:23`, `dashboard/backend/main.py`
- **Estimate:** 0.5h
- **Done means:** If `COOKIE_SECURE=False` at startup, `logger.warning()` fires explaining the risk. `ALLOW_INSECURE_COOKIES=true` env var suppresses the warning.
- **Verify by:**
  1. Start without `ALLOW_INSECURE_COOKIES` → warning in logs
  2. Start with `ALLOW_INSECURE_COOKIES=true` → no warning
- **Risk:** Low — purely additive, doesn't change cookie behavior.

- [ ] S02.8 — Add COOKIE_SECURE startup warning

---

## Exit criteria

- [ ] `LoginRequest` rejects usernames > 128 chars with 422
- [ ] RBAC endpoints reject unknown fields with 422
- [ ] Passkey endpoints reject malformed payloads with 422
- [ ] Passkey challenges are session-bound (cross-session replay fails)
- [ ] Audit log and security log endpoints return 403 for non-admin
- [ ] `grep "opc_db.json" agent_executor.py` → no match
- [ ] COOKIE_SECURE warning fires at startup unless suppressed
- [ ] All backend tests pass
- [ ] All frontend tests pass