Logto integration Phases 0-2: setup + JWT foundation + additive schema

.env.example

@@ -1,41 +1,120 @@
 # Court Command Environment Variables
-# Copy to .env for local development.
-# In Coolify, set these in the Docker Compose service's environment variables.
+#
+# Copy this file to .env for local development. The values below are the
+# DEV defaults, matching what `make dev-up` brings up via
+# docker-compose.dev.yml. See docs/LOCAL_DEV.md for the first-run flow.
+#
+# In production, Coolify sets these via its env var UI; the values
+# below are illustrative only. The `# PRODUCTION` block at the bottom
+# of this file documents the prod overrides.
 
-# --- Database ---
+# --- Database (local dev: db service in docker-compose.dev.yml) ---
 POSTGRES_USER=courtcommand
 POSTGRES_PASSWORD=courtcommand
 POSTGRES_DB=courtcommand
-DATABASE_URL=postgres://courtcommand:courtcommand@db:5432/courtcommand?sslmode=disable
+DATABASE_URL=postgres://courtcommand:courtcommand@localhost:5432/courtcommand?sslmode=disable
 
-# --- Redis ---
-REDIS_URL=redis://redis:6379/0
+# --- Redis (local dev: redis service in docker-compose.dev.yml) ---
+REDIS_URL=redis://localhost:6379/0
 
 # --- Backend ---
 PORT=8080
 APP_ENV=development
 CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
 
-# --- Frontend (baked into build) ---
+# --- Frontend (Vite dev server) ---
 VITE_API_URL=http://localhost:8080
 VITE_GOOGLE_MAPS_API_KEY=
 
-# --- Ghost CMS ---
+# --- Ghost CMS (not used in local dev unless explicitly started) ---
 GHOST_URL=http://localhost:2368
 
-# --- Port Overrides (optional, for local conflicts) ---
-# DB_PORT=5432
-# REDIS_PORT=6379
-# BACKEND_PORT=8080
-# FRONTEND_PORT=3000
-# GHOST_PORT=2368
+# =============================================================================
+# Logto (local dev: logto service in docker-compose.dev.yml on ports 3001/3002)
+# =============================================================================
+#
+# First-run flow:
+#   1. `make dev-up`             # starts postgres + redis + logto containers
+#   2. Open http://localhost:3002 in a browser, create the initial admin
+#      account (Logto's first-time setup wizard), then create:
+#        - Application -> Machine-to-machine -> name "Court Command Backend"
+#        - Open it -> Roles -> assign "Logto Management API access"
+#        - Open it -> Settings -> copy App ID and App Secret into the
+#          two env vars below.
+#   3. `make logto-seed`         # provisions everything else automatically
+#   4. Capture the seeder's output (it prints the values to paste back here)
+#   5. `make dev`                # starts the Go backend natively
+#
+# Subsequent runs: just `make dev-up` + `make dev`.
+
+# Core OIDC endpoint (issuer, JWKS, /oidc/token).
+LOGTO_ENDPOINT=http://localhost:3001
+# Admin UI (humans only, not used by the backend).
+LOGTO_ADMIN_ENDPOINT=http://localhost:3002
+
+# API resource indicator registered in Logto -> API resources.
+# Local dev points back at the Go backend's localhost address.
+LOGTO_API_RESOURCE=http://localhost:8080/api
+
+# Machine-to-machine app credentials. Operator creates this in the
+# Logto admin UI BEFORE the first run of `make logto-seed`.
+LOGTO_MANAGEMENT_API_APP_ID=
+LOGTO_MANAGEMENT_API_APP_SECRET=
+
+# Resource indicator for the built-in Logto Management API. This is a
+# Logto-internal fixed value, NOT a real URL. Same in dev and prod.
+LOGTO_MANAGEMENT_API_RESOURCE=https://default.logto.app/api
+
+# HMAC-SHA256 signing key from the webhook the seeder creates.
+# Populated by the seeder's output; paste the printed value here.
+LOGTO_WEBHOOK_SIGNING_KEY=
+
+# Sport organization IDs (created by the seeder). Populated by the
+# seeder's output; paste the printed values here.
+LOGTO_PICKLEBALL_ORG_ID=
+LOGTO_DEMO_SPORT_ORG_ID=
+
+# Where the seeder will register the webhook URL. Logto runs in a
+# Docker container, so it must reach the host-bound backend through
+# host.docker.internal (Docker's host-gateway alias).
+LOGTO_WEBHOOK_URL=http://host.docker.internal:8080/api/v1/webhooks/logto
+
+# Where the SPA app's redirect URI points (the Vite dev server).
+LOGTO_SPA_REDIRECT_URI=http://localhost:5173/auth/callback
+
+# Bootstrap admin (created by the seeder).
+# DO NOT USE THESE VALUES IN PRODUCTION.
+LOGTO_BOOTSTRAP_EMAIL=admin@courtcommand.local
+LOGTO_BOOTSTRAP_PASSWORD=TestPass123!
+LOGTO_BOOTSTRAP_NAME="Local Admin"
+
+# Optional: Logto user ID of the bootstrap admin. Used ONLY by the live
+# smoke test in api/logto/livesmoke_test.go when LOGTO_LIVE_SMOKE=1.
+# Populated by the seeder's output (look for "user_id:" in the summary).
+# LOGTO_BOOTSTRAP_USER_ID=
+
+# --- Frontend Logto config (baked into Vite build) ---
+VITE_LOGTO_ENDPOINT=http://localhost:3001
+# SPA App ID from the seeder's output.
+VITE_LOGTO_APP_ID=
+VITE_LOGTO_API_RESOURCE=http://localhost:8080/api
 
 # =============================================================================
-# PRODUCTION (Coolify) — Override these values in Coolify's env var UI:
+# PRODUCTION (Coolify) overrides -- set these in Coolify's env var UI:
 # =============================================================================
 # POSTGRES_PASSWORD=<strong-random-password>
 # DATABASE_URL=postgres://courtcommand:<password>@db:5432/courtcommand?sslmode=disable
+# REDIS_URL=redis://redis:6379/0
 # APP_ENV=production
 # CORS_ALLOWED_ORIGINS=https://courtcommand.app,https://news.courtcommand.app
 # VITE_API_URL=https://api.courtcommand.app
 # GHOST_URL=https://news.courtcommand.app
+# LOGTO_ENDPOINT=https://logto.courtcommand.app
+# LOGTO_ADMIN_ENDPOINT=https://logto-admin.courtcommand.app
+# LOGTO_API_RESOURCE=https://api.courtcommand.app/api
+# LOGTO_WEBHOOK_URL=https://api.courtcommand.app/api/v1/webhooks/logto
+# LOGTO_SPA_REDIRECT_URI=https://courtcommand.app/auth/callback
+# VITE_LOGTO_ENDPOINT=https://logto.courtcommand.app
+# VITE_LOGTO_API_RESOURCE=https://api.courtcommand.app/api
+# (Plus the LOGTO_MANAGEMENT_API_APP_ID/SECRET, sport org IDs, and
+#  webhook signing key captured during the production seed.)

.gitignore

@@ -1,5 +1,8 @@
 # .gitignore
 .env
+.env.prod
+.env.production
+.env.local
 *.exe
 *.dll
 *.so
@@ -21,3 +24,18 @@ web/src/routeTree.gen.ts
 *.tsbuildinfo
 backups/
 ghost-theme/cc-ghost-theme.zip
+
+# Playwright (Phase 3 Task 10)
+web/test-results/
+web/playwright-report/
+web/blob-report/
+
+# Local-only build outputs of the seeder (the binary is built into the
+# api Docker image; never check in the local one)
+api/logto-seed
+api/court-command
+
+# Editor backups
+*.save
+*~
+*.swp

Makefile

@@ -1,5 +1,76 @@
 # Makefile
-.PHONY: dev dev-frontend dev-all up down full full-down build migrate-up migrate-down migrate-create sqlc test test-db seed backup backup-full restore restore-db backup-list backup-before-deploy
+.PHONY: dev dev-frontend dev-all dev-up dev-down dev-logs dev-reset up down full full-down build migrate-up migrate-down migrate-create sqlc test test-db seed logto-seed backup backup-full restore restore-db backup-list backup-before-deploy
+
+# ---- Local development (docker-compose.dev.yml) ----
+# Brings up postgres + redis + logto with host port bindings; the Go
+# backend runs natively on the host for fast iteration. See
+# docs/LOCAL_DEV.md for the full first-run walkthrough.
+
+# Start the dev infra (db + redis + logto)
+dev-up:
+	docker compose -f docker-compose.dev.yml up -d
+	@echo ""
+	@echo "Dev infra ready:"
+	@echo "  Postgres   localhost:5432  (user=courtcommand pass=courtcommand db=courtcommand,logto)"
+	@echo "  Redis      localhost:6379"
+	@echo "  Logto OIDC http://localhost:3001"
+	@echo "  Logto admin http://localhost:3002"
+	@echo ""
+	@echo "Next: see docs/LOCAL_DEV.md for first-run setup."
+
+# Stop dev infra (preserves volumes / data)
+dev-down:
+	docker compose -f docker-compose.dev.yml down
+
+# Tail logs from the dev infra services
+dev-logs:
+	docker compose -f docker-compose.dev.yml logs -f
+
+# Wipe dev infra including all data (Postgres volume + Logto state)
+dev-reset:
+	docker compose -f docker-compose.dev.yml down -v
+	@echo "Dev infra wiped. Run 'make dev-up' to start fresh."
+
+# Provision Logto (idempotent): creates apps, resources, scopes, org
+# template, organizations, bootstrap admin, webhook. Reads config from
+# .env (LOGTO_MANAGEMENT_API_APP_ID/SECRET must be set first -- see
+# docs/LOCAL_DEV.md "First-run setup").
+logto-seed:
+	@if [ ! -f .env ]; then echo "ERROR: .env not found. Copy from .env.example first."; exit 1; fi
+	@cd api && set -a && . ../.env && set +a && go run ./cmd/logto-seed
+
+# Provision a production Logto tenant + sync sports.logto_org_id
+# in the production app DB. Run ONCE at launch (re-running is safe;
+# every step is idempotent). Env source order:
+#   1. .env.prod (preferred -- gitignored, holds prod values)
+#   2. .env (fallback for operators with a single env file)
+#
+# Required vars in the env file:
+#   LOGTO_ENDPOINT                       https://logto.courtcommand.app
+#   LOGTO_API_RESOURCE                   https://api.courtcommand.app/api
+#   LOGTO_MANAGEMENT_API_APP_ID          (from Logto admin -> Apps -> M2M)
+#   LOGTO_MANAGEMENT_API_APP_SECRET      (same place)
+#   LOGTO_MANAGEMENT_API_RESOURCE        https://default.logto.app/api  (Logto-internal, fixed)
+#   LOGTO_SPA_REDIRECT_URI               https://courtcommand.app/auth/callback
+#   LOGTO_WEBHOOK_URL                    https://api.courtcommand.app/api/v1/webhooks/logto
+#   LOGTO_BOOTSTRAP_EMAIL/PASSWORD/NAME  for the first admin
+#   DATABASE_URL                         points at the prod app DB (for sports.logto_org_id sync)
+#   APP_ENV                              must be "production" to skip Demo Sport
+#
+# Output: prints LOGTO_PICKLEBALL_ORG_ID, LOGTO_WEBHOOK_SIGNING_KEY,
+# VITE_LOGTO_APP_ID etc. Paste into Coolify env, restart api+web.
+prod-bootstrap:
+	@ENV_FILE=.env.prod; if [ ! -f $$ENV_FILE ]; then ENV_FILE=.env; fi; \
+	if [ ! -f $$ENV_FILE ]; then echo "ERROR: neither .env.prod nor .env found"; exit 1; fi; \
+	echo "Sourcing $$ENV_FILE"; \
+	cd api && set -a && . ../$$ENV_FILE && set +a && \
+	if [ "$$APP_ENV" != "production" ]; then \
+	  echo "ERROR: APP_ENV is not 'production' -- refusing to run prod-bootstrap with dev settings"; \
+	  exit 1; \
+	fi; \
+	go run ./cmd/logto-seed
+
+# ---- Legacy single-stack (docker-compose.yaml -- prod / Coolify shape) ----
 
 # Start Docker services (db + redis only)
 up:
@@ -60,11 +131,24 @@ test-db: up
 test: test-db
 	cd api && go test ./... -v -count=1
 
-# Seed development data (all entity types — run after migrations)
-seed: up
-	@echo "Seeding development data..."
-	docker compose exec -T db psql -U courtcommand -d courtcommand < api/db/seed.sql
-	@echo "Done! Login with admin@courtcommand.com / TestPass123!"
+# Seed development domain data (orgs, tournaments, leagues, venues,
+# matches, etc.) against the dev stack (docker-compose.dev.yml).
+# Preserves the Logto-bootstrap admin row (logto_user_id IS NOT NULL);
+# only wipes domain tables and shadow users.
+#
+# Prereqs:
+#   1. make dev-up         # postgres + redis + logto running
+#   2. make migrate-up     # schema is current
+#   3. make logto-seed     # Logto provisioned; bootstrap admin row exists
+#   4. (sign in once via the SPA so the admin is mirrored to local users)
+#
+# After seeding, the bootstrap admin remains the only signin-capable
+# user; all other users are shadow players (status='unclaimed') / staff
+# fixtures with logto_user_id=NULL.
+seed:
+	@echo "Seeding development domain data..."
+	docker compose -f docker-compose.dev.yml exec -T db psql -U courtcommand -d courtcommand < api/db/seed.sql
+	@echo "Done. Sign in via the SPA with the Logto bootstrap admin to see the seeded fixtures."
 
 # ---- Backup & Restore ----
 
@@ -75,12 +159,20 @@ backup:
 	docker compose exec -T db pg_dump -U courtcommand courtcommand > backups/db-$$TIMESTAMP.sql && \
 	echo "Database backup: backups/db-$$TIMESTAMP.sql ($$(wc -c < backups/db-$$TIMESTAMP.sql | tr -d ' ') bytes)"
 
-# Full backup: database + uploaded files (for before deploys or major changes)
+# Full backup: app database + Logto identity database + uploaded files
+# (for before deploys or major changes). Run as 'make backup-full' on
+# the production host where the compose stack is running.
 backup-full:
 	@mkdir -p backups
 	@TIMESTAMP=$$(date +%Y%m%d-%H%M%S); \
 	docker compose exec -T db pg_dump -U courtcommand courtcommand > backups/db-$$TIMESTAMP.sql && \
-	echo "Database backup: backups/db-$$TIMESTAMP.sql"; \
+	echo "App db backup: backups/db-$$TIMESTAMP.sql"; \
+	if docker compose ps -q db_logto >/dev/null 2>&1 && [ -n "$$(docker compose ps -q db_logto)" ]; then \
+		docker compose exec -T db_logto pg_dump -U $${LOGTO_DB_USER:-logto} $${LOGTO_DB_NAME:-logto} > backups/db_logto-$$TIMESTAMP.sql && \
+		echo "Logto db backup: backups/db_logto-$$TIMESTAMP.sql"; \
+	else \
+		echo "(db_logto service not running; skipped identity backup)"; \
+	fi; \
 	if [ -d api/uploads ] && [ "$$(ls -A api/uploads 2>/dev/null)" ]; then \
 		tar czf backups/uploads-$$TIMESTAMP.tar.gz -C api uploads && \
 		echo "Uploads backup: backups/uploads-$$TIMESTAMP.tar.gz"; \
@@ -125,12 +217,24 @@ restore-uploads:
 
 # List all available backups
 backup-list:
-	@echo "=== Database Backups ==="
+	@echo "=== App database backups ==="
 	@ls -lh backups/db-*.sql 2>/dev/null || echo "  None"
 	@echo ""
-	@echo "=== Upload Backups ==="
+	@echo "=== Logto identity database backups ==="
+	@ls -lh backups/db_logto-*.sql 2>/dev/null || echo "  None"
+	@echo ""
+	@echo "=== Upload backups ==="
 	@ls -lh backups/uploads-*.tar.gz 2>/dev/null || echo "  None"
 
+# Package the Court Command Ghost theme into a zip ready for upload
+# at https://news.courtcommand.app/ghost (Admin -> Design -> Change theme).
+# Output: ghost-theme/cc-ghost-theme.zip (gitignored).
+ghost-theme:
+	@cd ghost-theme && rm -f cc-ghost-theme.zip && \
+		zip -r cc-ghost-theme.zip . -x '*.zip' -x '.*' && \
+		echo "Created ghost-theme/cc-ghost-theme.zip ($$(du -h cc-ghost-theme.zip | cut -f1))"
+	@echo "Upload via Ghost admin: Settings -> Design -> Change theme -> Upload."
+
 # Include .env if it exists
 -include .env
 export

api/Dockerfile

@@ -1,5 +1,5 @@
 # api/Dockerfile
-# Multi-stage build for the Court Command API
+# Multi-stage build for the Court Command API.
 
 # --- Stage 1: Build ---
 FROM golang:1.24-alpine AS builder
@@ -15,11 +15,30 @@ WORKDIR /app
 COPY go.mod go.sum ./
 RUN go mod download
 
-# Copy source code
+# Copy source code (build context is ./api)
 COPY . .
 
-# Build the binary
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /court-command .
+# Build the binary, injecting the build timestamp into the binary so
+# /api/v1/health can report when the deployed image was built. The
+# commit SHA falls back to "unknown" because Coolify (this version)
+# does not expose SOURCE_COMMIT or COOLIFY_GIT_COMMIT_SHA at docker
+# build time. The built_at timestamp alone is sufficient to verify a
+# fresh deploy landed; pairing it with the local 'git log' tells you
+# the exact commit by time.
+#
+# If a future Coolify version surfaces the SHA at build time, set
+# COMMIT in docker-compose.yaml's build.args and the SHA will appear
+# in the health response automatically.
+ARG COMMIT
+RUN RESOLVED_COMMIT="${COMMIT:-unknown}" \
+ && BUILT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+ && echo "Building court-command commit=${RESOLVED_COMMIT} built_at=${BUILT_AT}" \
+ && CGO_ENABLED=0 GOOS=linux go build \
+      -ldflags="-s -w \
+        -X github.com/court-command/court-command/handler.buildCommit=${RESOLVED_COMMIT} \
+        -X github.com/court-command/court-command/handler.buildBuiltAt=${BUILT_AT}" \
+      -o /court-command . \
+ && CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /logto-seed ./cmd/logto-seed
 
 # --- Stage 2: Run ---
 FROM alpine:3.20
@@ -31,12 +50,16 @@ RUN addgroup -S appgroup && adduser -S appuser -G appgroup
 
 WORKDIR /app
 
-# Copy binary from builder
+# Copy binaries from builder. court-command is the API server; logto-seed
+# is the one-shot Logto provisioning tool used by docker-compose.bootstrap.yaml
+# to set up the Logto tenant + sync sports.logto_org_id on first deploy.
 COPY --from=builder /court-command .
+COPY --from=builder /logto-seed .
 
 # Copy migrations (embedded in binary via go:embed, but also available for manual goose runs)
 COPY --from=builder /app/db/migrations ./db/migrations
 
+
 # Create uploads directory
 RUN mkdir -p uploads && chown appuser:appgroup uploads