레포 업데이트

docs/superpowers/plans/2026-04-01-headless-login-debug-improvement.md

@@ -0,0 +1,150 @@
+# 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**