Phillip Tarrant
59dea99079
End-to-end passwordless admin auth. /admin/login accepts an email, POSTs
mint a 256-bit magic-link token stored only as SHA-256 in
magic_link_tokens (15-min TTL, single-use via atomic rowcount UPDATE).
Resend delivers the link; in dev with no API key, EmailService logs a
structured magic_link_dev_fallback event with the URL so the flow works
offline. /admin/auth/consume/{token} verifies, upserts a users row
(display_name from email local-part), creates a sessions row, and drops
an itsdangerous-signed cb_session cookie (HttpOnly, SameSite=Lax, Secure
in prod). /admin renders a placeholder "Welcome, <name>" page pending
Phase 4 CMS. /admin/logout flips revoked_at rather than deleting the row
to preserve the audit trail.
Rate limits use SlowAPI's in-memory limiter (5/15min/IP on login,
20/15min/IP on consume) plus a DB per-email count to catch
IP-rotating abuse. ADMIN_EMAILS enforces allowlist; non-allowlisted
submissions return the same "check your inbox" page with no token
inserted and no email sent (anti-enumeration). Every event lands in
auth_events via AuditService: link_requested, link_consumed,
consume_failed, session_created, session_revoked, rate_limited.
Add a production config validator refusing empty RESEND_API_KEY,
RESEND_FROM, or ADMIN_EMAILS; add PUBLIC_BASE_URL for email link
construction. CSRF deferred to Phase 6 per roadmap scoping; logout
handler marked # TODO(phase-6-csrf).
Mark Phase 3 complete in docs/ROADMAP.md.
Documentation Folder
This folder contains business planning, architecture decisions, and documentation.
No application code belongs here.
Contents
| Document | Purpose |
|---|---|
ROADMAP.md |
Phased build plan, data model (dataclasses), SQL schema, visual design, env-var contract |
code_guidelines.md |
Generic Python coding standards (FastAPI overrides its Flask default for this project) |
security.md |
Python security baseline (OWASP-aligned) |
MANUAL_TESTING.md (added in Phase 1) |
Manual test checklist for the public site + admin |
Related Docs (in repo root)
| Document | Purpose |
|---|---|
../CLAUDE.md |
Project instructions — stack, topology, security must-haves, git flow |
Guidelines
- Keep documents focused and concise.
- Update docs when architecture decisions change.
- Use markdown tables for structured information.
- Link to external documentation where relevant.