feat(api): M4.2 — REST surface + pgx Postgres store + OpenAPI 3.1

Full M4.2 deliverable: 16 endpoints (tenants CRUD + lifecycle, catalog, entitlements, API keys with argon2 hashing, audit append + filter), Store interface with pgx-backed Postgres + in-memory parallel implementations exercised by the same eachStore harness, openapi.yaml at 3.1 with kin-openapi contract test. M4.3 adds auth.

Refs: M4.2

internal/server/audit.go

@@ -0,0 +1,107 @@
+package server
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"time"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
+)
+
+type appendAuditReq struct {
+	TenantID   string                 `json:"tenant_id,omitempty"`
+	ProjectID  string                 `json:"project_id,omitempty"`
+	ActorID    string                 `json:"actor_id,omitempty"`
+	ActorName  string                 `json:"actor_name,omitempty"`
+	ActorType  string                 `json:"actor_type,omitempty"`
+	Action     string                 `json:"action"`
+	TargetID   string                 `json:"target_id,omitempty"`
+	TargetType string                 `json:"target_type,omitempty"`
+	TargetName string                 `json:"target_name,omitempty"`
+	Product    string                 `json:"product,omitempty"`
+	Metadata   map[string]interface{} `json:"metadata,omitempty"`
+}
+
+func (s *Server) appendAudit(w http.ResponseWriter, r *http.Request) {
+	var in appendAuditReq
+	if !decodeJSON(w, r, &in) {
+		return
+	}
+	if in.Action == "" {
+		writeError(w, http.StatusBadRequest, "invalid_action", "action is required")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+
+	ev, err := s.Store.AppendAudit(ctx, store.AuditEvent{
+		TenantID: in.TenantID, ProjectID: in.ProjectID,
+		ActorID: in.ActorID, ActorName: in.ActorName, ActorType: in.ActorType,
+		Action:   in.Action,
+		TargetID: in.TargetID, TargetType: in.TargetType, TargetName: in.TargetName,
+		Product: in.Product, Metadata: in.Metadata,
+		SourceIP: clientIP(r), UserAgent: r.UserAgent(),
+	})
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "internal", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusCreated, ev)
+}
+
+func (s *Server) listAudit(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query()
+	f := store.AuditFilter{
+		TenantID: q.Get("tenant_id"),
+		Product:  q.Get("product"),
+		ActorID:  q.Get("actor_id"),
+		Action:   q.Get("action"),
+	}
+	if s := q.Get("since"); s != "" {
+		t, err := time.Parse(time.RFC3339, s)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "invalid_since", "must be RFC3339")
+			return
+		}
+		f.Since = &t
+	}
+	if s := q.Get("until"); s != "" {
+		t, err := time.Parse(time.RFC3339, s)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "invalid_until", "must be RFC3339")
+			return
+		}
+		f.Until = &t
+	}
+	if s := q.Get("limit"); s != "" {
+		n, err := strconv.Atoi(s)
+		if err != nil || n < 1 || n > 500 {
+			writeError(w, http.StatusBadRequest, "invalid_limit", "must be 1..500")
+			return
+		}
+		f.Limit = n
+	}
+	if s := q.Get("cursor"); s != "" {
+		n, err := strconv.ParseInt(s, 10, 64)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "invalid_cursor", "must be an integer")
+			return
+		}
+		f.Cursor = n
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+	items, next, err := s.Store.ListAudit(ctx, f)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "internal", err.Error())
+		return
+	}
+	out := map[string]any{"items": items}
+	if next > 0 {
+		out["next_cursor"] = next
+	}
+	writeJSON(w, http.StatusOK, out)
+}