From c05e508d56345ae3d8c2bd0f29068ecf099b22f1 Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Tue, 5 May 2026 19:22:38 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20mkcert=20local=20HTTPS?= =?UTF-8?q?=20setup=20+=20Makefile=20cert=20target=20(ADR-0028=20Phase=20B?= =?UTF-8?q?=20prep)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 24 ++++++++ documentation/MKCERT.md | 120 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 Makefile create mode 100644 documentation/MKCERT.md diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..821b496 --- /dev/null +++ b/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) diff --git a/documentation/MKCERT.md b/documentation/MKCERT.md new file mode 100644 index 0000000..286240a --- /dev/null +++ b/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