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

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:

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:

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:

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:

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