# Headless Login Debug Improvement Implementation Plan

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

**Goal:** Make headless password login failures return safe reason-specific response codes and produce debug-only diagnostic logs.

**Architecture:** Keep the change local to `AuthHandler` by introducing a headless-password-specific error classification helper and reusing it across response mapping and structured logging. Preserve current success-path behavior while adding explicit tests for reason codes and debug-field gating.

**Tech Stack:** Go, Fiber, `log/slog`, `stretchr/testify`, `go-jose`

---

### Task 1: Add failing response-classification tests

**Files:**
- Modify: `backend/internal/handler/auth_handler_login_test.go`
- Reference: `backend/internal/handler/auth_handler.go`

- [ ] **Step 1: Write failing tests for classified 401 responses**

Add tests for:

- audience mismatch -> `code=invalid_client_assertion_audience`
- signature mismatch -> `code=invalid_client_assertion_signature`
- iss/sub mismatch -> `code=invalid_client_assertion_iss_sub`
- expired assertion -> `code=invalid_client_assertion_expired`
- invalid credentials -> `code=password_or_email_mismatch`

- [ ] **Step 2: Run only the new response tests and verify they fail for the expected reason**

Run:

```bash
cd backend && go test ./internal/handler -run 'TestHeadlessPasswordLogin_(AudienceMismatchReturnsDetailedCode|SignatureMismatchReturnsDetailedCode|IssSubMismatchReturnsDetailedCode|ExpiredAssertionReturnsDetailedCode)|TestPasswordLogin_InvalidCredentials_ReturnsCode' -v
```

Expected:

- new headless response tests fail because the handler still returns generic codes/messages
- existing invalid-credentials test remains green unless intentionally updated

### Task 2: Add failing log-gating tests

**Files:**
- Modify: `backend/internal/handler/auth_handler_login_test.go`
- Reference: `backend/internal/logger/logger.go`

- [ ] **Step 1: Write tests for debug-only diagnostic logging**

Add tests that install a temporary `slog` handler backed by a buffer and assert:

- debug logger emits `expected_audiences` and `received_audiences`
- info logger does not emit those debug-only fields

- [ ] **Step 2: Run only the new log tests and verify they fail**

Run:

```bash
cd backend && go test ./internal/handler -run 'TestHeadlessPasswordLogin_(DebugLogIncludesDiagnostics|InfoLogOmitsDebugDiagnostics)' -v
```

Expected:

- tests fail because the current handler does not emit reason-specific structured logs yet

### Task 3: Implement classified headless assertion failures

**Files:**
- Modify: `backend/internal/handler/auth_handler.go`

- [ ] **Step 1: Add a local classified error type and helpers**

Implement a small helper shape for:

- `status`
- `code`
- `safeMessage`
- `logMessage`
- `debugAttrs`

- [ ] **Step 2: Make claim validation return classified reasons**

Replace generic string errors from `validateHeadlessClientAssertionClaims` with typed/classified failures for:

- iss/sub mismatch
- expired
- not active yet
- iat in future
- audience mismatch

- [ ] **Step 3: Make assertion verification return signature/jwks-specific failures**

Ensure parse, jwks load, claims, and signature-verification paths map to distinct safe codes/messages.

### Task 4: Implement structured logging and handler integration

**Files:**
- Modify: `backend/internal/handler/auth_handler.go`

- [ ] **Step 1: Add a helper to detect whether debug logging is enabled**

Use the default `slog` logger handler to gate diagnostic fields without changing global logger initialization.

- [ ] **Step 2: Log classified assertion failures in `HeadlessPasswordLogin`**

Log:

- reason code
- client id
- path
- debug-only attrs when debug logging is enabled

- [ ] **Step 3: Log classified credential failures**

Keep response behavior safe while adding a structured log line for credential mismatch.

### Task 5: Verify and document

**Files:**
- Modify: `docs/test-plan/backend-test-inventory.md` if headless password login inventory needs expansion
- Modify: issue `#502` comment with failing-test evidence and implementation summary

- [ ] **Step 1: Run focused handler tests**

Run:

```bash
cd backend && go test ./internal/handler -run 'TestHeadlessPasswordLogin_|TestPasswordLogin_InvalidCredentials_ReturnsCode' -v
```

Expected:

- all targeted tests pass

- [ ] **Step 2: Run broader backend handler regression tests if practical**

Run:

```bash
cd backend && go test ./internal/handler -v
```

Expected:

- no regressions in auth handler tests

- [ ] **Step 3: Update issue `#502` with what failed first, what changed, and what passed**

- [ ] **Step 4: Review whether `docs/test-plan/backend-test-inventory.md` or troubleshooting docs should be updated**