crl/cache: schema + repository for crl_cache + crl_generation_events

Phase 1 of the CRL/OCSP responder bundle. Adds:

  * migration 000019 — crl_cache (one row per issuer; pre-generated CRL DER,
    monotonic crl_number per RFC 5280 §5.2.3, this_update/next_update,
    generation duration metric, revoked_count) + crl_generation_events
    (append-only audit log of every regeneration attempt, succeeded
    + error fields for ops grep)
  * internal/domain/crl_cache.go — CRLCacheEntry + IsStale helper +
    CRLGenerationEvent (raw DER omitted from JSON to avoid bloating
    admin responses; CRLDERBase64 field for explicit transit shaping)
  * internal/repository/interfaces.go — CRLCacheRepository interface
    (Get / Put / NextCRLNumber / RecordGenerationEvent /
    ListGenerationEvents)
  * internal/repository/postgres/crl_cache.go — Postgres impl with
    SERIALIZABLE-isolated NextCRLNumber to defeat the monotonicity
    race between concurrent generations of the same issuer
  * internal/repository/postgres/crl_cache_test.go — testcontainers
    suite (round-trip, overwrite, monotonicity, event recording,
    failure-event-with-error)

No behavior change at the HTTP layer yet — Phase 3 wires the cache into
GetDERCRL via a new CRLCacheService + crlGenerationLoop.

internal/domain/crl_cache.go

@@ -0,0 +1,50 @@
+package domain
+
+import "time"
+
+// CRLCacheEntry is one row in the crl_cache table — a CRL that the
+// scheduler has pre-generated for a specific issuer. The HTTP handler
+// at /.well-known/pki/crl/{issuer_id} reads from this cache rather
+// than triggering a fresh generation per request.
+//
+// Schema lives in migrations/000019_crl_cache.up.sql.
+type CRLCacheEntry struct {
+	IssuerID           string        `json:"issuer_id"`
+	CRLDER             []byte        `json:"-"`                        // raw DER, omitted from JSON to avoid bloating admin responses
+	CRLDERBase64       string        `json:"crl_der_base64,omitempty"` // populated by repository.Get when callers want the bytes JSON-shaped
+	CRLNumber          int64         `json:"crl_number"`               // monotonic per RFC 5280 §5.2.3
+	ThisUpdate         time.Time     `json:"this_update"`
+	NextUpdate         time.Time     `json:"next_update"`
+	GeneratedAt        time.Time     `json:"generated_at"`
+	GenerationDuration time.Duration `json:"generation_duration"`
+	RevokedCount       int           `json:"revoked_count"`
+}
+
+// IsStale returns true when next_update is in the past — the cached CRL
+// is no longer trustworthy according to its own thisUpdate/nextUpdate
+// promise. The cache service uses this to decide whether to serve from
+// cache or trigger an immediate regeneration.
+//
+// A small grace window (configurable upstream; defaults to 5 minutes)
+// lets the scheduler refresh proactively before the cache hits hard
+// staleness. Callers that want the strict definition pass time.Time{}
+// or now (no grace).
+func (e *CRLCacheEntry) IsStale(now time.Time) bool {
+	return !now.Before(e.NextUpdate)
+}
+
+// CRLGenerationEvent records one (re)generation attempt for ops visibility.
+// Persisted to crl_generation_events. Both successful and failed
+// generations get an event so operators can grep for "why is this issuer's
+// CRL not refreshing." On failure, the Error field carries the wrapped
+// error string from the issuer connector.
+type CRLGenerationEvent struct {
+	ID           int64         `json:"id,omitempty"` // bigserial, set by DB
+	IssuerID     string        `json:"issuer_id"`
+	CRLNumber    int64         `json:"crl_number"` // 0 if generation failed before assigning a number
+	Duration     time.Duration `json:"duration"`
+	RevokedCount int           `json:"revoked_count"`
+	StartedAt    time.Time     `json:"started_at"`
+	Succeeded    bool          `json:"succeeded"`
+	Error        string        `json:"error,omitempty"`
+}

internal/domain/crl_cache_test.go

@@ -0,0 +1,83 @@
+package domain_test
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/shankar0123/certctl/internal/domain"
+)
+
+func TestCRLCacheEntry_IsStale(t *testing.T) {
+	now := time.Date(2026, 4, 28, 12, 0, 0, 0, time.UTC)
+
+	cases := []struct {
+		name       string
+		nextUpdate time.Time
+		want       bool
+	}{
+		{"future next_update is fresh", now.Add(time.Hour), false},
+		{"exactly now is stale (boundary)", now, true},
+		{"past next_update is stale", now.Add(-time.Hour), true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			entry := &domain.CRLCacheEntry{NextUpdate: tc.nextUpdate}
+			if got := entry.IsStale(now); got != tc.want {
+				t.Fatalf("IsStale(%v) = %v, want %v", tc.nextUpdate, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestCRLCacheEntry_JSON_OmitsRawDER(t *testing.T) {
+	// Raw bytes can be 100s of KB for busy CAs; JSON-encoding them into
+	// every admin response would bloat the GUI's polling traffic. The DER
+	// is omitted from JSON; admin endpoints set CRLDERBase64 explicitly
+	// when they want the bytes shaped for transit.
+	entry := &domain.CRLCacheEntry{
+		IssuerID: "iss-test",
+		CRLDER:   []byte{0x30, 0x82, 0x01, 0x00, 0xde, 0xad, 0xbe, 0xef},
+	}
+	blob, err := json.Marshal(entry)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if got := string(blob); contains(got, "deadbeef") || contains(got, "MIIBAA==") {
+		t.Fatalf("raw DER should not appear in JSON, got %s", got)
+	}
+}
+
+func TestCRLGenerationEvent_JSON_RoundTrip(t *testing.T) {
+	now := time.Date(2026, 4, 28, 12, 0, 0, 0, time.UTC)
+	evt := domain.CRLGenerationEvent{
+		IssuerID:     "iss-test",
+		CRLNumber:    42,
+		Duration:     150 * time.Millisecond,
+		RevokedCount: 7,
+		StartedAt:    now,
+		Succeeded:    true,
+	}
+	blob, err := json.Marshal(evt)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	var got domain.CRLGenerationEvent
+	if err := json.Unmarshal(blob, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if got.IssuerID != evt.IssuerID || got.CRLNumber != evt.CRLNumber || got.Duration != evt.Duration {
+		t.Fatalf("round-trip mismatch: got %+v want %+v", got, evt)
+	}
+}
+
+// contains is a local helper to avoid importing strings from a test file
+// where the only use is a substring check.
+func contains(haystack, needle string) bool {
+	for i := 0; i+len(needle) <= len(haystack); i++ {
+		if haystack[i:i+len(needle)] == needle {
+			return true
+		}
+	}
+	return false
+}