feat(auth): password + session cookies, dual cookie/Bearer middleware (ADR-0001 Child A — refs #54)

[thinmintdev]

Summary

Wave 1 of ADR-0001 — additive FastAPI password auth + signed session cookies, alongside the existing bearer-token surface. No existing edge-auth install is broken; the Caddyfile, PUBLIC_PATHS, and --auth=basic installer flag are explicitly untouched and reserved for Child B (#56).

Parent: #54 · This issue: #55 · ADR: docs/adr/0001-collapse-edge-auth-into-fastapi.md

Does not close #54 — Children B (#56) and C (#57) must also land before #54 can close.

New endpoints (all under /api/auth)

Method	Path	Auth	Notes
POST	/login	public	Validates {username, password} and sets hal0_session cookie (HttpOnly, SameSite=Lax, Secure-when-TLS)
POST	/logout	public	Clears the cookie; 204
POST	/password	conditional	Public iff no password set (first-run claim ownership); writer scope thereafter; min length 8
GET	/status	public	Extended with password_set: bool and auth_mode: "open" | "password"
GET	/login	public	Legacy compat shim — returns a hint pointing at the POST endpoint

Middleware changes (hal0.api.middleware.auth)

• require_token grows a session-cookie path: precedence is Bearer → cookie → X-Forwarded-Email. Present-but-invalid cookies hard-fail with auth.invalid (clean re-login path).
• require_writer / require_admin enforce a CSRF tripwire when auth came via cookie and the verb mutates: either X-Requested-With: XMLHttpRequest or X-CSRF-Token matching the session cookie's first 16 chars. Bearer auth bypasses the check (per the ADR's threat model). GET/HEAD/OPTIONS are exempt (RFC 7231 §4.2.1).
• New AuthIdentity.source = "session" plus session_token field on the dataclass for the CSRF binding.
• New typed error CSRFRequired (auth.csrf_required, 403).

Storage

• TokenStore gains a top-level password_hash: str | None field. get_password_hash() / set_password_hash() round-trip through the existing atomic-write path so a single tokens.toml backup covers both surfaces.
• Session signing key generated on first use under HAL0_HOME/etc/hal0/keyring (secrets.token_urlsafe(32), atomic write, mode 0600).
• New deps in pyproject.toml: bcrypt>=4.0 (cost 12, parity with Caddy basicauth format), PyJWT>=2.8 (HS256).

Tests

tests/api/test_password_auth.py — 20 new tests, all passing. Covers:

• First-run set-password without auth
• Second set-password without auth → 401
• Second set-password with writer Bearer → 200
• Login happy path, wrong password, wrong username, login before any password set
• Cookie + X-Requested-With writer call → 200
• Cookie + X-CSRF-Token writer call → 200
• Cookie writer call without tripwire → 403 auth.csrf_required
• Cookie with garbage CSRF token → 403
• Bearer writer call without tripwire → 200 (CSRF bypass)
• Cookie reader call without tripwire → 200 (safe verbs exempt)
• Logout clears cookie; subsequent writer falls to 401
• Invalid cookie → 401 auth.invalid
• HttpOnly + SameSite=Lax always present
• Secure flag set when X-Forwarded-Proto: https
• /api/auth/status reports password_set and auth_mode correctly

Full suite still green: 856 passed, 6 skipped (no regressions on token-only auth, middleware, scope matrix, or any other existing tests).

Out of scope (hard gates per the brief)

• packaging/caddy/Caddyfile.template — Child B
• PUBLIC_PATHS frozenset — Child B
• --auth=basic installer flag — Child B
• Wizard UI — Child B
• README / PLAN / upgrade notes — Child C

CI note

Hal0ai org Actions are currently billing-blocked, so this PR's CI will fail in ~2 seconds with no logs. Verified locally with:

PYTHONPATH=<worktree>/src uv run --no-sync pytest tests/api/test_password_auth.py -v
PYTHONPATH=<worktree>/src uv run --no-sync pytest tests/

Both green. The user will admin-merge.

Test plan

• Local: pytest tests/api/test_password_auth.py — green
• Local: pytest tests/ — no regression on the existing 836 tests
• Manual: fresh install → GET /api/auth/status shows password_set: false, auth_mode: "open"
• Manual: curl -X POST /api/auth/password -d '{"password":"correcthorse"}' (no auth) succeeds once
• Manual: second POST /api/auth/password without auth → 401
• Manual: POST /api/auth/login → cookie issued, /api/auth/me returns source: "session"

🤖 Generated with Claude Code