feat(api): M4.2 — full REST surface + pgx-backed Postgres store

Replaces the M5.1-skeleton handler set with the M4.2 spec from
IMPLEMENTATION_PLAN.md:

Endpoints (authoritative shape in openapi.yaml):
  POST   /v1/tenants
  GET    /v1/tenants/{id}
  GET    /v1/tenants/by-slug/{slug}
  POST   /v1/tenants/{id}/activate
  POST   /v1/tenants/{id}/cancel
  GET    /v1/entitlements?tenant_id=...
  GET    /v1/catalog
  POST   /v1/catalog/request
  POST   /v1/catalog/trial-request
  POST   /v1/api-keys                       returns plaintext ONCE
  GET    /v1/api-keys?tenant_id=...
  DELETE /v1/api-keys/{id}
  POST   /v1/internal/api-keys/verify       always 200; valid: bool
  POST   /v1/audit
  GET    /v1/audit?{tenant_id,product,actor_id,action,since,until,limit,cursor}

Architecture:
  internal/store/store.go        Store interface (CRUD + audit + ping)
  internal/store/memory.go       in-process impl, used when DATABASE_URL
                                 is empty (seed acme tenant, no migrations)
  internal/store/postgres.go     pgxpool impl against the M4.1 schema
  internal/server/server.go      router + healthz/readyz
  internal/server/{tenants,catalog,apikeys,audit}.go
                                 per-concern handlers (≤250 LoC each)
  internal/server/helpers.go     writeJSON/writeError/error mapping/log mw
  openapi.yaml                   3.1 spec; openapi_test.go is the contract gate

API keys:
  Plaintext format 'bp_<22-char base64>'. Prefix bp_<8> stored for UI.
  Hash is argon2id(salt, time=1, mem=64MB, threads=4, len=32) encoded as
  'argon2id|<salt-b64>|<hash-b64>'. Format-tagged so we can rotate
  parameters without re-keying. Verify is constant-time.

Store selection:
  cmd/server picks Postgres when DATABASE_URL is set, otherwise Memory.
  Both implementations are exercised by the same eachStore test harness —
  parity is enforced.

Audit:
  Every state-changing endpoint emits via s.emitAudit() (fire-and-forget).
  audit_log uses ON DELETE SET NULL on tenant_id so forensic history
  outlives tenant deletes (per M4.1 schema).

Routing constraint:
  Go 1.22 ServeMux can't disambiguate /v1/tenants/{id}/products from
  /v1/tenants/by-slug/{slug=products}. Per-tenant subresources moved to
  query-param top-level paths: /v1/entitlements?tenant_id=… and
  /v1/api-keys?tenant_id=….

Tests:
  Every endpoint exercised against both Memory and Postgres via the
  eachStore harness. Includes happy paths, validation errors, conflicts,
  404s, auto-audit-emit assertion. testcontainers-go for the postgres
  harness; gated by -short.

  TestOpenAPISpec is the contract gate: every documented operation must
  resolve against the router. (kin-openapi v0.138.0.)

Refs: M4.2

internal/server/server.go

@@ -1,106 +1,71 @@
+// Package server wires the HTTP surface for tenant-registry.
+//
+// All routes are registered in NewRouter; per-concern handlers live in
+// peer files (tenants.go, catalog.go, apikeys.go, audit.go).
 package server
 
 import (
-	"context"
-	"encoding/json"
-	"errors"
 	"log/slog"
 	"net/http"
-	"time"
 
 	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
 
-type deps struct {
-	cfg    *config.Config
-	log    *slog.Logger
-	tenant *store.Memory
+// Server bundles the dependencies every handler needs.
+type Server struct {
+	Cfg   *config.Config
+	Log   *slog.Logger
+	Store store.Store
 }
 
-func NewRouter(cfg *config.Config, log *slog.Logger) http.Handler {
-	d := &deps{cfg: cfg, log: log, tenant: store.NewMemory()}
-
+// NewRouter builds the http.Handler with logging middleware applied.
+func NewRouter(s *Server) http.Handler {
 	mux := http.NewServeMux()
-	mux.HandleFunc("GET /healthz", d.healthz)
-	mux.HandleFunc("GET /v1/tenants/by-slug/{slug}", d.tenantBySlug)
-	mux.HandleFunc("GET /v1/tenants/{id}", d.tenantByID)
 
-	return logRequest(log)(mux)
+	// health + status
+	mux.HandleFunc("GET /healthz", s.healthz)
+	mux.HandleFunc("GET /readyz", s.readyz)
+
+	// tenants
+	mux.HandleFunc("POST /v1/tenants", s.createTenant)
+	mux.HandleFunc("GET /v1/tenants/{id}", s.getTenant)
+	mux.HandleFunc("GET /v1/tenants/by-slug/{slug}", s.getTenantBySlug)
+	mux.HandleFunc("POST /v1/tenants/{id}/activate", s.activateTenant)
+	mux.HandleFunc("POST /v1/tenants/{id}/cancel", s.cancelTenant)
+
+	// entitlements — top-level path so it doesn't conflict with
+	// /v1/tenants/by-slug/{slug} (Go 1.22 ServeMux can't disambiguate
+	// /v1/tenants/{id}/products vs /v1/tenants/by-slug/{slug=products}).
+	mux.HandleFunc("GET /v1/entitlements", s.listTenantProducts)
+
+	// catalog
+	mux.HandleFunc("GET /v1/catalog", s.getCatalog)
+	mux.HandleFunc("POST /v1/catalog/request", s.catalogRequest)
+	mux.HandleFunc("POST /v1/catalog/trial-request", s.catalogTrialRequest)
+
+	// api keys — same disambiguation: list lives at /v1/api-keys?tenant_id=X
+	// instead of /v1/tenants/{id}/api-keys.
+	mux.HandleFunc("POST /v1/api-keys", s.createAPIKey)
+	mux.HandleFunc("GET /v1/api-keys", s.listAPIKeys)
+	mux.HandleFunc("DELETE /v1/api-keys/{id}", s.revokeAPIKey)
+	mux.HandleFunc("POST /v1/internal/api-keys/verify", s.verifyAPIKey)
+
+	// audit
+	mux.HandleFunc("POST /v1/audit", s.appendAudit)
+	mux.HandleFunc("GET /v1/audit", s.listAudit)
+
+	return logRequest(s.Log)(mux)
 }
 
-func (d *deps) healthz(w http.ResponseWriter, _ *http.Request) {
+func (s *Server) healthz(w http.ResponseWriter, _ *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 }
 
-func (d *deps) tenantBySlug(w http.ResponseWriter, r *http.Request) {
-	slug := r.PathValue("slug")
-	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
-	defer cancel()
-
-	t, err := d.tenant.BySlug(ctx, slug)
-	if errors.Is(err, store.ErrNotFound) {
-		writeError(w, http.StatusNotFound, "tenant_not_found", "no tenant with that slug")
+func (s *Server) readyz(w http.ResponseWriter, r *http.Request) {
+	if err := s.Store.Ping(r.Context()); err != nil {
+		writeError(w, http.StatusServiceUnavailable, "store_unavailable", err.Error())
 		return
 	}
-	if err != nil {
-		d.log.Error("tenant lookup failed", "err", err)
-		writeError(w, http.StatusInternalServerError, "internal", "lookup failed")
-		return
-	}
-	writeJSON(w, http.StatusOK, t)
-}
-
-func (d *deps) tenantByID(w http.ResponseWriter, r *http.Request) {
-	id := r.PathValue("id")
-	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
-	defer cancel()
-
-	t, err := d.tenant.ByID(ctx, id)
-	if errors.Is(err, store.ErrNotFound) {
-		writeError(w, http.StatusNotFound, "tenant_not_found", "no tenant with that id")
-		return
-	}
-	if err != nil {
-		d.log.Error("tenant lookup failed", "err", err)
-		writeError(w, http.StatusInternalServerError, "internal", "lookup failed")
-		return
-	}
-	writeJSON(w, http.StatusOK, t)
-}
-
-func writeJSON(w http.ResponseWriter, code int, body any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(code)
-	_ = json.NewEncoder(w).Encode(body)
-}
-
-func writeError(w http.ResponseWriter, code int, kind, msg string) {
-	writeJSON(w, code, map[string]string{"error": kind, "message": msg})
-}
-
-func logRequest(log *slog.Logger) func(http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			start := time.Now()
-			ww := &statusRecorder{ResponseWriter: w, code: 200}
-			next.ServeHTTP(ww, r)
-			log.Info("http",
-				"method", r.Method,
-				"path", r.URL.Path,
-				"status", ww.code,
-				"duration_ms", time.Since(start).Milliseconds(),
-			)
-		})
-	}
-}
-
-type statusRecorder struct {
-	http.ResponseWriter
-	code int
-}
-
-func (s *statusRecorder) WriteHeader(c int) {
-	s.code = c
-	s.ResponseWriter.WriteHeader(c)
+	writeJSON(w, http.StatusOK, map[string]string{"status": "ready"})
 }