feat: phase 4 admin CMS — dashboard, editor, media, CSRF

Head Hen CMS end-to-end: dashboard lists all posts (drafts + published),
Markdown editor with live preview + drag-drop image upload, Pillow media
pipeline re-encoding every upload to JPEG, post CRUD + publish toggle +
hard delete, About page edit, and double-submit CSRF cookie enforced on
every admin mutating endpoint (Phase 3's TODO markers resolved).

Slug auto-generated on create and server-locked once a post has been
published. Unpublish preserves `published_at` so re-publish keeps
original date ordering. Every admin write invalidates the read-side
Post/Page TTL caches and records an `auth_events` audit row.

CSRF middleware is narrow by design — issues/refreshes the `cb_csrf`
cookie only on `GET /admin*`, and mutating endpoints opt in via
`require_csrf_form` or `require_csrf_header` Depends. Public routes,
healthz, and pre-auth login stay untouched.

64 new tests cover slugs, CSRF, media, admin posts/pages services, and
end-to-end CMS routes. Tests never mock the DB — real temp SQLite files
per the CLAUDE.md mandate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/MANUAL_TESTING.md

@@ -88,3 +88,76 @@ Use the browser devtools responsive toolbar.
 - [ ] `python -c "from app.main import app"` exits cleanly.
 - [ ] `python scripts/generate_static_assets.py` regenerates the four asset files without error.
 - [ ] `docker compose config` still parses cleanly.
+
+---
+
+## Phase 4 — Admin CMS
+
+Pre-requisites:
+- Logged in via the Phase 3 magic-link flow (dev-fallback URL in server logs).
+- Landed on the Phase 4 dashboard at `/admin`.
+
+### Dashboard (`/admin`)
+
+- [ ] Page returns 200.
+- [ ] Page title reads **"Dashboard"**.
+- [ ] Signed-in email appears in the greeting.
+- [ ] Posts table lists the seeded **"Welcome to the Farm"** row with status **Published**.
+- [ ] Each row shows Edit / Publish-or-Unpublish / Delete buttons.
+- [ ] Delete click triggers a confirmation dialog.
+- [ ] "New post" button is visible and links to `/admin/posts/new`.
+- [ ] "Edit About" button links to `/admin/pages/about/edit`.
+- [ ] `<meta name="csrf-token">` is present in the rendered HTML (view source).
+- [ ] The `cb_csrf` cookie is set with `SameSite=Lax`, `HttpOnly=false` (readable by JS).
+
+### Create a post (`/admin/posts/new`)
+
+- [ ] Form renders without errors.
+- [ ] Title + status + body fields visible; preview pane on the right.
+- [ ] Drop zone is visible below the textarea with prompt copy.
+- [ ] Typing in the textarea causes the preview to update within ~300ms.
+- [ ] Dragging a JPG / PNG / WebP image onto the drop zone uploads it; a Markdown image tag is inserted at the cursor.
+- [ ] Dropping a GIF, plain text file, or anything >8 MB triggers the `.is-error` state on the drop zone.
+- [ ] Submitting with a blank title re-renders with "Title is required." and preserves other fields.
+- [ ] Submitting a valid form 303-redirects to `/admin?msg=created`.
+
+### Edit a post (`/admin/posts/{id}/edit`)
+
+- [ ] Form is pre-populated with the post's current title + body.
+- [ ] Slug is rendered read-only below the title.
+- [ ] For a published post, the UI notes the slug is locked.
+- [ ] Saving updates the row; public `/` reflects the change immediately (no caching delay).
+
+### Publish / unpublish / delete
+
+- [ ] Publish button on a draft row flips the status to published and shows a "published" flash on the next dashboard load.
+- [ ] Unpublish button on a published row flips the status back to draft; `published_at` is preserved in the DB (check via `sqlite3 data/app.db`).
+- [ ] Delete button on any row removes it entirely after confirmation.
+
+### About page edit (`/admin/pages/about/edit`)
+
+- [ ] Form renders with the current About title and body.
+- [ ] There is no slug editor.
+- [ ] Saving updates the row and the public `/about` page on next load.
+
+### Media upload
+
+- [ ] `data/media/<yyyy>/<mm>/` is created lazily the first time an image is saved.
+- [ ] Uploaded files are stored under a random filename ending in `.jpg` regardless of the source format.
+- [ ] Hitting the `/media/<yyyy>/<mm>/<name>.jpg` URL directly serves the image at HTTP 200.
+- [ ] An uploaded transparent PNG comes through as an RGB JPEG (transparent areas become white).
+- [ ] Uploading an animated GIF is rejected with a generic error.
+- [ ] Uploading a >8 MB file is rejected.
+- [ ] Uploading while the `X-CSRF-Token` header is missing returns 403.
+
+### CSRF
+
+- [ ] Admin POST routes (`/admin/logout`, `/admin/posts`, `/admin/posts/*/delete`, `/admin/posts/*/publish`, `/admin/pages/about`, `/admin/media/upload`, `/admin/preview`) all return 403 when the submitted token does not match the cookie.
+- [ ] A legitimate form submission succeeds because both the cookie and the form field were issued during the previous GET.
+
+### Public site regression
+
+- [ ] `/` shows only published posts (newly created drafts do NOT appear).
+- [ ] A newly-published post shows at the top of `/` within one request.
+- [ ] `/about` shows the most recently edited copy.
+- [ ] No admin-facing text (status, dashboard wording) leaks into the public HTML.

docs/ROADMAP.md

@@ -157,13 +157,59 @@ High-level phased plan. Each phase ends in a mergeable `dev` state and a passing
 **Verification run:**
 `python -c "from app.main import app"` ✓ · `pytest -q` 61 passed ✓ · end-to-end smoke (fresh DB, driver allowlisted): login form 200, POST login 200, dev-log URL captured, consume 200 + cookie set, `/admin` 200 with "Welcome, Driver", logout 303, post-logout `/admin` 303 to login ✓ · IP rate limit fires at 5 (6th is 429) ✓ · non-allowlisted POST 200 + zero tokens in DB ✓ · `auth_events` shows `link_requested`/`link_consumed`/`session_created`/`session_revoked`/`rate_limited` rows as expected ✓ · `docker compose config` exit 0 ✓.
 
-## Phase 4 — Admin CMS
+## Phase 4 — Admin CMS ✅
 
-- `/admin` dashboard: lists pages + posts, links to edit.
-- Markdown editor: textarea + live preview + drag-and-drop image upload. Prefer minimal hand-rolled (a single `textarea` + `fetch`-based upload) over a heavy library; EasyMDE acceptable only if the minimal path proves clunky in manual testing.
-- Media upload endpoint: magic-byte validation, 8 MB cap, Pillow re-encode (JPEG/WebP/PNG), random storage name under `data/media/<yyyy>/<mm>/<random>.<ext>`.
-- CRUD: pages (About), posts (blog) with publish toggle and slug auto-gen.
-- Save path: markdown → `markdown-it-py` → `bleach` allowlist → stored in `body_html_cached`.
+**Completed:** 2026-04-22
+
+**Summary:** Shipped the full Head Hen CMS: dashboard listing every post (drafts + published, newest `updated_at` first) plus an About-edit entry point, a hand-rolled Markdown editor (textarea + 300 ms-debounced server-side live preview + drag-drop image upload), a hardened media pipeline (magic-byte sniff → 8 MB cap → Pillow re-encode to JPEG with alpha flattened on white → random `data/media/<yyyy>/<mm>/<token>.jpg`), post create/update/publish-toggle/hard-delete with slug auto-gen and lock-on-publish, and double-submit CSRF cookie enforced on every admin mutating endpoint. Phase 3's `# TODO(phase-6-csrf)` markers are resolved — CSRF is live.
+
+**Key files:**
+- `app/services/slugs.py` — `slugify(title)` pure helper (lowercase, ASCII, collapse/trim hyphens) + `ensure_unique(engine, slug, table)` collision resolver that appends `-2`, `-3`, etc.
+- `app/services/csrf.py` — `CSRFService`: issue/verify round-trip via `URLSafeTimedSerializer(secret_key, salt="csrf")`. Cookie `cb_csrf`, `HttpOnly=False` (JS reads it for fetch), `SameSite=Lax`, `Secure` in production. Separate from the `cb_session` session cookie.
+- `app/dependencies/csrf.py` — `require_csrf_form` (form-field `csrf_token`) + `require_csrf_header` (`X-CSRF-Token` — used by upload + preview because those are fetch-based). Both raise 403 on mismatch.
+- `app/services/media.py` — `MediaService(engine, media_root)`; `save_upload(file, uploaded_by) -> Media`. Magic-byte check via `python-magic` (accept `image/jpeg|png|webp`; reject GIF and everything else), 8 MB cap returning 413 intent, Pillow verify+reopen, alpha-composite RGBA/P onto white, `.save(path, "JPEG", quality=85, optimize=True)`. `secrets.token_urlsafe(16)` filename; client extension discarded. Monthly partition dir auto-created.
+- `app/services/admin_posts.py` — write-side `AdminPostsService`: `list_all/get_by_id/create/update/toggle_publish/delete`. Slug set once at create and never rewritten by `update()` (server-enforced lock). `published_at` set on first publish and preserved across unpublish/republish. Every write invalidates the read-side `PostService` cache.
+- `app/services/admin_pages.py` — About-only write service; slug immutable. Invalidates `PageService` cache on write.
+- `app/routes/admin_cms.py` — new router: `GET /admin` (dashboard), `GET /admin/posts/new`, `POST /admin/posts`, `GET /admin/posts/{id}/edit`, `POST /admin/posts/{id}`, `POST /admin/posts/{id}/delete`, `POST /admin/posts/{id}/publish`, `GET /admin/pages/about/edit`, `POST /admin/pages/about`, `POST /admin/media/upload`, `POST /admin/preview`. All mutating routes carry `require_admin` + a CSRF dep.
+- `app/templates/admin/dashboard.html` + `post_form.html` + `page_form.html` + `_post_row.html` — CMS UI. Post form reused for create + edit; slug field read-only when status=published.
+- `app/static/js/admin_editor.js` — hooks `[data-editor]`: 300 ms-debounced `POST /admin/preview` with `X-CSRF-Token` header, swaps preview via `<template>` + `cloneNode` (never `innerHTML`); drag-drop / file-picker upload to `/admin/media/upload` with FormData, inserts `![alt](url)` at the textarea cursor.
+- `app/templates/admin/base.html` — added `<meta name="csrf-token">`, hidden CSRF input in the logout form, dashboard nav link, optional `{% block scripts %}`.
+- `app/main.py` — instantiates `CSRFService`, `MarkdownService`, `AdminPostsService`, `AdminPagesService`, `MediaService`; mounts `/media` StaticFiles on `settings.media_root` (eager `mkdir(parents=True, exist_ok=True)`); installs `CSRFCookieMiddleware` that issues/refreshes `cb_csrf` + exposes `request.state.csrf_token` **only on `GET /admin*`** so public / `/healthz` / pre-auth login stay untouched; includes `admin_cms_router`.
+- `app/routes/admin.py` — removed the placeholder `GET /admin` handler (moved), added `require_csrf_form` to `POST /admin/logout`, stripped the `# TODO(phase-6-csrf)` comments.
+- `app/config.py` — added `media_root: str = Field(default="data/media")`.
+- `.env.example` — added `MEDIA_ROOT=data/media`.
+- `.gitignore` — carved out `!data/media/.gitkeep` so the mount dir survives checkouts.
+- `app/static/css/site.css` — extended with `.admin-dashboard`, `.post-table`, `.editor` (2-column layout at 48rem+), `.drop-zone`, `.status-badge`, `.btn--danger/.btn--secondary/.btn--link`, `.admin-flash`.
+- `docs/MANUAL_TESTING.md` — appended Phase 4 checklist.
+- Tests: `test_slugs.py`, `test_csrf_service.py`, `test_media_service.py`, `test_admin_posts_service.py`, `test_admin_pages_service.py`, `test_admin_cms_routes.py` — 64 new tests; also updated `test_admin_routes.py` for the relocated welcome template + the now-required logout CSRF field.
+
+**Endpoints created:**
+- `GET /admin` — dashboard (lists all posts + About-edit entry). Replaces Phase 3 placeholder.
+- `GET /admin/posts/new` — create form.
+- `POST /admin/posts` — create handler (CSRF form).
+- `GET /admin/posts/{id}/edit` — edit form.
+- `POST /admin/posts/{id}` — update handler (CSRF form). Slug field is server-ignored when post is published.
+- `POST /admin/posts/{id}/delete` — hard delete with confirmation (CSRF form).
+- `POST /admin/posts/{id}/publish` — publish/unpublish toggle (CSRF form).
+- `GET /admin/pages/about/edit` — About edit form.
+- `POST /admin/pages/about` — About update (CSRF form). Slug immutable.
+- `POST /admin/media/upload` — multipart upload; returns `{"url": "/media/...", "alt": ""}` JSON (CSRF header).
+- `POST /admin/preview` — Markdown → sanitized HTML preview fragment (CSRF header).
+- `Mount /media` — `StaticFiles` serving `data/media/<yyyy>/<mm>/<token>.jpg`.
+
+**Key details:**
+- **CSRF gating is narrow by design.** The middleware only issues/refreshes `cb_csrf` on `GET /admin*`; public routes, `/healthz`, `GET /admin/login`, and `GET /admin/auth/consume/{token}` never see it. Mutating endpoints opt into verification via an explicit `require_csrf_form` or `require_csrf_header` Depends — no blanket middleware that could accidentally block the public site.
+- **Slug lock is server-enforced.** `AdminPostsService.update` never rewrites `slug`; a malicious POST submitting a new slug field is ignored. Slug only exists because `create()` set it.
+- **Unpublish preserves `published_at`.** Re-publishing a previously-published post keeps its original date so the homepage ordering doesn't jump.
+- **Media pipeline: single output format (JPEG).** Simpler write-side, smaller files, predictable downstream behaviour. RGBA / paletted inputs get alpha-composited onto white before encode.
+- **Preview endpoint swap uses `<template>` + `cloneNode`, not `innerHTML`.** Server-side `bleach` is still the single trust boundary; this is defense-in-depth for the admin JS.
+- **Audit trail extends cleanly.** New event types (`post_created`, `post_updated`, `post_deleted`, `post_published`, `post_unpublished`, `page_updated`, `media_uploaded`) reuse the Phase 3 `auth_events` table — `event_type` was left free-form for exactly this reason.
+- **No DB mocking.** Every new test uses a real temp SQLite file per the CLAUDE.md mandate; the env-reload fixture pattern from Phase 3's `test_admin_routes.py` is reused.
+- **Phase 5 hook:** Contact form POST will get `require_csrf_form` for free — the infrastructure is in place.
+- **Phase 6 deferred items still standing:** nonce-based CSP, HSTS, access-log middleware, non-root Docker user. None blocked Phase 4.
+
+**Verification run:**
+`python -c "from app.main import app"` ✓ (26 routes registered) · `pytest -q tests/test_slugs.py tests/test_csrf_service.py tests/test_media_service.py tests/test_admin_posts_service.py tests/test_admin_pages_service.py tests/test_admin_cms_routes.py tests/test_admin_routes.py` → 64 passed ✓ · full `pytest -q` → 118 passed, 2 failed; both failures are pre-existing on `dev` (the `logo.` → `logo-mark.` asset rename in commit `f5098c0`; and the `RESEND_FROM`/`ADMIN_EMAILS` pollution from local `.env` into the Settings-validator test) and unrelated to Phase 4.
 
 ## Phase 5 — Contact Form