",
+ status_code=403,
+ )
+ await response(scope, receive, send)
+ return
+
+ # Token validation
+ session_token = request.session.get(SESSION_KEY)
+ if not session_token:
+ logger.warning("CSRF token missing from session on %s", request.url.path)
+ response = HTMLResponse(
+ "
403 Forbidden
CSRF validation failed
",
+ status_code=403,
+ )
+ await response(scope, receive, send)
+ return
+
+ # Try header first (works for both JSON and form requests)
+ submitted_token = request.headers.get("x-csrf-token")
+
+ # Fall back to form body
+ if not submitted_token:
+ # We need to read the body for form data
+ form = await request.form()
+ submitted_token = form.get("csrf_token")
+ if isinstance(submitted_token, str):
+ pass # good
+ else:
+ submitted_token = None
+
+ if not submitted_token or not hmac.compare_digest(submitted_token, session_token):
+ logger.warning("CSRF token mismatch on %s", request.url.path)
+ response = HTMLResponse(
+ "
403 Forbidden
CSRF validation failed
",
+ status_code=403,
+ )
+ await response(scope, receive, send)
+ return
+
+ await self.app(scope, receive, send)
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `uv run python -m pytest tests/test_csrf.py -v`
+Expected: All pass
+
+**Step 5: Commit**
+
+```bash
+git add src/porchlight/csrf.py tests/test_csrf.py
+git commit -m "feat: add CSRF middleware with synchronizer token pattern"
+```
+
+---
+
+### Task 2: Wire Middleware + Session Hardening + Template Globals
+
+**Files:**
+- Modify: `src/porchlight/app.py:94-128`
+- Modify: `src/porchlight/config.py:23-62`
+- Test: `tests/test_app.py` (existing tests should still pass)
+- Test: `tests/test_config.py` (existing tests should still pass)
+
+**Step 1: Write the failing tests**
+
+Add to `tests/test_csrf.py`:
+
+```python
+class TestAppIntegration:
+ """Test CSRF middleware is wired into the real app."""
+
+ async def test_post_without_csrf_token_returns_403(self, client: AsyncClient) -> None:
+ """Any POST to a session-protected endpoint without CSRF token gets 403."""
+ resp = await client.post("/login/password", data={"username": "x", "password": "y"})
+ assert resp.status_code == 403
+
+ async def test_exempt_token_endpoint(self, client: AsyncClient) -> None:
+ """The /token endpoint is exempt from CSRF (uses client auth)."""
+ resp = await client.post("/token", data={"grant_type": "authorization_code", "code": "fake"})
+ # Should NOT be 403 — it should fail for auth reasons, not CSRF
+ assert resp.status_code != 403
+```
+
+These tests need the `client` fixture from `tests/conftest.py`.
+
+**Step 2: Run tests to verify they fail**
+
+Run: `uv run python -m pytest tests/test_csrf.py::TestAppIntegration -v`
+Expected: First test FAILS (currently returns 200 with error HTML, not 403). Second test passes trivially.
+
+**Step 3: Add config field and wire middleware**
+
+Modify `src/porchlight/config.py` — add `session_https_only` field after `session_secret`:
+
+```python
+ # Session
+ session_secret: str | None = None # If None, a random secret is generated per process
+ session_https_only: bool = True
+```
+
+Modify `src/porchlight/app.py`:
+
+1. Add import:
+```python
+from porchlight.csrf import CSRFMiddleware, generate_csrf_token
+```
+
+2. Replace session middleware block (lines 108-110) with:
+```python
+ # Session middleware
+ session_secret = settings.session_secret or secrets.token_hex(32)
+ app.add_middleware(
+ CSRFMiddleware,
+ exempt_paths={"/token", "/userinfo"},
+ check_origin=settings.issuer,
+ )
+ app.add_middleware(
+ SessionMiddleware,
+ secret_key=session_secret,
+ same_site="lax",
+ https_only=settings.session_https_only,
+ ) # type: ignore[arg-type]
+```
+
+Note: Starlette middleware order is reversed — `SessionMiddleware` is added second but runs first (outermost). CSRF runs after session is available.
+
+3. Add CSRF token to template globals (after templates creation, line 113):
+```python
+ # Templates
+ templates = Jinja2Templates(directory=str(PACKAGE_DIR / "templates"))
+
+ def csrf_token_processor(request: Request) -> str:
+ return generate_csrf_token(request)
+
+ templates.env.globals["csrf_token_processor"] = csrf_token_processor
+ app.state.templates = templates
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `uv run python -m pytest tests/test_csrf.py -v`
+Expected: All pass
+
+Run: `uv run python -m pytest tests/test_app.py tests/test_config.py -v`
+Expected: All pass (config test for `session_https_only` default)
+
+**Step 5: Commit**
+
+```bash
+git add src/porchlight/app.py src/porchlight/config.py tests/test_csrf.py
+git commit -m "feat: wire CSRF middleware and harden session cookie"
+```
+
+---
+
+### Task 3: Template Changes
+
+**Files:**
+- Modify: `src/porchlight/templates/base.html`
+- Modify: `src/porchlight/templates/login.html`
+- Modify: `src/porchlight/templates/consent.html`
+- Modify: `src/porchlight/templates/manage/credentials.html`
+- Modify: `src/porchlight/templates/manage/profile.html`
+- Modify: `src/porchlight/static/webauthn.js`
+
+**Step 1: Modify base.html**
+
+Add CSRF meta tag and htmx headers to `base.html`:
+
+```html
+
+
+
+
+
+
+ {% block title %}Porchlight{% endblock %}
+
+
+
+
+ Skip to content
+```
+
+The `hx-headers` attribute on `` makes htmx automatically include the CSRF token as a header on every htmx request. The `` tag is for vanilla JS fetch calls (webauthn.js).
+
+**Step 2: Add hidden field to login.html**
+
+In the password form (after line 12):
+
+```html
+