From 886cbab36d76d81a3057b69e884114c5572fb78b Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Wed, 6 May 2026 07:03:15 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20refresh=20AGENTS.md=20+?= =?UTF-8?q?=20README.md=20(auth=20endpoints=20+=20ADR=20pointer=20+=20new?= =?UTF-8?q?=20packages)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md and README.md were stale since ~2026-04-11 (4 weeks). Updated to reflect magic-link + OIDC auth (ADR-0028), pkg/auth, pkg/email, pkg/user/api packages, and 30-ADR index. Endpoints listing decision : keep curated short list + pointer to swagger as source of truth (see body of changes). Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- AGENTS.md | 43 +++++++++++++++++++++++++++---------------- README.md | 22 +++++++++++++++------- 2 files changed, 42 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b41084..1693be0 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index bb347ff..40e3c16 100644 --- a/README.md +++ b/README.md @@ -17,10 +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 -- 🤖 Mistral autonomous PR pattern (cf. [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](documentation/MISTRAL-AUTONOMOUS-PATTERN.md)) +- 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 @@ -63,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 -- 2.49.1