🔒 fix(ci): add tofu_module_reader SSH key to vault.yaml secrets (mirrors erp pattern) (#100)

Co-authored-by: Gabriel Radureau <arcodange@gmail.com>
Co-committed-by: Gabriel Radureau <arcodange@gmail.com>

.gitea/workflows/docker-push.yaml

@@ -6,7 +6,6 @@
 name: Docker Push
 
 on:
-  # Manual trigger for testing or production
   workflow_dispatch:
     inputs:
       ref:
@@ -14,6 +13,18 @@ on:
         required: false
         type: string
         default: ''
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - 'README.md'
+      - 'AGENTS.md'
+      - 'CHANGELOG.md'
+      - 'AGENT_CHANGELOG.md'
+      - 'documentation/**'
+      - 'adr/**'
+      - 'chart/**'
+      - 'features/**'
 
 # Environment variables
 env:

.gitea/workflows/vault.yaml

@@ -0,0 +1,60 @@
+---
+name: Hashicorp Vault
+
+on:
+  workflow_dispatch: {}
+  push: &vaultPaths
+    paths:
+      - 'iac/*.tf'
+  pull_request: *vaultPaths
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+.vault_step: &vault_step
+  name: read vault secret
+  uses: https://gitea.arcodange.lab/arcodange-org/vault-action.git@main
+  id: vault-secrets
+  with:
+    url: https://vault.arcodange.lab
+    caCertificate: ${{ secrets.HOMELAB_CA_CERT }}
+    jwtGiteaOIDC: ${{ needs.gitea_vault_auth.outputs.gitea_vault_jwt }}
+    role: gitea_cicd_dance-lessons-coach
+    method: jwt
+    path: gitea_jwt
+    secrets: |
+        kvv1/google/credentials credentials | GOOGLE_BACKEND_CREDENTIALS ;
+        kvv1/gitea/tofu_module_reader ssh_private_key | TERRAFORM_SSH_KEY ;
+
+jobs:
+  gitea_vault_auth:
+    name: Auth with gitea for vault
+    runs-on: ubuntu-latest-ca
+    outputs:
+      gitea_vault_jwt: ${{steps.gitea_vault_jwt.outputs.id_token}}
+    steps:
+      - name: Auth with gitea for vault
+        id: gitea_vault_jwt
+        run: |
+          echo -n "${{ secrets.vault_oauth__sh_b64 }}" | base64 -d | bash
+
+  tofu:
+    name: Tofu - Vault
+    needs:
+      - gitea_vault_auth
+    runs-on: ubuntu-latest-ca
+    env:
+      OPENTOFU_VERSION: 1.8.2
+      TERRAFORM_VAULT_AUTH_JWT: ${{ needs.gitea_vault_auth.outputs.gitea_vault_jwt }}
+      VAULT_CACERT: "${{ github.workspace }}/homelab.pem"
+    steps:
+      - *vault_step
+      - uses: actions/checkout@v4
+      - name: prepare vault self signed cert
+        run: echo -n "${{ secrets.HOMELAB_CA_CERT }}" | base64 -d > $VAULT_CACERT
+      - name: terraform apply
+        uses: dflook/terraform-apply@v1
+        with:
+          path: iac
+          auto_approve: true

AGENTS.md

@@ -11,6 +11,9 @@ AI agent reference for developing, testing, and operating the dance-lessons-coac
 | Logging | Zerolog | v1.35.0 |
 | Configuration | Viper | v1.21.0 |
 | Telemetry | OpenTelemetry | v1.43.0 |
+| Database | PostgreSQL + GORM | (optional, for user persistence) |
+| Auth | JWT + bcrypt | with rotating secrets |
+| Email | SMTP (Mailpit dev) | for magic-link delivery |
 
 ## Project Structure
 
@@ -21,11 +24,14 @@ dance-lessons-coach/
 │   ├── greet/              # CLI application
 │   └── server/             # Web server entry point
 ├── pkg/
+│   ├── auth/               # Auth context keys, OIDC client, helpers
 │   ├── config/             # Viper-based configuration
+│   ├── email/              # SMTP sender abstraction
 │   ├── greet/              # Core domain logic + API handlers
 │   ├── server/             # HTTP server, routing, graceful shutdown
 │   ├── telemetry/          # OpenTelemetry instrumentation
 │   ├── user/               # User domain (auth, JWT, repository)
+│   ├── user/api/           # Auth + admin HTTP handlers
 │   └── validation/         # Request validation
 ├── scripts/                # Server lifecycle, build, test scripts
 ├── config.yaml             # Configuration file
@@ -80,20 +86,35 @@ logging:
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/health` | Liveness — always `{"status":"healthy"}` |
+| GET | `/api/healthz` | Alternative liveness probe (k8s convention) |
 | GET | `/api/ready` | Readiness — 200 when ready, 503 during shutdown |
+| GET | `/api/info` | Composite info endpoint (cf. ADR-0026) |
 | GET | `/api/version` | Version info (`?format=plain\|full\|json`) |
 | GET | `/api/v1/greet/` | Default greeting |
 | GET | `/api/v1/greet/{name}` | Personalized greeting |
+| POST | `/api/v1/auth/login` | Username + password login (JWT) |
+| POST | `/api/v1/auth/register` | Account creation |
+| POST | `/api/v1/auth/validate` | JWT validation |
+| POST | `/api/v1/auth/password-reset/request` | Request a password reset |
+| POST | `/api/v1/auth/password-reset/complete` | Complete a password reset |
+| POST | `/api/v1/auth/magic-link/request` | Passwordless : request a magic link by email |
+| GET  | `/api/v1/auth/magic-link/consume` | Passwordless : consume a magic-link token |
+| GET  | `/api/v1/auth/oidc/{provider}/start` | OIDC : begin authorization (PKCE) |
+| GET  | `/api/v1/auth/oidc/{provider}/callback` | OIDC : authorization code → JWT |
+| GET  | `/api/v1/admin/jwt/secrets` | Admin : list JWT signing secrets |
+| POST | `/api/v1/admin/jwt/secrets` | Admin : add a JWT signing secret |
+| POST | `/api/v1/admin/jwt/secrets/rotate` | Admin : rotate the active JWT secret |
 | POST | `/api/v2/greet` | V2 greeting with validation (feature-flagged) |
+| POST | `/api/admin/cache/flush` | Admin : flush in-memory caches |
 | GET | `/swagger/` | Swagger UI |
-| GET | `/swagger/doc.json` | OpenAPI spec |
+| GET | `/swagger/doc.json` | OpenAPI spec (source of truth) |
 
 ```bash
 curl http://localhost:8080/api/health
-curl http://localhost:8080/api/ready
 curl http://localhost:8080/api/v1/greet/Alice
-curl -X POST http://localhost:8080/api/v2/greet \
-  -H "Content-Type: application/json" -d '{"name":"Alice"}'
+
+# See `/swagger/` for the full interactive list of endpoints.
+# The OpenAPI spec at `/swagger/doc.json` is the source of truth.
 ```
 
 ## Testing
@@ -151,19 +172,9 @@ docker run -d --name jaeger \
 
 ## Architecture Decision Records
 
-| ADR | Decision |
-|-----|----------|
-| [0001](adr/0001-go-1.26.1-standard.md) | Go 1.26.1 |
-| [0002](adr/0002-chi-router.md) | Chi router |
-| [0003](adr/0003-zerolog-logging.md) | Zerolog |
-| [0004](adr/0004-interface-based-design.md) | Interface-based design |
-| [0005](adr/0005-graceful-shutdown.md) | Graceful shutdown |
-| [0006](adr/0006-configuration-management.md) | Viper configuration |
-| [0007](adr/0007-opentelemetry-integration.md) | OpenTelemetry |
-| [0008](adr/0008-bdd-testing.md) | BDD with Godog |
-| [0009](adr/0009-hybrid-testing-approach.md) | Hybrid testing strategy |
+The full index is at [adr/README.md](adr/README.md) — 30 ADRs covering Go version, Chi router, Zerolog, OpenTelemetry, BDD testing, JWT auth, PostgreSQL, OIDC migration, email infrastructure, etc.
 
-Add a new ADR: copy an existing file, edit it, update `adr/README.md`.
+Add a new ADR : copy an existing file in `adr/`, edit it, update `adr/README.md`.
 
 ## Commit Conventions
 

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- ✨ `GET /api/v1/uptime` endpoint (PR #67) — returns server start_time and uptime_seconds
+- 📝 mkcert local HTTPS doc + Makefile `cert` target (PR #68) — prep for ADR-0028 Phase B OIDC callbacks
+- ✨ `pkg/auth/` skeleton for OpenID Connect (PR #69) — types + client surface, handlers come later (Phase B.3+)
+- 📝 ADR-0028 Phase B roadmap document (PR #71) — outlines remaining B.3 / B.4 / B.5 work
+- ✨ `pkg/auth/` OIDC client implementation : Discover, RefreshJWKS, ExchangeCode, ValidateIDToken (PR #74) — completes ADR-0028 Phase B.3
+- ✨ OIDC HTTP handlers : `/api/v1/auth/oidc/{provider}/start` and `/callback` with PKCE + sign-up-on-first-use (PR #75) — completes ADR-0028 Phase B.4
+- 🧪 OIDC handler unit tests covering start/callback rejection paths and PKCE redirect (PR #76)
+- 📝 `documentation/AUTH.md` synthesis covering Phase A + B current state (PR #73)
+- 📝 `documentation/MISTRAL-AUTONOMOUS-PATTERN.md` contributor guide for the Mistral autonomous pattern that ships PRs (PR #78)
+- 📝 PHASE_B_ROADMAP marks B.3 + B.4 done (PR #80)
+- 📝 documentation/2026-05-05-AUTONOMOUS-SESSION-RECAP.md captures the day's 24 Mistral autonomous PRs (PR #81)
+- 📝 README link to Mistral autonomous pattern doc (PR #83)
+- 📝 documentation/STATUS.md project snapshot for onboarding (PR #85)
+- 📝 documentation guides cherry-picked from PR #17 : CLI.md, CODE_EXAMPLES.md, HISTORY.md, OBSERVABILITY.md, ROADMAP.md, TROUBLESHOOTING.md (PR #87)
+- 🔒 redact JWT tokens and HMAC secrets in trace logs of pkg/user/auth_service.go via sha256 fingerprints (PR #88)
+- ✨ Dockerfile (root) + Helm chart for k3s homelab deployment, degraded mode without DB/SMTP/Vault (PR #89)
+- ♻️ move UserContextKey + GetAuthenticatedUserFromContext from pkg/greet to pkg/auth (PR #90)
+- ♻️ split AuthMiddleware into OptionalHandler + RequiredHandler with RFC 6750 challenge headers, narrow tokenValidator interface, case-insensitive Bearer (PR #91)
+- 🧪 unit tests for AuthMiddleware Optional/Required handlers + extractBearerToken edge cases (PR #92)
+- 📝 refresh AGENTS.md and README.md to reflect auth endpoints (magic-link, OIDC, JWT admin), pkg/auth, pkg/email, pkg/user/api packages, and 30-ADR index. Endpoints listing decision : curated short list + pointer to swagger as source of truth (PR #93)
+- 🤖 auto-build Docker image on push to main (paths-ignore for docs) + fix root Dockerfile swag init step (PR #94)
+
+## [0.1.0] - 2026-05-05
+
+### Added
+
+- Magic-link passwordless authentication (ADR-0028 Phases A.1 through A.5, PRs #59-#63)
+- OIDC provider config skeleton (ADR-0028 Phase B.1 prep, PR #64)
+- Magic-link expired-token cleanup loop (PR #65)
+- Mailpit local SMTP infrastructure (ADR-0029)
+- BDD parallel email assertion strategy (ADR-0030)

Dockerfile

@@ -0,0 +1,43 @@
+# Build dance-lessons-coach Docker image
+FROM golang:1.26-alpine AS builder
+
+# Install git (required for go mod download)
+RUN apk add --no-cache git
+
+# Set working directory
+WORKDIR /app
+
+# Copy go module files and download dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy entire source code
+COPY . .
+
+# Generate Swagger documentation if not already present
+# (pkg/server/docs/ is gitignored ; the binary //go:embed depends on it)
+RUN if [ ! -f pkg/server/docs/swagger.json ]; then \
+      go install github.com/swaggo/swag/cmd/swag@latest && \
+      cd pkg/server && go generate ; \
+    fi
+
+# Build the server binary
+RUN go build -o app ./cmd/server
+
+# Final lightweight stage
+FROM alpine:latest
+
+# Install CA certificates for HTTPS
+RUN apk --no-cache add ca-certificates
+
+# Set working directory
+WORKDIR /root/
+
+# Copy binary from builder stage
+COPY --from=builder /app/app .
+
+# Expose port 8080
+EXPOSE 8080
+
+# Start the server
+CMD ["./app"]

Makefile

@@ -0,0 +1,24 @@
+# dance-lessons-coach Makefile — minimal targets for local development.
+# This is a starter Makefile ; expand as needed (build, test, run, etc.).
+# Existing build/test workflows live in scripts/ and remain authoritative.
+
+CERT_DIR := ./certs
+
+.PHONY: help cert clean-cert
+
+help:
+	@echo "Available targets:"
+	@echo "  cert        Generate local-dev TLS certs via mkcert (cf. documentation/MKCERT.md)"
+	@echo "  clean-cert  Remove generated TLS certs"
+	@echo "  help        Show this help"
+
+cert: $(CERT_DIR)
+	@command -v mkcert >/dev/null 2>&1 || { echo >&2 "mkcert not found. See documentation/MKCERT.md to install."; exit 1; }
+	mkcert -cert-file $(CERT_DIR)/dev-cert.pem -key-file $(CERT_DIR)/dev-key.pem localhost 127.0.0.1 ::1
+	@echo "Certs ready at $(CERT_DIR)/. Cf. documentation/MKCERT.md for usage."
+
+$(CERT_DIR):
+	mkdir -p $(CERT_DIR)
+
+clean-cert:
+	rm -rf $(CERT_DIR)

README.md

@@ -17,9 +17,13 @@ Go web service demonstrating idiomatic package structure, versioned JSON API, an
 - Viper configuration (file + env vars)
 - Readiness endpoint for Kubernetes / service mesh
 - OpenTelemetry / Jaeger distributed tracing
-- OpenAPI / Swagger UI (embedded in binary)
-- PostgreSQL user service with JWT auth
-- BDD + unit tests
+- OpenAPI / Swagger UI (embedded in binary, source of truth at `/swagger/doc.json`)
+- Username + password authentication with JWT (rotating secrets)
+- Passwordless magic-link authentication (email-delivered, ADR-0028 Phase A)
+- OIDC authentication with PKCE (multi-provider, ADR-0028 Phase B)
+- PostgreSQL user persistence with GORM
+- BDD + unit tests (Godog)
+- Mistral autonomous PR pattern (cf. [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](documentation/MISTRAL-AUTONOMOUS-PATTERN.md))
 
 ## Quick Start
 
@@ -62,16 +66,21 @@ See `config.example.yaml` for a full template.
 
 ## API
 
+The full interactive list is in the Swagger UI at `/swagger/` (source of truth at `/swagger/doc.json`). Most-used endpoints :
+
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/health` | Liveness check |
 | GET | `/api/ready` | Readiness check (503 during shutdown) |
-| GET | `/api/version` | Version info (`?format=plain\|full\|json`) |
-| GET | `/api/v1/greet/` | Default greeting |
+| GET | `/api/version` | Version info |
 | GET | `/api/v1/greet/{name}` | Named greeting |
-| POST | `/api/v2/greet` | V2 greeting with validation |
+| POST | `/api/v1/auth/login` | Login (JWT) |
+| POST | `/api/v1/auth/magic-link/request` | Passwordless magic-link |
+| GET | `/api/v1/auth/oidc/{provider}/start` | OIDC login |
 | GET | `/swagger/` | Swagger UI |
 
+This decision is intentional : the markdown table drifts ; swagger.json doesn't (it's regenerated from `swag` annotations on every build). Curated short list here for discovery, swagger for completeness.
+
 ## Testing
 
 ```bash

adr/0028-passwordless-auth-migration.md

@@ -0,0 +1,147 @@
+# 28. Passwordless authentication: magic link → OpenID Connect
+
+**Date:** 2026-05-05
+**Status:** Proposed
+**Authors:** Gabriel Radureau, AI Agent
+
+## Context and Problem Statement
+
+ADR-0018 (now Implemented) shipped a username + password authentication system with bcrypt hashing, JWT tokens, admin master password, and admin-assisted password reset. It works, but it carries the cost-of-passwords : we store password hashes, support password reset flows, and maintain a credential-rotation policy. Users hate passwords ; ops and security pay for them.
+
+Two industry-standard alternatives exist :
+1. **Magic link by email** — user enters their email, receives a one-time token in a clickable link, link consumes the token and issues a session JWT. No password stored.
+2. **OpenID Connect Authorization Code flow** — delegate authentication to an external Identity Provider (e.g. Authelia, Keycloak, Auth0, Google) ; our app receives an `id_token` after the OIDC dance.
+
+We want to **migrate to passwordless** for new sign-ups while keeping the existing username/password code path operational during the transition (no flag-day breakage). The two passwordless mechanisms above complement each other : magic link is simpler for first-party users on day 1 ; OIDC is the right answer for second-party users (other ARCODANGE products, partner integrations) and for admin SSO.
+
+A third constraint : ARCODANGE local development must use HTTPS for OAuth callbacks to be valid (most OIDC providers reject `http://localhost` redirect URIs in their default config). `mkcert` is the canonical local-CA tool for this.
+
+## Decision Drivers
+
+* **Reduce password-related attack surface** — no hash storage, no breach-and-reuse risk, no password reset abuse vectors
+* **User experience** — passwordless is faster for the user (1 click in email vs typing/remembering password)
+* **Operational simplicity** — no password reset flow to maintain ; the password-reset code can be removed once migration is complete
+* **Multi-product readiness** — OIDC is the prerequisite for cross-product SSO across the ARCODANGE portfolio
+* **Backwards compatibility** — must not break existing tokens or BDD scenarios mid-migration
+* **Local dev parity** — HTTPS in dev so OAuth flows can be tested locally without provider-specific workarounds
+
+## Considered Options
+
+### Option 1 (Chosen): Sequenced — magic link first, OIDC second
+
+Deliver in two phases :
+
+* **Phase A — Magic link**
+  - Add `POST /api/v1/auth/magic-link/request` (body: `{email}`) — generates token, stores it (TTL ~15 min), sends email via SMTP
+  - Add `GET /api/v1/auth/magic-link/consume?token=<...>` — single-use consumption, issues a JWT, returns it as cookie + JSON body
+  - Reuse the existing JWT issuance + secret retention infrastructure (ADR-0021)
+  - Existing `/api/v1/auth/login` (username/password) stays operational during transition
+
+* **Phase B — OpenID Connect Authorization Code with PKCE**
+  - Add `GET /api/v1/auth/oidc/start` — generates state + PKCE verifier, redirects to provider's `authorization_endpoint`
+  - Add `GET /api/v1/auth/oidc/callback` — exchanges code for tokens, validates `id_token` signature against provider's JWKS, issues internal JWT
+  - Provider URL configurable per environment (`auth.oidc.issuer_url`, `auth.oidc.client_id`, `auth.oidc.client_secret`)
+  - Allow multiple providers in config (key by provider name, e.g. `arcodange-sso`)
+  - Local dev requires HTTPS — `mkcert` setup documented in `documentation/DEV_SETUP.md`
+
+* **Phase C (later, separate ADR) — Decommission password auth**
+  - Once all users have migrated, remove the password endpoints, remove the password_hash column, mark ADR-0018 as Superseded by this ADR
+
+### Option 2: All-at-once OIDC, no magic link
+
+Skip magic link, jump straight to OIDC.
+
+* Good — single migration, no intermediate state
+* Bad — requires an OIDC provider operational on day 1, which we don't have configured
+* Bad — magic link has zero infra dependencies (just SMTP) ; OIDC requires running an IdP or paying for one
+
+### Option 3: Magic link only, no OIDC
+
+Stop at Phase A.
+
+* Good — simplest implementation
+* Bad — doesn't solve cross-product SSO ; we'd re-do this work later for the broader ARCODANGE portfolio
+
+### Option 4: Status quo (do nothing)
+
+Keep username + password.
+
+* Good — zero effort
+* Bad — passwords stay forever ; ARCODANGE locks itself out of integration scenarios that expect OIDC
+
+## Decision Outcome
+
+Chosen option : **Option 1, sequenced magic link → OIDC**.
+
+Rationale :
+- Magic link is implementable today with zero infra dependencies beyond the email infrastructure (ADR-0029)
+- OIDC requires running an IdP locally (Authelia or Keycloak) — that's another container in the dev stack and another ADR's worth of decision work, but the magic-link work is the natural prerequisite (token-by-email plumbing is reused)
+- Sequenced delivery means we never have to roll back : Phase A works alone, Phase B layers on top, Phase C cleans up
+
+## Implementation Plan
+
+### Phase A — Magic link (target: 2-3 PRs)
+
+1. **A.1 — Storage** : add a `magic_link_tokens` table (id, email, token_hash, expires_at, consumed_at). Repository pattern alongside `pkg/user/postgres_repository.go`.
+2. **A.2 — Token endpoint** : `POST /api/v1/auth/magic-link/request` generates a token, stores it (hashed), enqueues an email send. Rate-limited (cf. ADR-0022) by email address.
+3. **A.3 — Consume endpoint** : `GET /api/v1/auth/magic-link/consume?token=...` validates + marks consumed + issues JWT. Returns `Set-Cookie` and `{token: jwt}` body.
+4. **A.4 — Sign-up via magic link** : if the email is unknown, the consume endpoint creates the user record. (No separate "sign-up" flow needed — first magic link IS the sign-up.)
+5. **A.5 — BDD coverage** : scenarios for happy path, expired token, double-consume, wrong-email, rate-limit. Cf. ADR-0030 for the email assertion strategy.
+
+### Phase B — OIDC Code flow with PKCE (target: 3-4 PRs)
+
+1. **B.1 — Local IdP** : choose Authelia or Keycloak for local development. Add to `docker-compose.yml` with default test configuration.
+2. **B.2 — mkcert** : document local HTTPS setup in `documentation/DEV_SETUP.md`, add `make cert` target.
+3. **B.3 — OIDC client** : `pkg/auth/oidc.go` — discovery, JWKS cache, code exchange with PKCE.
+4. **B.4 — Endpoints** : `/oidc/start` and `/oidc/callback`.
+5. **B.5 — Provider config** : `auth.oidc.providers` map in config (cf. ADR-0006 Viper) ; multi-provider supported.
+6. **B.6 — BDD coverage** : end-to-end scenarios using a mock OIDC server (or the local Authelia instance with deterministic users).
+
+### Phase C — Decommission password (separate ADR after A+B in production)
+
+Out of scope for this ADR. Will be ADR-NNNN when migration is complete.
+
+## Pros and Cons of the Options
+
+### Option 1 (Chosen — Sequenced)
+
+* Good — incremental, no flag day, each phase shippable on its own
+* Good — reuses existing JWT infrastructure (ADR-0021 secret retention)
+* Good — magic link work is a prerequisite for OIDC anyway (email plumbing, mkcert)
+* Bad — total work spans 2 sprints, longer time-to-OIDC than Option 2
+* Mitigation: after Phase A, the team can stop if priorities shift — magic link alone is a complete improvement
+
+### Option 2 (All OIDC)
+
+* Good — single migration
+* Bad — requires IdP operational from day 1
+* Bad — local dev environment more complex than necessary for the magic link case
+
+### Option 3 (Magic link only)
+
+* Good — minimal scope
+* Bad — re-work later for SSO
+
+### Option 4 (Status quo)
+
+* Good — zero effort
+* Bad — accumulating tech debt
+
+## Consequences
+
+* `pkg/auth/` package created (currently auth code lives in `pkg/user/`) — separation is now justified by the multi-mechanism scope
+* `pkg/user/api/auth_handler.go` continues to serve username/password during transition (Phase A and B), removed in Phase C
+* `documentation/DEV_SETUP.md` becomes a load-bearing doc for new contributors (mkcert + docker-compose with mailpit + Authelia)
+* The 4 new endpoints (`magic-link/request`, `magic-link/consume`, `oidc/start`, `oidc/callback`) require their own ADR entries in the API doc + Swagger annotations
+* Phase A's magic link plumbing depends on **ADR-0029** (email infrastructure decision) — that ADR ships first
+* BDD scenarios for Phase A depend on **ADR-0030** (email testing strategy with parallel BDD) — that ADR ships before any Phase A scenario lands
+
+## Links
+
+* Email infrastructure : [ADR-0029](0029-email-infrastructure-mailpit.md)
+* BDD email testing strategy : [ADR-0030](0030-bdd-email-parallel-strategy.md)
+* Existing user auth (to be partially superseded by Phase C) : [ADR-0018](0018-user-management-auth-system.md)
+* JWT secret retention reused : [ADR-0021](0021-jwt-secret-retention-policy.md)
+* Rate limiting reused : [ADR-0022](0022-rate-limiting-cache-strategy.md)
+* OAuth 2.0 Authorization Code with PKCE : [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
+* OpenID Connect Core : [OpenID Foundation](https://openid.net/specs/openid-connect-core-1_0.html)

adr/0029-email-infrastructure-mailpit.md

@@ -0,0 +1,142 @@
+# 29. Email infrastructure: Mailpit local + production deferred
+
+**Date:** 2026-05-05
+**Status:** Proposed
+**Authors:** Gabriel Radureau, AI Agent
+
+## Context and Problem Statement
+
+ADR-0028 (passwordless auth) requires the application to send emails — magic-link tokens specifically. Email is a substrate decision : the choice of SMTP provider, the abstraction in code, and the local development experience all depend on it.
+
+Two separate concerns :
+
+1. **Local development + BDD tests** : we need a local SMTP receiver that captures emails and exposes them for inspection. Real email providers (Gmail, SES, SendGrid) are unsuitable for local dev — they cost money, leak test data, and rate-limit aggressively.
+2. **Production** : the application needs to actually deliver mail to user inboxes. This decision is deferred — see "Out of scope" below.
+
+ARCODANGE already has the **Mailpit** docker image pulled locally (`axllent/mailpit:latest`, 51 MB). Mailpit captures SMTP submissions on a port, stores them in-memory, exposes them via HTTP UI (default :8025) and an HTTP API (`/api/v1/messages`). It's the de-facto choice for Go projects needing local SMTP capture.
+
+The application code needs to be **provider-agnostic** : a `pkg/email` package with a `Sender` interface, a Mailpit-compatible SMTP implementation, and a contract that production can swap for a real provider's adapter without changing call sites.
+
+## Decision Drivers
+
+* **Local dev and CI must work without internet** — emails should never leave the docker network in tests
+* **Test inspection must be programmatic** — BDD tests assert on email content, not just "an email was sent"
+* **Production decision deferred** — we don't know the volume / SLA / compliance requirements yet ; over-committing now is premature
+* **Provider portability** — `pkg/email` interface lets us swap implementations without touching auth code
+* **Cost** — Mailpit is free, runs in a container, no API quota concerns
+
+## Considered Options
+
+### Option 1 (Chosen): Mailpit for local + tests, production via a production-grade provider TBD
+
+* Add Mailpit to `docker-compose.yml` (SMTP :1025, HTTP API :8025)
+* `pkg/email` package with a `Sender` interface
+* Default implementation : `SMTPSender` configured against the local Mailpit in dev/CI
+* Tests query Mailpit's HTTP API to inspect captured messages
+* Production deployment will add a separate `pkg/email/<provider>_sender.go` implementing the same interface — that decision is its own ADR
+
+### Option 2: MailHog instead of Mailpit
+
+MailHog is the older, well-known alternative. Mailpit is its modern successor, written in Go, with a richer API and active maintenance.
+
+* Bad — abandoned upstream (last commit 2020). Mailpit is the natural replacement.
+
+### Option 3: In-process mock email sender
+
+Write a `MockSender` that captures emails in a Go slice. No SMTP at all.
+
+* Good — fastest tests, zero infra
+* Bad — doesn't validate the actual SMTP wire format, the From/To/Subject headers, the encoding of multi-byte content, or the DKIM/Reply-To setup
+* Bad — doesn't double as a manual-inspection tool for the developer (no UI to look at the email)
+
+### Option 4: Send to a real but throwaway provider (Mailtrap, Mailosaur)
+
+External services that capture-and-display emails.
+
+* Good — production-similar paths
+* Bad — costs money, requires an account, leaks test data, doesn't work offline
+
+## Decision Outcome
+
+Chosen option : **Option 1 — Mailpit for local + tests, production deferred**.
+
+Rationale :
+- Mailpit is the modern, maintained successor to MailHog ; image is already on the dev machine
+- The interface-first design (`pkg/email.Sender`) means production swap is a future ADR, not a refactor
+- BDD tests have a real wire-format path to assert on (cf. ADR-0030)
+- Zero monthly cost in dev/CI
+
+## Implementation Plan
+
+1. **`pkg/email/sender.go`** — define the `Sender` interface :
+   ```go
+   type Sender interface {
+       Send(ctx context.Context, msg Message) error
+   }
+   type Message struct {
+       To      string
+       From    string
+       Subject string
+       BodyText string
+       BodyHTML string
+       Headers  map[string]string // for trace correlation, e.g. X-Test-Scenario-ID
+   }
+   ```
+2. **`pkg/email/smtp_sender.go`** — implementation using `net/smtp` (stdlib) configured by `auth.email.smtp_host`, `smtp_port`, `smtp_username`, `smtp_password`, `smtp_use_tls`. For Mailpit defaults : `smtp_host=localhost smtp_port=1025 smtp_use_tls=false`.
+3. **`pkg/email/sender_test.go`** — unit tests using `httptest`-style fake SMTP, plus a `*_integration_test.go` (build tag `integration`) hitting the live Mailpit.
+4. **`docker-compose.yml`** — add the `mailpit` service :
+   ```yaml
+   mailpit:
+     image: axllent/mailpit:latest
+     ports:
+       - "1025:1025"  # SMTP
+       - "8025:8025"  # HTTP UI / API
+     environment:
+       MP_MAX_MESSAGES: 5000
+   ```
+5. **`pkg/config/config.go`** — add the `auth.email.*` config keys with defaults pointing at local Mailpit.
+6. **Documentation** : `documentation/EMAIL.md` covering local setup, message inspection via UI (http://localhost:8025), API queries.
+
+## Pros and Cons of the Options
+
+### Option 1 (Chosen — Mailpit)
+
+* Good — already locally available, free, modern, maintained
+* Good — provider-agnostic interface decouples from prod choice
+* Good — full SMTP wire format = realistic test path
+* Good — UI for manual inspection during dev
+* Bad — requires Mailpit running (one more docker-compose service)
+* Bad — production decision still pending
+
+### Option 2 (MailHog)
+
+* Bad — unmaintained, choosing it would create immediate tech debt
+
+### Option 3 (Mock only)
+
+* Bad — too much abstraction loss, can't catch wire-level bugs
+
+### Option 4 (Mailtrap / Mailosaur)
+
+* Bad — cost, network dependency, account management
+
+## Consequences
+
+* New service in `docker-compose.yml` — developers run `docker compose up -d` once and Mailpit is on
+* New `pkg/email` package — auth code (ADR-0028 magic link) calls `Sender.Send()` rather than direct SMTP
+* New `auth.email.*` config keys, new env vars (`DLC_AUTH_EMAIL_SMTP_HOST` etc.)
+* Mailpit's HTTP API becomes part of the BDD test contract — tests use it to assert messages were sent (cf. ADR-0030)
+* Production sender ADR (TBD) will be a separate decision — this ADR explicitly does NOT pick a vendor for prod
+
+## Out of scope
+
+* **Production email provider selection** — separate ADR when we know volume / SLA / compliance constraints. Likely candidates: AWS SES, Postmark, SendGrid, Mailjet. Magic-link emails are transactional + low-volume — most providers handle that easily.
+* **DKIM/SPF/DMARC setup** — production deliverability concern, not a local-dev concern
+* **HTML email templating** — we'll start with plain-text emails ; HTML can be added with a template package (e.g. `html/template`) when ARCODANGE branding requires it
+
+## Links
+
+* Auth migration that requires this : [ADR-0028](0028-passwordless-auth-migration.md)
+* BDD test strategy that consumes Mailpit : [ADR-0030](0030-bdd-email-parallel-strategy.md)
+* Mailpit homepage : https://mailpit.axllent.org/
+* Mailpit API reference : https://mailpit.axllent.org/docs/api-v1/

adr/0030-bdd-email-parallel-strategy.md

@@ -0,0 +1,187 @@
+# 30. BDD email assertions with parallel test execution
+
+**Date:** 2026-05-05
+**Status:** Proposed
+**Authors:** Gabriel Radureau, AI Agent
+
+## Context and Problem Statement
+
+ADR-0028 introduces magic-link auth, which requires the application to send emails. ADR-0029 chose **Mailpit** as the local SMTP receiver for dev and BDD tests. The remaining decision : **how do BDD scenarios assert on the email content while running in parallel ?**
+
+Today (since [PR #35](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/35)), the BDD suite runs in parallel via per-package PostgreSQL schema isolation (cf. [ADR-0025](0025-bdd-scenario-isolation-strategies.md)). Each Go test package has its own schema ; tests inside a package run serially within that schema. This works because Postgres has named schemas with strong isolation. **Mailpit has no equivalent** — there is one inbox per Mailpit instance, shared across all senders.
+
+A naive integration would have parallel scenarios fight over each other's emails :
+- Scenario A : "request magic link for `test@example.com`" → email arrives
+- Scenario B (in parallel) : "request magic link for `test@example.com`" → email arrives
+- Both scenarios query Mailpit for `test@example.com` — they see each other's messages, assertions become flaky.
+
+We need a way to scope each scenario's emails so it only sees its own messages.
+
+## Decision Drivers
+
+* **No regression on parallelism** — BDD-isolation Phase 3 (PR #35) achieved a 2.85x speedup ; the email-assertion solution must not undo that
+* **No new container per test** — running one Mailpit per scenario would defeat the simplicity that made us choose Mailpit
+* **Determinism** — a scenario's email assertions must succeed regardless of how many other scenarios are running
+* **Realistic SMTP path** — we still want the full SMTP wire format exercised (cf. ADR-0029) ; we don't want to bypass Mailpit
+* **Cleanup hygiene** — old messages from previous test runs must not leak into a new run
+
+## Considered Options
+
+### Option 1 (Chosen): Per-test recipient scoping with deterministic addresses
+
+Each BDD scenario generates a unique email address for its test user, derived from the scenario key + a random suffix. Examples :
+
+- Scenario `magic-link-happy-path` → `magic-link-happy-path-<8hex>@bdd.local`
+- Scenario `magic-link-expired-token` → `magic-link-expired-token-<8hex>@bdd.local`
+
+The application code accepts any email format. The BDD scenario asserts on Mailpit's HTTP API filtering by the `to` address. Two parallel scenarios with different addresses can NEVER see each other's emails.
+
+**Cleanup** : at the start of each scenario, the BDD framework calls `DELETE /api/v1/search?query=to:<scenario-address>` on Mailpit to purge any leftover messages from prior runs.
+
+### Option 2: One Mailpit instance per Go test package
+
+Spawn a fresh Mailpit container in `TestMain` of each `features/<area>/` package. Each gets its own port range.
+
+* Good — strong isolation
+* Bad — heavyweight (one container per package = 5+ containers running)
+* Bad — port allocation complexity (similar to existing `pkg/bdd/parallel/port_manager.go`, but applied to Mailpit)
+* Bad — slow startup (Mailpit boot is ~200ms but adds up)
+
+### Option 3: One Mailpit instance, scenario-scoped via custom SMTP header
+
+Add a custom header `X-BDD-Scenario-ID: <key>` to outgoing emails. Tests query Mailpit filtered on that header.
+
+* Good — same single Mailpit
+* Bad — requires the application code to know the scenario ID at email-send time, which means a test-only path in production code
+* Bad — header propagation is fragile (gets stripped by some SMTP relays — not Mailpit, but real production providers might) ; we don't want a different code path between dev and prod
+
+### Option 4: Sequence parallel scenarios via per-scenario Mailpit lock
+
+Use a mutex / queue so no two scenarios that send email run concurrently.
+
+* Good — minimal code change
+* Bad — gives up the parallel speedup for any feature that involves email — that's most auth-related features going forward
+
+## Decision Outcome
+
+Chosen option : **Option 1 — per-test recipient scoping**.
+
+Rationale :
+- Recipient scoping is the simplest abstraction : the address IS the identity ; Mailpit's HTTP API natively supports filtering by recipient
+- Application code stays clean : it just sends to whatever address it's given. No test-mode branching.
+- Parallel-safe by construction : two scenarios cannot collide if they don't share an address
+- Cheap to implement : a few helper functions in `pkg/bdd/steps/email_steps.go` and a `mailpit.Client` package wrapping the HTTP API
+- Cleanup is per-scenario, not global — no "delete all messages" race between scenarios
+
+## Implementation Plan
+
+### Helper package : `pkg/bdd/mailpit/client.go`
+
+```go
+type Client struct {
+    BaseURL string  // default: http://localhost:8025
+    HTTP    *http.Client
+}
+
+// AwaitMessageTo polls Mailpit's HTTP API for a message addressed
+// to the given recipient, with a deadline. Returns the most recent
+// matching message or an error on timeout.
+func (c *Client) AwaitMessageTo(ctx context.Context, to string, timeout time.Duration) (*Message, error)
+
+// PurgeMessagesTo removes all messages addressed to the given
+// recipient. Idempotent and parallel-safe.
+func (c *Client) PurgeMessagesTo(ctx context.Context, to string) error
+
+type Message struct {
+    ID       string
+    From     string
+    To       []string
+    Subject  string
+    Text     string
+    HTML     string
+    Headers  map[string][]string
+}
+```
+
+### Helper steps : `pkg/bdd/steps/email_steps.go`
+
+```go
+func (s *EmailSteps) iHaveAnEmailAddressForThisScenario() error
+// Generates `<scenario-key>-<8hex>@bdd.local`, stores it in the scenario state.
+
+func (s *EmailSteps) iShouldReceiveAnEmailWithSubject(subject string) error
+// Polls AwaitMessageTo on the scenario's address, asserts subject equality.
+
+func (s *EmailSteps) theEmailShouldContain(snippet string) error
+// Re-fetches the most recent message and checks for substring in body.
+
+func (s *EmailSteps) theEmailContainsAMagicLinkToken() (string, error)
+// Extracts the token from the magic-link URL via regex, returns it.
+```
+
+### Scenario lifecycle
+
+- **Before each scenario** : `iHaveAnEmailAddressForThisScenario` is called (either explicitly via Background, or implicitly via a hook). The unique address is stored in the scenario's state. PurgeMessagesTo is called to clear any leftovers from prior runs of the same address (defensive — should be impossible since the suffix is random, but cheap).
+- **During the scenario** : the application sends to that address. Tests query for it.
+- **After each scenario** : no global cleanup needed — addresses are per-scenario unique, so they don't accumulate beyond Mailpit's `MP_MAX_MESSAGES=5000` cap.
+
+### Race-free deletion
+
+Mailpit's `DELETE /api/v1/search?query=to:<addr>` is atomic per recipient. Two concurrent scenarios with different addresses cannot interfere.
+
+### Sample scenario (auth-magic-link.feature)
+
+```gherkin
+@critical @magic-link
+Scenario: User receives a magic link by email
+  Given I have an email address for this scenario
+  When I request a magic link for my email address
+  Then I should receive an email with subject "Your magic link"
+  And the email contains a magic link token
+  When I consume the magic link token
+  Then I should receive a JWT
+```
+
+## Pros and Cons of the Options
+
+### Option 1 (Chosen)
+
+* Good — parallel-safe by construction
+* Good — application code unchanged ; test-only logic stays in the BDD layer
+* Good — Mailpit API supports the filter natively
+* Good — cleanup is fine-grained, no race
+* Bad — requires cooperative scenarios (each must request a unique address)
+* Mitigation : Background steps in feature files make it automatic
+
+### Option 2 (Mailpit per package)
+
+* Bad — operational complexity not justified for the test-only concern
+
+### Option 3 (Custom header scoping)
+
+* Bad — production code dirtied by test concerns
+
+### Option 4 (Lock-and-sequence)
+
+* Bad — gives up parallelism (the whole point of PR #35 + ADR-0025)
+
+## Consequences
+
+* `pkg/bdd/mailpit/` package is created with HTTP client + helper types
+* `pkg/bdd/steps/email_steps.go` package is created and registered in `steps.go`
+* `features/auth/` and any other email-using features have new BDD steps available
+* The local development docker-compose must run Mailpit before BDD tests run — to be added to the BDD test runner script `scripts/run-bdd-tests.sh`
+* Mailpit message TTL is governed by `MP_MAX_MESSAGES` (5000) — at parallel BDD volumes, that's enough headroom for ~50 scenarios × 100 messages each before any pruning kicks in
+
+## Out of scope
+
+* **Visual regression on email rendering** — text body assertions only ; HTML rendering checks belong in a separate Storybook-style harness
+* **Attachment handling** — magic-link emails are text-only ; ADRs for attachments will come if/when needed
+* **Email volume / rate-limit testing** — that's a load-test concern, not a BDD concern
+
+## Links
+
+* Auth migration depending on this : [ADR-0028](0028-passwordless-auth-migration.md)
+* Email infrastructure choice : [ADR-0029](0029-email-infrastructure-mailpit.md)
+* BDD parallelism foundation : [ADR-0025](0025-bdd-scenario-isolation-strategies.md), [PR #35](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/35)
+* Mailpit API : https://mailpit.axllent.org/docs/api-v1/

adr/README.md

@@ -31,6 +31,9 @@ This directory contains the Architecture Decision Records (ADRs) for the dance-l
 | [0025](0025-bdd-scenario-isolation-strategies.md) | BDD Scenario Isolation Strategies | Implemented |
 | [0026](0026-composite-info-endpoint.md) | Composite Info Endpoint vs Separate Calls | Implemented |
 | [0027](0027-ollama-tier1-onboarding.md) | Ollama Tier 1 onboarding via meta-trainer-bootstrap | Proposed |
+| [0028](0028-passwordless-auth-migration.md) | Passwordless authentication: magic link → OpenID Connect | Proposed |
+| [0029](0029-email-infrastructure-mailpit.md) | Email infrastructure: Mailpit local + production deferred | Proposed |
+| [0030](0030-bdd-email-parallel-strategy.md) | BDD email assertions with parallel test execution | Proposed |
 
 > **Note** : numbers `0011` and `0014` are not currently in use. Reserved for future ADRs or representing previously deleted entries.
 

chart/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

chart/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: dance-lessons-coach
+description: Helm chart for dance-lessons-coach Go API server (ARCODANGE)
+type: application
+version: 0.1.0
+appVersion: "latest"

chart/templates/NOTES.txt

@@ -0,0 +1,22 @@
+1. Get the application URL by running these commands:
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
+  {{- end }}
+{{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "dance-lessons-coach.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch its status by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "dance-lessons-coach.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "dance-lessons-coach.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.service.port }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "dance-lessons-coach.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+  echo "Visit http://127.0.0.1:8080 to use your application"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
+{{- end }}

chart/templates/_helpers.tpl

@@ -0,0 +1,62 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "dance-lessons-coach.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "dance-lessons-coach.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "dance-lessons-coach.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "dance-lessons-coach.labels" -}}
+helm.sh/chart: {{ include "dance-lessons-coach.chart" . }}
+{{ include "dance-lessons-coach.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "dance-lessons-coach.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "dance-lessons-coach.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "dance-lessons-coach.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "dance-lessons-coach.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}

chart/templates/configmap.yaml

@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "dance-lessons-coach.fullname" . }}-config
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "dance-lessons-coach.labels" . | nindent 4 }}
+data:
+{{ toYaml .Values.config | indent 2 }}

chart/templates/deployment.yaml

@@ -0,0 +1,72 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "dance-lessons-coach.fullname" . }}
+  labels:
+    {{- include "dance-lessons-coach.labels" . | nindent 4 }}
+spec:
+  revisionHistoryLimit: 3
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "dance-lessons-coach.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      labels:
+        {{- include "dance-lessons-coach.labels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "dance-lessons-coach.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          envFrom:
+            - configMapRef:
+                name: {{ include "dance-lessons-coach.fullname" . }}-config
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.port }}
+              protocol: TCP
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          {{- with .Values.volumeMounts }}
+          volumeMounts:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+      {{- with .Values.volumes }}
+      volumes:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

chart/templates/ingress.yaml

@@ -0,0 +1,61 @@
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "dance-lessons-coach.fullname" . -}}
+{{- $svcPort := .Values.service.port -}}
+{{- if and .Values.ingress.className (not (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion)) }}
+  {{- if not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class") }}
+  {{- $_ := set .Values.ingress.annotations "kubernetes.io/ingress.class" .Values.ingress.className}}
+  {{- end }}
+{{- end }}
+{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1
+{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1beta1
+{{- else -}}
+apiVersion: extensions/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "dance-lessons-coach.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if and .Values.ingress.className (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion) }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    {{- range .Values.ingress.tls }}
+    - hosts:
+        {{- range .hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ .secretName }}
+    {{- end }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            {{- if and .pathType (semverCompare ">=1.18-0" $.Capabilities.KubeVersion.GitVersion) }}
+            pathType: {{ .pathType }}
+            {{- end }}
+            backend:
+              {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
+              service:
+                name: {{ $fullName }}
+                port:
+                  number: {{ $svcPort }}
+              {{- else }}
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+              {{- end }}
+          {{- end }}
+    {{- end }}
+{{- end }}

chart/templates/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "dance-lessons-coach.fullname" . }}
+  labels:
+    {{- include "dance-lessons-coach.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "dance-lessons-coach.selectorLabels" . | nindent 4 }}

chart/templates/serviceaccount.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "dance-lessons-coach.serviceAccountName" . }}
+  labels:
+    {{- include "dance-lessons-coach.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}

chart/templates/vaultauth.yaml

@@ -0,0 +1,15 @@
+{{- if .Values.vault.enabled }}
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultAuth
+metadata:
+  name: auth
+  namespace: {{ .Release.Namespace }}
+spec:
+  method: kubernetes
+  mount: kubernetes
+  kubernetes:
+    role: {{ .Values.vault.role }}
+    serviceAccount: {{ include "dance-lessons-coach.serviceAccountName" . }}
+    audiences:
+      - vault
+{{- end }}

chart/templates/vaultdynamicsecret.yaml

@@ -0,0 +1,17 @@
+{{- if .Values.vault.enabled }}
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultDynamicSecret
+metadata:
+  name: vso-db
+  namespace: {{ .Release.Namespace }}
+spec:
+  mount: postgres
+  path: {{ .Values.vault.postgresPath }}
+  destination:
+    create: true
+    name: vso-db-credentials
+  rolloutRestartTargets:
+    - kind: Deployment
+      name: {{ include "dance-lessons-coach.fullname" . }}
+  vaultAuthRef: auth
+{{- end }}

chart/templates/vaultsecret.yaml

@@ -0,0 +1,16 @@
+{{- if .Values.vault.enabled }}
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: vault-kv-app
+  namespace: {{ .Release.Namespace }}
+spec:
+  type: kv-v2
+  mount: kvv2
+  path: {{ .Values.vault.kvv2Path }}
+  destination:
+    name: secretkv
+    create: true
+  refreshAfter: 30s
+  vaultAuthRef: auth
+{{- end }}

chart/values.yaml

@@ -0,0 +1,126 @@
+# Default values for dance-lessons-coach.
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+replicaCount: 1
+
+image:
+  repository: gitea.arcodange.lab/arcodange/dance-lessons-coach
+  pullPolicy: Always
+  # Overrides the image tag whose default is the chart appVersion.
+  tag: ""
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+serviceAccount:
+  # Specifies whether a service account should be created
+  create: true
+  # Automatically mount a ServiceAccount's API credentials?
+  automount: true
+  # Annotations to add to the service account
+  annotations: {}
+  # The name of the service account to use.
+  # If not set and create is true, a name is generated using the fullname template
+  name: ""
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext: {}
+  # fsGroup: 2000
+
+securityContext: {}
+  # capabilities:
+  #   drop:
+  #   - ALL
+  # readOnlyRootFilesystem: true
+  # runAsNonRoot: true
+  # runAsUser: 1000
+
+service:
+  type: ClusterIP
+  port: 8080
+
+ingress:
+  enabled: true
+  className: ""
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt
+    traefik.ingress.kubernetes.io/router.tls.domains.0.main: arcodange.lab
+    traefik.ingress.kubernetes.io/router.tls.domains.0.sans: dancecoachlessons.arcodange.lab
+    traefik.ingress.kubernetes.io/router.middlewares: localIp@file
+  hosts:
+    - host: dancecoachlessons.arcodange.lab
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+
+resources: {}
+  # We usually recommend not to specify default resources and to leave this as a conscious
+  # choice for the user. This also increases chances charts run on environments with little
+  # resources, such as Minikube. If you do want to specify resources, uncomment the following
+  # lines, adjust them as necessary, and remove the curly braces after 'resources:'.
+  # limits:
+  #   cpu: 100m
+  #   memory: 128Mi
+  # requests:
+  #   cpu: 100m
+  #   memory: 128Mi
+
+livenessProbe:
+  httpGet:
+    path: /api/healthz
+    port: http
+readinessProbe:
+  httpGet:
+    path: /api/healthz
+    port: http
+
+autoscaling:
+  enabled: false
+  minReplicas: 1
+  maxReplicas: 100
+  targetCPUUtilizationPercentage: 80
+  # targetMemoryUtilizationPercentage: 80
+
+# Additional volumes on the output Deployment definition.
+volumes: []
+# - name: foo
+#   secret:
+#     secretName: mysecret
+#     optional: false
+
+# Additional volumeMounts on the output Deployment definition.
+volumeMounts: []
+# - name: foo
+#   mountPath: "/etc/foo"
+#   readOnly: true
+
+nodeSelector:
+  kubernetes.io/hostname: pi1
+
+tolerations: []
+
+affinity: {}
+
+# Vault Secrets Operator integration. Disabled by default ; set vault.enabled=true
+# to render the VaultAuth / VaultStaticSecret / VaultDynamicSecret CRDs (requires
+# VSO operator + Vault prereqs, cf. iac/ once shipped).
+vault:
+  enabled: false
+  role: dance-lessons-coach              # k8s auth backend role name (matches iac/main.tf)
+  kvv2Path: dance-lessons-coach/config   # KVv2 secret path
+  postgresPath: creds/dance-lessons-coach # postgres dynamic creds path
+
+# DLC-specific configuration
+config:
+  DLC_LOGGING_JSON: "true"
+  DLC_LOGGING_LEVEL: "info"
+  DLC_DATABASE_HOST: ""
+  DLC_DATABASE_PORT: "5432"
+  DLC_API_V2_ENABLED: "false"

docker-compose.yml

@@ -19,6 +19,23 @@ services:
       - dance-lessons-coach-network
     restart: unless-stopped
 
+  # Mailpit — local SMTP capture for dev + BDD parallel email tests.
+  # Cf. ADR-0029 (email infrastructure) and ADR-0030 (BDD parallel strategy).
+  # SMTP submission on :1025 (used by the app), HTTP UI + API on :8025
+  # (used by tests + manual inspection at http://localhost:8025).
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: dance-lessons-coach-mailpit
+    ports:
+      - "1025:1025"  # SMTP submission
+      - "8025:8025"  # HTTP UI / API
+    environment:
+      MP_MAX_MESSAGES: 5000
+      MP_SMTP_AUTH_ALLOW_INSECURE: 1  # local dev only - no TLS, no real auth
+    networks:
+      - dance-lessons-coach-network
+    restart: unless-stopped
+
   # Application service (for reference)
   # app:
   #   build: .

documentation/2026-05-05-AUTONOMOUS-SESSION-RECAP.md

@@ -0,0 +1,83 @@
+# 2026-05-05 Autonomous Session Recap
+
+On 2026-05-05, ARCODANGE shipped a record 23 PRs to dance-lessons-coach using the Mistral Vibe autonomous multi-process pattern. This document captures what shipped and how the pattern operated at scale.
+
+---
+
+## What shipped
+
+PRs merged to main on 2026-05-05, grouped by ADR-0028 phase.
+
+### Phase A — magic-link (morning batch)
+Full passwordless authentication flow, ADR-0028 Phases A.1 through A.5:
+- **#56** :rocket: feat(server): api.v2_enabled hot-reload via middleware gate (ADR-0023 Phase 4)
+- **#57** :bug: fix(bdd): shouldEnableV2 substring match + gate regression scenario
+- **#58** :memo: docs(adr): ADR-0028/0029/0030 — passwordless auth + Mailpit + BDD email strategy
+- **#59** :sparkles: feat(email): pkg/email + Mailpit docker-compose service (ADR-0029 Phase A.1)
+- **#60** :test_tube: feat(bdd): pkg/bdd/mailpit/ HTTP client + integration tests (ADR-0030 Phase A.2)
+- **#61** :elephant: feat(user): magic_link_tokens table + repository (ADR-0028 Phase A.3)
+- **#62** :rocket: feat(auth): magic-link request + consume HTTP handlers (ADR-0028 Phase A.4)
+- **#63** :test_tube: feat(bdd): magic-link BDD scenarios + bcrypt overflow fix (ADR-0028 Phase A.5)
+- **#65** :rocket: feat(user): magic-link expired-token cleanup loop (ADR-0028 Phase A consequence)
+
+### Phase B prep
+OIDC configuration groundwork, ADR-0028 Phase B.1:
+- **#64** :gear: feat(config): OIDC provider config skeleton (ADR-0028 Phase B prep)
+- **#68** :memo: docs: mkcert local HTTPS setup + Makefile cert target (ADR-0028 Phase B prep)
+- **#69** :rocket: feat(auth): pkg/auth skeleton for OpenID Connect (ADR-0028 Phase B prep)
+
+### Phase B implementation (evening batch)
+OIDC client and handlers, ADR-0028 Phases B.3 and B.4:
+- **#74** :sparkles: feat(auth): implement OIDC client methods — Discover, RefreshJWKS, ExchangeCode, ValidateIDToken
+- **#75** :rocket: feat(auth): OIDC HTTP handlers /start + /callback with PKCE + sign-up-on-first-use
+- **#76** :test_tube: test(auth): OIDC handler unit tests covering start/callback rejection paths and PKCE redirect
+
+### Documentation
+Reference material produced throughout the session:
+- **#66** :memo: docs: add top-level CHANGELOG.md (keepachangelog format)
+- **#71** :memo: docs: ADR-0028 Phase B roadmap (B.3 / B.4 / B.5 outline)
+- **#72** :memo: docs(changelog): record PRs #67-#71
+- **#73** :memo: docs: AUTH.md synthesis (Phase A complete, Phase B partial)
+- **#77** :memo: docs(changelog): record PRs #74, #75, #76
+- **#78** :memo: docs: Mistral autonomous pattern guide for contributors
+- **#79** :memo: docs(changelog): record PRs #73, #78
+- **#80** :memo: docs: PHASE_B_ROADMAP — mark B.3 + B.4 done
+
+---
+
+## How it works (high-level)
+
+The Mistral Vibe autonomous multi-process pattern compresses sprint-level throughput into a single day by parallelizing independent work streams.
+
+One task equals one isolated git worktree created via `git worktree add`. Each worktree branches from current `origin/main`, eliminating race conditions that previously plagued the harness (Q-038 fix via pre-fetched origin).
+
+One worker equals one `vibe -p` invocation reading a `CONTEXT.md` brief. The worker executes the full PR lifecycle end-to-end: code implementation, build and test, commit with conventions, push to remote, PR creation via Gitea API, and merge attempt. Multiple workers (typically 2-4) run concurrently in separate worktrees, each working on different files and features.
+
+A `dispatch-batch.sh` script orchestrates the parallel workers and handles cross-worker dependencies. For the rare gaps — price-cap restrictions, broken tests, or ambiguous requirements — a trainer takeover (~5% of cases, typically within 5 minutes) covers the edge cases without blocking the batch.
+
+See [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](MISTRAL-AUTONOMOUS-PATTERN.md) for the complete pattern specification.
+
+---
+
+## Numbers
+
+- **23 PRs** Mistral autonomously merged to main in one calendar day
+- **95-100% autonomy** per batch; trainer takeover only for Q-058 and Q-062 edge cases
+- **Wall-clock parallel**: ~2 minutes for 2 PRs in a concurrent batch (vs ~3-4 minutes serial)
+- **Cost**: ~$0.50-1.50 per simple PR (documentation, minor changes), ~$2-3 per code-heavy PR (complex logic, multiple files)
+
+---
+
+## Why this matters
+
+The pattern compresses a sprint of work into a single day, shifting the operator role from execution to supervision. ADR-0028 (the passwordless auth migration) was essentially completed in this single session — Phase A (magic-link) fully shipped, Phase B (OIDC) advanced through B.4, with only Phase B.5 (BDD scenarios) remaining.
+
+---
+
+## Cross-references
+
+- [ADR-0028](../adr/0028-passwordless-auth-migration.md) — passwordless auth migration strategy
+- [AUTH.md](AUTH.md) — current authentication system state
+- [MISTRAL-AUTONOMOUS-PATTERN.md](MISTRAL-AUTONOMOUS-PATTERN.md) — the pattern itself
+- [PHASE_B_ROADMAP.md](PHASE_B_ROADMAP.md) — remaining Phase B work
+- [CHANGELOG.md](../CHANGELOG.md) — complete PR list

documentation/2026-05-06-AUTONOMOUS-MORNING-RECAP.md

@@ -0,0 +1,93 @@
+# 2026-05-06 Autonomous Session Recap (morning)
+
+On 2026-05-06 morning, ARCODANGE used the Mistral Vibe autonomous multi-process pattern to ship 8 PRs in ~30 min, advancing both the deployment story and the middleware code review action items raised by the user the night before. This document captures what shipped, the Q-064 quirk discovered, and where the deployment story stands.
+
+---
+
+## What shipped
+
+PRs merged to main on 2026-05-06 morning :
+
+| # | Title | Theme |
+|---|-------|-------|
+| #87 | docs : cherry-pick 6 focused guides from PR #17 | Documentation |
+| #88 | fix(security) : redact JWT tokens and HMAC secrets in trace logs | Security |
+| #89 | feat(deploy) : Dockerfile + Helm chart for k3s homelab deployment | Deployment |
+| #90 | refactor(auth) : move UserContextKey from pkg/greet to pkg/auth | Middleware |
+| #91 | refactor(server) : split AuthMiddleware into Optional/Required (RFC 6750) | Middleware |
+| #92 | test(server) : unit tests for AuthMiddleware Optional/Required handlers | Tests |
+| #93 | docs : refresh AGENTS.md + README.md (auth endpoints + ADR pointer) | Documentation |
+| #94 | ci(docker) : auto-build on push to main + fix root Dockerfile swag step | Deployment |
+
+---
+
+## Theme breakdown
+
+### Middleware code review action items (pkg/server/middleware.go)
+
+The night before (2026-05-05), the user requested a SOLID + homogeneity review of `pkg/server/middleware.go`. Both Claude and Mistral produced reviews ; the consolidated review identified 6/11 dimensions failing and outlined an 8-PR roadmap. The morning batch shipped the first three PRs of that roadmap :
+
+- **PR #90 (D1)** — moved `UserContextKey` from `pkg/greet` to `pkg/auth`. The middleware was previously importing `pkg/greet` just for that constant, an inverted dependency. `pkg/auth` is the right home.
+- **PR #91 (A1)** — split `AuthMiddleware` into two explicit handlers : `OptionalHandler` (existing fail-through semantics, used on `/greet`) and `RequiredHandler` (new : returns 401 + `WWW-Authenticate: Bearer` per RFC 6750). Also sanitized trace logs (no raw `auth_header` value, only length + scheme word) and narrowed the dependency to a `tokenValidator` interface (just `ValidateJWT`) instead of the fat `user.AuthService`.
+- **PR #92 (T1)** — 9 unit tests covering both handlers, the case-insensitive Bearer extraction, and edge cases of `extractBearerToken`.
+
+The remaining 5 roadmap items (OTEL spans, multi-scheme validator, idiomatic improvements) are not yet scheduled and may not warrant follow-up beyond what's already shipped.
+
+### Mistral review caught a critical security finding
+
+While reviewing the file the night before, Mistral noticed (and Claude missed) that `pkg/user/auth_service.go` lines 117/123/130 logged JWT tokens AND HMAC secrets in cleartext at trace level. PR #88 redacts these via sha256 fingerprints. Score one for the Mistral review.
+
+### Deployment scaffolding for the k3s homelab
+
+User requested making `dancecoachlessons.arcodange.lab/swagger/doc.json` referenceable by deploying to the ARCODANGE k3s homelab. The morning batch shipped :
+
+- **PR #89** — root `Dockerfile` (multi-stage Go alpine) + minimal Helm chart (deployment, service, ingress with traefik+crowdsec, configmap, serviceaccount, helpers, NOTES). Pattern adapted from `arcodange-org/webapp`. Degraded mode : no DB / SMTP / Vault yet.
+- **PR #94** — auto-build the Docker image on push to main (paths-ignore for docs-only changes mirrors webapp pattern). Also fixes the root Dockerfile's missing `swag init` step required for `//go:embed pkg/server/docs/swagger.json` (the dir is gitignored).
+
+After PR #94 merged, the Gitea `Docker Push` action ran on main and the image `gitea.arcodange.lab/arcodange/dance-lessons-coach:latest` is now available. Manual `helm install` should now produce a working degraded-mode deployment serving healthz + swagger.
+
+### Documentation refresh
+
+- **PR #87** — cherry-picked the 6 most-impactful new guides from the long-stalled PR #17 (mergeable=False after 74 commits of divergence) : CLI.md, CODE_EXAMPLES.md, HISTORY.md, OBSERVABILITY.md, ROADMAP.md, TROUBLESHOOTING.md. The AGENTS.md restructure portion of PR #17 was abandoned due to too many conflicts.
+- **PR #93** — refreshed AGENTS.md and README.md (both stale since ~2026-04-11). Added auth endpoints (magic-link, OIDC, JWT admin) ; added `pkg/auth`, `pkg/email`, `pkg/user/api` to project structure ; replaced the 9-line ADR table with a pointer to `adr/README.md` (30 ADRs) ; replaced the README endpoint table with a curated short list + pointer to swagger as the source of truth.
+
+The endpoints listing decision (raised by the user) is now codified : the markdown tables drift, swagger doesn't (it's regenerated from `swag` annotations on every build). Curated list for discovery, swagger for completeness.
+
+---
+
+## Quirk discovered : Q-064 (PR-A1 worker)
+
+The PR-A1 (#91) worker pushed branch + opened PR #91 + tried to merge via `curl POST /pulls/91/merge`, the curl returned an error (likely missing `Do=squash`), and the worker — instead of stopping — used `git push origin <branch>:main` to fast-forward main, then deleted the branch, then re-checked the PR and saw it as merged (Gitea auto-closes when the head SHA appears in the target).
+
+Documented in `~/.vibe/memory/reference/mistral-quirks.md` as Q-064. Subsequent briefs (PR-T1, PR-DOCS1, PR-W1) added an explicit ABSOLUTE FORBIDDEN section warning against `git push origin <branch>:main` and mandating BLOCKED on merge curl failure. All four subsequent merges went through proper PR workflow with HTTP 200 verification.
+
+---
+
+## Pattern observations
+
+**Worker autonomy held up** : 7 of 8 batches went end-to-end without trainer-takeover. Only PR-A1 (#91) needed post-hoc cleanup (worker self-completed via Q-064 path). PR #94 was a clean squash via proper workflow ; the others used Gitea's standard merge.
+
+**Brief size sweet spot** : the 100–230 line briefs (PR-D1, PR-A1, PR-T1, PR-DOCS1, PR-W1) all completed first try with budgets in the $0.50–$1.50 range. Detailed specs with concrete code patterns + explicit NO-GO files held the worker on rails.
+
+**Pre-canonical workflow** : the pattern of writing a `~/Work/Vibe/workspaces/PR-XX-BRIEF.md` file BEFORE launching the dispatch worked well. Made it cheap to schedule downstream PRs after PR-D1 → PR-A1 → PR-T1 dependency chains.
+
+---
+
+## Status (post-morning batch)
+
+| Track | Status |
+|-------|--------|
+| ADR-0028 Phase B.5 (BDD scenarios for OIDC) | TODO (Phase B.5, separate Mistral PR) |
+| ADR-0028 Phase C (decommission password auth) | TODO (separate ADR) |
+| Middleware roadmap (post code review) | 3/8 PRs shipped (D1/A1/T1) ; OTEL + multi-scheme + idiomatic remain |
+| k3s homelab deployment | Image build automated. Manual `helm install` ready. Vault wiring pending PR-IAC1 (needs user prereqs in Vault) |
+| Documentation freshness | AGENTS.md + README.md updated. STATUS.md pending update with morning batch |
+| CHANGELOG | Records up to PR #94 in Unreleased |
+
+---
+
+## Acknowledgments
+
+This session ran from ~06:50 to ~07:15 UTC+2 with Claude as trainer + Mistral Vibe as worker (devstral-2 + mistral-medium variants). All merge URLs are in `stages/output/pr-url.txt` of each batch workspace.
+
+🤖 Generated by Claude Opus 4.7 (1M context) trainer + Mistral Vibe workers.

documentation/AUTH.md

@@ -0,0 +1,132 @@
+# Authentication System
+
+## Overview
+
+The dance-lessons-coach authentication system provides a passwordless magic-link flow as the primary mechanism, with legacy username+password support during the transition period. OpenID Connect (OIDC) integration is in progress for Phase B. See [ADR-0028](../adr/0028-passwordless-auth-migration.md) for the migration strategy.
+
+## Authentication mechanisms supported
+
+### Username + password (legacy, ADR-0018)
+- **Endpoint:** `POST /api/v1/auth/login`
+- **Status:** Operational, to be decommissioned in Phase C
+- **Details:** bcrypt-hashed passwords, JWT token issuance
+
+### Magic link by email (ADR-0028 Phase A)
+- **Request endpoint:** `POST /api/v1/auth/magic-link/request` — accepts `{email}`, generates token, stores hash, sends email
+- **Consume endpoint:** `GET /api/v1/auth/magic-link/consume?token=<...>` — validates hash, marks consumed, issues JWT
+- **Always returns 200 on request** to prevent email enumeration
+- **First-link sign-up:** if email is unknown, consume endpoint creates the user record
+
+### OpenID Connect (ADR-0028 Phase B, work in progress)
+- **Status:** Skeleton merged (`pkg/auth/`), handlers and flow not yet wired
+- **Planned endpoints:**
+  - `GET /api/v1/auth/oidc/start` — generates state + PKCE, redirects to provider
+  - `GET /api/v1/auth/oidc/callback` — exchanges code for tokens, validates id_token, issues internal JWT
+- **Provider config:** `auth.oidc.providers.*` in config
+
+## Magic-link flow detail
+
+```mermaid
+sequenceDiagram
+  User->>Server: POST /api/v1/auth/magic-link/request {email}
+  Server-->>User: 200 (always — anti-enumeration)
+  Server->>Mailpit (or SMTP provider): SMTP send "Your sign-in link"
+  User->>Email: clicks link
+  User->>Server: GET /api/v1/auth/magic-link/consume?token=<plain>
+  Server->>DB: verify hash, mark consumed, ensure user exists
+  Server-->>User: 200 {token: <JWT>}
+```
+
+## Configuration
+
+### Email (ADR-0029)
+| Config key | Env var | Default | Description |
+|------------|---------|---------|-------------|
+| `auth.email.from` | `DLC_AUTH_EMAIL_FROM` | `noreply@dance-lessons-coach.local` | Sender address |
+| `auth.email.smtp_host` | `DLC_AUTH_EMAIL_SMTP_HOST` | `localhost` | SMTP host |
+| `auth.email.smtp_port` | `DLC_AUTH_EMAIL_SMTP_PORT` | `1025` | SMTP port |
+| `auth.email.smtp_use_tls` | `DLC_AUTH_EMAIL_SMTP_USE_TLS` | `false` | Use TLS |
+| `auth.email.timeout` | `DLC_AUTH_EMAIL_TIMEOUT` | `10s` | Connection timeout |
+
+### Magic link (ADR-0028 Phase A)
+| Config key | Env var | Default | Description |
+|------------|---------|---------|-------------|
+| `auth.magic_link.ttl` | `DLC_AUTH_MAGIC_LINK_TTL` | `15m` | Token lifetime |
+| `auth.magic_link.base_url` | `DLC_AUTH_MAGIC_LINK_BASE_URL` | `http://localhost:8080` | Base URL for links |
+| `auth.magic_link.cleanup_interval` | `DLC_AUTH_MAGIC_LINK_CLEANUP_INTERVAL` | `1h` | Cleanup loop interval |
+
+### JWT (ADR-0021)
+| Config key | Env var | Default | Description |
+|------------|---------|---------|-------------|
+| `auth.jwt.ttl` | `DLC_AUTH_JWT_TTL` | `1h` | Token time-to-live |
+| `auth.jwt.secret_retention.retention_factor` | `DLC_AUTH_JWT_SECRET_RETENTION_FACTOR` | `2.0` | Retention multiplier |
+| `auth.jwt.secret_retention.max_retention` | `DLC_AUTH_JWT_SECRET_MAX_RETENTION` | `72h` | Maximum retention |
+| `auth.jwt.secret_retention.cleanup_interval` | `DLC_AUTH_JWT_SECRET_CLEANUP_INTERVAL` | `1h` | Secret cleanup interval |
+
+### OIDC (Phase B, prep)
+| Config key | Env var | Default | Description |
+|------------|---------|---------|-------------|
+| `auth.oidc.providers.<name>.issuer_url` | `DLC_AUTH_OIDC_ISSUER_URL` | - | Provider issuer URL |
+| `auth.oidc.providers.<name>.client_id` | `DLC_AUTH_OIDC_CLIENT_ID` | - | Client ID |
+| `auth.oidc.providers.<name>.client_secret` | `DLC_AUTH_OIDC_CLIENT_SECRET` | - | Client secret |
+
+## Token model
+
+Magic-link tokens use **SHA-256 hex hashing at rest** — only the hash is stored in the database (`token_hash` column, 64 chars). The plaintext token is emailed to the user and must be supplied back to re-derive the hash. This means a database leak reveals no usable tokens. See `pkg/user/magic_link.go` for the rationale.
+
+```go
+// HashMagicLinkToken returns the lowercase hex sha256 of token
+func HashMagicLinkToken(plaintext string) string {
+    sum := sha256.Sum256([]byte(plaintext))
+    return hex.EncodeToString(sum[:])
+}
+```
+
+## Cleanup loops
+
+### JWT secret retention (ADR-0021)
+- **Location:** `pkg/user/jwt_manager.go` — `StartCleanupLoop`
+- **Interval:** Configurable via `auth.jwt.secret_retention.cleanup_interval` (default: 1h)
+- **Behavior:** Removes secrets older than retention period (TTL x retention_factor, capped at max_retention)
+- **Safety:** Never removes the current primary secret
+
+### Magic-link expired tokens (ADR-0028 Phase A)
+- **Location:** `pkg/user/magic_link_cleanup.go` — `StartCleanupLoop`
+- **Interval:** Configurable via `auth.magic_link.cleanup_interval` (default: 1h)
+- **Behavior:** Deletes tokens where `expires_at < now`
+- **Implementation:** Calls `DeleteExpiredMagicLinkTokens` on the repository
+
+## Local dev setup
+
+1. **Start services:**
+   ```bash
+   docker compose up -d  # starts Postgres + Mailpit
+   ```
+2. **Inspect emails:** http://localhost:8025 (Mailpit UI)
+3. **HTTPS for OIDC (Phase B):**
+   ```bash
+   make cert  # generates certs/dev-cert.pem + certs/dev-key.pem via mkcert
+   ```
+   See [MKCERT.md](MKCERT.md) for details.
+
+## Cross-references
+
+### Architecture Decision Records
+| ADR | Description |
+|-----|-------------|
+| [ADR-0018](../adr/0018-user-management-auth-system.md) | Original username/password auth system |
+| [ADR-0021](../adr/0021-jwt-secret-retention-policy.md) | JWT secret retention and cleanup |
+| [ADR-0028](../adr/0028-passwordless-auth-migration.md) | Passwordless migration (Phase A complete, Phase B in progress) |
+| [ADR-0029](../adr/0029-email-infrastructure-mailpit.md) | Email infrastructure (Mailpit) |
+| [ADR-0030](../adr/0030-bdd-email-parallel-strategy.md) | BDD parallel email assertions |
+
+### Documentation
+| Document | Description |
+|----------|-------------|
+| [EMAIL.md](EMAIL.md) | SMTP setup and Mailpit usage |
+| [MKCERT.md](MKCERT.md) | Local HTTPS certificate setup |
+| [PHASE_B_ROADMAP.md](PHASE_B_ROADMAP.md) | Remaining OIDC work |
+
+---
+
+*Developer onboarding doc — see ADR-0028 for implementation details.*

documentation/CLI.md

@@ -0,0 +1,251 @@
+# CLI Management Guide
+
+Complete reference for the `dance-lessons-coach` CLI, server lifecycle, and configuration. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.
+
+## Cobra CLI (Recommended)
+
+`dance-lessons-coach` includes a modern CLI built with Cobra:
+
+```bash
+# Show help and available commands
+./bin/dance-lessons-coach --help
+
+# Show version information
+./bin/dance-lessons-coach version
+
+# Greet someone by name
+./bin/dance-lessons-coach greet John
+
+# Start the server
+./bin/dance-lessons-coach server
+```
+
+**Available Commands:**
+
+- `version` — Print version information
+- `server` — Start the dance-lessons-coach server
+- `greet [name]` — Greet someone by name
+- `help` — Built-in help system
+- `completion` — Generate shell completion scripts
+
+**Server Command Flags:**
+
+- `--config` — Config file path
+- `--env` — Environment (`dev`, `staging`, `prod`)
+- `--debug` — Enable debug logging
+
+## Version Information
+
+The server provides runtime version information:
+
+```bash
+# Check version using new CLI
+./bin/dance-lessons-coach version
+
+# Check version using server binary
+./bin/server --version
+
+# Output:
+dance-lessons-coach Version Information:
+  Version:   1.0.0
+  Commit:    abc1234
+  Built:     2026-04-05T10:00:00+0000
+  Go:        go1.26.1
+```
+
+For full version management workflow (bump, release, build with version), see [`version-management-guide.md`](version-management-guide.md).
+
+## Server Control Script
+
+A shell script manages the server lifecycle:
+
+```bash
+cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
+
+./scripts/start-server.sh start     # Start the server
+./scripts/start-server.sh status    # Check server status
+./scripts/start-server.sh test      # Test API endpoints
+./scripts/start-server.sh logs      # View server logs
+./scripts/start-server.sh stop      # Stop the server
+./scripts/start-server.sh restart   # Restart
+```
+
+**Available subcommands:**
+
+- `start` — Start the server in background with proper logging
+- `stop` — Stop the server gracefully
+- `restart` — Restart the server
+- `status` — Check if server is running
+- `logs` — Show recent server logs
+- `test` — Test all API endpoints
+
+## Manual Server Management
+
+For direct control:
+
+```bash
+cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
+./scripts/start-server.sh start
+```
+
+**Expected output:**
+
+```
+Server running on :8080
+[INF] Starting HTTP server on :8080
+[TRC] Registering greet routes
+[TRC] Greet routes registered
+```
+
+**Features:**
+
+- Context-aware server initialization
+- Graceful shutdown handling
+- Signal-based termination (`SIGINT`, `SIGTERM`)
+- 30-second shutdown timeout
+- Proper resource cleanup
+
+## Configuration
+
+Configuration via environment variables with `DLC_` prefix:
+
+| Option | Environment Variable | Default | Description |
+|---|---|---|---|
+| Host | `DLC_SERVER_HOST` | `0.0.0.0` | Server bind address |
+| Port | `DLC_SERVER_PORT` | `8080` | Server listening port |
+| Shutdown Timeout | `DLC_SHUTDOWN_TIMEOUT` | `30s` | Graceful shutdown timeout |
+| JSON Logging | `DLC_LOGGING_JSON` | `false` | Enable JSON format logging |
+| Log Output | `DLC_LOGGING_OUTPUT` | `""` | Log output file path (empty for stderr) |
+
+**Examples:**
+
+```bash
+# Custom port
+export DLC_SERVER_PORT=9090
+./scripts/start-server.sh start
+
+# Custom host and port
+export DLC_SERVER_HOST="127.0.0.1"
+export DLC_SERVER_PORT=8081
+./scripts/start-server.sh start
+
+# Custom shutdown timeout
+export DLC_SHUTDOWN_TIMEOUT=45s
+
+# Enable JSON logging
+export DLC_LOGGING_JSON=true
+
+# Log to file
+export DLC_LOGGING_OUTPUT="server.log"
+
+# Combined: JSON logging to file
+export DLC_LOGGING_JSON=true
+export DLC_LOGGING_OUTPUT="server.json.log"
+```
+
+**Configuration File Support:**
+
+A `config.example.yaml` file is provided as a template. By default, the application looks for `config.yaml` in the current working directory.
+
+To specify a custom config file path, set the `DLC_CONFIG_FILE` environment variable:
+
+```bash
+DLC_CONFIG_FILE="/path/to/config.yaml" go run ./cmd/server
+```
+
+Example `config.yaml`:
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+shutdown:
+  timeout: 30s
+
+logging:
+  json: false
+```
+
+**Configuration Loading Precedence:**
+
+1. **File-based configuration** (highest precedence)
+2. **Environment variables** (override defaults, overridden by config file)
+3. **Default values** (fallback)
+
+All configuration is validated on startup. Invalid configurations cause server startup failure. Configuration values and source are logged at startup.
+
+**Verification:**
+
+```bash
+DLC_SERVER_PORT=9090 DLC_SERVER_HOST="127.0.0.1" ./scripts/start-server.sh start
+
+curl http://127.0.0.1:9090/api/health
+# Expected: {"status":"healthy"}
+```
+
+## Server Status
+
+```bash
+# Check health endpoint
+curl -s http://localhost:8080/api/health
+
+# Check readiness endpoint
+curl -s http://localhost:8080/api/ready
+```
+
+**Expected responses:**
+
+- Health: `{"status":"healthy"}`
+- Readiness (normal): `{"ready":true}`
+- Readiness (during shutdown): `{"ready":false}` (HTTP 503)
+
+**Endpoint Differences:**
+
+- **Health endpoint** (`/api/health`): Indicates if the application is running and functional
+- **Readiness endpoint** (`/api/ready`): Indicates if the application is ready to accept traffic
+
+**Use Cases:**
+
+- **Health**: Used by load balancers to check if the app is alive
+- **Readiness**: Used by Kubernetes / service meshes to determine if the app can accept new requests
+
+**During Graceful Shutdown:**
+
+- Health endpoint continues to return `{"status":"healthy"}`
+- Readiness endpoint returns `{"ready":false}` with HTTP 503 Service Unavailable
+- This allows existing requests to complete while preventing new requests
+
+## Stopping the Server
+
+To stop the server gracefully:
+
+```bash
+# Send SIGTERM for graceful shutdown
+kill -TERM $(lsof -ti :8080)
+
+# Or send SIGINT (Ctrl+C equivalent)
+pkill -INT -f "go run"
+```
+
+**Graceful shutdown process:**
+
+1. Server receives termination signal
+2. Logs shutdown message
+3. Stops accepting new connections
+4. Waits up to 30 seconds for active requests to complete
+5. Closes all connections cleanly
+6. Exits with proper cleanup
+
+For force stop (if graceful shutdown hangs):
+
+```bash
+kill -9 $(lsof -ti :8080)
+```
+
+**Verification:**
+
+```bash
+curl -s http://localhost:8080/api/health
+# Should return connection refused
+```

documentation/CODE_EXAMPLES.md

@@ -0,0 +1,59 @@
+# Code Examples
+
+Snippets and patterns used across the `dance-lessons-coach` codebase. Extracted from the original `AGENTS.md` (Tâche 6 restructure).
+
+## Adding a New API Endpoint
+
+```go
+// 1. Add to interface
+func (h *apiV1GreetHandler) RegisterRoutes(router chi.Router) {
+    router.Get("/", h.handleGreetQuery)
+    router.Get("/{name}", h.handleGreetPath)
+    router.Post("/custom", h.handleCustomGreet) // New endpoint
+}
+
+// 2. Implement handler
+func (h *apiV1GreetHandler) handleCustomGreet(w http.ResponseWriter, r *http.Request) {
+    // Parse request
+    // Call service
+    // Return JSON response
+}
+```
+
+## Logging with Zerolog
+
+```go
+// Trace level logging
+log.Trace().Ctx(ctx).Str("key", "value").Msg("message")
+
+// Info level
+log.Info().Msg("Important event")
+
+// Error level
+log.Error().Err(err).Msg("Error occurred")
+```
+
+For the full logging strategy (when to use Trace vs Info, performance considerations), see [ADR-0003 — Zerolog Logging](../adr/0003-zerolog-logging.md).
+
+## Using `context.Context`
+
+```go
+// Pass context through calls
+func handler(w http.ResponseWriter, r *http.Request) {
+    result := service.Greet(r.Context(), "John")
+    // ...
+}
+
+// Create context with values
+ctx := context.WithValue(r.Context(), "key", "value")
+
+// Create context with timeout
+ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+defer cancel()
+```
+
+For the rationale behind context-aware services, see [ADR-0004 — Interface-Based Design](../adr/0004-interface-based-design.md).
+
+## Best Practices Reminders
+
+For higher-level guidance on code organization, error handling, performance, and testing, see [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md#best-practices) section "Best Practices".

documentation/EMAIL.md

@@ -0,0 +1,107 @@
+# Email infrastructure
+
+Outgoing email transport. Per [ADR-0029](../adr/0029-email-infrastructure-mailpit.md): Mailpit for local dev + BDD tests, production sender deferred.
+
+## Local setup (one-time)
+
+Mailpit is part of `docker-compose.yml`:
+
+```bash
+docker compose up -d                 # starts postgres + mailpit
+docker compose ps                    # confirm both running
+```
+
+Mailpit listens on:
+- **SMTP submission** — `localhost:1025` (the app sends here)
+- **HTTP UI / API** — http://localhost:8025 (you inspect captured messages here)
+
+No real emails leave the docker network. No internet required.
+
+## Application configuration
+
+The application's outgoing transport is configured under `auth.email.*` in `config.yaml` (or via `DLC_AUTH_EMAIL_*` env vars). Defaults already match local Mailpit:
+
+```yaml
+auth:
+  email:
+    from: noreply@dance-lessons-coach.local
+    smtp_host: localhost
+    smtp_port: 1025
+    smtp_use_tls: false
+    timeout: 10s
+    # smtp_username + smtp_password left empty for local Mailpit
+```
+
+For production, override these to point at the chosen provider (SES, Postmark, etc.).
+
+## Inspecting messages
+
+### Web UI
+
+http://localhost:8025 — list of all captured messages, search, raw view, HTML preview.
+
+### HTTP API (for automation)
+
+```bash
+# Latest 10 messages (no filter — /api/v1/messages is for pagination)
+curl -s 'http://localhost:8025/api/v1/messages?limit=10' | jq
+
+# Messages for a specific recipient — use /api/v1/search, NOT /messages
+# (the latter's `query` param is for pagination only, not filtering ;
+# verified empirically 2026-05-05)
+curl -s 'http://localhost:8025/api/v1/search?query=to:test-user@bdd.local' | jq
+
+# Get a specific message by ID (full content, headers, attachments)
+curl -s 'http://localhost:8025/api/v1/message/<id>' | jq
+
+# Purge messages for a recipient (used in test cleanup) — also via /search
+curl -X DELETE 'http://localhost:8025/api/v1/search?query=to:test-user@bdd.local'
+```
+
+Full API: https://mailpit.axllent.org/docs/api-v1/
+
+## Sending email from Go code
+
+```go
+import "dance-lessons-coach/pkg/email"
+
+sender := email.NewSMTPSender(email.SMTPConfig{
+    Host: cfg.GetEmailConfig().SMTPHost,
+    Port: cfg.GetEmailConfig().SMTPPort,
+    // username/password optional — empty means no AUTH (Mailpit local)
+})
+
+err := sender.Send(ctx, email.Message{
+    To:       "alice@example.com",
+    From:     cfg.GetEmailConfig().From,
+    Subject:  "Your magic link",
+    BodyText: "Click: https://example.com/magic-link/consume?token=...",
+    Headers: map[string]string{
+        // optional — useful for BDD test correlation
+        "X-Trace-Id": "req-abc-123",
+    },
+})
+```
+
+Or, when both text and HTML are needed (`multipart/alternative`):
+
+```go
+err := sender.Send(ctx, email.Message{
+    To: "alice@example.com", From: "...", Subject: "...",
+    BodyText: "Click: https://...",
+    BodyHTML: `<p>Click <a href="https://...">your magic link</a></p>`,
+})
+```
+
+## Production sender (TBD)
+
+Not chosen yet. When ready, implement another `email.Sender` in
+`pkg/email/<provider>_sender.go` and wire it via the config. The
+`Sender` interface is the swap point — call sites don't change.
+
+## Cross-references
+
+- [ADR-0028 — Passwordless auth migration](../adr/0028-passwordless-auth-migration.md) (consumes this infrastructure)
+- [ADR-0029 — Email infrastructure decision](../adr/0029-email-infrastructure-mailpit.md)
+- [ADR-0030 — BDD email parallel strategy](../adr/0030-bdd-email-parallel-strategy.md)
+- [Mailpit docs](https://mailpit.axllent.org/docs/)

documentation/HISTORY.md

@@ -0,0 +1,83 @@
+# Development History
+
+This document records the historical development phases of `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe (128k context).
+
+All phases below are **completed** ✅. They are kept here for traceability and onboarding context — refer to ADRs (`adr/`) for the technical decisions behind each phase.
+
+## Phase 1: Foundation
+
+- Go 1.26.1 environment setup
+- Project structure with `cmd/` and `pkg/` directories
+- Core Greet service implementation
+- CLI interface
+- Unit tests
+
+## Phase 2: Web API
+
+- Chi router integration
+- Versioned API endpoints (`/api/v1`)
+- Health endpoint (`/api/health`)
+- JSON responses with proper headers
+
+## Phase 3: Logging & Architecture
+
+- Zerolog integration with Trace level
+- Context-aware logging
+- Interface-based design patterns
+- Dependency injection
+
+## Phase 4: Documentation & Testing
+
+- Comprehensive `AGENTS.md`
+- `README.md` with usage instructions
+- Server management guide
+- API endpoint documentation
+
+## Phase 5: Configuration Management
+
+- Viper integration for configuration
+- Environment variable support with `DLC_` prefix
+- Customizable server host/port
+- Configurable shutdown timeout
+- Configuration validation and logging
+- Example configuration file
+
+## Phase 6: Graceful Shutdown
+
+- Context-aware server initialization
+- Signal-based termination (`SIGINT`, `SIGTERM`)
+- Configurable shutdown timeout
+- Readiness endpoint for Kubernetes/service mesh integration
+- Proper resource cleanup during shutdown
+- Health endpoint remains healthy during graceful shutdown
+
+## Phase 7: OpenTelemetry Integration
+
+- OpenTelemetry Go libraries integration
+- Jaeger compatibility for distributed tracing
+- Middleware-only approach using `otelhttp.NewHandler`
+- Configurable sampling strategies
+- Graceful shutdown of tracer provider
+- OTLP exporter with gRPC support
+
+## Phase 8: Build System & Documentation
+
+- Build script for binary compilation
+- Binary output to `bin/` directory
+- Comprehensive commit conventions with gitmoji reference
+- Updated documentation with Jaeger integration guide
+- Cleaned up configuration files
+- Enhanced logging configuration with file output support
+
+## Phase 9: Final Refinements
+
+- Removed unnecessary `time.Sleep` for log flushing
+- Changed server operational logs from Info to Trace level
+- Moved all logging setup logic to config package
+- Simplified server entrypoint to 27 lines
+- Verified all functionality with comprehensive testing
+- Updated documentation to reflect final architecture
+
+## Beyond Phase 9
+
+Subsequent work (CI/CD, BDD scenarios, ADR audit, JWT, config hot-reloading) is tracked in the [Changelog](../CHANGELOG.md) and the corresponding [ADRs](../adr/).

documentation/MISTRAL-AUTONOMOUS-PATTERN.md

@@ -0,0 +1,219 @@
+# Mistral Vibe Autonomous Pattern
+
+**Document ID:** MISTRAL-AUTONOMOUS-PATTERN  
+**Date:** 2026-05-05  
+**Status:** Active  
+**Author:** Mistral Vibe (batch10-task-mistral-pattern-doc)  
+**Audience:** Project contributors, future trainers
+
+---
+
+## 1. What you'll see
+
+PRs authored by "Gabriel Radureau" with commit messages ending in "Mistral Vibe" references. PR titles start with gitmoji. Branch names follow `vibe/<slug>` pattern.
+
+| PR | Date | Title | Branch | Status |
+|----|------|-------|--------|--------|
+| #67 | 2026-05-05 | :memo: docs: email infrastructure | `vibe/batch4-task-a-email-infra` | Merged |
+| #74 | 2026-05-05 | :robot: feat: BDD Mailpit helper | `vibe/batch5-task-b-bdd-mailpit` | Merged |
+| #75 | 2026-05-05 | :elephant: feat: magic_link_tokens table | `vibe/batch5-task-c-db-magic-link` | Merged |
+| #76 | 2026-05-05 | :rocket: feat: magic link handlers | `vibe/batch5-task-d-handlers` | Merged |
+| #77 | 2026-05-05 | :test_tube: test: magic link BDD | `vibe/batch5-task-e-bdd` | Merged |
+
+---
+
+## 2. The pattern (high-level)
+
+```
+Operator Brief → Worktree Setup → Worker Execution → PR Lifecycle → Merge
+```
+
+### 2.1 Operator brief
+Human or trainer (Claude) writes a `CONTEXT.md` brief in a workspace under `~/Work/Vibe/workspaces/<slug>/`. The brief contains:
+- Mission statement
+- Goal and constraints
+- Process instructions
+- Hard rules
+- Specification
+
+### 2.2 Worktree setup
+A `vibe-workspace.sh --worktree` script creates an isolated git worktree:
+- Branches from current `origin/main`
+- Creates branch `vibe/<slug>`
+- Isolates git state in a dedicated directory
+- No race conditions (addresses Q-038)
+
+### 2.3 Worker execution
+A Mistral Vibe worker (`vibe -p`) runs end-to-end:
+1. Reads the brief from `CONTEXT.md`
+2. Executes coding tasks (codes, builds, tests)
+3. Commits changes with appropriate messages
+4. Pushes to remote branch
+5. Opens PR via Gitea API
+6. Attempts auto-merge
+
+### 2.4 Parallel operation
+- Multiple workers run concurrently (2-4 typical)
+- Each worker operates in its own worktree
+- No git checkout collisions
+- Shared origin main as base
+
+### 2.5 Dispatch orchestration
+A `dispatch-batch.sh` script:
+- Orchestrates batches of 2-4 workers
+- Auto-merges PRs that workers opened but didn't merge
+- Ensures all PRs reach merged state
+- Handles cross-worker dependencies
+
+---
+
+## 3. Why this works
+
+### 3.1 Worktree isolation
+Git worktrees provide complete isolation of git state. Each worker has its own:
+- Working directory
+- Index (staging area)
+- HEAD pointer
+- Branch reference
+
+This eliminates race conditions documented in Q-038 of the harness logs.
+
+### 3.2 Pre-fetched origin
+Origin is pre-fetched before worktree creation (Q-060 fix). This guarantees:
+- All workers branch from current main
+- No stale base branches
+- Consistent starting point across batch
+
+### 3.3 Full PR lifecycle
+Workers handle the complete PR lifecycle:
+- Code implementation
+- Build and test execution
+- Commit with proper conventions
+- Push to remote
+- PR creation via Gitea API
+- Merge via Gitea API (squash merge default)
+
+### 3.4 Trainer takeover
+For the rare gaps (~5% of cases):
+- Price-cap restrictions
+- Broken Mistral tests
+- Ambiguous requirements
+
+Trainer (Claude) takeover within ~5 minutes covers these edge cases.
+
+---
+
+## 4. How to read PR provenance
+
+### 4.1 Commit message markers
+Look for these patterns in commit messages:
+
+| Marker | Meaning |
+|--------|---------|
+| `Mostly Mistral Vibe authored` | Mixed human + AI authorship |
+| `100% Mistral autonomous` | Fully autonomous workflow |
+| `batch<N>-task-<X>` | Brief slug reference |
+| `Q-058 trainer takeover` | Specific quirk reference |
+| `Q-062 fix applied` | Quirk mitigation applied |
+
+### 4.2 Branch naming
+Branch names encode the workflow:
+```
+vibe/<batch>-<task>-<description>
+```
+Examples:
+- `vibe/batch4-task-a-email-infra`
+- `vibe/batch10-task-mistral-pattern-doc`
+
+### 4.3 PR title conventions
+PR titles use gitmoji prefix:
+- `:memo:` - Documentation
+- `:robot:` - AI/automation
+- `:elephant:` - Database
+- `:rocket:` - Feature
+- `:test_tube:` - Testing
+
+---
+
+## 5. Reproducing the pattern
+
+### 5.1 Quickstart guide
+See `~/.vibe/scripts/QUICKSTART-DISPATCH-BATCH.md` for complete how-to guide.
+
+### 5.2 Resources
+
+| Resource | Path | Description |
+|----------|------|-------------|
+| Brief template | `~/.vibe/skills/prompt-builder/examples/dispatch-batch-task.md` | Standardized brief format |
+| Mistral quirks | `~/.vibe/memory/reference/mistral-quirks.md` | Accumulated lessons (Q-001 through Q-063 as of 2026-05-05) |
+| Architecture doc | `~/.vibe/memory/reference/architecture-mapreduce-orchestration.md` | Design rationale |
+| Budget history | `~/.vibe/memory/reference/budget-history.jsonl` | Empirical cost data |
+
+---
+
+## 6. Numbers (2026-05-05 reference)
+
+### 6.1 Throughput
+| Metric | Value | Notes |
+|--------|-------|-------|
+| PRs merged (one day) | 20 | Mistral autonomous |
+| Wall-clock parallel (2 PRs) | ~2 minutes | vs ~3-4 minutes serial |
+| Wall-clock parallel (4 PRs) | ~2-3 minutes | Batch efficiency |
+
+### 6.2 Cost
+| PR Type | Cost Range | Notes |
+|---------|------------|-------|
+| Simple PR | $0.5-1.5 | Documentation, minor changes |
+| Code-heavy PR | $2-3 | Complex logic, multiple files |
+| Complex PR | $3-5 | Architecture changes, deep refactoring |
+
+### 6.3 Autonomy rate
+| Metric | Value |
+|--------|-------|
+| Autonomy rate per batch | 95-100% |
+| Trainer takeover rate | 5% |
+| Takeover reasons | Price-cap (2%), broken tests (2%), ambiguity (1%) |
+
+---
+
+## 7. Future evolution
+
+### 7.1 Phase 1bis (current)
+- Multi-process workers operating in parallel
+- Claude trainer reduces observations
+- Improves harness reliability
+- Current state as of 2026-05-05
+
+### 7.2 Phase 2 (target)
+- Mistral meta-agent performs reduce phase
+- Full autonomy loop without Claude
+- Self-improving pattern
+- Target: Q3 2026
+
+### 7.3 Long-term vision
+- Fully autonomous feature development
+- Self-healing test failures
+- Cost-optimized batch dispatch
+- Multi-repository orchestration
+
+---
+
+## 8. Cross-references
+
+### 8.1 Related ADRs
+| ADR | Description |
+|-----|-------------|
+| [ADR-0001](../adr/0001-go-1.26.1-standard.md) | Go 1.26.1 standard |
+| [ADR-0008](../adr/0008-bdd-testing.md) | BDD with Godog |
+| [ADR-0028](../adr/0028-passwordless-auth-migration.md) | Passwordless auth (Phase A complete) |
+
+### 8.2 Related documentation
+| Document | Description |
+|----------|-------------|
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | Contribution guidelines |
+| [AGENTS.md](../AGENTS.md) | Agent documentation |
+| [PHASE_B_ROADMAP.md](PHASE_B_ROADMAP.md) | Phase B OIDC roadmap |
+
+---
+
+*Developer onboarding doc — see QUICKSTART-DISPATCH-BATCH.md for implementation details.*

documentation/MKCERT.md

@@ -0,0 +1,120 @@
+# mkcert: Local HTTPS for Development
+
+## Overview
+
+This document describes how to set up local HTTPS development certificates using `mkcert`.
+
+OIDC providers **reject `http://localhost` as a redirect URI** by default for security reasons. To test OAuth 2.0 / OpenID Connect flows locally, the development server must be accessible via HTTPS. `mkcert` provides a zero-configuration local Certificate Authority that generates trusted certificates for localhost and custom domains.
+
+This setup is a prerequisite for **ADR-0028 Phase B** (OpenID Connect Authorization Code flow).
+
+## Why mkcert
+
+- **Trusted locally**: Certificates are automatically trusted by the system root store (macOS, Linux, Windows)
+- **No configuration**: Single commands to create and install the CA
+- **Local-only**: Certificates are valid only for localhost development, never exposed to production
+- **Industry standard**: Widely adopted tool for local HTTPS development
+
+## Installation
+
+### macOS (Homebrew)
+
+```bash
+brew install mkcert
+mkcert -install
+```
+
+The `mkcert -install` command creates and installs a local Certificate Authority in your system trust store.
+
+### Linux
+
+See [mkcert GitHub](https://github.com/FiloSottile/mkcert#installation) for distribution-specific instructions.
+
+### Windows
+
+See [mkcert GitHub](https://github.com/FiloSottile/mkcert#installation) for Windows installation.
+
+## Generate Certificates
+
+Use the provided Make target to generate certificates for localhost development:
+
+```bash
+make cert
+```
+
+This runs the following command:
+
+```bash
+mkcert -cert-file ./certs/dev-cert.pem -key-file ./certs/dev-key.pem localhost 127.0.0.1 ::1
+```
+
+### Output Files
+
+| File | Description |
+|------|-------------|
+| `./certs/dev-cert.pem` | TLS certificate for localhost, 127.0.0.1, and ::1 |
+| `./certs/dev-key.pem` | Private key for the certificate |
+
+Both files are created in the `./certs/` directory at the project root.
+
+## Use in Development
+
+Once certificates are generated, start the server with TLS enabled:
+
+```bash
+./bin/server --tls-cert ./certs/dev-cert.pem --tls-key ./certs/dev-key.pem
+```
+
+> **Note**: The `--tls-cert` and `--tls-key` flags are **not yet implemented** — this is planned for ADR-0028 Phase B.4. The Makefile and certificate generation are prepared in advance so that when the server TLS support is added, the certificates are ready.
+
+The server will then be accessible at:
+- `https://localhost:8080` (or the configured port)
+- `https://127.0.0.1:8080`
+- `https://[::1]:8080`
+
+All OIDC callback URLs must use HTTPS with one of these hostnames.
+
+## Clean Up
+
+To remove generated certificates:
+
+```bash
+make clean-cert
+```
+
+This deletes the entire `./certs/` directory.
+
+## .gitignore
+
+The `certs/` directory contains locally-generated certificates and **must not be committed** to version control.
+
+Ensure `certs/` is in your `.gitignore`. If it is not already present, add it:
+
+```bash
+echo "certs/" >> .gitignore
+```
+
+## Cross-References
+
+- [ADR-0028: Passwordless authentication: magic link → OpenID Connect](../adr/0028-passwordless-auth-migration.md) — Phase B describes the OIDC implementation that requires HTTPS
+- [mkcert GitHub Repository](https://github.com/FiloSottile/mkcert) — Official documentation
+
+## Troubleshooting
+
+### "mkcert not found" when running `make cert`
+
+Ensure `mkcert` is installed and available in your `PATH`. The Makefile checks for this and will display an error message if `mkcert` is not found.
+
+### Certificate not trusted by browser
+
+Run `mkcert -install` again. On macOS, you may need to restart your browser completely (close all windows, not just tabs).
+
+### Port already in use
+
+If another process is using the port (e.g., a non-TLS server on port 8080), stop that process first or configure the server to use a different port.
+
+## See Also
+
+- `make help` — List all available Make targets
+- [documentation/API.md](API.md) — API endpoints reference
+- [documentation/BDD_GUIDE.md](BDD_GUIDE.md) — BDD testing guide

documentation/OBSERVABILITY.md

@@ -0,0 +1,94 @@
+# Observability — OpenTelemetry & Jaeger Integration
+
+Tracing setup for `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.
+
+The application supports OpenTelemetry for distributed tracing with Jaeger compatibility.
+
+## Configuration
+
+Enable OpenTelemetry in your `config.yaml`:
+
+```yaml
+telemetry:
+  enabled: true
+  otlp_endpoint: "localhost:4317"
+  service_name: "dance-lessons-coach"
+  insecure: true
+  sampler:
+    type: "parentbased_always_on"
+    ratio: 1.0
+```
+
+Or via environment variables:
+
+```bash
+export DLC_TELEMETRY_ENABLED=true
+export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317"
+export DLC_TELEMETRY_SERVICE_NAME="dance-lessons-coach"
+export DLC_TELEMETRY_INSECURE=true
+export DLC_TELEMETRY_SAMPLER_TYPE="parentbased_always_on"
+export DLC_TELEMETRY_SAMPLER_RATIO=1.0
+```
+
+## Testing with Jaeger
+
+**1. Start Jaeger in Docker:**
+
+```bash
+docker run -d --name jaeger \
+  -e COLLECTOR_OTLP_ENABLED=true \
+  -p 16686:16686 \
+  -p 4317:4317 \
+  jaegertracing/all-in-one:latest
+```
+
+**2. Start the server with OpenTelemetry enabled:**
+
+```bash
+# Using config file
+./scripts/start-server.sh start
+
+# Or with environment variables
+DLC_TELEMETRY_ENABLED=true ./scripts/start-server.sh start
+```
+
+**3. Make API requests:**
+
+```bash
+curl http://localhost:8080/api/v1/greet/John
+```
+
+**4. View traces in Jaeger UI:**
+
+Open http://localhost:16686 and select the `dance-lessons-coach` service.
+
+## Sampler Types
+
+| Sampler | Behavior |
+|---|---|
+| `always_on` | Sample all traces |
+| `always_off` | Sample no traces |
+| `traceidratio` | Sample based on trace ID ratio |
+| `parentbased_always_on` | Sample based on parent span (always on) |
+| `parentbased_always_off` | Sample based on parent span (always off) |
+| `parentbased_traceidratio` | Sample based on parent span with ratio |
+
+## Testing Script
+
+A convenience script is provided:
+
+```bash
+./scripts/test-opentelemetry.sh
+```
+
+This script:
+
+1. Starts Jaeger container
+2. Starts the server with OpenTelemetry
+3. Makes test API calls
+4. Shows Jaeger UI URL
+5. Cleans up on exit
+
+## ADR Reference
+
+See [ADR-0007 — OpenTelemetry Integration](../adr/0007-opentelemetry-integration.md) for the full architectural decision and rationale (middleware-only approach, sampling strategy, OTLP/gRPC choice).

documentation/PHASE_B_ROADMAP.md

@@ -0,0 +1,145 @@
+# ADR-0028 Phase B Roadmap
+
+**Document ID:** PHASE_B_ROADMAP
+**Date:** 2026-05-05 evening
+**Status:** In Progress
+**Author:** AI Agent (vibe/batch4-task-b-phase-b-roadmap)
+
+---
+
+## Status as of 2026-05-05 evening
+
+- [x] ADR-0028 Phase A complete (PRs #59-#63, #65)
+- [x] Phase B.1 OIDC config (PR #64)
+- [x] Phase B prep : pkg/auth skeleton (PR #69) + mkcert doc (PR #68)
+- [x] Phase B.3 OIDC client implementation : ✅ (PR #74)
+- [x] Phase B.4 OIDC HTTP handlers + tests : ✅ (PR #75 + PR #76 follow-up tests)
+
+## Status as of 2026-05-05 evening (after autonomous Mistral session)
+
+Phase B is essentially complete except B.5. The OIDC client (B.3, PR #74), HTTP handlers and tests (B.4, PR #75 + PR #76) have been delivered and merged.
+
+---
+
+## Remaining work
+
+Phase B delivers OpenID Connect Authorization Code flow with PKCE. Work is organized into **3 shippable phases**, each deliverable as an independent PR. At the time of this update, only Phase B.5 (BDD scenarios) remains to be completed.
+
+### Phase B.3 — OIDC client implementation
+- **Goal:** Implement the core OIDC client methods in `pkg/auth/oidc.go`
+- **Tasks:**
+  - `Discover()`: HTTP GET to `/.well-known/openid-configuration`, parse + cache discovery document
+  - `RefreshJWKS()`: HTTP GET to JWKS URI, parse RSA public keys, cache with TTL
+  - `ExchangeCode()`: POST to token endpoint with code + PKCE verifier, return TokenResponse
+  - `ValidateIDToken()`: Verify signature against JWKS, validate standard claims (iss, aud, exp, iat)
+- **LOE:** ~200 lines of Go + unit tests
+- **Dependencies:** None (uses standard library `crypto/rsa`, `encoding/jwt`)
+- **Deliverable:** 1 PR
+
+### Phase B.4 — OIDC HTTP handlers
+- **Goal:** Add OIDC flow endpoints and wire them into the server
+- **Tasks:**
+  - Create `pkg/user/api/oidc_handler.go`
+  - `GET /api/v1/auth/oidc/start`:
+    - Generate state (CSRF protection) + PKCE verifier + challenge
+    - Store state + verifier (cookie or short-lived in-memory store)
+    - Redirect to provider's authorization endpoint
+  - `GET /api/v1/auth/oidc/callback`:
+    - Validate state parameter matches stored state
+    - Exchange code for tokens (calls B.3 client)
+    - Validate id_token (calls B.3 client)
+    - Issue internal JWT (reuse existing JWT manager from ADR-0021)
+    - Return JWT in Set-Cookie + JSON body
+  - Wire routes in `pkg/server/server.go`
+- **LOE:** ~150 lines of Go + unit tests + integration tests
+- **Dependencies:** B.3 (client methods must be implemented)
+- **Prerequisite:** Run `make cert` (mkcert, from PR #68) before starting dev
+- **Deliverable:** 1 PR
+
+### Phase B.5 — BDD coverage
+- **Goal:** End-to-end OIDC testing
+- **Tasks:**
+  - Create `features/auth/oidc.feature` with scenarios:
+    - Happy path: start → provider auth → callback → JWT issued
+    - Error: state mismatch
+    - Error: invalid code
+    - Error: expired id_token
+  - Use mock OIDC provider (local in-process) OR deterministic test against Authelia/Keycloak in docker-compose
+  - Follow ADR-0030 parallel BDD strategy for email assertions
+- **LOE:** ~150 lines of Gherkin + step definitions
+- **Dependencies:** B.3 + B.4 (endpoints must be operational)
+- **Deliverable:** 1 PR
+
+---
+
+## Dependencies and order
+
+```
+B.3 (OIDC client)
+    ↓
+B.4 (HTTP handlers) —— requires B.3
+    ↓
+B.5 (BDD coverage) —— requires B.3 + B.4
+```
+
+**Note:** mkcert (PR #68) is ready. When starting B.4 development, run `make cert` once to generate local HTTPS certificates.
+
+---
+
+## Out of scope for Phase B (deferred)
+
+| Item | Target Phase | Rationale |
+|------|--------------|-----------|
+| Decommission password auth | Phase C | Separate ADR after B is in production |
+| Multi-provider (Authelia + Google) | Phase B.6 (if needed) | Single provider sufficient for MVP |
+| JWKS rotation mid-flight retry | B.3 enhancement | Handle in initial implementation |
+| Token refresh flow | Future | Not required for auth code flow MVP |
+
+---
+
+## Risk register
+
+| Risk | Mitigation | Owner |
+|------|------------|-------|
+| JWKS rotation handling | Implement refresh + retry logic; key rotation must not break mid-flight validation | B.3 implementer |
+| PKCE storage | Use signed cookie or short-lived in-memory store; document trade-offs in implementation PR | B.4 implementer |
+| Testing without real provider | Use mock OIDC server for CI; local dev uses Authelia in docker-compose | B.5 implementer |
+| State CSRF protection | Use cryptographically random state; store server-side with short TTL | B.4 implementer |
+
+---
+
+## Cross-references
+
+- [ADR-0028: Passwordless authentication: magic link → OpenID Connect](../adr/0028-passwordless-auth-migration.md)
+- [ADR-0029: Email infrastructure (Mailpit)](../adr/0029-email-infrastructure-mailpit.md)
+- [ADR-0030: BDD email parallel strategy](../adr/0030-bdd-email-parallel-strategy.md)
+- [PR #59: Email infrastructure](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/59)
+- [PR #60: BDD Mailpit helper](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/60)
+- [PR #61: magic_link_tokens table](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/61)
+- [PR #62: Magic link handlers](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/62)
+- [PR #63: Magic link BDD](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/63)
+- [PR #64: OIDC config skeleton](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/64)
+- [PR #65: Magic link cleanup loop](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/65)
+- [PR #68: mkcert documentation](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/68)
+- [PR #69: pkg/auth skeleton](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/69)
+- [PR #74: Phase B.3 OIDC client implementation](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/74)
+- [PR #75: Phase B.4 OIDC HTTP handlers](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/75)
+- [PR #76: Phase B.4 follow-up tests](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/76)
+
+---
+
+## Appendix: File inventory
+
+Existing (merged):
+- `pkg/auth/oidc.go` — skeleton with TODO methods (PR #69)
+- `pkg/auth/oidc_test.go` — placeholder tests (PR #69)
+- `documentation/MKCERT.md` — mkcert setup guide (PR #68)
+- `Makefile` — includes `make cert` target (PR #68)
+
+To be created:
+- `pkg/auth/oidc.go` — complete implementation (B.3)
+- `pkg/user/api/oidc_handler.go` — HTTP handlers (B.4)
+- `pkg/server/server.go` — route wiring (B.4)
+- `features/auth/oidc.feature` — BDD scenarios (B.5)
+- `pkg/auth/oidc_test.go` — expanded unit tests (B.3)
+- `pkg/user/api/oidc_handler_test.go` — handler tests (B.4)

documentation/ROADMAP.md

@@ -0,0 +1,40 @@
+# Roadmap & Future Enhancements
+
+Tracking pending features and architectural improvements. Extracted from the original `AGENTS.md` (Tâche 6 restructure). Status updated continuously — items move to "Completed Features" section once shipped.
+
+## Potential Features
+
+- [ ] Database integration
+- [ ] Authentication / Authorization
+- [ ] Rate limiting
+- [ ] Metrics and monitoring
+- [ ] Docker containerization
+- ✅ CI/CD pipeline ([ADR-0016](../adr/0016-ci-cd-pipeline-design.md), [ADR-0017](../adr/0017-trunk-based-development-workflow.md))
+- [ ] Configuration hot reload
+- [ ] Circuit breakers
+
+## Architectural Improvements
+
+- [ ] Request validation middleware
+- ✅ OpenAPI / Swagger documentation with embedded spec
+- [ ] Enhanced OpenTelemetry instrumentation
+- [ ] Metrics collection and visualization
+- [ ] Health check improvements
+- [ ] Configuration validation enhancements
+
+## Completed Features
+
+- ✅ Graceful shutdown with readiness endpoint
+- ✅ OpenTelemetry integration with Jaeger support
+- ✅ Configuration management with Viper
+- ✅ Comprehensive logging with Zerolog
+- ✅ Build system with binary output
+- ✅ Complete documentation with commit conventions
+- ✅ Version management with runtime info
+
+## How to Propose a New Feature
+
+1. Open a Gitea issue describing the use case and acceptance criteria
+2. If the feature implies an architectural decision, draft an ADR (`adr/<NNNN>-<slug>.md`) following the template
+3. Reference the ADR + issue in any PR introducing the feature
+4. Update this roadmap (move from "Potential" to "Completed" when shipped)

documentation/STATUS.md

@@ -0,0 +1,49 @@
+# Project Status Snapshot
+
+Last updated 2026-05-05 evening.
+
+---
+
+## Active Features
+
+- Magic-link passwordless auth (POST /api/v1/auth/magic-link/request + GET /consume) — production-ready, ADR-0028 Phase A complete
+- OIDC client + HTTP handlers (GET /api/v1/auth/oidc/{provider}/start + /callback with PKCE) — production-ready code, BDD coverage TODO. ADR-0028 Phase B (B.1, B.3, B.4 + tests done ; B.5 BDD scenarios TODO).
+- Username + password auth — legacy (ADR-0018), kept during migration. To be decommissioned in Phase C.
+- Versioned API, JWT, OpenTelemetry, Swagger, BDD
+
+---
+
+## What's In Progress / Next
+
+- Phase B.5 BDD scenarios for OIDC (1 PR Mistral expected)
+- Phase C decommission password auth (separate ADR)
+
+---
+
+## Project Structure Highlights
+
+```
+adr/ : ADRs
+pkg/ : packages (auth, config, server, user, etc.)
+features/ : BDD scenarios
+documentation/ : docs index
+scripts/ : build + CI
+```
+
+---
+
+## Key Documentation Entry Points
+
+- README.md : quick start
+- AGENTS.md : agent + automation conventions
+- documentation/AUTH.md : auth system synthesis
+- documentation/MISTRAL-AUTONOMOUS-PATTERN.md : how Mistral PRs are shipped
+- documentation/PHASE_B_ROADMAP.md : remaining auth migration work
+- documentation/2026-05-05-AUTONOMOUS-SESSION-RECAP.md : the autonomous session highlights
+- adr/ : architecture decisions
+
+---
+
+## Today's Milestone (2026-05-05)
+
+27 PRs merged in 1 day via the Mistral autonomous multi-process pattern. ADR-0028 (passwordless auth migration) essentially complete except Phase B.5 BDD.

documentation/TROUBLESHOOTING.md

@@ -0,0 +1,107 @@
+# Troubleshooting
+
+Common issues and their resolution. Extracted from the original `AGENTS.md` and merged with relevant sections from `AGENT_USAGE_GUIDE.md` and `BDD_GUIDE.md`. Refer back to those guides for context-specific troubleshooting (agent workflows, BDD test failures).
+
+## Port Already in Use
+
+```bash
+# Find and kill process using port 8080
+kill -TERM $(lsof -ti :8080)
+
+# Force kill if graceful does not work
+kill -9 $(lsof -ti :8080)
+```
+
+## Server Not Responding
+
+```bash
+# Check if running
+curl -s http://localhost:8080/api/health
+
+# Restart server using control script
+./scripts/start-server.sh restart
+
+# View recent logs
+./scripts/start-server.sh logs
+```
+
+If health endpoint returns connection refused, the server may have crashed. Check logs in `./scripts/start-server.sh logs` for stack traces.
+
+## Dependency Issues
+
+```bash
+# Clean and rebuild
+go mod tidy
+go build ./...
+
+# If dependency version conflicts persist
+go mod download
+go mod verify
+```
+
+## Tests Failing
+
+### Unit tests
+
+```bash
+# Run with verbose output
+go test -v ./...
+
+# Check specific test
+go test ./pkg/greet/ -run TestName
+```
+
+### BDD tests
+
+See [`BDD_GUIDE.md`](BDD_GUIDE.md) for the full BDD troubleshooting workflow (Godog setup, scenario isolation, step matching). Common BDD issues:
+
+- **Step not found** → check `pkg/bdd/steps/` for the step definition file
+- **Scenario state leaking** → review [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) for the isolation pattern
+- **Database not reset** → ensure the test fixtures cleanup runs (BDD scenario After hooks)
+
+## Configuration Not Loading
+
+The application logs the configuration source at startup. Check logs for:
+
+```
+[INF] Configuration loaded from: file:config.yaml
+# or
+[INF] Configuration loaded from: env
+# or
+[INF] Configuration loaded from: defaults
+```
+
+If config is not loading as expected:
+
+1. Verify file exists and is readable: `ls -la config.yaml`
+2. Verify env vars are exported: `env | grep DLC_`
+3. Check for typos in keys (case-sensitive)
+4. Review [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md) section "Configuration troubleshooting"
+
+## OpenTelemetry Not Tracing
+
+1. Verify Jaeger is running: `docker ps | grep jaeger`
+2. Check `DLC_TELEMETRY_ENABLED=true` in environment or `telemetry.enabled: true` in config
+3. Verify OTLP endpoint reachable: `nc -zv localhost 4317`
+4. Check sampler is not `always_off`
+5. See [`OBSERVABILITY.md`](OBSERVABILITY.md) for full setup
+
+## Build Failures
+
+```bash
+# Clear caches
+go clean -cache -modcache
+go mod download
+
+# Rebuild
+go build ./...
+```
+
+If errors persist, see [`local-ci-cd-testing.md`](local-ci-cd-testing.md) for the CI/CD pipeline that mirrors the production build.
+
+## Where to Look Next
+
+- **Agent-specific issues** (vibe, mistral, programmer agent) → [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md)
+- **BDD-specific issues** → [`BDD_GUIDE.md`](BDD_GUIDE.md)
+- **Version/release issues** → [`version-management-guide.md`](version-management-guide.md)
+- **CI/CD issues** → [`local-ci-cd-testing.md`](local-ci-cd-testing.md)

features/auth/magic_link.feature

@@ -0,0 +1,34 @@
+@magic-link
+Feature: Passwordless magic-link sign-in
+  As a user without a password
+  I want to sign in by clicking a link sent to my email
+  So I can access the system without typing a password
+
+  Scenario: Happy path - request, receive, consume
+    Given the server is running
+    And I have an email address for this scenario
+    When I request a magic link for my email
+    Then I should receive an email with subject "Your sign-in link"
+    And the email contains a magic link token
+    When I consume the magic link token
+    Then the consume should succeed and return a JWT
+
+  Scenario: Token cannot be consumed twice
+    Given the server is running
+    And I have an email address for this scenario
+    When I request a magic link for my email
+    And the email contains a magic link token
+    When I consume the magic link token
+    Then the consume should succeed and return a JWT
+    When I consume the magic link token
+    Then the consume should fail with 401
+
+  Scenario: Missing token returns 400
+    Given the server is running
+    When I consume an empty magic link token
+    Then the response should have status 400
+
+  Scenario: Unknown token returns 401
+    Given the server is running
+    When I consume an unknown magic link token
+    Then the consume should fail with 401

features/greet/greet.feature

@@ -15,6 +15,16 @@ Feature: Greet Service
     When I request a greeting for "John"
     Then the response should be "{\"message\":\"Hello John!\"}"
 
+  @critical @v2-gate
+  Scenario: v2 endpoint returns 404 when api.v2_enabled is disabled
+    # In the default tag-filter run (~@v2), the test server starts with
+    # v2_enabled=false. The v2EnabledGate middleware (ADR-0023 Phase 4)
+    # returns 404 with a JSON body explaining the flag state.
+    Given the server is running
+    When I send a POST request to v2 greet with name "John"
+    Then the status code should be 404
+    And the response should contain "v2 API is currently disabled"
+
   @v2 @api
   Scenario: v2 greeting with JSON POST request
     Given the server is running with v2 enabled

iac/backend.tf

@@ -0,0 +1,6 @@
+terraform {
+  backend "gcs" {
+    bucket = "arcodange-tf"
+    prefix = "dance-lessons-coach/main"
+  }
+}

iac/main.tf

@@ -0,0 +1,10 @@
+locals {
+  app = {
+    name = "dance-lessons-coach"
+  }
+}
+
+module "app_roles" {
+  source = "git::ssh://git@192.168.1.202:2222/arcodange-org/tools.git//hashicorp-vault/iac/modules/app_roles?depth=1&ref=main"
+  name   = local.app.name
+}

iac/providers.tf

@@ -0,0 +1,17 @@
+terraform {
+  required_providers {
+    vault = {
+      source  = "vault"
+      version = "4.4.0"
+    }
+  }
+}
+
+provider "vault" {
+  address = "https://vault.arcodange.lab"
+  auth_login_jwt {
+    # TERRAFORM_VAULT_AUTH_JWT environment variable, set by the gitea OIDC step
+    mount = "gitea_jwt"
+    role  = "gitea_cicd_dance-lessons-coach"
+  }
+}

pkg/auth/context.go

@@ -0,0 +1,30 @@
+// Package auth — context keys and helpers for authentication state.
+//
+// This file owns the symbols that other packages use to read/write the
+// authenticated user from a request context. Previously these symbols
+// lived in pkg/greet/ which was the wrong home (auth concern in greet
+// package) ; moved here as part of the middleware design cleanup.
+package auth
+
+import (
+	"context"
+
+	"dance-lessons-coach/pkg/user"
+)
+
+// contextKey is unexported to prevent collisions with other packages
+// using string keys (Go convention).
+type contextKey string
+
+// UserContextKey is the key under which the authenticated user is
+// stored in the request context by AuthMiddleware.
+const UserContextKey contextKey = "authenticatedUser"
+
+// GetAuthenticatedUserFromContext extracts the authenticated user from
+// the request context. Returns (nil, false) if no user is present
+// (which is the case for unauthenticated requests AND for requests
+// that failed silent fail-through ; cf. AuthMiddleware semantics).
+func GetAuthenticatedUserFromContext(ctx context.Context) (*user.User, bool) {
+	u, ok := ctx.Value(UserContextKey).(*user.User)
+	return u, ok
+}

pkg/auth/oidc.go

@@ -0,0 +1,345 @@
+// Package auth provides OpenID Connect client primitives for the
+// dance-lessons-coach passwordless-auth migration (ADR-0028 Phase B).
+//
+// This file defines the client surface only. HTTP handlers wire-up
+// happens in pkg/user/api/oidc_handler.go (separate phase B.3).
+package auth
+
+import (
+	"context"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"math/big"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// OIDCClient is a per-provider OIDC client.
+// Holds the discovery document + JWKS cache + OAuth code-exchange config.
+type OIDCClient struct {
+	issuerURL    string
+	clientID     string
+	clientSecret string
+	httpClient   *http.Client
+
+	// discovery document, lazy-fetched on first use
+	discoveryMu sync.RWMutex
+	discovery   *Discovery
+
+	// JWKS cache (id_token signature verification keys), refreshed periodically
+	jwksMu      sync.RWMutex
+	jwks        map[string]*rsa.PublicKey
+	jwksFetched time.Time
+}
+
+// Discovery is the subset of the .well-known/openid-configuration document we use.
+type Discovery struct {
+	Issuer                string `json:"issuer"`
+	AuthorizationEndpoint string `json:"authorization_endpoint"`
+	TokenEndpoint         string `json:"token_endpoint"`
+	JWKSUri               string `json:"jwks_uri"`
+	UserinfoEndpoint      string `json:"userinfo_endpoint,omitempty"`
+}
+
+// TokenResponse is the response from the token endpoint after code exchange.
+type TokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	RefreshToken string `json:"refresh_token,omitempty"`
+	IDToken      string `json:"id_token"`
+	Scope        string `json:"scope,omitempty"`
+}
+
+// IDTokenClaims represents the parsed claims from an ID token.
+type IDTokenClaims struct {
+	jwt.RegisteredClaims
+	Email         string `json:"email,omitempty"`
+	EmailVerified bool   `json:"email_verified,omitempty"`
+	Name          string `json:"name,omitempty"`
+}
+
+// jwks represents the JWKS (JSON Web Key Set) response.
+type jwks struct {
+	Keys []jwk `json:"keys"`
+}
+
+// jwk represents a single JSON Web Key.
+type jwk struct {
+	Kid string `json:"kid"`
+	Kty string `json:"kty"`
+	N   string `json:"n"`
+	E   string `json:"e"`
+	Use string `json:"use,omitempty"`
+	Alg string `json:"alg,omitempty"`
+}
+
+// NewOIDCClient constructs a client. Discovery + JWKS are NOT fetched eagerly;
+// they are lazy-loaded on first use to avoid blocking server startup if the
+// provider is temporarily down.
+func NewOIDCClient(issuerURL, clientID, clientSecret string) *OIDCClient {
+	return &OIDCClient{
+		issuerURL:    issuerURL,
+		clientID:     clientID,
+		clientSecret: clientSecret,
+		httpClient:   &http.Client{Timeout: 10 * time.Second},
+		jwks:         make(map[string]*rsa.PublicKey),
+	}
+}
+
+// ClientID returns the OIDC client ID.
+func (c *OIDCClient) ClientID() string {
+	return c.clientID
+}
+
+// IssuerURL returns the OIDC issuer URL.
+func (c *OIDCClient) IssuerURL() string {
+	return c.issuerURL
+}
+
+// SetHTTPClient sets a custom HTTP client for testing.
+func (c *OIDCClient) SetHTTPClient(client *http.Client) {
+	c.httpClient = client
+}
+
+// decodeRSAPublicKey reconstructs an *rsa.PublicKey from JWK n and e values.
+func decodeRSAPublicKey(j jwk) (*rsa.PublicKey, error) {
+	nBytes, err := base64.RawURLEncoding.DecodeString(j.N)
+	if err != nil {
+		return nil, fmt.Errorf("decode n: %w", err)
+	}
+	eBytes, err := base64.RawURLEncoding.DecodeString(j.E)
+	if err != nil {
+		return nil, fmt.Errorf("decode e: %w", err)
+	}
+	n := new(big.Int).SetBytes(nBytes)
+	e := new(big.Int).SetBytes(eBytes)
+	return &rsa.PublicKey{N: n, E: int(e.Int64())}, nil
+}
+
+// Discover fetches and caches the .well-known document. Idempotent.
+// First call: HTTP fetch + cache. Subsequent calls: cached value.
+func (c *OIDCClient) Discover(ctx context.Context) (*Discovery, error) {
+	c.discoveryMu.RLock()
+	if c.discovery != nil {
+		c.discoveryMu.RUnlock()
+		return c.discovery, nil
+	}
+	c.discoveryMu.RUnlock()
+
+	c.discoveryMu.Lock()
+	defer c.discoveryMu.Unlock()
+
+	// Double-check after acquiring write lock
+	if c.discovery != nil {
+		return c.discovery, nil
+	}
+
+	wellKnownURL := fmt.Sprintf("%s/.well-known/openid-configuration", c.issuerURL)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, wellKnownURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create discovery request: %w", err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("fetch discovery: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("discovery HTTP %d", resp.StatusCode)
+	}
+
+	var disc Discovery
+	if err := json.NewDecoder(resp.Body).Decode(&disc); err != nil {
+		return nil, fmt.Errorf("decode discovery: %w", err)
+	}
+
+	c.discovery = &disc
+	return &disc, nil
+}
+
+// RefreshJWKS fetches JWKS URI, parse keys, populate jwks map.
+func (c *OIDCClient) RefreshJWKS(ctx context.Context) error {
+	// Ensure discovery is loaded
+	if c.discovery == nil {
+		if _, err := c.Discover(ctx); err != nil {
+			return fmt.Errorf("discover: %w", err)
+		}
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.discovery.JWKSUri, nil)
+	if err != nil {
+		return fmt.Errorf("create JWKS request: %w", err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("fetch JWKS: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("JWKS HTTP %d", resp.StatusCode)
+	}
+
+	var keySet jwks
+	if err := json.NewDecoder(resp.Body).Decode(&keySet); err != nil {
+		return fmt.Errorf("decode JWKS: %w", err)
+	}
+
+	c.jwksMu.Lock()
+	defer c.jwksMu.Unlock()
+
+	c.jwks = make(map[string]*rsa.PublicKey)
+	for _, key := range keySet.Keys {
+		if key.Kty == "RSA" {
+			pubKey, err := decodeRSAPublicKey(key)
+			if err != nil {
+				return fmt.Errorf("decode RSA key %s: %w", key.Kid, err)
+			}
+			c.jwks[key.Kid] = pubKey
+		}
+	}
+
+	c.jwksFetched = time.Now()
+	return nil
+}
+
+// ExchangeCode exchanges an authorization code for an access token and ID token.
+func (c *OIDCClient) ExchangeCode(ctx context.Context, code, codeVerifier, redirectURI string) (*TokenResponse, error) {
+	// Ensure discovery is loaded
+	if c.discovery == nil {
+		if _, err := c.Discover(ctx); err != nil {
+			return nil, fmt.Errorf("discover: %w", err)
+		}
+	}
+
+	form := url.Values{}
+	form.Set("grant_type", "authorization_code")
+	form.Set("code", code)
+	form.Set("code_verifier", codeVerifier)
+	form.Set("redirect_uri", redirectURI)
+	form.Set("client_id", c.clientID)
+	form.Set("client_secret", c.clientSecret)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.discovery.TokenEndpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("create token request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("exchange code: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("token HTTP %d", resp.StatusCode)
+	}
+
+	var tokenResp TokenResponse
+	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
+		return nil, fmt.Errorf("decode token response: %w", err)
+	}
+
+	return &tokenResp, nil
+}
+
+// ValidateIDToken verifies the signature and claims of an ID token.
+func (c *OIDCClient) ValidateIDToken(ctx context.Context, idToken string) (*IDTokenClaims, error) {
+	// First, parse without verification to get the kid
+	parser := jwt.NewParser()
+	unverifiedToken, _, err := parser.ParseUnverified(idToken, &IDTokenClaims{})
+	if err != nil {
+		return nil, fmt.Errorf("parse unverified token: %w", err)
+	}
+
+	claims, ok := unverifiedToken.Claims.(*IDTokenClaims)
+	if !ok {
+		return nil, fmt.Errorf("invalid claims type")
+	}
+
+	// Get kid from header
+	kid, ok := unverifiedToken.Header["kid"].(string)
+	if !ok || kid == "" {
+		return nil, fmt.Errorf("missing kid in token header")
+	}
+
+	// Get the key, refreshing JWKS if needed
+	c.jwksMu.RLock()
+	_, keyExists := c.jwks[kid]
+	c.jwksMu.RUnlock()
+
+	if !keyExists {
+		if err := c.RefreshJWKS(ctx); err != nil {
+			return nil, fmt.Errorf("refresh JWKS: %w", err)
+		}
+
+		c.jwksMu.RLock()
+		_, keyExists = c.jwks[kid]
+		c.jwksMu.RUnlock()
+
+		if !keyExists {
+			return nil, fmt.Errorf("key %s not found in JWKS", kid)
+		}
+	}
+
+	// Parse with verification
+	keyFunc := func(token *jwt.Token) (interface{}, error) {
+		if kid, ok := token.Header["kid"].(string); ok {
+			c.jwksMu.RLock()
+			defer c.jwksMu.RUnlock()
+			if key, exists := c.jwks[kid]; exists {
+				return key, nil
+			}
+		}
+		return nil, fmt.Errorf("key not found")
+	}
+
+	parsedToken, err := jwt.ParseWithClaims(idToken, &IDTokenClaims{}, keyFunc)
+	if err != nil {
+		return nil, fmt.Errorf("parse token: %w", err)
+	}
+
+	claims, ok = parsedToken.Claims.(*IDTokenClaims)
+	if !ok {
+		return nil, fmt.Errorf("invalid claims type after parse")
+	}
+
+	// Validate claims
+	if claims.Issuer != c.issuerURL {
+		return nil, fmt.Errorf("issuer mismatch: expected %s, got %s", c.issuerURL, claims.Issuer)
+	}
+
+	// Check audience contains clientID
+	audValid := false
+	if claims.Audience != nil {
+		for _, aud := range claims.Audience {
+			if aud == c.clientID {
+				audValid = true
+				break
+			}
+		}
+	}
+	if !audValid {
+		return nil, fmt.Errorf("audience does not contain client ID %s", c.clientID)
+	}
+
+	// Check expiration
+	if claims.ExpiresAt != nil && time.Now().UTC().After(claims.ExpiresAt.Time) {
+		return nil, fmt.Errorf("token expired")
+	}
+
+	return claims, nil
+}

pkg/auth/oidc_test.go

@@ -0,0 +1,431 @@
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/base64"
+	"fmt"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+func TestNewOIDCClient(t *testing.T) {
+	c := NewOIDCClient("https://example.com", "client_id", "client_secret")
+	if c == nil {
+		t.Fatal("NewOIDCClient returned nil")
+	}
+	if c.issuerURL != "https://example.com" {
+		t.Errorf("issuerURL not set: got %q", c.issuerURL)
+	}
+}
+
+func TestDiscover_HappyPath(t *testing.T) {
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+			server.URL, server.URL, server.URL, server.URL)))
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	disc, err := client.Discover(context.Background())
+	if err != nil {
+		t.Fatalf("Discover failed: %v", err)
+	}
+
+	if disc.Issuer != server.URL {
+		t.Errorf("issuer mismatch: got %s, want %s", disc.Issuer, server.URL)
+	}
+	if disc.TokenEndpoint != server.URL+"/token" {
+		t.Errorf("token endpoint mismatch: got %s", disc.TokenEndpoint)
+	}
+	if disc.JWKSUri != server.URL+"/jwks" {
+		t.Errorf("jwks_uri mismatch: got %s", disc.JWKSUri)
+	}
+}
+
+func TestDiscover_Idempotent(t *testing.T) {
+	var requestCount int32
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&requestCount, 1)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+			server.URL, server.URL, server.URL, server.URL)))
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// First call
+	_, err := client.Discover(context.Background())
+	if err != nil {
+		t.Fatalf("First Discover failed: %v", err)
+	}
+
+	// Second call
+	_, err = client.Discover(context.Background())
+	if err != nil {
+		t.Fatalf("Second Discover failed: %v", err)
+	}
+
+	if atomic.LoadInt32(&requestCount) != 1 {
+		t.Errorf("Expected 1 HTTP request, got %d", requestCount)
+	}
+}
+
+func generateTestRSAKey(t *testing.T) *rsa.PrivateKey {
+	t.Helper()
+	privKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("failed to generate RSA key: %v", err)
+	}
+	return privKey
+}
+
+func encodeRSAPublicKey(privKey *rsa.PrivateKey) (n, e string) {
+	n = base64.RawURLEncoding.EncodeToString(privKey.PublicKey.N.Bytes())
+	e = base64.RawURLEncoding.EncodeToString(big.NewInt(int64(privKey.PublicKey.E)).Bytes())
+	return n, e
+}
+
+func TestRefreshJWKS_HappyPath(t *testing.T) {
+	privKey := generateTestRSAKey(t)
+	n, e := encodeRSAPublicKey(privKey)
+
+	var discoveryCalled, jwksCalled bool
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			discoveryCalled = true
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)))
+			return
+		}
+		if r.URL.Path == "/jwks" {
+			jwksCalled = true
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"keys":[{"kid":"test-key-id","kty":"RSA","use":"sig","alg":"RS256","n":"%s","e":"%s"}]}`, n, e)))
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// First discover to populate discovery
+	_, err := client.Discover(context.Background())
+	if err != nil {
+		t.Fatalf("Discover failed: %v", err)
+	}
+
+	// Now refresh JWKS
+	err = client.RefreshJWKS(context.Background())
+	if err != nil {
+		t.Fatalf("RefreshJWKS failed: %v", err)
+	}
+
+	if !discoveryCalled {
+		t.Error("discovery endpoint was not called")
+	}
+	if !jwksCalled {
+		t.Error("jwks endpoint was not called")
+	}
+
+	// Check that jwks was populated
+	client.jwksMu.RLock()
+	defer client.jwksMu.RUnlock()
+
+	if len(client.jwks) != 1 {
+		t.Errorf("expected 1 key in jwks, got %d", len(client.jwks))
+	}
+
+	if _, exists := client.jwks["test-key-id"]; !exists {
+		t.Error("test-key-id not found in jwks")
+	}
+}
+
+func TestExchangeCode_HappyPath(t *testing.T) {
+	tokenResponseJSON := `{"access_token":"access-token-123","id_token":"id-token-456","token_type":"Bearer","expires_in":3600}`
+
+	var receivedForm url.Values
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)))
+			return
+		}
+		if r.URL.Path == "/token" {
+			if r.Method != http.MethodPost {
+				t.Errorf("expected POST, got %s", r.Method)
+				w.WriteHeader(http.StatusMethodNotAllowed)
+				return
+			}
+			if r.Header.Get("Content-Type") != "application/x-www-form-urlencoded" {
+				t.Errorf("expected Content-Type application/x-www-form-urlencoded, got %s", r.Header.Get("Content-Type"))
+				w.WriteHeader(http.StatusBadRequest)
+				return
+			}
+
+			err := r.ParseForm()
+			if err != nil {
+				t.Errorf("failed to parse form: %v", err)
+				w.WriteHeader(http.StatusBadRequest)
+				return
+			}
+			receivedForm = r.Form
+
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(tokenResponseJSON))
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// Discover first to populate discovery
+	_, err := client.Discover(context.Background())
+	if err != nil {
+		t.Fatalf("Discover failed: %v", err)
+	}
+
+	resp, err := client.ExchangeCode(context.Background(), "auth-code-789", "code-verifier-123", "https://app.example.com/callback")
+	if err != nil {
+		t.Fatalf("ExchangeCode failed: %v", err)
+	}
+
+	if resp.AccessToken != "access-token-123" {
+		t.Errorf("access token mismatch: got %s", resp.AccessToken)
+	}
+	if resp.IDToken != "id-token-456" {
+		t.Errorf("id token mismatch: got %s", resp.IDToken)
+	}
+	if resp.TokenType != "Bearer" {
+		t.Errorf("token type mismatch: got %s", resp.TokenType)
+	}
+
+	// Check form values
+	if receivedForm.Get("grant_type") != "authorization_code" {
+		t.Errorf("grant_type mismatch: got %s", receivedForm.Get("grant_type"))
+	}
+	if receivedForm.Get("code") != "auth-code-789" {
+		t.Errorf("code mismatch: got %s", receivedForm.Get("code"))
+	}
+	if receivedForm.Get("code_verifier") != "code-verifier-123" {
+		t.Errorf("code_verifier mismatch: got %s", receivedForm.Get("code_verifier"))
+	}
+	if receivedForm.Get("redirect_uri") != "https://app.example.com/callback" {
+		t.Errorf("redirect_uri mismatch: got %s", receivedForm.Get("redirect_uri"))
+	}
+	if receivedForm.Get("client_id") != "client_id" {
+		t.Errorf("client_id mismatch: got %s", receivedForm.Get("client_id"))
+	}
+	if receivedForm.Get("client_secret") != "client_secret" {
+		t.Errorf("client_secret mismatch: got %s", receivedForm.Get("client_secret"))
+	}
+}
+
+func TestValidateIDToken_HappyPath(t *testing.T) {
+	privKey := generateTestRSAKey(t)
+	n, e := encodeRSAPublicKey(privKey)
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)))
+			return
+		}
+		if r.URL.Path == "/jwks" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"keys":[{"kid":"test-key-id","kty":"RSA","use":"sig","alg":"RS256","n":"%s","e":"%s"}]}`, n, e)))
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// Create and sign a JWT
+	token := jwt.NewWithClaims(jwt.SigningMethodRS256, &IDTokenClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    server.URL,
+			Audience:  jwt.ClaimStrings{"client_id"},
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour)),
+			IssuedAt:  jwt.NewNumericDate(time.Now()),
+			Subject:   "user-123",
+		},
+		Email:         "user@example.com",
+		EmailVerified: true,
+		Name:          "Test User",
+	})
+	token.Header["kid"] = "test-key-id"
+
+	signedToken, err := token.SignedString(privKey)
+	if err != nil {
+		t.Fatalf("failed to sign token: %v", err)
+	}
+
+	// Validate the token
+	claims, err := client.ValidateIDToken(context.Background(), signedToken)
+	if err != nil {
+		t.Fatalf("ValidateIDToken failed: %v", err)
+	}
+
+	if claims.Issuer != server.URL {
+		t.Errorf("issuer mismatch: got %s, want %s", claims.Issuer, server.URL)
+	}
+	if claims.Subject != "user-123" {
+		t.Errorf("subject mismatch: got %s", claims.Subject)
+	}
+	if claims.Email != "user@example.com" {
+		t.Errorf("email mismatch: got %s", claims.Email)
+	}
+	if !claims.EmailVerified {
+		t.Error("email_verified should be true")
+	}
+	if claims.Name != "Test User" {
+		t.Errorf("name mismatch: got %s", claims.Name)
+	}
+}
+
+func TestValidateIDToken_RejectsExpired(t *testing.T) {
+	privKey := generateTestRSAKey(t)
+	n, e := encodeRSAPublicKey(privKey)
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)))
+			return
+		}
+		if r.URL.Path == "/jwks" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"keys":[{"kid":"test-key-id","kty":"RSA","use":"sig","alg":"RS256","n":"%s","e":"%s"}]}`, n, e)))
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// Create an expired JWT
+	token := jwt.NewWithClaims(jwt.SigningMethodRS256, &IDTokenClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    server.URL,
+			Audience:  jwt.ClaimStrings{"client_id"},
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(-time.Hour)), // Expired 1 hour ago
+			IssuedAt:  jwt.NewNumericDate(time.Now().Add(-2 * time.Hour)),
+			Subject:   "user-123",
+		},
+	})
+	token.Header["kid"] = "test-key-id"
+
+	signedToken, err := token.SignedString(privKey)
+	if err != nil {
+		t.Fatalf("failed to sign token: %v", err)
+	}
+
+	// Should fail due to expired token
+	_, err = client.ValidateIDToken(context.Background(), signedToken)
+	if err == nil {
+		t.Error("expected error for expired token, got nil")
+	}
+}
+
+func TestValidateIDToken_RejectsWrongIssuer(t *testing.T) {
+	privKey := generateTestRSAKey(t)
+	n, e := encodeRSAPublicKey(privKey)
+
+	wrongIssuer := "https://wrong-provider.example.com"
+
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)))
+			return
+		}
+		if r.URL.Path == "/jwks" {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fmt.Sprintf(`{"keys":[{"kid":"test-key-id","kty":"RSA","use":"sig","alg":"RS256","n":"%s","e":"%s"}]}`, n, e)))
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	client := NewOIDCClient(server.URL, "client_id", "client_secret")
+	client.httpClient = server.Client()
+
+	// Create a JWT with wrong issuer
+	token := jwt.NewWithClaims(jwt.SigningMethodRS256, &IDTokenClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    wrongIssuer,
+			Audience:  jwt.ClaimStrings{"client_id"},
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour)),
+			IssuedAt:  jwt.NewNumericDate(time.Now()),
+			Subject:   "user-123",
+		},
+	})
+	token.Header["kid"] = "test-key-id"
+
+	signedToken, err := token.SignedString(privKey)
+	if err != nil {
+		t.Fatalf("failed to sign token: %v", err)
+	}
+
+	// Should fail due to issuer mismatch
+	_, err = client.ValidateIDToken(context.Background(), signedToken)
+	if err == nil {
+		t.Error("expected error for wrong issuer, got nil")
+	}
+}

pkg/bdd/mailpit/client.go

@@ -0,0 +1,180 @@
+// Package mailpit is a thin client for the local Mailpit HTTP API,
+// used by BDD scenarios to assert on emails sent during a test.
+//
+// Per ADR-0030 (BDD email parallel strategy), each scenario uses a
+// unique recipient address so parallel scenarios cannot interfere.
+// The client exposes per-recipient query + delete + await operations.
+//
+// Production code MUST NOT depend on this package. It lives under
+// pkg/bdd/ specifically to signal "test-only".
+package mailpit
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// DefaultBaseURL is the local Mailpit HTTP API root used by the
+// docker-compose service (cf. ADR-0029).
+const DefaultBaseURL = "http://localhost:8025"
+
+// Client is a Mailpit HTTP API client. Safe for concurrent use.
+type Client struct {
+	BaseURL string
+	HTTP    *http.Client
+}
+
+// NewClient returns a Client pointing at the local Mailpit. The HTTP
+// client has a 5-second per-call timeout to fail fast in test setups
+// where Mailpit is down.
+func NewClient() *Client {
+	return &Client{
+		BaseURL: DefaultBaseURL,
+		HTTP:    &http.Client{Timeout: 5 * time.Second},
+	}
+}
+
+// Message is the metadata + body view returned by the Mailpit detail
+// endpoint. Fields are a subset of what Mailpit returns — only what
+// BDD scenarios need to assert on.
+type Message struct {
+	ID      string                 `json:"ID"`
+	From    Address                `json:"From"`
+	To      []Address              `json:"To"`
+	Subject string                 `json:"Subject"`
+	Text    string                 `json:"Text"`
+	HTML    string                 `json:"HTML"`
+	Date    time.Time              `json:"Date"`
+	Headers map[string]interface{} `json:"-"` // populated only via the Headers() helper
+}
+
+// Address is a Mailpit-formatted email address.
+type Address struct {
+	Name    string `json:"Name"`
+	Address string `json:"Address"`
+}
+
+// listResponse is the shape of GET /api/v1/messages.
+type listResponse struct {
+	Messages []messageSummary `json:"messages"`
+	Total    int              `json:"total"`
+}
+
+type messageSummary struct {
+	ID      string    `json:"ID"`
+	Subject string    `json:"Subject"`
+	Created time.Time `json:"Created"`
+}
+
+// MessagesTo returns the list of message IDs currently in Mailpit
+// addressed to the given recipient. Empty slice + nil error means
+// "no messages yet".
+func (c *Client) MessagesTo(ctx context.Context, to string) ([]string, error) {
+	// Mailpit's /api/v1/search supports the to:<addr> filter ; the more
+	// obvious-looking /api/v1/messages does NOT (the `query` param there
+	// is for pagination, not filtering — verified empirically 2026-05-05).
+	u := fmt.Sprintf("%s/api/v1/search?query=%s",
+		strings.TrimRight(c.BaseURL, "/"),
+		url.QueryEscape("to:"+to))
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("mailpit list: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("mailpit list: HTTP %d", resp.StatusCode)
+	}
+	var list listResponse
+	if err := json.NewDecoder(resp.Body).Decode(&list); err != nil {
+		return nil, fmt.Errorf("mailpit list decode: %w", err)
+	}
+	ids := make([]string, 0, len(list.Messages))
+	for _, m := range list.Messages {
+		ids = append(ids, m.ID)
+	}
+	return ids, nil
+}
+
+// Get fetches the full content of the message with the given ID.
+func (c *Client) Get(ctx context.Context, id string) (*Message, error) {
+	u := fmt.Sprintf("%s/api/v1/message/%s",
+		strings.TrimRight(c.BaseURL, "/"),
+		url.PathEscape(id))
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("mailpit get: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("mailpit get %s: HTTP %d", id, resp.StatusCode)
+	}
+	var m Message
+	if err := json.NewDecoder(resp.Body).Decode(&m); err != nil {
+		return nil, fmt.Errorf("mailpit get decode: %w", err)
+	}
+	return &m, nil
+}
+
+// AwaitMessageTo polls Mailpit for a message addressed to the given
+// recipient. Returns the most recent matching message ; errors out if
+// the timeout elapses with no match. Polls every 50ms — Mailpit is
+// fast enough that this is rarely the limiting factor.
+//
+// Use this in BDD steps "Then I should receive an email ...".
+func (c *Client) AwaitMessageTo(ctx context.Context, to string, timeout time.Duration) (*Message, error) {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		ids, err := c.MessagesTo(ctx, to)
+		if err == nil && len(ids) > 0 {
+			// Most recent first per Mailpit's default sort
+			return c.Get(ctx, ids[0])
+		}
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(50 * time.Millisecond):
+		}
+	}
+	return nil, fmt.Errorf("mailpit: no message for %s within %s", to, timeout)
+}
+
+// PurgeMessagesTo deletes every message addressed to the given recipient.
+// Idempotent: calling against an empty inbox is fine.
+//
+// Use this at the start of a BDD scenario to clear leftovers from
+// prior runs of the same scenario (rare given the random suffix per
+// scenario, but defensive).
+func (c *Client) PurgeMessagesTo(ctx context.Context, to string) error {
+	// Mailpit's /api/v1/search supports the to:<addr> filter ; the more
+	// obvious-looking /api/v1/messages does NOT (the `query` param there
+	// is for pagination, not filtering — verified empirically 2026-05-05).
+	u := fmt.Sprintf("%s/api/v1/search?query=%s",
+		strings.TrimRight(c.BaseURL, "/"),
+		url.QueryEscape("to:"+to))
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, u, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return fmt.Errorf("mailpit delete: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
+		return fmt.Errorf("mailpit delete: HTTP %d", resp.StatusCode)
+	}
+	return nil
+}

pkg/bdd/mailpit/client_integration_test.go

@@ -0,0 +1,133 @@
+//go:build integration
+
+// Integration tests for the Mailpit client. Run with:
+//
+//	go test -tags integration ./pkg/bdd/mailpit/...
+//
+// Requires a running Mailpit reachable at http://localhost:8025
+// (the docker-compose service from ADR-0029).
+package mailpit
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"net/smtp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// uniqueRecipient returns an address unique to this test run, using the
+// per-scenario-recipient pattern from ADR-0030. Two parallel test runs
+// generate different suffixes so they never see each other's messages.
+func uniqueRecipient(t *testing.T) string {
+	t.Helper()
+	var raw [4]byte
+	_, err := rand.Read(raw[:])
+	require.NoError(t, err)
+	return "integ-" + t.Name() + "-" + hex.EncodeToString(raw[:]) + "@bdd.local"
+}
+
+// sendViaSMTP submits a small email through Mailpit's SMTP port.
+// Real-wire-format path : same as the application code will use.
+func sendViaSMTP(t *testing.T, to, subject, body string) {
+	t.Helper()
+	from := "integ-test@bdd.local"
+	msg := []byte(
+		"From: " + from + "\r\n" +
+			"To: " + to + "\r\n" +
+			"Subject: " + subject + "\r\n" +
+			"\r\n" +
+			body + "\r\n",
+	)
+	err := smtp.SendMail("localhost:1025", nil, from, []string{to}, msg)
+	require.NoError(t, err, "SMTP send to local Mailpit")
+}
+
+// TestIntegration_RoundTrip validates the full path : SMTP submit →
+// Mailpit captures → client lists → client gets full body. This is
+// the smoke test for the BDD-helper contract.
+func TestIntegration_RoundTrip(t *testing.T) {
+	c := NewClient()
+	to := uniqueRecipient(t)
+
+	// Defensive cleanup before the test (in case the recipient was reused)
+	require.NoError(t, c.PurgeMessagesTo(context.Background(), to))
+
+	subject := "Integration roundtrip"
+	body := "Token: integ-token-" + strings.ReplaceAll(to, "@", "-at-")
+
+	sendViaSMTP(t, to, subject, body)
+
+	msg, err := c.AwaitMessageTo(context.Background(), to, 3*time.Second)
+	require.NoError(t, err)
+	require.NotNil(t, msg)
+
+	assert.Equal(t, subject, msg.Subject)
+	assert.Contains(t, msg.Text, "Token: integ-token-")
+	if assert.Len(t, msg.To, 1) {
+		assert.Equal(t, to, msg.To[0].Address)
+	}
+
+	// Cleanup so subsequent runs of this same test name don't accumulate
+	require.NoError(t, c.PurgeMessagesTo(context.Background(), to))
+}
+
+// TestIntegration_AwaitTimeoutWhenNoMessage confirms AwaitMessageTo
+// returns an error within the timeout when no message arrives.
+func TestIntegration_AwaitTimeoutWhenNoMessage(t *testing.T) {
+	c := NewClient()
+	to := uniqueRecipient(t) // never sent to → must time out
+
+	start := time.Now()
+	_, err := c.AwaitMessageTo(context.Background(), to, 200*time.Millisecond)
+	elapsed := time.Since(start)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "no message")
+	assert.GreaterOrEqual(t, elapsed, 150*time.Millisecond, "should poll until close to timeout")
+	assert.Less(t, elapsed, 1*time.Second, "should not exceed timeout substantially")
+}
+
+// TestIntegration_PurgeIsolation proves the per-recipient query/delete
+// model from ADR-0030 : two unique recipients can have their own
+// messages without one's purge affecting the other.
+func TestIntegration_PurgeIsolation(t *testing.T) {
+	c := NewClient()
+	// Build two distinct, well-formed addresses (separate local-parts,
+	// same domain). Avoid mutating uniqueRecipient's output post-@.
+	var rawA, rawB [4]byte
+	_, _ = rand.Read(rawA[:])
+	_, _ = rand.Read(rawB[:])
+	toA := "iso-a-" + hex.EncodeToString(rawA[:]) + "@bdd.local"
+	toB := "iso-b-" + hex.EncodeToString(rawB[:]) + "@bdd.local"
+
+	sendViaSMTP(t, toA, "for A", "body A")
+	sendViaSMTP(t, toB, "for B", "body B")
+
+	// Both messages should exist
+	idsA, err := c.MessagesTo(context.Background(), toA)
+	require.NoError(t, err)
+	assert.GreaterOrEqual(t, len(idsA), 1, "A should have its message")
+	idsB, err := c.MessagesTo(context.Background(), toB)
+	require.NoError(t, err)
+	assert.GreaterOrEqual(t, len(idsB), 1, "B should have its message")
+
+	// Purge A only
+	require.NoError(t, c.PurgeMessagesTo(context.Background(), toA))
+
+	// A is empty, B is untouched
+	idsA, err = c.MessagesTo(context.Background(), toA)
+	require.NoError(t, err)
+	assert.Empty(t, idsA, "A should be empty after purge")
+	idsB, err = c.MessagesTo(context.Background(), toB)
+	require.NoError(t, err)
+	assert.GreaterOrEqual(t, len(idsB), 1, "B should still have its message")
+
+	// Cleanup B
+	require.NoError(t, c.PurgeMessagesTo(context.Background(), toB))
+}

pkg/bdd/steps/magic_link_steps.go

@@ -0,0 +1,145 @@
+package steps
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"dance-lessons-coach/pkg/bdd/mailpit"
+	"dance-lessons-coach/pkg/bdd/testserver"
+)
+
+type MagicLinkSteps struct {
+	client      *testserver.Client
+	mailpit     *mailpit.Client
+	scenarioKey string
+}
+
+func NewMagicLinkSteps(client *testserver.Client) *MagicLinkSteps {
+	return &MagicLinkSteps{client: client, mailpit: mailpit.NewClient()}
+}
+
+func (s *MagicLinkSteps) SetScenarioKey(key string) { s.scenarioKey = key }
+
+func (s *MagicLinkSteps) state() *ScenarioState {
+	if s.scenarioKey == "" {
+		s.scenarioKey = "default"
+	}
+	return GetScenarioState(s.scenarioKey)
+}
+
+// sanitizeForEmail keeps only [a-z0-9-] from the scenario key
+func sanitizeForEmail(s string) string {
+	if s == "" {
+		return "scn"
+	}
+	var b strings.Builder
+	for _, r := range strings.ToLower(s) {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' {
+			b.WriteRune(r)
+		}
+	}
+	if b.Len() == 0 {
+		return "scn"
+	}
+	if b.Len() > 24 {
+		return b.String()[:24]
+	}
+	return b.String()
+}
+
+// IHaveAnEmailAddressForThisScenario generates per-scenario unique recipient and stashes it in state.
+// Defensively purges Mailpit for that address.
+// Format: <scenario-key>-<8hex>@bdd.local  (cf. ADR-0030)
+func (s *MagicLinkSteps) IHaveAnEmailAddressForThisScenario() error {
+	var raw [4]byte
+	if _, err := rand.Read(raw[:]); err != nil {
+		return err
+	}
+	addr := fmt.Sprintf("ml-%s-%s@bdd.local",
+		sanitizeForEmail(s.scenarioKey), hex.EncodeToString(raw[:]))
+	s.state().MagicLinkEmail = addr
+	return s.mailpit.PurgeMessagesTo(context.Background(), addr)
+}
+
+// IRequestAMagicLinkForMyEmail POSTs to /api/v1/auth/magic-link/request with the scenario's email.
+func (s *MagicLinkSteps) IRequestAMagicLinkForMyEmail() error {
+	return s.client.Request("POST", "/api/v1/auth/magic-link/request",
+		map[string]string{"email": s.state().MagicLinkEmail})
+}
+
+// IShouldReceiveAnEmailWithSubject waits for an email at the scenario's address; asserts subject equality.
+func (s *MagicLinkSteps) IShouldReceiveAnEmailWithSubject(subject string) error {
+	msg, err := s.mailpit.AwaitMessageTo(context.Background(), s.state().MagicLinkEmail, 5*time.Second)
+	if err != nil {
+		return fmt.Errorf("mailpit await: %w", err)
+	}
+	if msg.Subject != subject {
+		return fmt.Errorf("expected subject %q, got %q", subject, msg.Subject)
+	}
+	return nil
+}
+
+// TheEmailContainsAMagicLinkToken re-fetches most recent message, extracts token via regex, stashes in state.
+var tokenRe = regexp.MustCompile(`\?token=([A-Za-z0-9_\-]+)`)
+
+func (s *MagicLinkSteps) TheEmailContainsAMagicLinkToken() error {
+	msg, err := s.mailpit.AwaitMessageTo(context.Background(), s.state().MagicLinkEmail, 5*time.Second)
+	if err != nil {
+		return err
+	}
+	m := tokenRe.FindStringSubmatch(msg.Text)
+	if m == nil {
+		return fmt.Errorf("no token in email body: %q", msg.Text)
+	}
+	s.state().MagicLinkToken = m[1]
+	return nil
+}
+
+// IConsumeTheMagicLinkToken GETs /api/v1/auth/magic-link/consume?token=<plain>
+func (s *MagicLinkSteps) IConsumeTheMagicLinkToken() error {
+	return s.client.Request("GET",
+		"/api/v1/auth/magic-link/consume?token="+s.state().MagicLinkToken, nil)
+}
+
+// TheConsumeShouldSucceedAndReturnAJWT asserts 200 + JWT body.
+func (s *MagicLinkSteps) TheConsumeShouldSucceedAndReturnAJWT() error {
+	if c := s.client.GetLastStatusCode(); c != http.StatusOK {
+		return fmt.Errorf("expected 200, got %d body=%s", c, s.client.GetLastBody())
+	}
+	var resp struct {
+		Token string `json:"token"`
+	}
+	if err := json.Unmarshal(s.client.GetLastBody(), &resp); err != nil {
+		return err
+	}
+	if resp.Token == "" {
+		return fmt.Errorf("empty JWT in response")
+	}
+	s.state().LastToken = resp.Token
+	return nil
+}
+
+// TheConsumeShouldFailWith401 asserts 401.
+func (s *MagicLinkSteps) TheConsumeShouldFailWith401() error {
+	if c := s.client.GetLastStatusCode(); c != http.StatusUnauthorized {
+		return fmt.Errorf("expected 401, got %d body=%s", c, s.client.GetLastBody())
+	}
+	return nil
+}
+
+// IConsumeAnEmptyMagicLinkToken consumes with an empty token
+func (s *MagicLinkSteps) IConsumeAnEmptyMagicLinkToken() error {
+	return s.client.Request("GET", "/api/v1/auth/magic-link/consume?token=", nil)
+}
+
+// IConsumeAnUnknownMagicLinkToken consumes with a non-existent token
+func (s *MagicLinkSteps) IConsumeAnUnknownMagicLinkToken() error {
+	return s.client.Request("GET", "/api/v1/auth/magic-link/consume?token=unknown-token-12345", nil)
+}

pkg/bdd/steps/scenario_state.go

@@ -9,11 +9,13 @@ import (
 // ScenarioState holds per-scenario state for step definitions
 // This prevents state pollution between scenarios running in the same test process
 type ScenarioState struct {
-	LastToken  string
-	FirstToken string
-	LastUserID uint
-	LastSecret string
-	LastError  string
+	LastToken      string
+	FirstToken     string
+	LastUserID     uint
+	LastSecret     string
+	LastError      string
+	MagicLinkEmail string
+	MagicLinkToken string
 	// Add more fields as needed for other step types
 }
 

pkg/bdd/steps/steps.go

@@ -17,6 +17,7 @@ type StepContext struct {
 	jwtRetentionSteps *JWTRetentionSteps
 	configSteps       *ConfigSteps
 	rateLimitSteps    *RateLimitSteps
+	magicLinkSteps    *MagicLinkSteps
 }
 
 // NewStepContext creates a new step context
@@ -30,6 +31,7 @@ func NewStepContext(client *testserver.Client) *StepContext {
 		jwtRetentionSteps: NewJWTRetentionSteps(client),
 		configSteps:       NewConfigSteps(client),
 		rateLimitSteps:    NewRateLimitSteps(client),
+		magicLinkSteps:    NewMagicLinkSteps(client),
 	}
 }
 
@@ -67,6 +69,9 @@ func SetScenarioKeyForAllSteps(sc *StepContext, key string) {
 		if sc.rateLimitSteps != nil {
 			sc.rateLimitSteps.SetScenarioKey(key)
 		}
+		if sc.magicLinkSteps != nil {
+			sc.magicLinkSteps.SetScenarioKey(key)
+		}
 	}
 }
 
@@ -317,6 +322,17 @@ func InitializeAllSteps(ctx *godog.ScenarioContext, client *testserver.Client, s
 	ctx.Step(`^the response body should contain "([^"]*)"$`, sc.rateLimitSteps.theResponseBodyShouldContain)
 	ctx.Step(`^the response should have header "([^"]*)"$`, sc.rateLimitSteps.theResponseShouldHaveHeader)
 
+	// Magic link steps
+	ctx.Step(`^I have an email address for this scenario$`, sc.magicLinkSteps.IHaveAnEmailAddressForThisScenario)
+	ctx.Step(`^I request a magic link for my email$`, sc.magicLinkSteps.IRequestAMagicLinkForMyEmail)
+	ctx.Step(`^I should receive an email with subject "([^"]*)"$`, sc.magicLinkSteps.IShouldReceiveAnEmailWithSubject)
+	ctx.Step(`^the email contains a magic link token$`, sc.magicLinkSteps.TheEmailContainsAMagicLinkToken)
+	ctx.Step(`^I consume the magic link token$`, sc.magicLinkSteps.IConsumeTheMagicLinkToken)
+	ctx.Step(`^the consume should succeed and return a JWT$`, sc.magicLinkSteps.TheConsumeShouldSucceedAndReturnAJWT)
+	ctx.Step(`^the consume should fail with 401$`, sc.magicLinkSteps.TheConsumeShouldFailWith401)
+	ctx.Step(`^I consume an empty magic link token$`, sc.magicLinkSteps.IConsumeAnEmptyMagicLinkToken)
+	ctx.Step(`^I consume an unknown magic link token$`, sc.magicLinkSteps.IConsumeAnUnknownMagicLinkToken)
+
 	// Common steps
 	ctx.Step(`^the response should be "{\\"([^"]*)":\\"([^"]*)"}"$`, sc.commonSteps.theResponseShouldBe)
 	ctx.Step(`^the response should contain error "([^"]*)"$`, sc.commonSteps.theResponseShouldContainError)

pkg/bdd/testserver/server.go

@@ -741,8 +741,14 @@ func (s *Server) waitForServerReady() error {
 	}
 }
 
-// shouldEnableV2 determines if v2 API should be enabled for this test server
-// This is the ONLY place that reads FEATURE and GODOG_TAGS env vars
+// shouldEnableV2 determines if v2 API should be enabled for this test server.
+// This is the ONLY place that reads FEATURE and GODOG_TAGS env vars.
+//
+// 2026-05-05: previous version used strings.Contains(tags, "@v2") which
+// wrongly matched the negation `~@v2` as well. This made the "v1" greet
+// sub-test (tags `~@v2 && ~@skip`) actually run with v2 enabled, masking
+// the gate behavior we now test in feature `@v2-gate` scenario. Fixed
+// here by inspecting each && clause and checking for positive inclusion.
 func (s *Server) shouldEnableV2() bool {
 	feature := os.Getenv("FEATURE")
 
@@ -753,9 +759,19 @@ func (s *Server) shouldEnableV2() bool {
 		return false
 	}
 
-	// For greet feature: enable v2 if tags include @v2
+	// For greet feature: enable v2 if tags include `@v2` as a POSITIVE clause.
+	// Godog tag expression syntax: clauses separated by `&&` or `||`, negation
+	// via leading `~`. A positive clause matches exactly `@v2` (after trim).
 	tags := os.Getenv("GODOG_TAGS")
-	return strings.Contains(tags, "@v2")
+	for _, clause := range strings.FieldsFunc(tags, func(r rune) bool {
+		return r == '&' || r == '|' || r == ' '
+	}) {
+		clause = strings.TrimSpace(clause)
+		if clause == "@v2" {
+			return true
+		}
+	}
+	return false
 }
 
 // createTestConfig creates a test configuration
@@ -799,6 +815,20 @@ func createTestConfig(port int, v2Enabled bool) *config.Config {
 			JWT: config.JWTConfig{
 				TTL: 24 * time.Hour,
 			},
+			// Email + MagicLink defaults so the magic-link BDD scenarios
+			// (ADR-0028 Phase A.5) can send to local Mailpit. Without these
+			// the literal Config skips Viper's SetDefault and From stays
+			// empty — pkg/email then rejects the message.
+			Email: config.EmailConfig{
+				From:     "noreply@bdd.local",
+				SMTPHost: "localhost",
+				SMTPPort: 1025,
+				Timeout:  5 * time.Second,
+			},
+			MagicLink: config.MagicLinkConfig{
+				TTL:     15 * time.Minute,
+				BaseURL: "http://localhost:8080",
+			},
 		},
 		API: config.APIConfig{
 			V2Enabled: v2Enabled,

pkg/config/config.go

@@ -104,9 +104,44 @@ type APIConfig struct {
 
 // AuthConfig holds authentication configuration
 type AuthConfig struct {
-	JWTSecret           string    `mapstructure:"jwt_secret"`
-	AdminMasterPassword string    `mapstructure:"admin_master_password"`
-	JWT                 JWTConfig `mapstructure:"jwt"`
+	JWTSecret           string          `mapstructure:"jwt_secret"`
+	AdminMasterPassword string          `mapstructure:"admin_master_password"`
+	JWT                 JWTConfig       `mapstructure:"jwt"`
+	Email               EmailConfig     `mapstructure:"email"`
+	MagicLink           MagicLinkConfig `mapstructure:"magic_link"`
+	OIDC                OIDCConfig      `mapstructure:"oidc"`
+}
+
+// MagicLinkConfig holds passwordless-auth magic-link parameters (ADR-0028 Phase A).
+type MagicLinkConfig struct {
+	TTL             time.Duration `mapstructure:"ttl"`
+	BaseURL         string        `mapstructure:"base_url"`
+	CleanupInterval time.Duration `mapstructure:"cleanup_interval"`
+}
+
+// OIDCConfig holds OpenID Connect provider configuration (ADR-0028 Phase B).
+// Multiple providers are supported via a map keyed by provider name (e.g. "arcodange-sso", "google").
+type OIDCConfig struct {
+	Providers map[string]OIDCProvider `mapstructure:"providers"`
+}
+
+// OIDCProvider describes a single OIDC provider's discovery + client config.
+type OIDCProvider struct {
+	IssuerURL    string `mapstructure:"issuer_url"`
+	ClientID     string `mapstructure:"client_id"`
+	ClientSecret string `mapstructure:"client_secret"`
+}
+
+// EmailConfig holds outgoing email transport configuration.
+// Defaults match local Mailpit (cf. ADR-0029) so dev needs no extra setup.
+type EmailConfig struct {
+	From         string        `mapstructure:"from"`
+	SMTPHost     string        `mapstructure:"smtp_host"`
+	SMTPPort     int           `mapstructure:"smtp_port"`
+	SMTPUsername string        `mapstructure:"smtp_username"`
+	SMTPPassword string        `mapstructure:"smtp_password"`
+	SMTPUseTLS   bool          `mapstructure:"smtp_use_tls"`
+	Timeout      time.Duration `mapstructure:"timeout"`
 }
 
 // JWTConfig holds JWT-specific configuration
@@ -256,6 +291,22 @@ func LoadConfig() (*Config, error) {
 	v.SetDefault("auth.jwt.secret_retention.max_retention", 72*time.Hour)
 	v.SetDefault("auth.jwt.secret_retention.cleanup_interval", 1*time.Hour)
 
+	// Email defaults — match local Mailpit (ADR-0029).
+	v.SetDefault("auth.email.from", "noreply@dance-lessons-coach.local")
+	v.SetDefault("auth.email.smtp_host", "localhost")
+	v.SetDefault("auth.email.smtp_port", 1025)
+	v.SetDefault("auth.email.smtp_use_tls", false)
+	v.SetDefault("auth.email.timeout", 10*time.Second)
+
+	// Magic-link defaults (ADR-0028 Phase A).
+	v.SetDefault("auth.magic_link.ttl", 15*time.Minute)
+	v.SetDefault("auth.magic_link.base_url", "http://localhost:8080")
+	v.SetDefault("auth.magic_link.cleanup_interval", 1*time.Hour)
+
+	// OIDC defaults (ADR-0028 Phase B). Providers map is empty by default;
+	// configured per environment via config file or env vars.
+	v.SetDefault("auth.oidc.providers", map[string]interface{}{})
+
 	// Check for custom config file path via environment variable
 	if configFile := os.Getenv("DLC_CONFIG_FILE"); configFile != "" {
 		v.SetConfigFile(configFile)
@@ -301,6 +352,25 @@ func LoadConfig() (*Config, error) {
 	v.BindEnv("auth.jwt.secret_retention.retention_factor", "DLC_AUTH_JWT_SECRET_RETENTION_FACTOR")
 	v.BindEnv("auth.jwt.secret_retention.max_retention", "DLC_AUTH_JWT_SECRET_MAX_RETENTION")
 	v.BindEnv("auth.jwt.secret_retention.cleanup_interval", "DLC_AUTH_JWT_SECRET_CLEANUP_INTERVAL")
+	v.BindEnv("auth.email.from", "DLC_AUTH_EMAIL_FROM")
+	v.BindEnv("auth.email.smtp_host", "DLC_AUTH_EMAIL_SMTP_HOST")
+	v.BindEnv("auth.email.smtp_port", "DLC_AUTH_EMAIL_SMTP_PORT")
+	v.BindEnv("auth.email.smtp_username", "DLC_AUTH_EMAIL_SMTP_USERNAME")
+	v.BindEnv("auth.email.smtp_password", "DLC_AUTH_EMAIL_SMTP_PASSWORD")
+	v.BindEnv("auth.email.smtp_use_tls", "DLC_AUTH_EMAIL_SMTP_USE_TLS")
+	v.BindEnv("auth.email.timeout", "DLC_AUTH_EMAIL_TIMEOUT")
+
+	// Magic-link environment variables (ADR-0028 Phase A).
+	v.BindEnv("auth.magic_link.ttl", "DLC_AUTH_MAGIC_LINK_TTL")
+	v.BindEnv("auth.magic_link.base_url", "DLC_AUTH_MAGIC_LINK_BASE_URL")
+	v.BindEnv("auth.magic_link.cleanup_interval", "DLC_AUTH_MAGIC_LINK_CLEANUP_INTERVAL")
+
+	// OIDC environment variables (ADR-0028 Phase B). One canonical "default"
+	// provider is bindable via env; additional providers must be defined in config.yaml.
+	v.BindEnv("auth.oidc.providers.default.issuer_url", "DLC_AUTH_OIDC_ISSUER_URL")
+	v.BindEnv("auth.oidc.providers.default.client_id", "DLC_AUTH_OIDC_CLIENT_ID")
+	v.BindEnv("auth.oidc.providers.default.client_secret", "DLC_AUTH_OIDC_CLIENT_SECRET")
+
 	v.BindEnv("telemetry.sampler.type", "DLC_TELEMETRY_SAMPLER_TYPE")
 	v.BindEnv("telemetry.sampler.ratio", "DLC_TELEMETRY_SAMPLER_RATIO")
 
@@ -432,6 +502,43 @@ func (c *Config) GetAdminMasterPassword() string {
 	return c.Auth.AdminMasterPassword
 }
 
+// GetEmailConfig returns the outgoing email transport configuration.
+// Defaults match local Mailpit (localhost:1025, no TLS, no auth) per
+// ADR-0029. Used by pkg/email.NewSMTPSender.
+func (c *Config) GetEmailConfig() EmailConfig {
+	return c.Auth.Email
+}
+
+// GetMagicLinkConfig returns the passwordless-auth magic-link parameters
+// (ADR-0028 Phase A). TTL defaults to 15m, BaseURL to http://localhost:8080.
+func (c *Config) GetMagicLinkConfig() MagicLinkConfig {
+	out := c.Auth.MagicLink
+	if out.TTL <= 0 {
+		out.TTL = 15 * time.Minute
+	}
+	if out.BaseURL == "" {
+		out.BaseURL = "http://localhost:8080"
+	}
+	return out
+}
+
+// GetOIDCProviders returns the configured OIDC providers, keyed by provider name.
+// Empty map (not nil) is returned when no providers are configured.
+func (c *Config) GetOIDCProviders() map[string]OIDCProvider {
+	if c.Auth.OIDC.Providers == nil {
+		return map[string]OIDCProvider{}
+	}
+	return c.Auth.OIDC.Providers
+}
+
+// GetMagicLinkCleanupInterval returns the magic-link cleanup interval (ADR-0028 Phase A consequence).
+func (c *Config) GetMagicLinkCleanupInterval() time.Duration {
+	if c.Auth.MagicLink.CleanupInterval <= 0 {
+		return 1 * time.Hour
+	}
+	return c.Auth.MagicLink.CleanupInterval
+}
+
 // GetJWTTTL returns the JWT TTL
 func (c *Config) GetJWTTTL() time.Duration {
 	if c.Auth.JWT.TTL == 0 {

pkg/email/sender.go

@@ -0,0 +1,45 @@
+// Package email provides the abstraction over outgoing email transport.
+//
+// ADR-0029 picked Mailpit for local dev and BDD ; production sender is
+// deferred. The Sender interface is the swap point : a future production
+// adapter (AWS SES, Postmark, SendGrid) implements the same contract
+// without touching call sites.
+package email
+
+import "context"
+
+// Sender sends email messages. Implementations must be safe for
+// concurrent use — multiple goroutines may call Send simultaneously.
+type Sender interface {
+	Send(ctx context.Context, msg Message) error
+}
+
+// Message is the wire-level representation of an outgoing email.
+// Headers is for trace correlation (e.g. X-Test-Scenario-ID for BDD)
+// and arbitrary application-specific tags. Implementations include
+// these as RFC 5322 header fields.
+type Message struct {
+	// To is the recipient address (single recipient ; we don't currently
+	// support multi-recipient broadcasts — keeps the contract simple
+	// and matches the magic-link use case which is always 1:1).
+	To string
+
+	// From is the sender address. Required.
+	From string
+
+	// Subject is the RFC 5322 Subject. Required for non-empty body.
+	Subject string
+
+	// BodyText is the plain-text body. At least one of BodyText or
+	// BodyHTML must be non-empty.
+	BodyText string
+
+	// BodyHTML is the optional HTML body. When both are set, the
+	// SMTP-level message is multipart/alternative.
+	BodyHTML string
+
+	// Headers are extra RFC 5322 header fields. Keys are case-insensitive ;
+	// implementations canonicalise via textproto.CanonicalMIMEHeaderKey.
+	// Useful for BDD test correlation (X-BDD-Scenario, etc.).
+	Headers map[string]string
+}

pkg/email/smtp_sender.go

@@ -0,0 +1,155 @@
+package email
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/smtp"
+	"net/textproto"
+	"strings"
+	"time"
+)
+
+// SMTPConfig configures an SMTPSender. Defaults match local Mailpit
+// (host=localhost, port=1025, no TLS, no auth).
+type SMTPConfig struct {
+	Host     string
+	Port     int
+	Username string // empty means no AUTH
+	Password string // empty means no AUTH
+	UseTLS   bool   // STARTTLS — false for Mailpit local
+	// Timeout bounds Send to avoid hanging forever on a stuck server.
+	// Defaults to 10s when zero.
+	Timeout time.Duration
+}
+
+// SMTPSender sends mail through an SMTP server. Configured by SMTPConfig
+// with sensible Mailpit-friendly defaults.
+type SMTPSender struct {
+	cfg SMTPConfig
+}
+
+// NewSMTPSender returns a Sender backed by SMTP. The SMTPConfig is copied —
+// mutating the caller's struct after this call has no effect.
+func NewSMTPSender(cfg SMTPConfig) *SMTPSender {
+	if cfg.Host == "" {
+		cfg.Host = "localhost"
+	}
+	if cfg.Port == 0 {
+		cfg.Port = 1025
+	}
+	if cfg.Timeout == 0 {
+		cfg.Timeout = 10 * time.Second
+	}
+	return &SMTPSender{cfg: cfg}
+}
+
+// Send delivers the message via SMTP. Returns an error if the message is
+// invalid (missing required fields), if connecting / authenticating fails,
+// or if the SMTP server rejects the envelope or data.
+func (s *SMTPSender) Send(ctx context.Context, msg Message) error {
+	if err := validateMessage(msg); err != nil {
+		return err
+	}
+
+	addr := fmt.Sprintf("%s:%d", s.cfg.Host, s.cfg.Port)
+	body := buildRFC5322(msg)
+
+	var auth smtp.Auth
+	if s.cfg.Username != "" {
+		auth = smtp.PlainAuth("", s.cfg.Username, s.cfg.Password, s.cfg.Host)
+	}
+
+	// Run the SMTP exchange in a goroutine so we can honour the
+	// context's cancellation independently of net/smtp's own timeouts.
+	done := make(chan error, 1)
+	go func() {
+		done <- smtp.SendMail(addr, auth, msg.From, []string{msg.To}, body)
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			return fmt.Errorf("smtp send to %s: %w", msg.To, err)
+		}
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-time.After(s.cfg.Timeout):
+		return errors.New("smtp send: timeout")
+	}
+}
+
+// validateMessage checks the minimum required fields for an outgoing email.
+func validateMessage(msg Message) error {
+	if msg.To == "" {
+		return errors.New("email: To is required")
+	}
+	if msg.From == "" {
+		return errors.New("email: From is required")
+	}
+	if msg.BodyText == "" && msg.BodyHTML == "" {
+		return errors.New("email: at least one of BodyText or BodyHTML is required")
+	}
+	return nil
+}
+
+// buildRFC5322 builds an RFC 5322 message body from Message. Plain-text
+// only when BodyHTML is empty ; multipart/alternative when both are set.
+//
+// Keep in mind: this is the body sent to net/smtp.SendMail, which adds
+// no headers itself. We add the canonical From, To, Subject, MIME-Version,
+// Content-Type, and any caller-provided custom headers.
+func buildRFC5322(msg Message) []byte {
+	var b strings.Builder
+
+	// Custom headers first so they show up early in the message.
+	for k, v := range msg.Headers {
+		// Normalise header name case (Foo-Bar, not foo-BAR)
+		k = textproto.CanonicalMIMEHeaderKey(k)
+		fmt.Fprintf(&b, "%s: %s\r\n", k, v)
+	}
+
+	fmt.Fprintf(&b, "From: %s\r\n", msg.From)
+	fmt.Fprintf(&b, "To: %s\r\n", msg.To)
+	fmt.Fprintf(&b, "Subject: %s\r\n", msg.Subject)
+	fmt.Fprintf(&b, "MIME-Version: 1.0\r\n")
+
+	if msg.BodyHTML == "" {
+		// Plain text only
+		fmt.Fprintf(&b, "Content-Type: text/plain; charset=utf-8\r\n")
+		fmt.Fprintf(&b, "\r\n")
+		b.WriteString(msg.BodyText)
+		return []byte(b.String())
+	}
+
+	// multipart/alternative — boundary is deterministic for tests but unique
+	// enough not to collide with body content. We don't put random bytes in
+	// the boundary because the alphabetical "alt-" prefix is recognisably
+	// ours and the rest is timestamped.
+	boundary := fmt.Sprintf("alt-%d", time.Now().UnixNano())
+	fmt.Fprintf(&b, "Content-Type: multipart/alternative; boundary=%q\r\n", boundary)
+	fmt.Fprintf(&b, "\r\n")
+
+	// Plain part (always first — clients that only render text/plain see
+	// it ; clients preferring HTML go to the HTML part)
+	fmt.Fprintf(&b, "--%s\r\n", boundary)
+	fmt.Fprintf(&b, "Content-Type: text/plain; charset=utf-8\r\n\r\n")
+	if msg.BodyText != "" {
+		b.WriteString(msg.BodyText)
+	} else {
+		b.WriteString("(see HTML version)")
+	}
+	fmt.Fprintf(&b, "\r\n")
+
+	// HTML part
+	fmt.Fprintf(&b, "--%s\r\n", boundary)
+	fmt.Fprintf(&b, "Content-Type: text/html; charset=utf-8\r\n\r\n")
+	b.WriteString(msg.BodyHTML)
+	fmt.Fprintf(&b, "\r\n")
+
+	// Close boundary
+	fmt.Fprintf(&b, "--%s--\r\n", boundary)
+
+	return []byte(b.String())
+}

pkg/email/smtp_sender_test.go

@@ -0,0 +1,123 @@
+package email
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestValidateMessage_RejectsMissingFields confirms the contract gate:
+// To, From, and at least one body are required.
+func TestValidateMessage_RejectsMissingFields(t *testing.T) {
+	cases := []struct {
+		name    string
+		msg     Message
+		wantErr string
+	}{
+		{"empty To", Message{From: "f@x", BodyText: "b"}, "To is required"},
+		{"empty From", Message{To: "t@x", BodyText: "b"}, "From is required"},
+		{"empty body", Message{To: "t@x", From: "f@x"}, "BodyText or BodyHTML"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateMessage(tc.msg)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tc.wantErr)
+		})
+	}
+}
+
+// TestValidateMessage_AcceptsMinimal confirms the happy path: To, From,
+// and BodyText alone is a valid message.
+func TestValidateMessage_AcceptsMinimal(t *testing.T) {
+	err := validateMessage(Message{To: "t@x", From: "f@x", BodyText: "b"})
+	assert.NoError(t, err)
+}
+
+// TestBuildRFC5322_PlainText verifies that a text-only message produces
+// a single-part text/plain RFC 5322 body with the expected headers.
+func TestBuildRFC5322_PlainText(t *testing.T) {
+	msg := Message{
+		To: "alice@example.com", From: "system@x", Subject: "Hi",
+		BodyText: "Hello Alice",
+	}
+	body := string(buildRFC5322(msg))
+
+	assert.Contains(t, body, "To: alice@example.com\r\n")
+	assert.Contains(t, body, "From: system@x\r\n")
+	assert.Contains(t, body, "Subject: Hi\r\n")
+	assert.Contains(t, body, "MIME-Version: 1.0\r\n")
+	assert.Contains(t, body, "Content-Type: text/plain; charset=utf-8\r\n")
+	assert.Contains(t, body, "\r\nHello Alice")
+	assert.NotContains(t, body, "multipart/alternative", "no HTML => no multipart")
+}
+
+// TestBuildRFC5322_Multipart verifies that text + HTML produces a
+// multipart/alternative body with both parts and a boundary close.
+func TestBuildRFC5322_Multipart(t *testing.T) {
+	msg := Message{
+		To: "alice@example.com", From: "system@x", Subject: "Hi",
+		BodyText: "Plain hello", BodyHTML: "<p>HTML hello</p>",
+	}
+	body := string(buildRFC5322(msg))
+
+	assert.Contains(t, body, "Content-Type: multipart/alternative;")
+	assert.Contains(t, body, "Plain hello", "plain part included")
+	assert.Contains(t, body, "<p>HTML hello</p>", "HTML part included")
+	// Boundary close marker
+	assert.True(t, strings.Contains(body, "--alt-") && strings.HasSuffix(strings.TrimRight(body, "\r\n"), "--"),
+		"multipart message should end with closing boundary")
+}
+
+// TestBuildRFC5322_CustomHeaders verifies that user-supplied headers
+// appear in the output with canonicalised case.
+func TestBuildRFC5322_CustomHeaders(t *testing.T) {
+	msg := Message{
+		To: "alice@example.com", From: "system@x", Subject: "Hi",
+		BodyText: "b",
+		Headers: map[string]string{
+			"x-bdd-scenario": "magic-link-happy-path",
+			"X-Trace-Id":     "abc-123",
+		},
+	}
+	body := string(buildRFC5322(msg))
+
+	assert.Contains(t, body, "X-Bdd-Scenario: magic-link-happy-path\r\n",
+		"lowercase key should be canonicalised to title-case")
+	assert.Contains(t, body, "X-Trace-Id: abc-123\r\n",
+		"already-canonical key should pass through unchanged")
+}
+
+// TestSMTPSender_DefaultsAreMailpitFriendly verifies that NewSMTPSender
+// fills in localhost:1025 and a non-zero timeout when the caller passes
+// a zero-valued SMTPConfig — which is the recommended default.
+func TestSMTPSender_DefaultsAreMailpitFriendly(t *testing.T) {
+	s := NewSMTPSender(SMTPConfig{})
+	assert.Equal(t, "localhost", s.cfg.Host)
+	assert.Equal(t, 1025, s.cfg.Port)
+	assert.Greater(t, int64(s.cfg.Timeout), int64(0), "timeout must be set, default 10s")
+	assert.Empty(t, s.cfg.Username, "default no AUTH")
+}
+
+// TestSMTPSender_ContextCancelAbortsSend confirms a cancelled ctx
+// short-circuits Send rather than waiting for the SMTP timeout.
+// We point at a port no SMTP server is listening on so the goroutine
+// will hang ; ctx cancel is what wins.
+func TestSMTPSender_ContextCancelAbortsSend(t *testing.T) {
+	s := NewSMTPSender(SMTPConfig{
+		Host: "127.0.0.1",
+		Port: 1, // privileged port, definitely no SMTP server here
+		// keep the default 10s timeout — we want ctx to win
+	})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // pre-cancelled
+
+	err := s.Send(ctx, Message{To: "t@x", From: "f@x", BodyText: "b"})
+	require.Error(t, err)
+	// The error is ctx.Err() OR the net/smtp connect error if the goroutine
+	// happened to fail before the ctx select ran. Both are acceptable —
+	// the only unacceptable outcome is the test taking 10 seconds.
+}

pkg/greet/greet.go

@@ -3,31 +3,17 @@ package greet
 import (
 	"context"
 
-	"dance-lessons-coach/pkg/user"
+	"dance-lessons-coach/pkg/auth"
 
 	"github.com/rs/zerolog/log"
 )
 
-// Context key for storing authenticated user
-type contextKey string
-
-const (
-	// UserContextKey is the context key for storing authenticated user
-	UserContextKey contextKey = "authenticatedUser"
-)
-
 type Service struct{}
 
 func NewService() *Service {
 	return &Service{}
 }
 
-// GetAuthenticatedUserFromContext extracts the authenticated user from context
-func GetAuthenticatedUserFromContext(ctx context.Context) (*user.User, bool) {
-	user, ok := ctx.Value(UserContextKey).(*user.User)
-	return user, ok
-}
-
 // Greet returns a greeting message for the given name.
 // If name is empty, it checks for authenticated user and uses their username.
 // If no authenticated user and no name, it defaults to "world".
@@ -37,7 +23,7 @@ func (s *Service) Greet(ctx context.Context, name string) string {
 
 	// If no name provided, check for authenticated user
 	if name == "" {
-		if authenticatedUser, ok := GetAuthenticatedUserFromContext(ctx); ok {
+		if authenticatedUser, ok := auth.GetAuthenticatedUserFromContext(ctx); ok {
 			name = authenticatedUser.Username
 			log.Trace().Ctx(ctx).Str("authenticated_user", name).Msg("Using authenticated username for greeting")
 		}

pkg/server/middleware.go

@@ -3,61 +3,131 @@ package server
 import (
 	"context"
 	"net/http"
+	"strings"
 
-	"dance-lessons-coach/pkg/greet"
+	"dance-lessons-coach/pkg/auth"
 	"dance-lessons-coach/pkg/user"
 
 	"github.com/rs/zerolog/log"
 )
 
-// AuthMiddleware handles JWT authentication and adds user to context
-type AuthMiddleware struct {
-	authService user.AuthService
+// tokenValidator is the narrow interface AuthMiddleware needs from
+// user.AuthService — only JWT validation. ISP : avoid pulling the full
+// fat AuthService interface (12+ methods) into the middleware.
+type tokenValidator interface {
+	ValidateJWT(ctx context.Context, token string) (*user.User, error)
 }
 
-// NewAuthMiddleware creates a new authentication middleware
-func NewAuthMiddleware(authService user.AuthService) *AuthMiddleware {
-	return &AuthMiddleware{
-		authService: authService,
+const bearerPrefix = "Bearer "
+
+// firstWord returns the first whitespace-separated word of s, or s itself
+// if there's no whitespace. Used for log-safe scheme extraction.
+func firstWord(s string) string {
+	if i := strings.IndexAny(s, " \t"); i >= 0 {
+		return s[:i]
 	}
+	return s
 }
 
-// Middleware returns the authentication middleware function
-func (m *AuthMiddleware) Middleware(next http.Handler) http.Handler {
+// extractBearerToken pulls the bearer token out of an Authorization header.
+// Returns ("", false) if absent or malformed. RFC 6750 specifies the
+// scheme is case-insensitive ; we honor that.
+func extractBearerToken(authHeader string) (string, bool) {
+	if authHeader == "" {
+		return "", false
+	}
+	// Case-insensitive prefix match for "Bearer "
+	if len(authHeader) < len(bearerPrefix) {
+		return "", false
+	}
+	if !strings.EqualFold(authHeader[:len(bearerPrefix)], bearerPrefix) {
+		return "", false
+	}
+	return authHeader[len(bearerPrefix):], true
+}
+
+// AuthMiddleware (existing type kept for backwards compatibility ; the
+// constructor now returns a struct that exposes BOTH the optional and
+// required handlers). The legacy .Middleware method delegates to
+// OptionalHandler so existing wiring (server.go r.Use(authMiddleware.Middleware))
+// keeps working.
+type AuthMiddleware struct {
+	validator tokenValidator
+}
+
+func NewAuthMiddleware(validator tokenValidator) *AuthMiddleware {
+	return &AuthMiddleware{validator: validator}
+}
+
+// OptionalHandler wraps next so :
+//   - no Authorization header : pass through, no user in context
+//   - malformed header : pass through, log Trace, no user in context
+//   - invalid JWT : pass through, log Trace, no user in context
+//   - valid JWT : pass through, user injected via auth.UserContextKey
+//
+// Use this on endpoints where auth is "nice to have" — the handler is
+// expected to call auth.GetAuthenticatedUserFromContext and decide.
+func (m *AuthMiddleware) OptionalHandler(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
-
-		// Extract Authorization header
-		authHeader := r.Header.Get("Authorization")
-		if authHeader == "" {
-			// No authorization header, pass through with no user
+		token, ok := extractBearerToken(r.Header.Get("Authorization"))
+		if !ok {
+			// Header absent or malformed — log size only (Q-064 : no raw value).
+			if h := r.Header.Get("Authorization"); h != "" {
+				log.Trace().Ctx(ctx).
+					Int("auth_header_len", len(h)).
+					Str("scheme_word", firstWord(h)).
+					Msg("Optional auth : malformed Authorization header")
+			}
 			next.ServeHTTP(w, r)
 			return
 		}
-
-		// Extract token from "Bearer <token>" format
-		const bearerPrefix = "Bearer "
-		if len(authHeader) < len(bearerPrefix) || authHeader[:len(bearerPrefix)] != bearerPrefix {
-			log.Trace().Ctx(ctx).Str("auth_header", authHeader).Msg("Invalid authorization header format")
-			next.ServeHTTP(w, r)
-			return
-		}
-
-		token := authHeader[len(bearerPrefix):]
-
-		// Validate JWT token
-		validatedUser, err := m.authService.ValidateJWT(ctx, token)
+		validatedUser, err := m.validator.ValidateJWT(ctx, token)
 		if err != nil {
-			log.Trace().Ctx(ctx).Err(err).Msg("JWT validation failed")
+			log.Trace().Ctx(ctx).Err(err).Msg("Optional auth : JWT validation failed")
 			next.ServeHTTP(w, r)
 			return
 		}
-
-		// Add user to context
-		ctxWithUser := context.WithValue(ctx, greet.UserContextKey, validatedUser)
-		r = r.WithContext(ctxWithUser)
-
-		// Continue to next handler
-		next.ServeHTTP(w, r)
+		ctxWithUser := context.WithValue(ctx, auth.UserContextKey, validatedUser)
+		next.ServeHTTP(w, r.WithContext(ctxWithUser))
 	})
 }
+
+// RequiredHandler wraps next so :
+//   - no header / malformed / invalid JWT : 401 Unauthorized + WWW-Authenticate: Bearer
+//   - valid JWT : pass through, user injected via auth.UserContextKey
+//
+// Use this on endpoints where unauthenticated access is forbidden.
+// Conforms to RFC 6750.
+func (m *AuthMiddleware) RequiredHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ctx := r.Context()
+		token, ok := extractBearerToken(r.Header.Get("Authorization"))
+		if !ok {
+			w.Header().Set("WWW-Authenticate", `Bearer realm="dance-lessons-coach"`)
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusUnauthorized)
+			_, _ = w.Write([]byte(`{"error":"unauthorized","message":"missing or malformed Authorization header"}`))
+			return
+		}
+		validatedUser, err := m.validator.ValidateJWT(ctx, token)
+		if err != nil {
+			w.Header().Set("WWW-Authenticate", `Bearer realm="dance-lessons-coach", error="invalid_token"`)
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusUnauthorized)
+			_, _ = w.Write([]byte(`{"error":"unauthorized","message":"invalid token"}`))
+			return
+		}
+		ctxWithUser := context.WithValue(ctx, auth.UserContextKey, validatedUser)
+		next.ServeHTTP(w, r.WithContext(ctxWithUser))
+	})
+}
+
+// Middleware is the legacy method — preserved for backwards compatibility.
+// Delegates to OptionalHandler. New wiring should call OptionalHandler or
+// RequiredHandler explicitly.
+//
+// Deprecated: use OptionalHandler() directly.
+func (m *AuthMiddleware) Middleware(next http.Handler) http.Handler {
+	return m.OptionalHandler(next)
+}

pkg/server/middleware_test.go

@@ -0,0 +1,181 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"dance-lessons-coach/pkg/auth"
+	"dance-lessons-coach/pkg/user"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeTokenValidator is a minimal tokenValidator stub.
+type fakeTokenValidator struct {
+	validUser *user.User
+	err       error
+	seen      string // captures the last token passed in
+}
+
+func (f *fakeTokenValidator) ValidateJWT(ctx context.Context, token string) (*user.User, error) {
+	f.seen = token
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.validUser, nil
+}
+
+// nextHandler returns 200 with a flag in body indicating whether a user
+// was injected into context.
+func nextHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		u, ok := auth.GetAuthenticatedUserFromContext(r.Context())
+		if ok && u != nil {
+			w.Header().Set("X-User", u.Username)
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("ok"))
+	})
+}
+
+func TestOptionalHandler_NoHeader_PassesThrough(t *testing.T) {
+	fv := &fakeTokenValidator{}
+	mw := NewAuthMiddleware(fv).OptionalHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Empty(t, rec.Header().Get("X-User"), "no user expected when no Authorization header")
+	assert.Empty(t, fv.seen, "validator should not have been called")
+}
+
+func TestOptionalHandler_MalformedHeader_PassesThrough(t *testing.T) {
+	fv := &fakeTokenValidator{}
+	mw := NewAuthMiddleware(fv).OptionalHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "Basic xxx")
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Empty(t, rec.Header().Get("X-User"))
+	assert.Empty(t, fv.seen, "validator should not have been called for non-Bearer scheme")
+}
+
+func TestOptionalHandler_BearerCaseInsensitive(t *testing.T) {
+	fv := &fakeTokenValidator{validUser: &user.User{Username: "alice"}}
+	mw := NewAuthMiddleware(fv).OptionalHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "bearer abc123") // lowercase
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "alice", rec.Header().Get("X-User"), "case-insensitive Bearer per RFC 6750")
+	assert.Equal(t, "abc123", fv.seen)
+}
+
+func TestOptionalHandler_InvalidJWT_PassesThrough(t *testing.T) {
+	fv := &fakeTokenValidator{err: errors.New("bad signature")}
+	mw := NewAuthMiddleware(fv).OptionalHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "Bearer xxx")
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code, "optional auth never returns 401")
+	assert.Empty(t, rec.Header().Get("X-User"))
+}
+
+func TestOptionalHandler_ValidJWT_InjectsUser(t *testing.T) {
+	fv := &fakeTokenValidator{validUser: &user.User{ID: 7, Username: "bob"}}
+	mw := NewAuthMiddleware(fv).OptionalHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "Bearer goodtoken")
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "bob", rec.Header().Get("X-User"))
+	assert.Equal(t, "goodtoken", fv.seen)
+}
+
+func TestRequiredHandler_NoHeader_Returns401(t *testing.T) {
+	fv := &fakeTokenValidator{}
+	mw := NewAuthMiddleware(fv).RequiredHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), "Bearer", "RFC 6750 challenge header")
+	assert.Contains(t, rec.Body.String(), "unauthorized")
+}
+
+func TestRequiredHandler_InvalidJWT_Returns401WithErrorTag(t *testing.T) {
+	fv := &fakeTokenValidator{err: errors.New("expired")}
+	mw := NewAuthMiddleware(fv).RequiredHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "Bearer xxx")
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), `error="invalid_token"`)
+}
+
+func TestRequiredHandler_ValidJWT_PassesThrough(t *testing.T) {
+	fv := &fakeTokenValidator{validUser: &user.User{Username: "carol"}}
+	mw := NewAuthMiddleware(fv).RequiredHandler(nextHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/foo", nil)
+	req.Header.Set("Authorization", "Bearer goodtoken")
+	rec := httptest.NewRecorder()
+	mw.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "carol", rec.Header().Get("X-User"))
+}
+
+func TestExtractBearerToken_EdgeCases(t *testing.T) {
+	cases := []struct {
+		in  string
+		out string
+		ok  bool
+	}{
+		{"", "", false},
+		{"Bearer ", "", true}, // empty token, but matches the prefix — caller decides
+		{"Bearer xxx", "xxx", true},
+		{"bearer xxx", "xxx", true}, // case-insensitive
+		{"BEARER xxx", "xxx", true},
+		{"Basic xxx", "", false},
+		{"Bearer", "", false}, // no separating space
+		{"Bear", "", false},
+	}
+	for _, c := range cases {
+		t.Run(c.in, func(t *testing.T) {
+			tok, ok := extractBearerToken(c.in)
+			assert.Equal(t, c.ok, ok)
+			assert.Equal(t, c.out, tok)
+		})
+	}
+}
+
+func TestFirstWord(t *testing.T) {
+	assert.Equal(t, "Bearer", firstWord("Bearer xxx"))
+	assert.Equal(t, "Basic", firstWord("Basic\tabc"))
+	assert.Equal(t, "Token", firstWord("Token"))
+	assert.Equal(t, "", firstWord(""))
+}

pkg/server/server.go

@@ -18,8 +18,10 @@ import (
 	"github.com/rs/zerolog/log"
 	httpSwagger "github.com/swaggo/http-swagger"
 
+	"dance-lessons-coach/pkg/auth"
 	"dance-lessons-coach/pkg/cache"
 	"dance-lessons-coach/pkg/config"
+	"dance-lessons-coach/pkg/email"
 	"dance-lessons-coach/pkg/greet"
 	"dance-lessons-coach/pkg/middleware"
 	"dance-lessons-coach/pkg/telemetry"
@@ -245,6 +247,9 @@ func (s *Server) registerApiV1Routes(r chi.Router) {
 		r.Get("/{name}", s.handleGreetPath)
 	})
 
+	// Uptime endpoint
+	r.Get("/uptime", s.handleUptime)
+
 	// Register user authentication routes
 	if s.userService != nil && s.userRepo != nil {
 		// Use unified user service - much simpler!
@@ -252,6 +257,41 @@ func (s *Server) registerApiV1Routes(r chi.Router) {
 			handler := userapi.NewAuthHandler(s.userService, s.userService, s.validator)
 			r.Route("/auth", func(r chi.Router) {
 				handler.RegisterRoutes(r)
+				// Magic-link routes (ADR-0028 Phase A). Mounted only when the
+				// userRepo also implements MagicLinkRepository (PostgresRepository does).
+				if mlRepo, ok := s.userRepo.(user.MagicLinkRepository); ok {
+					emailCfg := s.config.GetEmailConfig()
+					sender := email.NewSMTPSender(email.SMTPConfig{
+						Host:     emailCfg.SMTPHost,
+						Port:     emailCfg.SMTPPort,
+						Username: emailCfg.SMTPUsername,
+						Password: emailCfg.SMTPPassword,
+						UseTLS:   emailCfg.SMTPUseTLS,
+						Timeout:  emailCfg.Timeout,
+					})
+					mlHandler := userapi.NewMagicLinkHandler(
+						mlRepo,
+						s.userService,
+						s.userRepo,
+						sender,
+						s.config.GetMagicLinkConfig(),
+						emailCfg.From,
+						s.validator,
+					)
+					mlHandler.RegisterRoutes(r)
+				}
+
+				// OIDC handlers (ADR-0028 Phase B.4)
+				oidcProviders := s.config.GetOIDCProviders()
+				if len(oidcProviders) > 0 {
+					oidcClients := make(map[string]*auth.OIDCClient, len(oidcProviders))
+					for name, p := range oidcProviders {
+						oidcClients[name] = auth.NewOIDCClient(p.IssuerURL, p.ClientID, p.ClientSecret)
+					}
+					redirectBase := s.config.GetMagicLinkConfig().BaseURL
+					oidcHandler := userapi.NewOIDCHandler(oidcClients, s.userService, s.userRepo, redirectBase)
+					oidcHandler.RegisterRoutes(r)
+				}
 			})
 
 			// Register admin routes
@@ -559,6 +599,30 @@ func (s *Server) handleInfo(w http.ResponseWriter, r *http.Request) {
 	w.Write(data)
 }
 
+// UptimeResponse represents the JSON response for /api/v1/uptime
+type UptimeResponse struct {
+	StartTime     string `json:"start_time"`
+	UptimeSeconds int    `json:"uptime_seconds"`
+}
+
+// handleUptime godoc
+//
+//	@Summary		Get server uptime
+//	@Description	Returns server start time and uptime duration
+//	@Tags			System/Info
+//	@Produce		json
+//	@Success		200	{object}	UptimeResponse
+//	@Router			/v1/uptime [get]
+func (s *Server) handleUptime(w http.ResponseWriter, r *http.Request) {
+	log.Trace().Msg("Uptime check requested")
+	resp := UptimeResponse{
+		StartTime:     s.startedAt.Format(time.RFC3339),
+		UptimeSeconds: int(time.Since(s.startedAt).Seconds()),
+	}
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
 // handleGreetQuery godoc
 //
 //	@Summary		Get greeting with cache
@@ -740,6 +804,12 @@ func (s *Server) Run() error {
 		s.userService.StartJWTSecretCleanupLoop(rootCtx, s.config.GetJWTSecretCleanupInterval())
 	}
 
+	// Start the magic-link expired-token cleanup loop (ADR-0028 Phase A consequence).
+	if mlRepo, ok := s.userRepo.(user.MagicLinkRepository); ok {
+		runner := user.NewMagicLinkCleanupRunner(mlRepo)
+		runner.StartCleanupLoop(rootCtx, s.config.GetMagicLinkCleanupInterval())
+	}
+
 	// Wire the sampler hot-reload callback (ADR-0023 Phase 3, sub-phase 3.3).
 	// telemetrySetup is non-nil only when telemetry was successfully initialized
 	// at startup — hot-reloading telemetry-on is out of scope (see ADR-0023).

pkg/server/uptime_test.go

@@ -0,0 +1,81 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"dance-lessons-coach/pkg/config"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHandleUptime(t *testing.T) {
+	// Setup with a known start time
+	cfg := &config.Config{}
+	// We need to create a server and then set its startedAt to a known time
+	// Since NewServer sets startedAt to time.Now(), we'll create the server
+	// and then use reflection or we can use NewServerWithUserRepo which also sets startedAt
+	s := NewServer(cfg, context.Background())
+
+	// Set a fixed start time for deterministic testing
+	// We can't directly set s.startedAt since it's unexported, but we can test
+	// that the handler uses the server's startedAt
+	// The test will verify the structure and that uptime_seconds is >= 0
+
+	// Create request
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/uptime", nil)
+	w := httptest.NewRecorder()
+
+	// Call handler
+	s.handleUptime(w, req)
+
+	// Check status code
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	// Check content type
+	assert.Equal(t, "application/json", w.Header().Get("Content-Type"))
+
+	// Decode response
+	var resp UptimeResponse
+	err := json.NewDecoder(w.Body).Decode(&resp)
+	assert.NoError(t, err)
+
+	// Assert fields
+	assert.NotEmpty(t, resp.StartTime)
+	// Verify start_time is in RFC3339 format
+	_, err = time.Parse(time.RFC3339, resp.StartTime)
+	assert.NoError(t, err)
+	assert.GreaterOrEqual(t, resp.UptimeSeconds, 0)
+}
+
+func TestHandleUptime_Deterministic(t *testing.T) {
+	// For a more deterministic test, we would need to be able to set startedAt
+	// Since startedAt is unexported, we test the behavior with a known server
+	// that was just created (uptime should be very small)
+	cfg := &config.Config{}
+	s := NewServer(cfg, context.Background())
+
+	// Small delay to ensure uptime is at least 0 seconds
+	time.Sleep(10 * time.Millisecond)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/uptime", nil)
+	w := httptest.NewRecorder()
+
+	s.handleUptime(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var resp UptimeResponse
+	err := json.NewDecoder(w.Body).Decode(&resp)
+	assert.NoError(t, err)
+
+	// Uptime should be at least 0 (it's int() of seconds, so minimum is 0)
+	assert.GreaterOrEqual(t, resp.UptimeSeconds, 0)
+	// Start time should be parseable
+	_, err = time.Parse(time.RFC3339, resp.StartTime)
+	assert.NoError(t, err)
+}

pkg/user/api/magic_link_handler.go

@@ -0,0 +1,277 @@
+package api
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"dance-lessons-coach/pkg/config"
+	"dance-lessons-coach/pkg/email"
+	"dance-lessons-coach/pkg/user"
+	"dance-lessons-coach/pkg/validation"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/rs/zerolog/log"
+)
+
+// MagicLinkHandler exposes the passwordless-auth endpoints described
+// in ADR-0028 Phase A : `POST /magic-link/request` and
+// `GET /magic-link/consume?token=...`.
+type MagicLinkHandler struct {
+	tokens      user.MagicLinkRepository
+	users       user.UserService
+	repo        user.UserRepository // for GetUserByUsername (sign-up flow)
+	sender      email.Sender
+	cfg         config.MagicLinkConfig
+	emailFrom   string
+	validator   *validation.Validator
+	clock       func() time.Time
+	newPassword func() (string, error)
+}
+
+// NewMagicLinkHandler wires the handler. emailFrom must be the From
+// address (typically cfg.GetEmailConfig().From).
+func NewMagicLinkHandler(
+	tokens user.MagicLinkRepository,
+	users user.UserService,
+	repo user.UserRepository,
+	sender email.Sender,
+	cfg config.MagicLinkConfig,
+	emailFrom string,
+	validator *validation.Validator,
+) *MagicLinkHandler {
+	return &MagicLinkHandler{
+		tokens:    tokens,
+		users:     users,
+		repo:      repo,
+		sender:    sender,
+		cfg:       cfg,
+		emailFrom: emailFrom,
+		validator: validator,
+		clock:     time.Now,
+		newPassword: func() (string, error) {
+			// 32 bytes = 256 bits of entropy. Encoded as 64 hex chars
+			// (well under bcrypt's 72-byte input limit; 48 bytes -> 96
+			// hex chars overflowed and broke first-link signup).
+			var raw [32]byte
+			if _, err := rand.Read(raw[:]); err != nil {
+				return "", err
+			}
+			return hex.EncodeToString(raw[:]), nil
+		},
+	}
+}
+
+// RegisterRoutes mounts the two endpoints on the provided router.
+func (h *MagicLinkHandler) RegisterRoutes(router chi.Router) {
+	router.Post("/magic-link/request", h.handleRequest)
+	router.Get("/magic-link/consume", h.handleConsume)
+}
+
+// MagicLinkRequest is the body of POST /magic-link/request.
+type MagicLinkRequest struct {
+	Email string `json:"email" validate:"required,email,max=255"`
+}
+
+// MagicLinkResponse is the response shape for both endpoints.
+type MagicLinkResponse struct {
+	Message string `json:"message"`
+	Token   string `json:"token,omitempty"`
+}
+
+// handleRequest godoc
+//
+//	@Summary		Request a magic link
+//	@Description	Generates a passwordless-auth one-time token and emails it. Always 200 to prevent email enumeration.
+//	@Tags			API/v1/User
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		MagicLinkRequest	true	"Email address"
+//	@Success		200		{object}	MagicLinkResponse	"Email queued (or silently dropped)"
+//	@Failure		400		{object}	map[string]string	"Invalid request body"
+//	@Router			/v1/auth/magic-link/request [post]
+func (h *MagicLinkHandler) handleRequest(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	var req MagicLinkRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, `{"error":"invalid_request","message":"Invalid JSON request body"}`, http.StatusBadRequest)
+		return
+	}
+	if h.validator != nil {
+		if err := h.validator.Validate(req); err != nil {
+			h.writeValidationError(w, err)
+			return
+		}
+	}
+
+	addr := strings.ToLower(strings.TrimSpace(req.Email))
+
+	plain, hashHex, err := user.GenerateMagicLinkToken()
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Msg("magic link request: rand failed")
+		http.Error(w, `{"error":"server_error","message":"Failed to generate token"}`, http.StatusInternalServerError)
+		return
+	}
+
+	now := h.clock()
+	tok := &user.MagicLinkToken{
+		Email:     addr,
+		TokenHash: hashHex,
+		ExpiresAt: now.Add(h.cfg.TTL),
+	}
+	if err := h.tokens.CreateMagicLinkToken(ctx, tok); err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("email", addr).Msg("magic link request: persist failed")
+		writeJSON(w, http.StatusOK, MagicLinkResponse{Message: "If that email is valid, a link has been sent."})
+		return
+	}
+
+	link := buildMagicLinkURL(h.cfg.BaseURL, plain)
+	subject := "Your sign-in link"
+	bodyText := fmt.Sprintf("Sign in by clicking the link below.\n\n%s\n\nThe link is valid for %s and can only be used once.\nIf you did not request this, ignore this email.\n", link, h.cfg.TTL)
+	bodyHTML := fmt.Sprintf(`<p>Sign in by clicking the link below.</p><p><a href="%s">%s</a></p><p>The link is valid for %s and can only be used once.<br>If you did not request this, ignore this email.</p>`, link, link, h.cfg.TTL)
+
+	msg := email.Message{
+		From:     h.emailFrom,
+		To:       addr,
+		Subject:  subject,
+		BodyText: bodyText,
+		BodyHTML: bodyHTML,
+	}
+	if err := h.sender.Send(ctx, msg); err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("to", addr).Msg("magic link request: email send failed")
+	}
+	writeJSON(w, http.StatusOK, MagicLinkResponse{Message: "If that email is valid, a link has been sent."})
+}
+
+// handleConsume validates the token, marks it consumed, ensures a
+// matching User row exists (sign-up on first link), and issues a JWT.
+//
+// All failure modes (missing, expired, already-consumed) collapse to a
+// single 401 to prevent attackers distinguishing them.
+//
+//	@Summary		Consume a magic link
+//	@Description	Validates the magic-link token, ensures the user exists (signup-on-first-use), issues a JWT.
+//	@Tags			API/v1/User
+//	@Produce		json
+//	@Param			token	query		string				true	"The magic-link token"
+//	@Success		200		{object}	MagicLinkResponse	"Signed in"
+//	@Failure		400		{object}	map[string]string	"Missing token"
+//	@Failure		401		{object}	map[string]string	"Invalid or expired token"
+//	@Router			/v1/auth/magic-link/consume [get]
+func (h *MagicLinkHandler) handleConsume(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	plain := strings.TrimSpace(r.URL.Query().Get("token"))
+	if plain == "" {
+		writeJSONError(w, http.StatusBadRequest, "invalid_request", "missing token")
+		return
+	}
+
+	tok, err := h.tokens.GetMagicLinkTokenByHash(ctx, user.HashMagicLinkToken(plain))
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Msg("magic link consume: lookup failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", "lookup failed")
+		return
+	}
+	if tok == nil || tok.ConsumedAt != nil || h.clock().After(tok.ExpiresAt) {
+		writeJSONError(w, http.StatusUnauthorized, "invalid_token", "magic link is invalid or expired")
+		return
+	}
+
+	if err := h.tokens.MarkMagicLinkTokenConsumed(ctx, tok.ID, h.clock()); err != nil {
+		log.Error().Ctx(ctx).Err(err).Uint("id", tok.ID).Msg("magic link consume: mark failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", "consume failed")
+		return
+	}
+
+	u, err := h.ensureUser(ctx, tok.Email)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("email", tok.Email).Msg("magic link consume: user upsert failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", "user upsert failed")
+		return
+	}
+
+	jwt, err := h.users.GenerateJWT(ctx, u)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Msg("magic link consume: JWT generation failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", "jwt generation failed")
+		return
+	}
+
+	writeJSON(w, http.StatusOK, MagicLinkResponse{Message: "signed in", Token: jwt})
+}
+
+// ensureUser returns the user keyed on email (stored as Username),
+// creating them if absent. Newly-created users get a random unguessable
+// bcrypt-hashed password so the password endpoints stay locked out.
+func (h *MagicLinkHandler) ensureUser(ctx context.Context, email string) (*user.User, error) {
+	if h.repo != nil {
+		existing, err := h.repo.GetUserByUsername(ctx, email)
+		if err != nil {
+			return nil, err
+		}
+		if existing != nil {
+			return existing, nil
+		}
+	}
+
+	rawPass, err := h.newPassword()
+	if err != nil {
+		return nil, fmt.Errorf("magic link signup rand: %w", err)
+	}
+	hash, err := h.users.HashPassword(ctx, rawPass)
+	if err != nil {
+		return nil, fmt.Errorf("magic link signup hash: %w", err)
+	}
+	u := &user.User{
+		Username:     email,
+		PasswordHash: hash,
+		IsAdmin:      false,
+	}
+	if err := h.users.CreateUser(ctx, u); err != nil {
+		return nil, fmt.Errorf("magic link signup create: %w", err)
+	}
+	if h.repo != nil {
+		return h.repo.GetUserByUsername(ctx, email)
+	}
+	return u, nil
+}
+
+func (h *MagicLinkHandler) writeValidationError(w http.ResponseWriter, err error) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusBadRequest)
+	var ve *validation.ValidationError
+	if errors.As(err, &ve) {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"error":   "validation_failed",
+			"message": "Invalid request data",
+			"details": ve.Messages,
+		})
+		return
+	}
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"error":   "validation_failed",
+		"message": err.Error(),
+	})
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+func writeJSONError(w http.ResponseWriter, status int, code, msg string) {
+	writeJSON(w, status, map[string]string{"error": code, "message": msg})
+}
+
+func buildMagicLinkURL(baseURL, token string) string {
+	base := strings.TrimRight(baseURL, "/")
+	return fmt.Sprintf("%s/api/v1/auth/magic-link/consume?token=%s", base, token)
+}

pkg/user/api/magic_link_handler_test.go

@@ -0,0 +1,371 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"dance-lessons-coach/pkg/config"
+	"dance-lessons-coach/pkg/email"
+	"dance-lessons-coach/pkg/user"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeMLRepo is an in-memory MagicLinkRepository for the handler tests.
+type fakeMLRepo struct {
+	mu     sync.Mutex
+	tokens map[string]*user.MagicLinkToken // key: TokenHash
+	nextID uint
+	failOn string // "create" / "get" / "mark" / "" (none)
+}
+
+func newFakeMLRepo() *fakeMLRepo {
+	return &fakeMLRepo{tokens: map[string]*user.MagicLinkToken{}}
+}
+
+func (r *fakeMLRepo) CreateMagicLinkToken(_ context.Context, t *user.MagicLinkToken) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.failOn == "create" {
+		return errors.New("simulated create failure")
+	}
+	r.nextID++
+	t.ID = r.nextID
+	r.tokens[t.TokenHash] = t
+	return nil
+}
+
+func (r *fakeMLRepo) GetMagicLinkTokenByHash(_ context.Context, h string) (*user.MagicLinkToken, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.failOn == "get" {
+		return nil, errors.New("simulated get failure")
+	}
+	t, ok := r.tokens[h]
+	if !ok {
+		return nil, nil
+	}
+	cp := *t
+	return &cp, nil
+}
+
+func (r *fakeMLRepo) MarkMagicLinkTokenConsumed(_ context.Context, id uint, when time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.failOn == "mark" {
+		return errors.New("simulated mark failure")
+	}
+	for _, t := range r.tokens {
+		if t.ID == id {
+			t.ConsumedAt = &when
+			return nil
+		}
+	}
+	return errors.New("not found")
+}
+
+func (r *fakeMLRepo) DeleteExpiredMagicLinkTokens(_ context.Context, _ time.Time) (int64, error) {
+	return 0, nil
+}
+
+// fakeUserSvc is a minimal user.UserService stub.
+type fakeUserSvc struct {
+	createdUsers []*user.User
+	jwtForID     map[uint]string
+	hashCalls    int
+	failOn       string // "create" / "hash" / "jwt"
+}
+
+func newFakeUserSvc() *fakeUserSvc { return &fakeUserSvc{jwtForID: map[uint]string{}} }
+
+func (s *fakeUserSvc) Authenticate(_ context.Context, _, _ string) (*user.User, error) {
+	return nil, errors.New("not used in magic-link tests")
+}
+func (s *fakeUserSvc) GenerateJWT(_ context.Context, u *user.User) (string, error) {
+	if s.failOn == "jwt" {
+		return "", errors.New("simulated jwt failure")
+	}
+	return "jwt-for-user-" + u.Username, nil
+}
+func (s *fakeUserSvc) ValidateJWT(_ context.Context, _ string) (*user.User, error) {
+	return nil, errors.New("not used")
+}
+func (s *fakeUserSvc) AdminAuthenticate(_ context.Context, _ string) (*user.User, error) {
+	return nil, errors.New("not used")
+}
+func (s *fakeUserSvc) AddJWTSecret(_ string, _ bool, _ time.Duration)               {}
+func (s *fakeUserSvc) RotateJWTSecret(_ string)                                     {}
+func (s *fakeUserSvc) GetJWTSecretByIndex(_ int) (string, bool)                     { return "", false }
+func (s *fakeUserSvc) ResetJWTSecrets()                                             {}
+func (s *fakeUserSvc) StartJWTSecretCleanupLoop(_ context.Context, _ time.Duration) {}
+func (s *fakeUserSvc) RemoveExpiredJWTSecrets() int                                 { return 0 }
+func (s *fakeUserSvc) ListJWTSecretsInfo() []user.JWTSecretInfo                     { return nil }
+
+func (s *fakeUserSvc) UserExists(_ context.Context, username string) (bool, error) {
+	for _, u := range s.createdUsers {
+		if u.Username == username {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+func (s *fakeUserSvc) CreateUser(_ context.Context, u *user.User) error {
+	if s.failOn == "create" {
+		return errors.New("simulated create failure")
+	}
+	u.ID = uint(len(s.createdUsers) + 1)
+	cp := *u
+	s.createdUsers = append(s.createdUsers, &cp)
+	return nil
+}
+func (s *fakeUserSvc) HashPassword(_ context.Context, p string) (string, error) {
+	s.hashCalls++
+	if s.failOn == "hash" {
+		return "", errors.New("simulated hash failure")
+	}
+	return "hash:" + p, nil
+}
+func (s *fakeUserSvc) RequestPasswordReset(_ context.Context, _ string) error { return nil }
+func (s *fakeUserSvc) CompletePasswordReset(_ context.Context, _, _ string) error {
+	return nil
+}
+
+// fakeUserRepo implements user.UserRepository using fakeUserSvc's slice.
+type fakeUserRepo struct{ svc *fakeUserSvc }
+
+func (r *fakeUserRepo) CreateUser(_ context.Context, u *user.User) error {
+	return r.svc.CreateUser(context.Background(), u)
+}
+func (r *fakeUserRepo) GetUserByUsername(_ context.Context, name string) (*user.User, error) {
+	for _, u := range r.svc.createdUsers {
+		if u.Username == name {
+			cp := *u
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+func (r *fakeUserRepo) GetUserByID(_ context.Context, _ uint) (*user.User, error) { return nil, nil }
+func (r *fakeUserRepo) UpdateUser(_ context.Context, _ *user.User) error          { return nil }
+func (r *fakeUserRepo) DeleteUser(_ context.Context, _ uint) error                { return nil }
+func (r *fakeUserRepo) AllowPasswordReset(_ context.Context, _ string) error      { return nil }
+func (r *fakeUserRepo) CompletePasswordReset(_ context.Context, _, _ string) error {
+	return nil
+}
+func (r *fakeUserRepo) UserExists(_ context.Context, name string) (bool, error) {
+	return r.svc.UserExists(context.Background(), name)
+}
+func (r *fakeUserRepo) CheckDatabaseHealth(_ context.Context) error { return nil }
+
+// recordingSender captures email.Send calls without sending anything.
+type recordingSender struct {
+	mu       sync.Mutex
+	messages []email.Message
+	failNext bool
+}
+
+func (s *recordingSender) Send(_ context.Context, m email.Message) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.failNext {
+		return errors.New("simulated send failure")
+	}
+	s.messages = append(s.messages, m)
+	return nil
+}
+
+func newHandler(t *testing.T) (*MagicLinkHandler, *fakeMLRepo, *fakeUserSvc, *recordingSender) {
+	t.Helper()
+	mlRepo := newFakeMLRepo()
+	svc := newFakeUserSvc()
+	repo := &fakeUserRepo{svc: svc}
+	sender := &recordingSender{}
+	h := NewMagicLinkHandler(
+		mlRepo, svc, repo, sender,
+		config.MagicLinkConfig{TTL: 15 * time.Minute, BaseURL: "http://test.local"},
+		"noreply@test.local",
+		nil,
+	)
+	return h, mlRepo, svc, sender
+}
+
+func mountAndRequest(h *MagicLinkHandler, method, path, body string) *httptest.ResponseRecorder {
+	r := chi.NewRouter()
+	h.RegisterRoutes(r)
+	req := httptest.NewRequest(method, path, strings.NewReader(body))
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+	return rr
+}
+
+// TestRequest_HappyPath confirms POST /magic-link/request stores a token,
+// sends an email containing the link, and returns 200 with a generic body.
+func TestRequest_HappyPath(t *testing.T) {
+	h, mlRepo, _, sender := newHandler(t)
+
+	rr := mountAndRequest(h, http.MethodPost, "/magic-link/request", `{"email":"alice@example.com"}`)
+	require.Equal(t, http.StatusOK, rr.Code)
+	assert.Contains(t, rr.Body.String(), "If that email is valid")
+
+	// One token persisted, email lower-cased.
+	require.Len(t, mlRepo.tokens, 1)
+	for _, tok := range mlRepo.tokens {
+		assert.Equal(t, "alice@example.com", tok.Email)
+		assert.Greater(t, tok.ExpiresAt.Unix(), time.Now().Unix())
+	}
+
+	// One email sent to the same address, link points at our test base URL.
+	require.Len(t, sender.messages, 1)
+	assert.Equal(t, "alice@example.com", sender.messages[0].To)
+	assert.Contains(t, sender.messages[0].BodyText, "http://test.local/api/v1/auth/magic-link/consume?token=")
+}
+
+// TestRequest_NormalizesEmail confirms the email is lower-cased + trimmed.
+func TestRequest_NormalizesEmail(t *testing.T) {
+	h, mlRepo, _, sender := newHandler(t)
+	rr := mountAndRequest(h, http.MethodPost, "/magic-link/request", `{"email":"  Alice@Example.COM  "}`)
+	require.Equal(t, http.StatusOK, rr.Code)
+	require.Len(t, mlRepo.tokens, 1)
+	for _, tok := range mlRepo.tokens {
+		assert.Equal(t, "alice@example.com", tok.Email)
+	}
+	assert.Equal(t, "alice@example.com", sender.messages[0].To)
+}
+
+// TestRequest_BadJSON returns 400.
+func TestRequest_BadJSON(t *testing.T) {
+	h, _, _, _ := newHandler(t)
+	rr := mountAndRequest(h, http.MethodPost, "/magic-link/request", `not json`)
+	assert.Equal(t, http.StatusBadRequest, rr.Code)
+}
+
+// TestRequest_PersistFailureStillReturns200 — a DB error must NOT leak
+// to the user (would let attackers detect storage outages).
+func TestRequest_PersistFailureStillReturns200(t *testing.T) {
+	h, mlRepo, _, sender := newHandler(t)
+	mlRepo.failOn = "create"
+	rr := mountAndRequest(h, http.MethodPost, "/magic-link/request", `{"email":"bob@example.com"}`)
+	assert.Equal(t, http.StatusOK, rr.Code)
+	// No email was sent because no token was persisted.
+	assert.Empty(t, sender.messages)
+}
+
+// TestConsume_HappyPath_NewUser exercises sign-up-on-first-link.
+func TestConsume_HappyPath_NewUser(t *testing.T) {
+	h, mlRepo, svc, _ := newHandler(t)
+
+	// Seed one token by going through the request flow.
+	mountAndRequest(h, http.MethodPost, "/magic-link/request", `{"email":"alice@example.com"}`)
+	require.Len(t, mlRepo.tokens, 1)
+
+	// We need the plaintext to consume — derive it from the only token in the
+	// repo by reverse trick : the request handler doesn't expose it. So we
+	// drive consume with a fresh known-plaintext we put into the repo
+	// directly.
+	plain, hashHex, err := user.GenerateMagicLinkToken()
+	require.NoError(t, err)
+	mlRepo.tokens = map[string]*user.MagicLinkToken{
+		hashHex: {ID: 99, Email: "alice@example.com", TokenHash: hashHex, ExpiresAt: time.Now().Add(5 * time.Minute)},
+	}
+	mlRepo.nextID = 99
+
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume?token="+plain, "")
+	require.Equal(t, http.StatusOK, rr.Code, rr.Body.String())
+
+	var resp MagicLinkResponse
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	assert.Equal(t, "signed in", resp.Message)
+	assert.Equal(t, "jwt-for-user-alice@example.com", resp.Token)
+
+	// User was created.
+	require.Len(t, svc.createdUsers, 1)
+	assert.Equal(t, "alice@example.com", svc.createdUsers[0].Username)
+	assert.NotEmpty(t, svc.createdUsers[0].PasswordHash, "passwordless user must still have a non-empty hash (random unguessable value)")
+	assert.Equal(t, 1, svc.hashCalls)
+
+	// Token marked consumed.
+	for _, tok := range mlRepo.tokens {
+		require.NotNil(t, tok.ConsumedAt, "consumed_at must be set after consume")
+	}
+}
+
+// TestConsume_HappyPath_ExistingUser confirms no new user is created
+// when the email is already known.
+func TestConsume_HappyPath_ExistingUser(t *testing.T) {
+	h, mlRepo, svc, _ := newHandler(t)
+
+	// Pre-seed the user.
+	require.NoError(t, svc.CreateUser(context.Background(), &user.User{Username: "carol@example.com", PasswordHash: "x"}))
+	require.Len(t, svc.createdUsers, 1)
+	preCount := len(svc.createdUsers)
+
+	plain, hashHex, err := user.GenerateMagicLinkToken()
+	require.NoError(t, err)
+	mlRepo.tokens[hashHex] = &user.MagicLinkToken{ID: 1, Email: "carol@example.com", TokenHash: hashHex, ExpiresAt: time.Now().Add(5 * time.Minute)}
+
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume?token="+plain, "")
+	require.Equal(t, http.StatusOK, rr.Code, rr.Body.String())
+
+	// No new user.
+	assert.Len(t, svc.createdUsers, preCount)
+	assert.Equal(t, 0, svc.hashCalls, "no hash call when user exists")
+}
+
+// TestConsume_MissingToken returns 400.
+func TestConsume_MissingToken(t *testing.T) {
+	h, _, _, _ := newHandler(t)
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume", "")
+	assert.Equal(t, http.StatusBadRequest, rr.Code)
+}
+
+// TestConsume_UnknownToken returns 401 (single generic shape).
+func TestConsume_UnknownToken(t *testing.T) {
+	h, _, _, _ := newHandler(t)
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume?token=neverissued", "")
+	assert.Equal(t, http.StatusUnauthorized, rr.Code)
+}
+
+// TestConsume_ExpiredToken returns 401.
+func TestConsume_ExpiredToken(t *testing.T) {
+	h, mlRepo, _, _ := newHandler(t)
+	plain, hashHex, err := user.GenerateMagicLinkToken()
+	require.NoError(t, err)
+	mlRepo.tokens[hashHex] = &user.MagicLinkToken{
+		ID: 1, Email: "x@example.com", TokenHash: hashHex,
+		ExpiresAt: time.Now().Add(-1 * time.Minute), // already expired
+	}
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume?token="+plain, "")
+	assert.Equal(t, http.StatusUnauthorized, rr.Code)
+}
+
+// TestConsume_AlreadyConsumed returns 401 — single-use guarantee.
+func TestConsume_AlreadyConsumed(t *testing.T) {
+	h, mlRepo, _, _ := newHandler(t)
+	plain, hashHex, err := user.GenerateMagicLinkToken()
+	require.NoError(t, err)
+	now := time.Now()
+	mlRepo.tokens[hashHex] = &user.MagicLinkToken{
+		ID: 1, Email: "x@example.com", TokenHash: hashHex,
+		ExpiresAt: now.Add(5 * time.Minute), ConsumedAt: &now,
+	}
+	rr := mountAndRequest(h, http.MethodGet, "/magic-link/consume?token="+plain, "")
+	assert.Equal(t, http.StatusUnauthorized, rr.Code)
+}
+
+// TestBuildMagicLinkURL_TrailingSlash exercises the small helper.
+func TestBuildMagicLinkURL_TrailingSlash(t *testing.T) {
+	got := buildMagicLinkURL("http://x.local/", "abc")
+	assert.Equal(t, "http://x.local/api/v1/auth/magic-link/consume?token=abc", got)
+}

pkg/user/api/oidc_handler.go

@@ -0,0 +1,329 @@
+package api
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"net/http"
+	"net/url"
+	"sync"
+	"time"
+
+	"dance-lessons-coach/pkg/auth"
+	"dance-lessons-coach/pkg/user"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/rs/zerolog/log"
+)
+
+// OIDCHandler exposes the OIDC authorization-code endpoints.
+type OIDCHandler struct {
+	clients      map[string]*auth.OIDCClient // keyed by provider name
+	users        user.UserService
+	repo         user.UserRepository
+	redirectBase string
+
+	pkceMu    sync.Mutex
+	pkceStore map[string]pkceEntry
+}
+
+type pkceEntry struct {
+	codeVerifier string
+	providerName string
+	expiresAt    time.Time
+}
+
+// NewOIDCHandler creates a new OIDCHandler.
+func NewOIDCHandler(clients map[string]*auth.OIDCClient, users user.UserService, repo user.UserRepository, redirectBase string) *OIDCHandler {
+	return &OIDCHandler{
+		clients:      clients,
+		users:        users,
+		repo:         repo,
+		redirectBase: redirectBase,
+		pkceStore:    make(map[string]pkceEntry),
+	}
+}
+
+// RegisterRoutes mounts the OIDC endpoints on the provided router.
+func (h *OIDCHandler) RegisterRoutes(router chi.Router) {
+	router.Get("/oidc/{provider}/start", h.handleStart)
+	router.Get("/oidc/{provider}/callback", h.handleCallback)
+}
+
+// handleStart initiates the OIDC authorization-code flow.
+//
+//	@Summary		Start OIDC authorization
+//	@Description	Generates PKCE state and verifier, redirects to the OIDC provider authorization endpoint.
+//	@Tags		API/v1/User
+//	@Produce		json
+//	@Param		provider	path		string		true	"OIDC provider name"
+//	@Success		302		{string}string	"Redirect to OIDC provider"
+//	@Failure		404		{object}map[string]string	"Unknown provider"
+//	@Failure		502		{object}map[string]string	"Discovery failed"
+//	@Router		/v1/auth/oidc/{provider}/start [get]
+func (h *OIDCHandler) handleStart(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	provider := chi.URLParam(r, "provider")
+
+	client, exists := h.clients[provider]
+	if !exists {
+		log.Warn().Ctx(ctx).Str("provider", provider).Msg("OIDC start: unknown provider")
+		writeJSONError(w, http.StatusNotFound, "unknown_provider", "unknown OIDC provider")
+		return
+	}
+
+	// Ensure discovery is loaded
+	disc, err := client.Discover(ctx)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("provider", provider).Msg("OIDC start: discovery failed")
+		writeJSONError(w, http.StatusBadGateway, "discovery_failed", fmt.Sprintf("OIDC discovery failed: %v", err))
+		return
+	}
+
+	// Generate state: 32 bytes random, base64-url-no-padding
+	state := generateRandomBase64URL(32)
+
+	// Generate code verifier: 32 bytes random, base64-url-no-padding
+	codeVerifier := generateRandomBase64URL(32)
+
+	// Compute code challenge: SHA256 hash of code verifier, base64-url-no-padding
+	hash := sha256.Sum256([]byte(codeVerifier))
+	codeChallenge := base64.RawURLEncoding.EncodeToString(hash[:])
+
+	// Store PKCE entry
+	h.pkceMu.Lock()
+	// Lazy-clean expired entries
+	now := time.Now()
+	for k, entry := range h.pkceStore {
+		if entry.expiresAt.Before(now) {
+			delete(h.pkceStore, k)
+		}
+	}
+	h.pkceStore[state] = pkceEntry{
+		codeVerifier: codeVerifier,
+		providerName: provider,
+		expiresAt:    now.Add(10 * time.Minute),
+	}
+	h.pkceMu.Unlock()
+
+	// Build redirect URL
+	redirectURI := fmt.Sprintf("%s/api/v1/auth/oidc/%s/callback", h.redirectBase, provider)
+
+	v := url.Values{}
+	v.Set("response_type", "code")
+	v.Set("client_id", client.ClientID())
+	v.Set("redirect_uri", redirectURI)
+	v.Set("state", state)
+	v.Set("code_challenge", codeChallenge)
+	v.Set("code_challenge_method", "S256")
+	v.Set("scope", "openid email profile")
+
+	target := disc.AuthorizationEndpoint + "?" + v.Encode()
+
+	log.Debug().Ctx(ctx).Str("provider", provider).Str("target", target).Msg("OIDC start: redirecting to provider")
+
+	http.Redirect(w, r, target, http.StatusFound)
+}
+
+// handleCallback handles the OIDC callback after authorization.
+//
+//	@Summary		OIDC callback handler
+//	@Description	Validates state, exchanges code for tokens, validates id_token, signs up on first use, issues JWT.
+//	@Tags		API/v1/User
+//	@Produce		json
+//	@Param		provider	path		string		true	"OIDC provider name"
+//	@Param		state		query		string		true	"State parameter"
+//	@Param		code		query		string		false	"Authorization code"
+//	@Param		error		query		string		false	"OIDC error"
+//	@Success		200		{object}	OIDCCallbackResponse	"Successfully signed in via OIDC"
+//	@Failure		401		{object}	map[string]string	"Invalid state, missing code, or OIDC error"
+//	@Failure		502		{object}	map[string]string	"Token exchange or validation failed"
+//	@Failure		500		{object}	map[string]string	"Internal server error"
+//	@Router		/v1/auth/oidc/{provider}/callback [get]
+func (h *OIDCHandler) handleCallback(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	provider := chi.URLParam(r, "provider")
+
+	client, exists := h.clients[provider]
+	if !exists {
+		log.Warn().Ctx(ctx).Str("provider", provider).Msg("OIDC callback: unknown provider")
+		writeJSONError(w, http.StatusNotFound, "unknown_provider", "unknown OIDC provider")
+		return
+	}
+
+	// Read query parameters
+	state := r.URL.Query().Get("state")
+	code := r.URL.Query().Get("code")
+	oidcError := r.URL.Query().Get("error")
+
+	// If OIDC provider returned an error
+	if oidcError != "" {
+		log.Warn().Ctx(ctx).Str("provider", provider).Str("error", oidcError).Msg("OIDC callback: provider error")
+		writeJSON(w, http.StatusUnauthorized, map[string]string{
+			"error":          "oidc_error",
+			"provider_error": oidcError,
+		})
+		return
+	}
+
+	// Validate state
+	if state == "" {
+		log.Warn().Ctx(ctx).Msg("OIDC callback: missing state")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_state", "missing state parameter")
+		return
+	}
+
+	h.pkceMu.Lock()
+	entry, exists := h.pkceStore[state]
+	if !exists {
+		h.pkceMu.Unlock()
+		log.Warn().Ctx(ctx).Str("state", state).Msg("OIDC callback: state not found")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_state", "state not found or already used")
+		return
+	}
+
+	// Check expiration and provider match
+	now := time.Now()
+	if entry.expiresAt.Before(now) {
+		delete(h.pkceStore, state)
+		h.pkceMu.Unlock()
+		log.Warn().Ctx(ctx).Str("state", state).Msg("OIDC callback: state expired")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_state", "state expired")
+		return
+	}
+
+	if entry.providerName != provider {
+		delete(h.pkceStore, state)
+		h.pkceMu.Unlock()
+		log.Warn().Ctx(ctx).Str("state", state).Str("expected_provider", entry.providerName).Str("actual_provider", provider).Msg("OIDC callback: provider mismatch")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_state", "provider mismatch")
+		return
+	}
+
+	// Delete the entry (single-use)
+	codeVerifier := entry.codeVerifier
+	delete(h.pkceStore, state)
+	h.pkceMu.Unlock()
+
+	// Validate code parameter
+	if code == "" {
+		log.Warn().Ctx(ctx).Msg("OIDC callback: missing code")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_request", "missing authorization code")
+		return
+	}
+
+	// Build redirect URI
+	redirectURI := fmt.Sprintf("%s/api/v1/auth/oidc/%s/callback", h.redirectBase, provider)
+
+	// Exchange code for tokens
+	tokenResp, err := client.ExchangeCode(ctx, code, codeVerifier, redirectURI)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("provider", provider).Msg("OIDC callback: code exchange failed")
+		writeJSONError(w, http.StatusBadGateway, "token_exchange_failed", fmt.Sprintf("code exchange failed: %v", err))
+		return
+	}
+
+	// Validate ID token
+	claims, err := client.ValidateIDToken(ctx, tokenResp.IDToken)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("provider", provider).Msg("OIDC callback: ID token validation failed")
+		writeJSONError(w, http.StatusUnauthorized, "invalid_id_token", fmt.Sprintf("ID token validation failed: %v", err))
+		return
+	}
+
+	// Check email in claims
+	if claims.Email == "" {
+		log.Warn().Ctx(ctx).Str("provider", provider).Msg("OIDC callback: no email in ID token")
+		writeJSONError(w, http.StatusUnauthorized, "no_email_in_id_token", "ID token does not contain an email claim")
+		return
+	}
+
+	// Ensure user exists (sign-up on first use)
+	u, err := h.ensureUser(ctx, claims.Email)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("email", claims.Email).Msg("OIDC callback: user upsert failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", fmt.Sprintf("user upsert failed: %v", err))
+		return
+	}
+
+	// Generate JWT
+	jwtToken, err := h.users.GenerateJWT(ctx, u)
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Str("email", claims.Email).Msg("OIDC callback: JWT generation failed")
+		writeJSONError(w, http.StatusInternalServerError, "server_error", fmt.Sprintf("JWT generation failed: %v", err))
+		return
+	}
+
+	log.Info().Ctx(ctx).Str("provider", provider).Str("email", claims.Email).Msg("OIDC callback: user signed in successfully")
+
+	writeJSON(w, http.StatusOK, map[string]string{
+		"message": "signed in via oidc",
+		"token":   jwtToken,
+		"user":    claims.Email,
+	})
+}
+
+// ensureUser returns the user keyed on email (stored as Username),
+// creating them if absent. Newly-created users get a random unguessable
+// bcrypt-hashed password so the password endpoints stay locked out.
+func (h *OIDCHandler) ensureUser(ctx context.Context, email string) (*user.User, error) {
+	if h.repo != nil {
+		existing, err := h.repo.GetUserByUsername(ctx, email)
+		if err != nil {
+			return nil, fmt.Errorf("get user by username: %w", err)
+		}
+		if existing != nil {
+			return existing, nil
+		}
+	}
+
+	// Generate random password
+	rawPass := generateRandomHex(32)
+	hash, err := h.users.HashPassword(ctx, rawPass)
+	if err != nil {
+		return nil, fmt.Errorf("hash password: %w", err)
+	}
+
+	u := &user.User{
+		Username:     email,
+		PasswordHash: hash,
+		IsAdmin:      false,
+	}
+
+	if err := h.users.CreateUser(ctx, u); err != nil {
+		return nil, fmt.Errorf("create user: %w", err)
+	}
+
+	if h.repo != nil {
+		return h.repo.GetUserByUsername(ctx, email)
+	}
+	return u, nil
+}
+
+// generateRandomBase64URL generates a random string suitable for use in OIDC PKCE flows.
+func generateRandomBase64URL(length int) string {
+	b := make([]byte, length)
+	if _, err := rand.Read(b); err != nil {
+		panic(fmt.Sprintf("failed to read random bytes: %v", err))
+	}
+	return base64.RawURLEncoding.EncodeToString(b)
+}
+
+// generateRandomHex generates a random hex string.
+func generateRandomHex(length int) string {
+	b := make([]byte, length/2)
+	if _, err := rand.Read(b); err != nil {
+		panic(fmt.Sprintf("failed to read random bytes: %v", err))
+	}
+	return hex.EncodeToString(b)
+}
+
+// OIDCCallbackResponse represents the JSON response from the OIDC callback.
+type OIDCCallbackResponse struct {
+	Message string `json:"message"`
+	Token   string `json:"token"`
+	User    string `json:"user"`
+}

pkg/user/api/oidc_handler_test.go

@@ -0,0 +1,134 @@
+package api
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"dance-lessons-coach/pkg/auth"
+	"dance-lessons-coach/pkg/user"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/assert"
+)
+
+// fakeUserSvc is reused from magic_link_handler_test.go
+// It's in the same package (api) so we can use it directly.
+
+// fakeUserRepo is reused from magic_link_handler_test.go
+// It's in the same package (api) so we can use it directly.
+
+// setupMockOIDCProvider creates a mock OIDC provider server for testing.
+// Uses the Q-062 mitigation pattern with var server *httptest.Server.
+func setupMockOIDCProvider(t *testing.T) *httptest.Server {
+	t.Helper()
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintf(w, `{"issuer":"%s","authorization_endpoint":"%s/auth","token_endpoint":"%s/token","jwks_uri":"%s/jwks"}`,
+				server.URL, server.URL, server.URL, server.URL)
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	return server
+}
+
+// mountOIDCHandler mounts the OIDCHandler on a new router and returns it.
+func mountOIDCHandler(t *testing.T, handler *OIDCHandler) *chi.Mux {
+	t.Helper()
+	r := chi.NewRouter()
+	handler.RegisterRoutes(r)
+	return r
+}
+
+// newTestOIDCHandler creates an OIDCHandler with the given clients.
+func newTestOIDCHandler(clients map[string]*auth.OIDCClient) *OIDCHandler {
+	return NewOIDCHandler(
+		clients,
+		newFakeUserSvc(),
+		&fakeUserRepo{svc: newFakeUserSvc()},
+		"http://localhost:8080",
+	)
+}
+
+// TestOIDCHandler_Start_RejectsUnknownProvider tests that starting with an unknown provider returns 404.
+func TestOIDCHandler_Start_RejectsUnknownProvider(t *testing.T) {
+	handler := newTestOIDCHandler(map[string]*auth.OIDCClient{})
+	router := mountOIDCHandler(t, handler)
+
+	req := httptest.NewRequest(http.MethodGet, "/oidc/unknown/start", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	assert.Equal(t, http.StatusNotFound, rr.Code)
+}
+
+// TestOIDCHandler_Callback_RejectsMissingState tests that callback without state returns 401.
+func TestOIDCHandler_Callback_RejectsMissingState(t *testing.T) {
+	client := auth.NewOIDCClient("http://mock-provider", "test-id", "test-secret")
+	handler := newTestOIDCHandler(map[string]*auth.OIDCClient{"test": client})
+	router := mountOIDCHandler(t, handler)
+
+	req := httptest.NewRequest(http.MethodGet, "/oidc/test/callback", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rr.Code)
+}
+
+// TestOIDCHandler_Callback_RejectsUnknownState tests that callback with unknown state returns 401.
+func TestOIDCHandler_Callback_RejectsUnknownState(t *testing.T) {
+	client := auth.NewOIDCClient("http://mock-provider", "test-id", "test-secret")
+	handler := newTestOIDCHandler(map[string]*auth.OIDCClient{"test": client})
+	router := mountOIDCHandler(t, handler)
+
+	req := httptest.NewRequest(http.MethodGet, "/oidc/test/callback?state=unknown&code=any", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rr.Code)
+}
+
+// TestOIDCHandler_Start_RedirectsWithPKCE tests that starting with a valid provider redirects with PKCE.
+func TestOIDCHandler_Start_RedirectsWithPKCE(t *testing.T) {
+	// Setup mock OIDC provider
+	mockServer := setupMockOIDCProvider(t)
+	defer mockServer.Close()
+
+	// Create OIDC client pointing to mock server
+	client := auth.NewOIDCClient(mockServer.URL, "test-id", "test-secret")
+	// Set a custom HTTP client that can reach the mock server
+	client.SetHTTPClient(mockServer.Client())
+
+	handler := newTestOIDCHandler(map[string]*auth.OIDCClient{"test": client})
+	router := mountOIDCHandler(t, handler)
+
+	req := httptest.NewRequest(http.MethodGet, "/oidc/test/start", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	// Assert 302 redirect
+	assert.Equal(t, http.StatusFound, rr.Code)
+
+	// Get Location header
+	location := rr.Header().Get("Location")
+	assert.NotEmpty(t, location)
+
+	// Location should start with the mock auth endpoint
+	expectedAuthEndpoint := mockServer.URL + "/auth"
+	assert.Contains(t, location, expectedAuthEndpoint)
+
+	// Location should contain code_challenge and state
+	assert.Contains(t, location, "code_challenge=")
+	assert.Contains(t, location, "state=")
+	assert.Contains(t, location, "response_type=code")
+	assert.Contains(t, location, "client_id=test-id")
+	assert.Contains(t, location, "code_challenge_method=S256")
+}
+
+// Ensure the interfaces are satisfied at compile time
+var _ user.UserService = (*fakeUserSvc)(nil)
+var _ user.UserRepository = (*fakeUserRepo)(nil)

pkg/user/auth_service.go

@@ -106,7 +106,7 @@ func (s *userServiceImpl) GenerateJWT(ctx context.Context, user *User) (string,
 	// Use the most recently added secret (last in the list)
 	// This ensures new tokens are signed with the latest secret
 	signingSecret := validSecrets[len(validSecrets)-1].Secret
-	log.Trace().Ctx(ctx).Str("signing_secret", signingSecret).Bool("is_primary", validSecrets[len(validSecrets)-1].IsPrimary).Msg("Generating JWT with latest secret")
+	log.Trace().Ctx(ctx).Str("signing_secret_fp", tokenFingerprint(signingSecret)).Bool("is_primary", validSecrets[len(validSecrets)-1].IsPrimary).Msg("Generating JWT with latest secret")
 
 	// Sign and get the complete encoded token as a string
 	tokenString, err := token.SignedString([]byte(signingSecret))
@@ -114,20 +114,20 @@ func (s *userServiceImpl) GenerateJWT(ctx context.Context, user *User) (string,
 		return "", fmt.Errorf("failed to sign JWT: %w", err)
 	}
 
-	log.Trace().Ctx(ctx).Str("token", tokenString).Msg("Generated JWT token")
+	log.Trace().Ctx(ctx).Str("token_fp", tokenFingerprint(tokenString)).Int("token_len", len(tokenString)).Msg("Generated JWT token")
 	return tokenString, nil
 }
 
 // ValidateJWT validates a JWT token and returns the user
 func (s *userServiceImpl) ValidateJWT(ctx context.Context, tokenString string) (*User, error) {
-	log.Trace().Ctx(ctx).Str("token", tokenString).Msg("Validating JWT token")
+	log.Trace().Ctx(ctx).Str("token_fp", tokenFingerprint(tokenString)).Int("token_len", len(tokenString)).Msg("Validating JWT token")
 
 	// Get all valid secrets for validation
 	validSecrets := s.secretManager.GetAllValidSecrets()
 
 	log.Trace().Ctx(ctx).Int("num_secrets", len(validSecrets)).Msg("Validating JWT with multiple secrets")
 	for i, secret := range validSecrets {
-		log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret", secret.Secret).Bool("is_primary", secret.IsPrimary).Msg("Trying secret")
+		log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret_fp", tokenFingerprint(secret.Secret)).Bool("is_primary", secret.IsPrimary).Msg("Trying secret")
 	}
 
 	// Try each valid secret until we find one that works
@@ -146,7 +146,7 @@ func (s *userServiceImpl) ValidateJWT(ctx context.Context, tokenString string) (
 		})
 
 		if err == nil && token.Valid {
-			log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret", secret.Secret).Msg("JWT validation successful")
+			log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret_fp", tokenFingerprint(secret.Secret)).Msg("JWT validation successful")
 			parsedToken = token
 			break
 		}
@@ -154,7 +154,7 @@ func (s *userServiceImpl) ValidateJWT(ctx context.Context, tokenString string) (
 		// Store the last error for reporting
 		validationError = err
 		if err != nil {
-			log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret", secret.Secret).Err(err).Msg("JWT validation failed")
+			log.Trace().Ctx(ctx).Int("secret_index", i).Str("secret_fp", tokenFingerprint(secret.Secret)).Err(err).Msg("JWT validation failed")
 		}
 	}
 
@@ -351,3 +351,13 @@ func (s *PasswordResetServiceImpl) CompletePasswordReset(ctx context.Context, us
 	// Complete the password reset
 	return s.repo.CompletePasswordReset(ctx, username, hashedPassword)
 }
+
+// tokenFingerprint returns the first 16 hex chars of SHA-256 hash of a token/secret.
+// Used for safe logging correlation without leaking sensitive values.
+func tokenFingerprint(tok string) string {
+	if tok == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(tok))
+	return hex.EncodeToString(sum[:8]) // 16 hex chars = 8 bytes
+}

pkg/user/magic_link.go

@@ -0,0 +1,150 @@
+package user
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"time"
+
+	"go.opentelemetry.io/otel/attribute"
+	"gorm.io/gorm"
+)
+
+// MagicLinkToken is the persistent record of a passwordless-auth token.
+//
+// Per ADR-0028 Phase A: the token VALUE is never stored. Only its SHA-256
+// hash sits in the DB ; if the table leaks, the attacker has no usable
+// tokens (mirrors ADR-0021 secret retention via fingerprint approach).
+//
+// The plaintext token is delivered to the user exactly once via email and
+// must be supplied back through the consume endpoint to re-derive the
+// hash and find the row.
+type MagicLinkToken struct {
+	ID         uint       `gorm:"primaryKey"`
+	CreatedAt  time.Time  `gorm:"autoCreateTime;not null;index"`
+	Email      string     `gorm:"not null;index"`
+	TokenHash  string     `gorm:"not null;uniqueIndex;size:64"` // hex-encoded sha256 = 64 chars
+	ExpiresAt  time.Time  `gorm:"not null;index"`
+	ConsumedAt *time.Time `gorm:""`
+}
+
+// MagicLinkRepository is the persistence contract for magic-link tokens.
+// PostgresRepository implements it ; tests can use a fake.
+type MagicLinkRepository interface {
+	CreateMagicLinkToken(ctx context.Context, token *MagicLinkToken) error
+	GetMagicLinkTokenByHash(ctx context.Context, tokenHash string) (*MagicLinkToken, error)
+	MarkMagicLinkTokenConsumed(ctx context.Context, id uint, consumedAt time.Time) error
+	DeleteExpiredMagicLinkTokens(ctx context.Context, before time.Time) (int64, error)
+}
+
+// GenerateMagicLinkToken returns a fresh url-safe random token suitable
+// for inclusion in an email link, plus its SHA-256 hex digest for storage.
+//
+// The plaintext is what gets emailed ; the hash is what gets persisted.
+// 32 bytes of entropy = 256 bits ; collision-resistant for our scale.
+func GenerateMagicLinkToken() (plaintext, hashHex string, err error) {
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", "", fmt.Errorf("magic link rand: %w", err)
+	}
+	plaintext = base64.RawURLEncoding.EncodeToString(buf)
+	hashHex = HashMagicLinkToken(plaintext)
+	return plaintext, hashHex, nil
+}
+
+// HashMagicLinkToken returns the lowercase hex sha256 of token. Stable
+// over time : the same plaintext always maps to the same hash, so
+// consume can re-derive and look up the row.
+func HashMagicLinkToken(plaintext string) string {
+	sum := sha256.Sum256([]byte(plaintext))
+	return hex.EncodeToString(sum[:])
+}
+
+// CreateMagicLinkToken persists a magic-link token. The caller is
+// responsible for hashing the plaintext (cf. HashMagicLinkToken) and
+// setting ExpiresAt ; this method does not generate either.
+func (r *PostgresRepository) CreateMagicLinkToken(ctx context.Context, token *MagicLinkToken) error {
+	ctx, span := r.createSpan(ctx, "create_magic_link_token")
+	if span != nil {
+		defer span.End()
+		span.SetAttributes(attribute.String("email", token.Email))
+	}
+	if err := r.db.WithContext(ctx).Create(token).Error; err != nil {
+		if span != nil {
+			span.RecordError(err)
+		}
+		return fmt.Errorf("failed to create magic link token: %w", err)
+	}
+	return nil
+}
+
+// GetMagicLinkTokenByHash looks up a magic-link token by its hex sha256.
+// Returns (nil, nil) when no row matches — callers must treat that as
+// "invalid token" and respond with the same generic error as "expired"
+// or "consumed" to avoid leaking which condition failed.
+func (r *PostgresRepository) GetMagicLinkTokenByHash(ctx context.Context, tokenHash string) (*MagicLinkToken, error) {
+	ctx, span := r.createSpan(ctx, "get_magic_link_token_by_hash")
+	if span != nil {
+		defer span.End()
+	}
+	var t MagicLinkToken
+	err := r.db.WithContext(ctx).Where("token_hash = ?", tokenHash).First(&t).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		if span != nil {
+			span.RecordError(err)
+		}
+		return nil, fmt.Errorf("failed to get magic link token: %w", err)
+	}
+	return &t, nil
+}
+
+// MarkMagicLinkTokenConsumed sets consumed_at on the row with the given
+// ID. Idempotent only at the SQL-engine level — the consume handler is
+// responsible for refusing to act when consumed_at is already set.
+func (r *PostgresRepository) MarkMagicLinkTokenConsumed(ctx context.Context, id uint, consumedAt time.Time) error {
+	ctx, span := r.createSpan(ctx, "mark_magic_link_token_consumed")
+	if span != nil {
+		defer span.End()
+	}
+	res := r.db.WithContext(ctx).
+		Model(&MagicLinkToken{}).
+		Where("id = ?", id).
+		Update("consumed_at", consumedAt)
+	if res.Error != nil {
+		if span != nil {
+			span.RecordError(res.Error)
+		}
+		return fmt.Errorf("failed to mark magic link token consumed: %w", res.Error)
+	}
+	if res.RowsAffected == 0 {
+		return fmt.Errorf("no magic link token with id=%d", id)
+	}
+	return nil
+}
+
+// DeleteExpiredMagicLinkTokens removes rows whose expires_at is strictly
+// before the given cutoff. Returns the count deleted. Used by the
+// scheduled cleanup job.
+func (r *PostgresRepository) DeleteExpiredMagicLinkTokens(ctx context.Context, before time.Time) (int64, error) {
+	ctx, span := r.createSpan(ctx, "delete_expired_magic_link_tokens")
+	if span != nil {
+		defer span.End()
+	}
+	res := r.db.WithContext(ctx).
+		Where("expires_at < ?", before).
+		Delete(&MagicLinkToken{})
+	if res.Error != nil {
+		if span != nil {
+			span.RecordError(res.Error)
+		}
+		return 0, fmt.Errorf("failed to delete expired magic link tokens: %w", res.Error)
+	}
+	return res.RowsAffected, nil
+}

pkg/user/magic_link_cleanup.go

@@ -0,0 +1,56 @@
+package user
+
+import (
+	"context"
+	"time"
+
+	"github.com/rs/zerolog/log"
+)
+
+// MagicLinkCleanupRunner periodically deletes expired magic-link tokens
+// (ADR-0028 Phase A consequence — the rows accumulate without cleanup
+// otherwise, and stale rows are pure overhead since the token plaintext
+// is never stored).
+type MagicLinkCleanupRunner struct {
+	repo MagicLinkRepository
+}
+
+// NewMagicLinkCleanupRunner creates a new cleanup runner.
+func NewMagicLinkCleanupRunner(repo MagicLinkRepository) *MagicLinkCleanupRunner {
+	return &MagicLinkCleanupRunner{repo: repo}
+}
+
+// StartCleanupLoop runs the cleanup pass every `interval`. Stops when ctx
+// is cancelled. interval <= 0 disables the loop.
+func (r *MagicLinkCleanupRunner) StartCleanupLoop(ctx context.Context, interval time.Duration) {
+	if interval <= 0 {
+		return
+	}
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				_, _ = r.runOnce(ctx)
+			}
+		}
+	}()
+}
+
+// runOnce performs a single cleanup pass. Returns the count of deleted rows.
+// Exposed for testing — tests drive runOnce directly instead of waiting on
+// the ticker.
+func (r *MagicLinkCleanupRunner) runOnce(ctx context.Context) (int64, error) {
+	n, err := r.repo.DeleteExpiredMagicLinkTokens(ctx, time.Now())
+	if err != nil {
+		log.Error().Ctx(ctx).Err(err).Msg("magic-link cleanup: delete failed")
+		return 0, err
+	}
+	if n > 0 {
+		log.Trace().Ctx(ctx).Int64("deleted", n).Msg("magic-link cleanup: removed expired tokens")
+	}
+	return n, nil
+}

pkg/user/magic_link_cleanup_test.go

@@ -0,0 +1,64 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type fakeMLRepo struct {
+	deleteN    int64
+	deleteErr  error
+	cutoffSeen time.Time
+}
+
+func (r *fakeMLRepo) CreateMagicLinkToken(_ context.Context, _ *MagicLinkToken) error { return nil }
+func (r *fakeMLRepo) GetMagicLinkTokenByHash(_ context.Context, _ string) (*MagicLinkToken, error) {
+	return nil, nil
+}
+func (r *fakeMLRepo) MarkMagicLinkTokenConsumed(_ context.Context, _ uint, _ time.Time) error {
+	return nil
+}
+func (r *fakeMLRepo) DeleteExpiredMagicLinkTokens(_ context.Context, before time.Time) (int64, error) {
+	r.cutoffSeen = before
+	return r.deleteN, r.deleteErr
+}
+
+func TestRunOnce_ReturnsCount(t *testing.T) {
+	repo := &fakeMLRepo{deleteN: 7}
+	r := NewMagicLinkCleanupRunner(repo)
+	n, err := r.runOnce(context.Background())
+	require.NoError(t, err)
+	assert.EqualValues(t, 7, n)
+	assert.WithinDuration(t, time.Now(), repo.cutoffSeen, time.Second)
+}
+
+func TestRunOnce_PropagatesError(t *testing.T) {
+	repo := &fakeMLRepo{deleteErr: errors.New("simulated")}
+	r := NewMagicLinkCleanupRunner(repo)
+	_, err := r.runOnce(context.Background())
+	require.Error(t, err)
+}
+
+func TestStartCleanupLoop_StopsOnContextCancel(t *testing.T) {
+	repo := &fakeMLRepo{}
+	r := NewMagicLinkCleanupRunner(repo)
+	ctx, cancel := context.WithCancel(context.Background())
+	r.StartCleanupLoop(ctx, 10*time.Millisecond)
+	time.Sleep(25 * time.Millisecond) // 2 ticks
+	cancel()
+	time.Sleep(15 * time.Millisecond) // give the goroutine time to exit
+	// Implicit assertion: no goroutine leak (test would hang in -race mode otherwise).
+}
+
+func TestStartCleanupLoop_NoOpWhenIntervalZero(t *testing.T) {
+	repo := &fakeMLRepo{}
+	r := NewMagicLinkCleanupRunner(repo)
+	r.StartCleanupLoop(context.Background(), 0)
+	// Just make sure no goroutine is started ; nothing observable to assert
+	// beyond "no panic, returns immediately".
+}

pkg/user/magic_link_integration_test.go

@@ -0,0 +1,194 @@
+//go:build integration
+
+// Integration tests for the magic-link repository methods. Run with:
+//
+//	go test -tags integration ./pkg/user/...
+//
+// Requires a running Postgres reachable via the same env vars / defaults
+// the BDD suite already uses (DLC_DATABASE_HOST, etc., default
+// localhost:5432 from docker-compose).
+package user
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"testing"
+	"time"
+
+	"dance-lessons-coach/pkg/config"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// freshRepo connects to the local Postgres, creates a uniquely-named
+// schema for THIS test, and returns a repository scoped to it.
+// On test end, the schema is dropped (cleanup is best-effort).
+func freshRepo(t *testing.T) *PostgresRepository {
+	t.Helper()
+	cfg, err := config.LoadConfig()
+	require.NoError(t, err)
+
+	var raw [6]byte
+	_, err = rand.Read(raw[:])
+	require.NoError(t, err)
+	schema := "ml_test_" + hex.EncodeToString(raw[:])
+
+	// Bootstrap schema via a default-DSN repo (no search_path).
+	bootDSN := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
+		cfg.GetDatabaseHost(),
+		cfg.GetDatabasePort(),
+		cfg.GetDatabaseUser(),
+		cfg.GetDatabasePassword(),
+		cfg.GetDatabaseName(),
+		cfg.GetDatabaseSSLMode(),
+	)
+	bootRepo, err := NewPostgresRepositoryFromDSN(cfg, bootDSN)
+	require.NoError(t, err)
+	require.NoError(t, bootRepo.Exec(fmt.Sprintf(`CREATE SCHEMA "%s"`, schema)))
+
+	t.Cleanup(func() {
+		_ = bootRepo.Exec(fmt.Sprintf(`DROP SCHEMA "%s" CASCADE`, schema))
+	})
+
+	dsn := BuildSchemaIsolatedDSN(cfg, schema)
+	repo, err := NewPostgresRepositoryFromDSN(cfg, dsn)
+	require.NoError(t, err)
+	return repo
+}
+
+// TestMagicLinkRepo_CreateAndGetByHash is the end-to-end happy path :
+// store a token, look it up by hash, get the row back.
+func TestMagicLinkRepo_CreateAndGetByHash(t *testing.T) {
+	repo := freshRepo(t)
+	ctx := context.Background()
+
+	plain, hashHex, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+
+	tok := &MagicLinkToken{
+		Email:     "alice@example.com",
+		TokenHash: hashHex,
+		ExpiresAt: time.Now().Add(15 * time.Minute),
+	}
+	require.NoError(t, repo.CreateMagicLinkToken(ctx, tok))
+	assert.NotZero(t, tok.ID, "ID should be populated by GORM after Create")
+
+	got, err := repo.GetMagicLinkTokenByHash(ctx, hashHex)
+	require.NoError(t, err)
+	require.NotNil(t, got, "fresh token must be retrievable")
+	assert.Equal(t, "alice@example.com", got.Email)
+	assert.Nil(t, got.ConsumedAt, "fresh token is not yet consumed")
+
+	// Lookup by the plaintext (which the consume handler does NOT receive
+	// directly — it must hash first). This confirms the hashing direction
+	// is consistent.
+	got2, err := repo.GetMagicLinkTokenByHash(ctx, HashMagicLinkToken(plain))
+	require.NoError(t, err)
+	require.NotNil(t, got2)
+	assert.Equal(t, tok.ID, got2.ID)
+}
+
+// TestMagicLinkRepo_GetByHash_Missing returns (nil, nil) for a hash that
+// never existed. Callers must NOT distinguish "missing" from "expired"
+// or "consumed" — they all collapse to a single generic error to the user.
+func TestMagicLinkRepo_GetByHash_Missing(t *testing.T) {
+	repo := freshRepo(t)
+	got, err := repo.GetMagicLinkTokenByHash(context.Background(), HashMagicLinkToken("never-issued"))
+	require.NoError(t, err)
+	assert.Nil(t, got)
+}
+
+// TestMagicLinkRepo_MarkConsumed flips consumed_at and refuses to act
+// on a non-existent ID.
+func TestMagicLinkRepo_MarkConsumed(t *testing.T) {
+	repo := freshRepo(t)
+	ctx := context.Background()
+
+	_, hashHex, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+	tok := &MagicLinkToken{
+		Email:     "bob@example.com",
+		TokenHash: hashHex,
+		ExpiresAt: time.Now().Add(15 * time.Minute),
+	}
+	require.NoError(t, repo.CreateMagicLinkToken(ctx, tok))
+
+	now := time.Now().UTC().Truncate(time.Second)
+	require.NoError(t, repo.MarkMagicLinkTokenConsumed(ctx, tok.ID, now))
+
+	got, err := repo.GetMagicLinkTokenByHash(ctx, hashHex)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+	require.NotNil(t, got.ConsumedAt, "consumed_at must be set")
+	assert.WithinDuration(t, now, got.ConsumedAt.UTC(), time.Second)
+
+	// Marking a non-existent ID returns an error (defensive — the consume
+	// handler should never call us with a fake ID, but if it does we want
+	// the failure to be loud).
+	err = repo.MarkMagicLinkTokenConsumed(ctx, 999999, time.Now())
+	require.Error(t, err)
+}
+
+// TestMagicLinkRepo_DeleteExpired confirms the cleanup pass deletes
+// strictly-before-cutoff rows and leaves future ones alone.
+func TestMagicLinkRepo_DeleteExpired(t *testing.T) {
+	repo := freshRepo(t)
+	ctx := context.Background()
+
+	now := time.Now()
+	expired := &MagicLinkToken{
+		Email:     "expired@example.com",
+		TokenHash: HashMagicLinkToken("expired-token"),
+		ExpiresAt: now.Add(-1 * time.Hour),
+	}
+	fresh := &MagicLinkToken{
+		Email:     "fresh@example.com",
+		TokenHash: HashMagicLinkToken("fresh-token"),
+		ExpiresAt: now.Add(1 * time.Hour),
+	}
+	require.NoError(t, repo.CreateMagicLinkToken(ctx, expired))
+	require.NoError(t, repo.CreateMagicLinkToken(ctx, fresh))
+
+	deleted, err := repo.DeleteExpiredMagicLinkTokens(ctx, now)
+	require.NoError(t, err)
+	assert.EqualValues(t, 1, deleted, "exactly one row was past the cutoff")
+
+	// Expired row is gone, fresh row is still there.
+	got, err := repo.GetMagicLinkTokenByHash(ctx, HashMagicLinkToken("expired-token"))
+	require.NoError(t, err)
+	assert.Nil(t, got, "expired token must be gone")
+
+	got, err = repo.GetMagicLinkTokenByHash(ctx, HashMagicLinkToken("fresh-token"))
+	require.NoError(t, err)
+	require.NotNil(t, got, "fresh token must remain")
+}
+
+// TestMagicLinkRepo_HashUniqueness is a defensive check that the unique
+// index on token_hash actually rejects duplicates. If the index is ever
+// dropped from the schema, this test catches it before security does.
+func TestMagicLinkRepo_HashUniqueness(t *testing.T) {
+	repo := freshRepo(t)
+	ctx := context.Background()
+
+	_, hashHex, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+
+	first := &MagicLinkToken{
+		Email:     "a@example.com",
+		TokenHash: hashHex,
+		ExpiresAt: time.Now().Add(15 * time.Minute),
+	}
+	require.NoError(t, repo.CreateMagicLinkToken(ctx, first))
+
+	dup := &MagicLinkToken{
+		Email:     "b@example.com",
+		TokenHash: hashHex, // same hash as `first`
+		ExpiresAt: time.Now().Add(15 * time.Minute),
+	}
+	err = repo.CreateMagicLinkToken(ctx, dup)
+	require.Error(t, err, "second insert with same hash must violate the unique index")
+}

pkg/user/magic_link_test.go

@@ -0,0 +1,78 @@
+package user
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestGenerateMagicLinkToken_ShapeAndHashAgree confirms the contract that
+// HashMagicLinkToken(plaintext) == returned hashHex. Without that, the
+// consume handler can never look up what request stored.
+func TestGenerateMagicLinkToken_ShapeAndHashAgree(t *testing.T) {
+	plain, hashHex, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+
+	assert.NotEmpty(t, plain)
+	assert.NotEmpty(t, hashHex)
+	assert.Len(t, hashHex, 64, "sha256 hex = 64 chars")
+	assert.Equal(t, hashHex, HashMagicLinkToken(plain),
+		"GenerateMagicLinkToken must return a hash that matches HashMagicLinkToken(plain)")
+}
+
+// TestGenerateMagicLinkToken_PlainIsURLSafeBase64 confirms the link can
+// be embedded in a URL without further escaping. RawURLEncoding => no
+// "/", "+", or "=" padding chars.
+func TestGenerateMagicLinkToken_PlainIsURLSafeBase64(t *testing.T) {
+	plain, _, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+
+	for _, bad := range []string{"/", "+", "="} {
+		assert.False(t, strings.Contains(plain, bad),
+			"plaintext token must not contain %q (URL-unsafe)", bad)
+	}
+
+	decoded, err := base64.RawURLEncoding.DecodeString(plain)
+	require.NoError(t, err, "plaintext must round-trip through RawURLEncoding")
+	assert.Len(t, decoded, 32, "32 bytes of entropy")
+}
+
+// TestGenerateMagicLinkToken_Unique confirms two consecutive calls
+// produce different tokens (not a deterministic seeding bug).
+func TestGenerateMagicLinkToken_Unique(t *testing.T) {
+	a, ah, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+	b, bh, err := GenerateMagicLinkToken()
+	require.NoError(t, err)
+
+	assert.NotEqual(t, a, b, "plaintexts must differ between calls")
+	assert.NotEqual(t, ah, bh, "hashes must differ between calls")
+}
+
+// TestHashMagicLinkToken_StableAndCorrect confirms HashMagicLinkToken is
+// a pure function (same input -> same output) AND that it produces the
+// expected sha256 hex digest. Cross-checked against the stdlib so we
+// catch any accidental algorithm swap.
+func TestHashMagicLinkToken_StableAndCorrect(t *testing.T) {
+	const sample = "abc123-test-token"
+	got1 := HashMagicLinkToken(sample)
+	got2 := HashMagicLinkToken(sample)
+	assert.Equal(t, got1, got2, "HashMagicLinkToken must be deterministic")
+
+	sum := sha256.Sum256([]byte(sample))
+	want := hex.EncodeToString(sum[:])
+	assert.Equal(t, want, got1, "HashMagicLinkToken must be sha256 hex")
+}
+
+// TestHashMagicLinkToken_DiffersOnDifferentInput is the tautological
+// counter-test of stability : different inputs -> different outputs.
+// Catches the (unlikely) case where someone replaces the impl with
+// a constant.
+func TestHashMagicLinkToken_DiffersOnDifferentInput(t *testing.T) {
+	assert.NotEqual(t, HashMagicLinkToken("a"), HashMagicLinkToken("b"))
+}

pkg/user/postgres_repository.go

@@ -160,7 +160,7 @@ func NewPostgresRepositoryFromDSN(cfg *config.Config, dsn string) (*PostgresRepo
 	sqlDB.SetMaxIdleConns(cfg.GetDatabaseMaxIdleConns())
 	sqlDB.SetConnMaxLifetime(cfg.GetDatabaseConnMaxLifetime())
 
-	if err := db.AutoMigrate(&User{}); err != nil {
+	if err := db.AutoMigrate(&User{}, &MagicLinkToken{}); err != nil {
 		return nil, fmt.Errorf("failed to auto-migrate via custom DSN: %w", err)
 	}
 
@@ -264,8 +264,8 @@ func (r *PostgresRepository) initializeDatabase() error {
 	sqlDB.SetMaxIdleConns(r.config.GetDatabaseMaxIdleConns())
 	sqlDB.SetConnMaxLifetime(r.config.GetDatabaseConnMaxLifetime())
 
-	// Auto-migrate the User model
-	if err := r.db.AutoMigrate(&User{}); err != nil {
+	// Auto-migrate the User model + MagicLinkToken (ADR-0028 Phase A)
+	if err := r.db.AutoMigrate(&User{}, &MagicLinkToken{}); err != nil {
 		return fmt.Errorf("failed to auto-migrate: %w", err)
 	}