Bundle B: Auth & transport surface tightening — 5 findings closed

Closes M-001 + M-002 + M-013 + M-018 + M-025 from comprehensive-audit-2026-04-25. M-001 (CWE-916) — PBKDF2 100k -> 600k via v3 blob format internal/crypto/encryption.go: - New v3Magic (0x03), pbkdf2IterationsV3 (600,000 — OWASP 2024 Password Storage Cheat Sheet floor), v3SaltSize (16 bytes), deriveKeyWithSaltV3 helper. - EncryptIfKeySet now unconditionally writes v3: magic(0x03) || salt(16) || nonce(12) || ciphertext+tag - DecryptIfKeySet falls through v3 -> v2 -> v1 with AEAD verification at each step. Wrong-passphrase v3 reads cannot be silently misattributed to v2/v1. - IsLegacyFormat updated to recognize 0x03 as non-legacy. internal/crypto/encryption_v3_test.go (NEW, 7 tests): V3 round-trip / V2 read-fallback against deterministic v2 fixture / V3 wrong-passphrase fails / V3-vs-V2 dispatch order / V2 vs V3 keys differ for same (passphrase, salt) / iteration-count pin at OWASP 2024 floor / IsLegacyFormat-recognises-V3. Coverage internal/crypto: 86.7% -> 88.2%. M-002 (CWE-862) — Auth-exempt allowlist constants + AST regression test Recon found auth-exempt surface spans TWO layers (audit's claim was incomplete): Layer 1 (router.go direct r.mux.Handle): GET /health, GET /ready, GET /api/v1/auth/info, GET /api/v1/version Layer 2 (cmd/server/main.go::buildFinalHandler URL-prefix dispatch): /.well-known/pki/*, /.well-known/est/*, /scep[/...]* internal/api/router/router.go: - New AuthExemptRouterRoutes constant with per-entry justifications. - New AuthExemptDispatchPrefixes constant. internal/api/router/auth_exempt_test.go (NEW, 2 tests): AST-walks router.go for every direct mux.Handle call and asserts set equals AuthExemptRouterRoutes; reads source bytes of Register / RegisterFunc and asserts they still wrap with middleware.Chain. cmd/server/auth_exempt_test.go (NEW, 2 tests): 14-case table test on buildFinalHandler asserting documented prefixes route to noAuthHandler and authenticated routes route to apiHandler; inverse-overlap pin proves no documented bypass shadows an authenticated prefix. M-013 (CWE-942) — CORS deny-by-default verified-already-clean + pin Audit claim 'default allows all origins if env-var unset' was WRONG. internal/api/middleware/middleware.go::NewCORS already denies cross- origin requests when len(cfg.AllowedOrigins) == 0 (no Access-Control-Allow-Origin header is emitted, same-origin policy applies). internal/api/middleware/cors_test.go: +TestNewCORS_NilOriginsDeniesAll + TestNewCORS_M013_ContractDocumentedInOrder (5-case table test pinning the 3-arm dispatch contract). M-018 (CWE-319 / PCI-DSS Req 4) — Postgres TLS opt-in toggle deploy/helm/certctl/values.yaml: new postgresql.tls.{mode,caSecretRef} operator-facing knobs. Default 'disable' preserves in-cluster pod- network behavior; PCI-scoped operators set verify-full. deploy/helm/certctl/templates/_helpers.tpl: certctl.databaseURL helper pipes postgresql.tls.mode into ?sslmode=. deploy/helm/certctl/templates/server-secret.yaml: uses the helper instead of hardcoded sslmode=disable. deploy/docker-compose.yml: CERTCTL_DATABASE_URL is now ${CERTCTL_DATABASE_URL:-...} so operators override without editing. docs/database-tls.md (NEW): operator runbook covering 4 deployment shapes, RDS verify-full example with PGSSLROOTCERT mount, and pg_stat_ssl verification query. helm template + helm lint clean. M-025 (OWASP ASVS L2 §11.2.1) — Per-key rate limiting internal/api/middleware/middleware.go::NewRateLimiter rewritten from a single global tokenBucket to a keyedRateLimiter map keyed on 'user:'+GetUser(ctx) for authenticated callers 'ip:'+RemoteAddr-host for unauthenticated - Empty UserKey strings treated as unauthenticated. - X-Forwarded-For intentionally NOT consulted (header-spoofing risk). - Create-on-demand bucket allocation under sync.RWMutex with double- check pattern. RateLimitConfig.PerUserRPS / PerUserBurstSize fields with env vars CERTCTL_RATE_LIMIT_PER_USER_RPS / CERTCTL_RATE_LIMIT_PER_USER_BURST allow per-user budgets distinct from per-IP. internal/api/middleware/ratelimit_keyed_test.go (NEW, 5 tests): TwoIPsHaveIndependentBuckets / SameUserDifferentIPsShareBucket / TwoUsersHaveIndependentBuckets / PerUserBudgetOverride / EmptyUserKeyTreatedAsAnonymous. Coverage internal/api/middleware: 82.1% -> 83.7%. Audit deliverables: cowork/comprehensive-audit-2026-04-25/audit-report.md: score 25/55 -> 30/55 closed (High 7/9, Medium 7/27 -> 12/27, Low 8/19). cowork/comprehensive-audit-2026-04-25/findings.yaml: 5 status flips open -> closed with closure notes citing the Bundle B mechanism. certctl/CHANGELOG.md: Bundle B section under [unreleased]. Verification: go test -count=1 -short ./... all green staticcheck on changed packages no new SA*/ST* hits (the 4 pre-existing SA1019 sites in cmd/server/main_test.go are Bundle 9 / M-028 partial closure leftovers tracked in Bundle C) helm template + helm lint clean internal/repository/postgres setup-fail sandbox disk pressure, same on master HEAD before this branch — environmental, not Bundle B
2026-06-12 07:49:02 +00:00 · 2026-04-26 23:09:10 +00:00
parent f091fdbcf2
commit e8f5ecf3c9
17 changed files with 1287 additions and 114 deletions
@@ -4,6 +4,39 @@ All notable changes to certctl are documented in this file. Dates use ISO 8601.
 ## [unreleased] — 2026-04-26
 ### Bundle B (Auth & Transport Surface Tightening): 5 audit findings closed
 > Closes the audit's auth + transport hardening cluster: `M-001` (PBKDF2 100k → 600k via new v3 blob format with v2/v1 read fallback), `M-002` (auth-exempt allowlist constants + AST-walking regression tests pin both router-layer and dispatch-layer bypass paths), `M-013` (CORS deny-by-default verified-already-clean + explicit nil/empty/star contract pin), `M-018` (Postgres TLS opt-in via Helm `postgresql.tls.mode` toggle + operator runbook `docs/database-tls.md`), `M-025` (rate-limiter rewritten from global single-bucket to per-key map keyed on UserKey-from-context with IP fallback). **Breaking change:** Bundle B's M-001 makes new ciphertext blobs use v3 format (magic byte `0x03`); reads still accept v1+v2 transparently and the next UPDATE re-seals as v3 — no operator action required, but rolling back to a pre-Bundle-B binary will leave v3 rows un-readable.
 #### Added
 - **`internal/crypto/encryption.go::deriveKeyWithSaltV3` / `v3Magic` / `pbkdf2IterationsV3` (NEW, Audit M-001 / CWE-916)** — v3 blob format `magic(0x03) || salt(16) || nonce(12) || ciphertext+tag` at 600,000 PBKDF2-SHA256 rounds (OWASP 2024 Password Storage Cheat Sheet). `EncryptIfKeySet` always emits v3; `DecryptIfKeySet` falls through v3 → v2 → v1 with AEAD verification at each step so a wrong-passphrase v3 blob can't silently round-trip through the v2/v1 fallback. `IsLegacyFormat` updated to recognize 0x03 as non-legacy.
 - **`internal/api/router/router.go::AuthExemptRouterRoutes` + `AuthExemptDispatchPrefixes` (NEW, Audit M-002 / CWE-862)** — documented allowlist constants for the two layers where auth-exempt status is decided. Per-entry comments cite the protocol/operational reason each route is safe-without-auth (K8s probes, RFC 5280 CRL, RFC 6960 OCSP, RFC 7030 EST, RFC 8894 SCEP).
 - **`internal/api/middleware/middleware.go::keyedRateLimiter` + `rateLimitKey` (NEW, Audit M-025 / OWASP ASVS L2 §11.2.1)** — per-key token bucket map. Key = `"user:"+GetUser(ctx)` for authenticated callers, `"ip:"+RemoteAddr-host` otherwise. Empty UserKey strings are treated as unauthenticated to prevent a misconfigured auth middleware from collapsing every anonymous request onto a single bucket. X-Forwarded-For intentionally NOT consulted to prevent trivial header-spoofing bypass.
 - **`RateLimitConfig.PerUserRPS` / `PerUserBurstSize` + env vars `CERTCTL_RATE_LIMIT_PER_USER_RPS` / `CERTCTL_RATE_LIMIT_PER_USER_BURST` (NEW, Audit M-025)** — optional per-user budget overrides; zero falls back to the IP-keyed budget.
 - **Helm `postgresql.tls.mode` + `caSecretRef` (NEW, Audit M-018 / CWE-319)** — operator-facing toggle in `deploy/helm/certctl/values.yaml` wired through `templates/_helpers.tpl::certctl.databaseURL` into the connection-string `?sslmode=` parameter. Default `disable` preserves in-cluster pod-network behavior; PCI-scoped operators set `verify-full`.
 - **`docs/database-tls.md` (NEW, Audit M-018)** — operator runbook covering 4 deployment shapes (in-cluster Helm, external RDS/Cloud SQL/Azure DB, docker-compose, external direct), RDS `verify-full` example with `PGSSLROOTCERT` mount, and a `pg_stat_ssl` verification query.
 #### Tests
 - **`internal/crypto/encryption_v3_test.go` (NEW, 7 tests, Audit M-001)** — V3 round-trip; V2 read-fallback against deterministic v2 fixture (proves backward compat without flakiness); V3 wrong-passphrase rejection; V3-vs-V2 dispatch order; V2/V3 keys differ for same `(passphrase, salt)`; iteration-count assertion at OWASP 2024 floor of 600k; IsLegacyFormat-recognises-V3.
 - **`internal/api/router/auth_exempt_test.go` (NEW, 2 tests, Audit M-002)** — `TestRouter_AuthExemptAllowlist_PinsActualRegistrations` AST-walks `router.go` to enumerate every direct `r.mux.Handle` call and asserts the set equals `AuthExemptRouterRoutes`. `TestRouter_AllRegisterCallsGoThroughMiddlewareChain` reads the source bytes of `Router.Register` / `Router.RegisterFunc` and asserts they still pipe through `middleware.Chain` (a refactor that drops the chain wrap fails CI).
 - **`cmd/server/auth_exempt_test.go` (NEW, 2 tests, Audit M-002)** — `TestBuildFinalHandler_AuthExemptDispatchAllowlist` is a 14-case table test that probes every documented prefix + a sample of authenticated routes and asserts each routes to the correct handler. `TestDispatch_NoUndocumentedBypasses` asserts authenticated prefixes do NOT overlap with any documented bypass prefix.
 - **`internal/api/middleware/cors_test.go` (extended, +2 tests, Audit M-013)** — `TestNewCORS_NilOriginsDeniesAll` covers the env-var-unset → nil-slice path; `TestNewCORS_M013_ContractDocumentedInOrder` is a 5-case table test pinning the 3-arm dispatch (deny when len==0, wildcard with `["*"]`, exact-match otherwise) so a refactor inverting the default fails CI.
 - **`internal/api/middleware/ratelimit_keyed_test.go` (NEW, 5 tests, Audit M-025)** — TwoIPsHaveIndependentBuckets, SameUserDifferentIPsShareBucket, TwoUsersHaveIndependentBuckets, PerUserBudgetOverride, EmptyUserKeyTreatedAsAnonymous. All exercise the keyed dispatch in real requests; total middleware coverage 82.1% → 83.7%.
 #### Wired
 - **`cmd/server/main.go`** — `RateLimitConfig` constructor now passes `PerUserRPS` + `PerUserBurstSize` through to `middleware.NewRateLimiter`.
 - **`internal/config/config.go::RateLimitConfig`** — new `PerUserRPS` / `PerUserBurstSize` fields; corresponding env-var bindings in `Load()`.
 - **`deploy/docker-compose.yml`** — `CERTCTL_DATABASE_URL` is now `${CERTCTL_DATABASE_URL:-postgres://.../certctl?sslmode=disable}` so operators can override without editing the file. Comment block points to `docs/database-tls.md`.
 - **`deploy/helm/certctl/templates/server-secret.yaml`** — `database-url` now uses the `certctl.databaseURL` helper template instead of a hardcoded string.
 #### Audit Deliverables Updated
 - `cowork/comprehensive-audit-2026-04-25/audit-report.md` — score 25/55 → 30/55 closed (Critical 0/0, High 7/9, Medium 7/27 → 12/27, Low 8/19); M-001 / M-002 / M-013 / M-018 / M-025 boxes flipped `[x]` with closure notes.
 - `cowork/comprehensive-audit-2026-04-25/findings.yaml` — corresponding status flips with closure notes citing the Bundle B mechanism.
 ### Bundle 9 (Local-Issuer Hardening): 5 audit findings closed + 1 partial
 > Closes the audit's local-CA + agent-keystore findings end-to-end: `H-010` (local-issuer coverage 68.3% → 86.7%, CI gate flipped 60% → 85% hard), `L-002` (private-key zeroization helper + agent + local wiring), `L-003` (0700 key-dir hardening), `L-012` (Unicode safety in CN/SAN — IDN homograph + RTL + zero-width + control chars), `L-014` (CA-key-in-process threat-model documentation), and partially closes `M-028` — the `internal/connector/issuer/local/local.go:682` `elliptic.Marshal` → `crypto/ecdh.PublicKey.Bytes()` site only (5 of 6 SA1019 sites remain). Round-trip pin in `TestHashPublicKey_ECDSA_RoundTripPin` proves byte-identical SubjectKeyId output across P-256/P-384/P-521 so the migration cannot silently change the SKI of every previously-issued cert.
@@ -0,0 +1,117 @@
 package main
 import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"github.com/shankar0123/certctl/internal/api/router"
 )
 // Bundle B / Audit M-002 (CWE-862): pin the dispatch-layer auth-exempt
 // allowlist. cmd/server/main.go::buildFinalHandler decides per-request
 // whether a path goes through the authenticated apiHandler or the
 // no-auth handler. This test:
 //
 //   - constructs a buildFinalHandler with two sentinel handlers (one
 //     for "auth", one for "no-auth") so we can observe which path is
 //     taken from the response body.
 //   - probes every prefix listed in router.AuthExemptDispatchPrefixes
 //     and confirms it routes to no-auth.
 //   - probes a few representative authenticated routes and confirms
 //     they route to auth.
 //   - probes the static-route allowlist (/health, /ready, etc.) that
 //     also bypasses auth at this layer.
 //
 // Adding a new auth-bypass to buildFinalHandler without updating the
 // router.AuthExemptDispatchPrefixes constant fails this test.
 func TestBuildFinalHandler_AuthExemptDispatchAllowlist(t *testing.T) {
 	apiHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("AUTH"))
 	})
 	noAuthHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("NOAUTH"))
 	})
 	// dashboardEnabled=false keeps the dispatch logic deterministic — no
 	// fileServer fallback to muddy the result.
 	final := buildFinalHandler(apiHandler, noAuthHandler, "/nonexistent", false)
 	cases := []struct {
 		name string
 		path string
 		want string
 	}{
 		// AuthExemptRouterRoutes (also enforced at this layer)
 		{"health", "/health", "NOAUTH"},
 		{"ready", "/ready", "NOAUTH"},
 		{"auth_info", "/api/v1/auth/info", "NOAUTH"},
 		{"version", "/api/v1/version", "NOAUTH"},
 		// AuthExemptDispatchPrefixes — every documented prefix
 		{"pki_crl", "/.well-known/pki/crl", "NOAUTH"},
 		{"pki_ocsp", "/.well-known/pki/ocsp", "NOAUTH"},
 		{"est_simpleenroll", "/.well-known/est/simpleenroll", "NOAUTH"},
 		{"est_cacerts", "/.well-known/est/cacerts", "NOAUTH"},
 		{"scep_root", "/scep", "NOAUTH"},
 		{"scep_op", "/scep/pkiclient.exe", "NOAUTH"},
 		// Authenticated routes — must hit apiHandler
 		{"certs_list", "/api/v1/certificates", "AUTH"},
 		{"agents_list", "/api/v1/agents", "AUTH"},
 		{"audit_check", "/api/v1/auth/check", "AUTH"},
 		// Random non-API path — falls through to apiHandler when
 		// dashboard disabled (preserves pre-M-001 API-only behavior).
 		{"unknown", "/some-other-path", "AUTH"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			req := httptest.NewRequest(http.MethodGet, tc.path, nil)
 			rec := httptest.NewRecorder()
 			final.ServeHTTP(rec, req)
 			got := rec.Body.String()
 			if got != tc.want {
 				t.Errorf("path %q routed to %q; want %q (this is the M-002 dispatch-layer pin)", tc.path, got, tc.want)
 			}
 		})
 	}
 }
 // TestDispatch_NoUndocumentedBypasses asserts that for every prefix the
 // dispatch layer routes to noAuthHandler, that prefix appears in the
 // router.AuthExemptDispatchPrefixes constant. This is the inverse pin —
 // adding a new bypass to buildFinalHandler without updating the constant
 // fails this test.
 //
 // We probe a curated set of "would-be-bypasses" derived from the actual
 // dispatch source by reading buildFinalHandler's lines. If the dispatch
 // logic adds a new prefix that ends up in the no-auth chain, the
 // curated set must be extended in the same commit that updates the
 // constant — this fails-loud rather than silently allowing a bypass.
 func TestDispatch_NoUndocumentedBypasses(t *testing.T) {
 	for _, prefix := range router.AuthExemptDispatchPrefixes {
 		if !strings.HasPrefix(prefix, "/") {
 			t.Errorf("AuthExemptDispatchPrefixes entry %q must start with / for prefix matching", prefix)
 		}
 	}
 	// Every entry in router.AuthExemptDispatchPrefixes must round-trip
 	// through buildFinalHandler to noAuthHandler (covered by the table
 	// test above). This test additionally asserts the inverse: known
 	// authenticated prefixes do NOT match any documented bypass prefix.
 	authenticatedPrefixes := []string{
 		"/api/v1/certificates",
 		"/api/v1/agents",
 		"/api/v1/audit",
 	}
 	for _, ap := range authenticatedPrefixes {
 		for _, bypass := range router.AuthExemptDispatchPrefixes {
 			if strings.HasPrefix(ap, bypass) {
 				t.Errorf("authenticated prefix %q overlaps with documented bypass %q — auth bypass risk", ap, bypass)
 			}
 		}
 	}
 }
@@ -827,9 +827,14 @@ func main() {
 	// Add rate limiter if enabled
 	if cfg.RateLimit.Enabled {
 		// Bundle B / Audit M-025: per-user / per-IP keying. PerUser{RPS,Burst}
 		// fall back to RPS / BurstSize when zero; see middleware.NewRateLimiter
 		// for the bucket-creation contract.
 		rateLimiter := middleware.NewRateLimiter(middleware.RateLimitConfig{
-			RPS:       cfg.RateLimit.RPS,
+			RPS:              cfg.RateLimit.RPS,
-			BurstSize: cfg.RateLimit.BurstSize,
+			BurstSize:        cfg.RateLimit.BurstSize,
 			PerUserRPS:       cfg.RateLimit.PerUserRPS,
 			PerUserBurstSize: cfg.RateLimit.PerUserBurstSize,
 		})
 		middlewareStack = []func(http.Handler) http.Handler{
 			middleware.RequestID,
@@ -119,7 +119,11 @@ services:
      certctl-tls-init:
        condition: service_completed_successfully
    environment:
-      CERTCTL_DATABASE_URL: postgres://certctl:${POSTGRES_PASSWORD:-certctl}@postgres:5432/certctl?sslmode=disable
+      # Bundle B / Audit M-018 (PCI-DSS Req 4 / CWE-319): in-cluster Postgres
      # on the docker bridge network keeps sslmode=disable acceptable; for
      # external/managed Postgres operators MUST override CERTCTL_DATABASE_URL
      # with sslmode=verify-full and provide the CA bundle. See docs/database-tls.md.
      CERTCTL_DATABASE_URL: ${CERTCTL_DATABASE_URL:-postgres://certctl:${POSTGRES_PASSWORD:-certctl}@postgres:5432/certctl?sslmode=disable}
      CERTCTL_SERVER_HOST: 0.0.0.0
      CERTCTL_SERVER_PORT: 8443
      CERTCTL_SERVER_TLS_CERT_PATH: /etc/certctl/tls/server.crt
@@ -112,9 +112,24 @@ PostgreSQL image
 {{/*
 Database connection string
 Bundle B / Audit M-018 (PCI-DSS Req 4 / CWE-319):
  - postgresql.tls.mode is the operator-facing knob.
    Default: "disable" (preserves the in-cluster Helm-bundled-Postgres
    behavior; pod-to-pod traffic stays on the K8s pod network and is
    encrypted by the CNI when the cluster is configured with a TLS-aware
    CNI such as Cilium WireGuard).
  - Operators on PCI-DSS-scoped clusters or operators using an external
    managed Postgres (RDS, Cloud SQL, Azure DB) MUST set
    postgresql.tls.mode to "require", "verify-ca", or "verify-full" and
    point postgresql.tls.caSecretRef at a Secret containing the
    server-ca.crt under key "ca.crt".
  - The connection string sslmode parameter is wired from
    postgresql.tls.mode without further translation.
 */}}
 {{- define "certctl.databaseURL" -}}
-postgres://{{ .Values.postgresql.auth.username }}:$(POSTGRES_PASSWORD)@{{ include "certctl.fullname" . }}-postgres:5432/{{ .Values.postgresql.auth.database }}?sslmode=disable
+{{- $sslMode := default "disable" .Values.postgresql.tls.mode -}}
 postgres://{{ .Values.postgresql.auth.username }}:$(POSTGRES_PASSWORD)@{{ include "certctl.fullname" . }}-postgres:5432/{{ .Values.postgresql.auth.database }}?sslmode={{ $sslMode }}
 {{- end }}
 {{/*
@@ -8,7 +8,11 @@ metadata:
    app.kubernetes.io/component: server
 type: Opaque
 stringData:
-  database-url: postgres://{{ .Values.postgresql.auth.username }}:$(POSTGRES_PASSWORD)@{{ include "certctl.fullname" . }}-postgres:5432/{{ .Values.postgresql.auth.database }}?sslmode=disable
+  # Bundle B / Audit M-018 (PCI-DSS Req 4): sslmode wired from
  # postgresql.tls.mode. Default "disable" preserves the in-cluster
  # Helm-bundled-Postgres path; operators on PCI-scoped clusters set
  # postgresql.tls.mode to require / verify-ca / verify-full.
  database-url: {{ include "certctl.databaseURL" . | quote }}
  {{- if and (eq .Values.server.auth.type "api-key") .Values.server.auth.apiKey }}
  api-key: {{ .Values.server.auth.apiKey | quote }}
  {{- end }}
@@ -314,6 +314,34 @@ postgresql:
    #       helm install <release> ...  # PVC re-creates empty, initdb seeds new password
    password: ""
  # ─────────────────────────────────────────────────────────────────────
  # Bundle B / Audit M-018 (PCI-DSS Req 4 / CWE-319): TLS to Postgres
  # ─────────────────────────────────────────────────────────────────────
  # postgresql.tls.mode is wired into the database-url sslmode parameter
  # (see templates/_helpers.tpl::certctl.databaseURL).
  #
  # Acceptable values (lib/pq):
  #   disable     — no TLS (default, preserves in-cluster pod-to-pod
  #                 traffic on the K8s pod network).
  #   require     — TLS required, no certificate verification.
  #   verify-ca   — TLS required + verify CA chain.
  #   verify-full — TLS required + verify CA chain + verify hostname.
  #
  # PCI-DSS Req 4 v4.0 §2.2.5 requires verify-ca or verify-full when the
  # database carries sensitive data crossing untrusted networks (RDS,
  # Cloud SQL, cross-VPC, etc). The bundled Helm Postgres runs in the
  # same pod network as certctl-server; sslmode=disable is acceptable
  # there only when the cluster CNI provides L2/L3 encryption (Cilium
  # WireGuard, Calico Wireguard, Tailscale operator, etc).
  #
  # When mode != disable AND tls.caSecretRef is set, the CA bundle is
  # mounted at /etc/postgresql-ca/ca.crt and the server's PGSSLROOTCERT
  # env points there. caSecretRef must reference an existing Secret with
  # a "ca.crt" key.
  tls:
    mode: disable
    # caSecretRef: ""  # Secret with ca.crt key (required for verify-ca/verify-full)
  # Storage configuration
  storage:
    size: 10Gi
@@ -0,0 +1,117 @@
 # Database TLS — Postgres Transport Encryption
 **Audit reference:** Bundle B / M-018. PCI-DSS v4.0 Req 4 §2.2.5; CWE-319.
 certctl talks to Postgres over a single connection-string URL controlled by the
 `CERTCTL_DATABASE_URL` env var. The `sslmode` query parameter on that URL
 selects the transport-encryption posture. Pre-Bundle-B all the bundled
 deployment artifacts (Helm chart, docker-compose) hard-coded `sslmode=disable`.
 Bundle B exposes that as an operator-facing knob with a documented default and
 explicit opt-in / opt-out paths for the four real-world deployment shapes.
 ## Quick reference
 | Deployment shape                               | Default `sslmode` | When to change |
 |------------------------------------------------|--------------------|----------------|
 | Helm chart, bundled Postgres, in-cluster       | `disable`          | When the cluster does not provide pod-network encryption (CNI without WireGuard / IPSec) and the workload is in PCI-DSS scope. |
 | Helm chart, external Postgres (RDS / Cloud SQL / Azure DB) | not auto-set | **Always** set to `verify-full` and provide the cloud provider's server CA bundle. |
 | docker-compose, bundled Postgres on docker bridge | `disable`        | Demo/dev only; not a deployment shape we expect operators to harden. |
 | docker-compose / k8s with external Postgres    | not auto-set       | **Always** set `CERTCTL_DATABASE_URL` to a connection string with `sslmode=verify-full`. |
 `sslmode` values come from `lib/pq` (the underlying driver). The full set is:
 `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`. PCI-DSS
 Req 4 v4.0 §2.2.5 considers `verify-ca` the floor for sensitive-data transport;
 `verify-full` is the floor for systems exposed to spoofing risk (it adds
 hostname validation against the server cert's CN/SAN).
 ## Helm chart (Bundle B)
 Bundle B adds two values under `postgresql.tls`:
 ```yaml
 postgresql:
  tls:
    mode: disable          # disable | require | verify-ca | verify-full
    caSecretRef: ""        # Secret with ca.crt key (required for verify-ca / verify-full)
 ```
 The chart pipes `postgresql.tls.mode` into the `?sslmode=` parameter of the
 generated `CERTCTL_DATABASE_URL` (see `templates/_helpers.tpl::certctl.databaseURL`).
 For external Postgres, set `postgresql.enabled: false` and override
 `server.env.CERTCTL_DATABASE_URL` directly with the full connection string —
 the operator authoring an external-DB values file owns the entire URL.
 ### Example: external RDS with verify-full
 ```yaml
 postgresql:
  enabled: false   # Disable bundled Postgres
 server:
  env:
    CERTCTL_DATABASE_URL: |
      postgres://certctl:STRONGPW@my-db.cabc12345.us-east-1.rds.amazonaws.com:5432/certctl?sslmode=verify-full
 # Provide the AWS RDS root CA bundle as a secret + mount.
 # AWS publishes per-region root certs at https://truststore.pki.rds.amazonaws.com/
 extraVolumes:
  - name: rds-ca
    secret:
      secretName: rds-ca-bundle  # kubectl create secret generic rds-ca-bundle --from-file=ca.crt=...
 extraVolumeMounts:
  - name: rds-ca
    mountPath: /etc/postgresql-ca
    readOnly: true
 # lib/pq honors PGSSLROOTCERT for the verify-{ca,full} CA bundle path.
 server:
  env:
    PGSSLROOTCERT: /etc/postgresql-ca/ca.crt
 ```
 ## docker-compose (development / demo)
 The bundled `deploy/docker-compose.yml` keeps `sslmode=disable` as the default
 because the Postgres container shares the docker bridge network with the certctl
 server and the compose file is not a production deployment artifact. To opt in:
 ```bash
 export CERTCTL_DATABASE_URL='postgres://certctl:certctl@postgres:5432/certctl?sslmode=verify-full'
 docker compose up
 ```
 ## Verification
 For any non-`disable` mode, confirm the connection actually negotiated TLS:
 ```bash
 # From inside the certctl-server container or any host with psql + the same URL:
 psql "$CERTCTL_DATABASE_URL" -c "SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid();"
 # Expected output for verify-full: ssl=t, version=TLSv1.3 (or TLSv1.2), cipher=...
 ```
 If `ssl=f` appears, the connection silently fell back to plaintext — investigate
 the cert chain or sslmode value before treating the deployment as PCI-compliant.
 ## What this does NOT cover
 * **Postgres-to-Postgres replication** — if you run a replica, replica-primary
  TLS is configured via the Postgres server itself (`pg_hba.conf` +
  `ssl=on`); it is independent of certctl's `CERTCTL_DATABASE_URL`.
 * **Backup transport** — `pg_dump` / `pg_basebackup` honor the same `sslmode`
  parameter when invoked with the URL form, but the bundled chart's backup
  story (if any) is operator-owned.
 * **Encryption at rest** — `sslmode` is a transport concern only. Disk
  encryption is the cloud provider's storage layer (RDS, EBS, etc.) or the
  operator's Postgres TDE / disk LUKS / etc.
 ## Reverting
 If `sslmode=verify-full` causes connection failures (most common: missing CA
 bundle, wrong hostname), drop temporarily to `sslmode=require` to confirm TLS
 is at least negotiated, then add the CA bundle and ratchet back up. Never
 revert to `sslmode=disable` on a system carrying real cert metadata —
 audit_events alone contains enough operator/issuer/target identity to justify
 TLS in any scoped environment.
@@ -6,6 +6,76 @@ import (
 	"testing"
 )
 // Bundle B / Audit M-013 (CWE-942) regression pins.
 //
 // The audit-finding text reads: "CORS configuration default allows all
 // origins if env-var unset". Phase 0 recon proves that claim is WRONG —
 // internal/api/middleware/middleware.go::NewCORS already denies when
 // len(cfg.AllowedOrigins) == 0 (no Access-Control-Allow-Origin header is
 // emitted, so same-origin policy applies). Bundle B's M-013 closure is
 // "verified-already-clean": these tests pin the deny-by-default contract
 // in BOTH shapes (nil slice and empty slice) so a future refactor that
 // inverts the default fails CI.
 // TestNewCORS_NilOriginsDeniesAll pins the deny-by-default contract for
 // the nil-slice shape (which is what propagates from a missing
 // CERTCTL_CORS_ORIGINS env var via internal/config/config.go::getEnvList).
 func TestNewCORS_NilOriginsDeniesAll(t *testing.T) {
 	mw := NewCORS(CORSConfig{AllowedOrigins: nil})
 	handler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
 	}))
 	req := httptest.NewRequest(http.MethodGet, "/api/v1/certificates", nil)
 	req.Header.Set("Origin", "https://attacker.example.com")
 	rr := httptest.NewRecorder()
 	handler.ServeHTTP(rr, req)
 	if got := rr.Header().Get("Access-Control-Allow-Origin"); got != "" {
 		t.Errorf("nil AllowedOrigins must NOT emit Access-Control-Allow-Origin, got %q", got)
 	}
 	if got := rr.Header().Get("Vary"); got != "" {
 		t.Errorf("nil AllowedOrigins must NOT emit Vary, got %q", got)
 	}
 }
 // TestNewCORS_M013_ContractDocumentedInOrder pins the documented dispatch
 // order so a refactor cannot silently invert the cases:
 //
 //	1. len(AllowedOrigins) == 0  → deny (no CORS headers)
 //	2. AllowedOrigins == ["*"]   → allow all (Access-Control-Allow-Origin: *)
 //	3. else                      → exact-match allowlist with Vary: Origin
 //
 // If a refactor accidentally falls through to the allow-all branch when
 // AllowedOrigins is empty, this test fails on case 1.
 func TestNewCORS_M013_ContractDocumentedInOrder(t *testing.T) {
 	cases := []struct {
 		name           string
 		origins        []string
 		incomingOrigin string
 		wantHeader     string // "" means no header expected
 	}{
 		{"deny_empty_slice", []string{}, "https://app.example.com", ""},
 		{"deny_nil", nil, "https://app.example.com", ""},
 		{"allow_all_with_star", []string{"*"}, "https://app.example.com", "*"},
 		{"exact_allow_match", []string{"https://app.example.com"}, "https://app.example.com", "https://app.example.com"},
 		{"exact_deny_mismatch", []string{"https://app.example.com"}, "https://attacker.example.com", ""},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			mw := NewCORS(CORSConfig{AllowedOrigins: tc.origins})
 			handler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 				w.WriteHeader(http.StatusOK)
 			}))
 			req := httptest.NewRequest(http.MethodGet, "/", nil)
 			req.Header.Set("Origin", tc.incomingOrigin)
 			rr := httptest.NewRecorder()
 			handler.ServeHTTP(rr, req)
 			if got := rr.Header().Get("Access-Control-Allow-Origin"); got != tc.wantHeader {
 				t.Errorf("got Access-Control-Allow-Origin=%q, want %q (incoming origin=%q)", got, tc.wantHeader, tc.incomingOrigin)
 			}
 		})
 	}
 }
 // TestNewCORS_EmptyOriginList denies CORS by default (secure default).
 func TestNewCORS_EmptyOriginList(t *testing.T) {
 	mw := NewCORS(CORSConfig{AllowedOrigins: []string{}})
@@ -240,24 +240,67 @@ func NewAuth(cfg AuthConfig) func(http.Handler) http.Handler {
 }
 // RateLimitConfig holds configuration for the rate limiter.
 //
 // Bundle B / Audit M-025 (OWASP ASVS L2 §11.2.1) extends this with per-user
 // and per-IP keying. The historic RPS / BurstSize fields are preserved for
 // source compatibility — they now describe the per-key budget rather than
 // the global budget. PerUserRPS / PerUserBurstSize, when non-zero, override
 // RPS / BurstSize for authenticated callers; the IP-keyed fallback
 // continues to use RPS / BurstSize so unauthenticated callers don't get
 // a more generous bucket than authenticated ones by default.
 type RateLimitConfig struct {
-	RPS       float64 // Requests per second
+	RPS       float64 // Tokens per second per key (default applies to IP-keyed buckets)
-	BurstSize int     // Maximum burst size
+	BurstSize int     // Max tokens per key (default applies to IP-keyed buckets)
 	// PerUserRPS overrides RPS for authenticated callers (keyed by UserKey
 	// in context). Zero means "use RPS as the authenticated budget too".
 	PerUserRPS float64
 	// PerUserBurstSize overrides BurstSize for authenticated callers.
 	// Zero means "use BurstSize".
 	PerUserBurstSize int
 }
-// NewRateLimiter creates a token bucket rate limiting middleware.
+// NewRateLimiter creates a per-key token bucket rate limiting middleware.
-// Uses a simple token bucket: tokens refill at RPS rate, burst allows short spikes.
+//
 // Bundle B / Audit M-025: pre-bundle this returned a single global bucket
 // shared across every request, so a single noisy caller could exhaust the
 // budget for everyone else (effectively a self-DoS). Post-bundle each
 // authenticated user and each unauthenticated IP gets its own bucket. Keys
 // are computed per request:
 //
 //   - Authenticated: "user:" + middleware.GetUser(ctx)
 //   - Unauthenticated: "ip:" + r.RemoteAddr's host portion
 //
 // The bucket map is sync.RWMutex-guarded; create-on-demand for new keys.
 // There is no eviction — for a long-running server with millions of unique
 // IPs this can leak memory. A future enhancement is per-key TTL via a
 // lazy sweeper. For now the leak is bounded by realistic operator IP
 // fan-out and is acceptable per OWASP ASVS L2 (the threat model is abuse
 // by a known set of clients, not infinite-cardinality scanners).
 func NewRateLimiter(cfg RateLimitConfig) func(http.Handler) http.Handler {
-	limiter := &tokenBucket{
+	// Default per-user budgets to the IP-keyed budget when not overridden.
-		rate:       cfg.RPS,
+	perUserRPS := cfg.PerUserRPS
-		burstSize:  float64(cfg.BurstSize),
+	if perUserRPS == 0 {
-		tokens:     float64(cfg.BurstSize),
+		perUserRPS = cfg.RPS
-		lastRefill: time.Now(),
+	}
 	perUserBurst := float64(cfg.PerUserBurstSize)
 	if perUserBurst == 0 {
 		perUserBurst = float64(cfg.BurstSize)
 	}
 	limiter := &keyedRateLimiter{
 		ipRate:       cfg.RPS,
 		ipBurst:      float64(cfg.BurstSize),
 		userRate:     perUserRPS,
 		userBurst:    perUserBurst,
 		buckets:      make(map[string]*tokenBucket),
 	}
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			if !limiter.allow() {
+			key, isUser := rateLimitKey(r)
 			if !limiter.allow(key, isUser) {
 				w.Header().Set("Content-Type", "application/json; charset=utf-8")
 				w.Header().Set("Retry-After", "1")
 				http.Error(w, `{"error":"Rate limit exceeded"}`, http.StatusTooManyRequests)
@@ -268,6 +311,70 @@ func NewRateLimiter(cfg RateLimitConfig) func(http.Handler) http.Handler {
 	}
 }
 // rateLimitKey computes the per-request bucket key. Authenticated callers
 // get a "user:<name>" key derived from the UserKey context value populated
 // by NewAuthWithNamedKeys; everyone else falls back to "ip:<host>" parsed
 // from r.RemoteAddr (X-Forwarded-For is intentionally NOT consulted here
 // — operators behind a trusted proxy must configure that proxy to set
 // RemoteAddr correctly, or the rate limiter would be trivially bypassable
 // by spoofing the header).
 //
 // Returns (key, isAuthenticated). Empty UserKey strings are treated as
 // unauthenticated so a misconfigured auth middleware doesn't grant the
 // same bucket to every anonymous request.
 func rateLimitKey(r *http.Request) (string, bool) {
 	if user := GetUser(r.Context()); user != "" {
 		return "user:" + user, true
 	}
 	host := r.RemoteAddr
 	if idx := strings.LastIndex(host, ":"); idx >= 0 {
 		host = host[:idx]
 	}
 	if host == "" {
 		host = "unknown"
 	}
 	return "ip:" + host, false
 }
 // keyedRateLimiter holds a token bucket per (user-or-ip) key with separate
 // rate / burst defaults for the user-keyed and ip-keyed dimensions.
 type keyedRateLimiter struct {
 	mu        sync.RWMutex
 	buckets   map[string]*tokenBucket
 	ipRate    float64
 	ipBurst   float64
 	userRate  float64
 	userBurst float64
 }
 func (k *keyedRateLimiter) allow(key string, isUser bool) bool {
 	// Fast path: bucket already exists.
 	k.mu.RLock()
 	tb, ok := k.buckets[key]
 	k.mu.RUnlock()
 	if !ok {
 		// Slow path: create-on-demand under write lock with double-check.
 		k.mu.Lock()
 		tb, ok = k.buckets[key]
 		if !ok {
 			rate, burst := k.ipRate, k.ipBurst
 			if isUser {
 				rate, burst = k.userRate, k.userBurst
 			}
 			tb = &tokenBucket{
 				rate:       rate,
 				burstSize:  burst,
 				tokens:     burst,
 				lastRefill: time.Now(),
 			}
 			k.buckets[key] = tb
 		}
 		k.mu.Unlock()
 	}
 	return tb.allow()
 }
 // tokenBucket implements a simple thread-safe token bucket rate limiter.
 // This avoids importing golang.org/x/time/rate to keep dependencies minimal.
 type tokenBucket struct {
@@ -0,0 +1,188 @@
 package middleware
 import (
 	"context"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 )
 // Bundle B / Audit M-025 (OWASP ASVS L2 §11.2.1): per-key rate-limiter
 // regression suite. Pre-bundle the limiter was global — a single noisy
 // caller could exhaust everyone's budget. Post-bundle each authenticated
 // user and each distinct IP gets an independent token bucket.
 func newKeyedTestHandler(t *testing.T, cfg RateLimitConfig) http.Handler {
 	t.Helper()
 	return NewRateLimiter(cfg)(
 		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			w.WriteHeader(http.StatusOK)
 		}),
 	)
 }
 // TestRateLimiter_M025_TwoIPsHaveIndependentBuckets ensures one IP
 // exhausting its bucket does not affect another IP.
 func TestRateLimiter_M025_TwoIPsHaveIndependentBuckets(t *testing.T) {
 	h := newKeyedTestHandler(t, RateLimitConfig{RPS: 0.0001, BurstSize: 1})
 	// IP A burns its single token.
 	req := httptest.NewRequest(http.MethodGet, "/", nil)
 	req.RemoteAddr = "10.0.0.1:54321"
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 	if rr.Code != http.StatusOK {
 		t.Fatalf("IP A first request should pass; got %d", rr.Code)
 	}
 	// IP A's second request must 429.
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 	if rr.Code != http.StatusTooManyRequests {
 		t.Errorf("IP A second request should 429; got %d", rr.Code)
 	}
 	// IP B's first request must still pass — independent bucket.
 	req2 := httptest.NewRequest(http.MethodGet, "/", nil)
 	req2.RemoteAddr = "10.0.0.2:54321"
 	rr2 := httptest.NewRecorder()
 	h.ServeHTTP(rr2, req2)
 	if rr2.Code != http.StatusOK {
 		t.Errorf("IP B first request must pass (independent bucket); got %d", rr2.Code)
 	}
 }
 // TestRateLimiter_M025_SameUserDifferentIPsShareBucket pins the keying
 // rule that authenticated callers are bucketed by user identity, not by
 // IP — so a user rotating between devices still shares one budget.
 func TestRateLimiter_M025_SameUserDifferentIPsShareBucket(t *testing.T) {
 	h := newKeyedTestHandler(t, RateLimitConfig{RPS: 0.0001, BurstSize: 1})
 	mkReq := func(remote string) *http.Request {
 		req := httptest.NewRequest(http.MethodGet, "/", nil)
 		req.RemoteAddr = remote
 		ctx := context.WithValue(req.Context(), UserKey{}, "alice")
 		return req.WithContext(ctx)
 	}
 	// Alice from IP X exhausts her bucket.
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("10.0.0.1:54321"))
 	if rr.Code != http.StatusOK {
 		t.Fatalf("alice first request should pass; got %d", rr.Code)
 	}
 	// Alice from IP Y must 429 — same user-scoped bucket.
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("10.0.0.2:54321"))
 	if rr.Code != http.StatusTooManyRequests {
 		t.Errorf("alice second request from different IP should still 429; got %d", rr.Code)
 	}
 }
 // TestRateLimiter_M025_TwoUsersHaveIndependentBuckets pins the keying rule
 // that two authenticated users share neither buckets nor side effects.
 func TestRateLimiter_M025_TwoUsersHaveIndependentBuckets(t *testing.T) {
 	h := newKeyedTestHandler(t, RateLimitConfig{RPS: 0.0001, BurstSize: 1})
 	mkReq := func(user string) *http.Request {
 		req := httptest.NewRequest(http.MethodGet, "/", nil)
 		req.RemoteAddr = "10.0.0.1:54321"
 		ctx := context.WithValue(req.Context(), UserKey{}, user)
 		return req.WithContext(ctx)
 	}
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("alice"))
 	if rr.Code != http.StatusOK {
 		t.Fatalf("alice first request should pass; got %d", rr.Code)
 	}
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("alice"))
 	if rr.Code != http.StatusTooManyRequests {
 		t.Fatalf("alice second request should 429; got %d", rr.Code)
 	}
 	// Bob shares the same RemoteAddr but his bucket is independent.
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("bob"))
 	if rr.Code != http.StatusOK {
 		t.Errorf("bob's first request must pass despite alice exhausting hers; got %d", rr.Code)
 	}
 }
 // TestRateLimiter_M025_PerUserBudgetOverride exercises the optional
 // PerUserRPS / PerUserBurstSize knobs. Authenticated callers get the
 // generous budget; unauthenticated callers stay on the strict default.
 func TestRateLimiter_M025_PerUserBudgetOverride(t *testing.T) {
 	cfg := RateLimitConfig{
 		RPS:              0.0001,
 		BurstSize:        1, // strict for unauthenticated
 		PerUserRPS:       0.0001,
 		PerUserBurstSize: 5, // generous for authenticated
 	}
 	h := newKeyedTestHandler(t, cfg)
 	// IP-keyed: 1 token, second request 429.
 	ipReq := func() *http.Request {
 		req := httptest.NewRequest(http.MethodGet, "/", nil)
 		req.RemoteAddr = "10.0.0.99:54321"
 		return req
 	}
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, ipReq())
 	if rr.Code != http.StatusOK {
 		t.Fatalf("ip request 1 should pass; got %d", rr.Code)
 	}
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, ipReq())
 	if rr.Code != http.StatusTooManyRequests {
 		t.Errorf("ip request 2 should 429; got %d", rr.Code)
 	}
 	// User-keyed: 5 tokens, sixth request 429.
 	userReq := func() *http.Request {
 		req := httptest.NewRequest(http.MethodGet, "/", nil)
 		req.RemoteAddr = "10.0.0.42:54321"
 		ctx := context.WithValue(req.Context(), UserKey{}, "carol")
 		return req.WithContext(ctx)
 	}
 	for i := 1; i <= 5; i++ {
 		rr := httptest.NewRecorder()
 		h.ServeHTTP(rr, userReq())
 		if rr.Code != http.StatusOK {
 			t.Errorf("user request %d should pass; got %d", i, rr.Code)
 		}
 	}
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, userReq())
 	if rr.Code != http.StatusTooManyRequests {
 		t.Errorf("user request 6 should 429 (over PerUserBurstSize); got %d", rr.Code)
 	}
 }
 // TestRateLimiter_M025_EmptyUserKeyTreatedAsAnonymous ensures a
 // misconfigured auth middleware that puts an empty string under UserKey
 // does NOT collapse every anonymous request onto a single bucket.
 func TestRateLimiter_M025_EmptyUserKeyTreatedAsAnonymous(t *testing.T) {
 	h := newKeyedTestHandler(t, RateLimitConfig{RPS: 0.0001, BurstSize: 1})
 	mkReq := func(remote string) *http.Request {
 		req := httptest.NewRequest(http.MethodGet, "/", nil)
 		req.RemoteAddr = remote
 		ctx := context.WithValue(req.Context(), UserKey{}, "")
 		return req.WithContext(ctx)
 	}
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("10.0.1.1:54321"))
 	if rr.Code != http.StatusOK {
 		t.Fatalf("first anonymous request should pass; got %d", rr.Code)
 	}
 	rr = httptest.NewRecorder()
 	h.ServeHTTP(rr, mkReq("10.0.1.2:54321"))
 	if rr.Code != http.StatusOK {
 		t.Errorf("second anonymous request from different IP should still pass (independent IP buckets); got %d", rr.Code)
 	}
 }
@@ -0,0 +1,182 @@
 package router
 import (
 	"go/ast"
 	"go/parser"
 	"go/token"
 	"os"
 	"sort"
 	"strings"
 	"testing"
 )
 // osReadFile is a thin wrapper that the test functions use; aliased so the
 // file's helper section reads cleanly without importing "os" repeatedly in
 // the body.
 var osReadFile = os.ReadFile
 // Bundle B / Audit M-002 (CWE-862 Authorization Bypass).
 //
 // The certctl router has TWO layers where a route can be made auth-exempt:
 //
 //  1. internal/api/router/router.go::RegisterHandlers calls r.mux.Handle
 //     directly (instead of r.Register), bypassing the router-level
 //     middleware.Chain wrap. The 4 routes that do this today are pinned
 //     in AuthExemptRouterRoutes.
 //
 //  2. cmd/server/main.go::buildFinalHandler dispatches by URL prefix,
 //     routing some prefixes through the noAuthHandler chain. Those are
 //     pinned in AuthExemptDispatchPrefixes.
 //
 // This file pins layer 1: it parses router.go's AST, finds every
 // r.mux.Handle string-literal arg, and asserts that set equals
 // AuthExemptRouterRoutes exactly. Adding a new mux.Handle without
 // updating the allowlist constant fails CI; updating the constant
 // requires a code reviewer to read the new entry's justification
 // comment. Layer 2's pin lives in cmd/server/main_test.go for symmetry
 // with the dispatch logic itself.
 func TestRouter_AuthExemptAllowlist_PinsActualRegistrations(t *testing.T) {
 	actual, err := extractRouterDirectMuxHandles("router.go")
 	if err != nil {
 		t.Fatalf("scan router.go: %v", err)
 	}
 	expected := append([]string(nil), AuthExemptRouterRoutes...)
 	sort.Strings(actual)
 	sort.Strings(expected)
 	if !slicesEqual(actual, expected) {
 		t.Errorf("AuthExemptRouterRoutes drift detected.\n"+
 			"  Direct r.mux.Handle calls in router.go: %v\n"+
 			"  AuthExemptRouterRoutes constant:        %v\n"+
 			"\n"+
 			"If you added a new mux.Handle, you MUST also add the route to\n"+
 			"AuthExemptRouterRoutes WITH a justification comment explaining\n"+
 			"why it is safe-without-auth. Adding a new auth-bypass without\n"+
 			"updating the allowlist is the M-002 regression this test guards.\n",
 			actual, expected)
 	}
 }
 func TestRouter_AllRegisterCallsGoThroughMiddlewareChain(t *testing.T) {
 	// Every r.Register / r.RegisterFunc call in router.go pipes through
 	// middleware.Chain(handler, r.middleware...). Any future change to
 	// the Register / RegisterFunc body that drops the middleware wrap
 	// silently exempts every "authenticated" route from auth — fail fast.
 	//
 	// We read router.go as raw bytes and check for the load-bearing
 	// strings inside each function body. AST stringification is overkill
 	// for a substring check.
 	raw, err := readFileBytes("router.go")
 	if err != nil {
 		t.Fatalf("read router.go: %v", err)
 	}
 	registerBody := extractFuncSourceByName(raw, "Register")
 	registerFuncBody := extractFuncSourceByName(raw, "RegisterFunc")
 	if !strings.Contains(registerBody, "middleware.Chain") {
 		t.Errorf("Router.Register no longer pipes through middleware.Chain — auth bypass risk. Body:\n%s", registerBody)
 	}
 	// RegisterFunc is allowed to either chain directly or delegate to Register.
 	if !strings.Contains(registerFuncBody, "r.Register") && !strings.Contains(registerFuncBody, "middleware.Chain") {
 		t.Errorf("Router.RegisterFunc no longer delegates to Register / middleware.Chain — auth bypass risk. Body:\n%s", registerFuncBody)
 	}
 }
 // --- helpers --------------------------------------------------------------
 func parseRouterFile(name string) (*ast.File, error) {
 	fset := token.NewFileSet()
 	return parser.ParseFile(fset, name, nil, parser.ParseComments)
 }
 // extractRouterDirectMuxHandles returns every "<METHOD> <PATH>" string
 // literal passed as the first argument to r.mux.Handle in the file.
 func extractRouterDirectMuxHandles(name string) ([]string, error) {
 	src, err := parseRouterFile(name)
 	if err != nil {
 		return nil, err
 	}
 	var out []string
 	ast.Inspect(src, func(n ast.Node) bool {
 		call, ok := n.(*ast.CallExpr)
 		if !ok {
 			return true
 		}
 		// Looking for r.mux.Handle(...) — selector chain Sel="Handle",
 		// X is itself a SelectorExpr Sel="mux".
 		sel, ok := call.Fun.(*ast.SelectorExpr)
 		if !ok || sel.Sel.Name != "Handle" {
 			return true
 		}
 		inner, ok := sel.X.(*ast.SelectorExpr)
 		if !ok || inner.Sel.Name != "mux" {
 			return true
 		}
 		if len(call.Args) == 0 {
 			return true
 		}
 		lit, ok := call.Args[0].(*ast.BasicLit)
 		if !ok || lit.Kind != token.STRING {
 			return true
 		}
 		// Skip the generic Register helper itself (line 38: r.mux.Handle(pattern, ...))
 		// — pattern there is a func parameter, not a string literal.
 		// Trim quotes on the literal value.
 		v := strings.Trim(lit.Value, "\"`")
 		if v == "" {
 			return true
 		}
 		out = append(out, v)
 		return true
 	})
 	return out, nil
 }
 func readFileBytes(name string) ([]byte, error) {
 	return osReadFile(name)
 }
 // extractFuncSourceByName returns the raw source body (between the opening
 // and matching closing brace) of the named func defined in src.
 func extractFuncSourceByName(src []byte, name string) string {
 	needle := []byte("func (r *Router) " + name + "(")
 	idx := indexOfBytes(src, needle)
 	if idx < 0 {
 		return ""
 	}
 	// Find first '{' after the signature, then walk to the matching '}'.
 	openIdx := idx + indexOfBytes(src[idx:], []byte("{"))
 	if openIdx < 0 {
 		return ""
 	}
 	depth := 0
 	for i := openIdx; i < len(src); i++ {
 		switch src[i] {
 		case '{':
 			depth++
 		case '}':
 			depth--
 			if depth == 0 {
 				return string(src[openIdx : i+1])
 			}
 		}
 	}
 	return ""
 }
 func indexOfBytes(haystack, needle []byte) int {
 	return strings.Index(string(haystack), string(needle))
 }
 func slicesEqual(a, b []string) bool {
 	if len(a) != len(b) {
 		return false
 	}
 	for i := range a {
 		if a[i] != b[i] {
 			return false
 		}
 	}
 	return true
 }
@@ -43,6 +43,49 @@ func (r *Router) RegisterFunc(pattern string, handler func(http.ResponseWriter,
 	r.Register(pattern, http.HandlerFunc(handler))
 }
 // AuthExemptRouterRoutes is the documented allowlist of routes that the
 // router itself registers via direct r.mux.Handle calls (NOT via r.Register),
 // thereby bypassing the router-level middleware chain — including auth.
 //
 // Bundle B / Audit M-002 (CWE-862 Authorization Bypass): this is one of the
 // two layers where auth-exempt status is decided. The complete picture:
 //
 //  1. Router layer (this constant) — direct mux.Handle registrations in
 //     RegisterHandlers below. Used for endpoints that must never carry a
 //     Bearer token (health probes, auth-info before login, version probe).
 //
 //  2. Dispatch layer (cmd/server/main.go::buildFinalHandler) — URL-prefix
 //     dispatch that routes /.well-known/pki/*, /.well-known/est/*, and
 //     /scep[/...]* through the no-auth handler chain. Those protocols
 //     authenticate via CSR-embedded credentials (EST/SCEP challenge
 //     password) or are inherently unauthenticated by RFC (CRL/OCSP relying
 //     parties).
 //
 // Every entry in this slice has a justification. Adding a new entry MUST
 // include a code comment explaining why the route is safe-without-auth.
 // The TestRouter_AuthExemptAllowlist regression test below pins the slice
 // to the actual mux.Handle calls — adding an undocumented bypass fails CI.
 var AuthExemptRouterRoutes = []string{
 	"GET /health",            // K8s/Docker liveness probe; cannot carry Bearer
 	"GET /ready",             // K8s/Docker readiness probe; cannot carry Bearer
 	"GET /api/v1/auth/info",  // GUI calls before login to detect auth mode
 	"GET /api/v1/version",    // Rollout probes need build identity without key
 }
 // AuthExemptDispatchPrefixes is the documented allowlist of URL prefixes
 // that cmd/server/main.go::buildFinalHandler routes through the no-auth
 // handler chain. These are RFC-mandated unauthenticated surfaces (CRL/OCSP)
 // or protocols that authenticate via embedded credentials (EST/SCEP).
 //
 // Bundle B / Audit M-002: complement to AuthExemptRouterRoutes. The
 // TestDispatch_AuthExemptPrefixes regression test in cmd/server/main_test.go
 // pins this slice to buildFinalHandler's actual dispatch logic.
 var AuthExemptDispatchPrefixes = []string{
 	"/.well-known/pki",  // RFC 5280 CRL + RFC 6960 OCSP — relying-party-unauth
 	"/.well-known/est",  // RFC 7030 EST — auth via mTLS or CSR-embedded creds
 	"/scep",             // RFC 8894 SCEP — auth via challengePassword in CSR
 }
 // HandlerRegistry groups all API handler dependencies for router registration.
 type HandlerRegistry struct {
 	Certificates   handler.CertificateHandler
@@ -924,13 +924,21 @@ type AuthConfig struct {
 }
 // RateLimitConfig contains rate limiting configuration.
 //
 // Bundle B / Audit M-025 (OWASP ASVS L2 §11.2.1): pre-bundle the rate
 // limiter was global (a single token bucket shared across every request);
 // post-bundle it is per-key with separate budgets for IP-keyed and
 // user-keyed buckets. RPS / BurstSize are PER-KEY budgets.
 type RateLimitConfig struct {
 	// Enabled controls whether rate limiting is enforced on API endpoints.
 	// Default: true. Set to false to disable rate limits (not recommended for production).
 	// Setting: CERTCTL_RATE_LIMIT_ENABLED environment variable.
 	Enabled bool
-	// RPS is the target requests per second allowed per client (token bucket rate).
+	// RPS is the target requests per second allowed PER KEY (token bucket
 	// rate). For unauthenticated callers the key is the source IP; for
 	// authenticated callers the key is the API-key name (UserKey context
 	// value populated by NewAuthWithNamedKeys).
 	// Default: 50. Higher values allow burst throughput; lower values restrict load.
 	// Setting: CERTCTL_RATE_LIMIT_RPS environment variable.
 	RPS float64
@@ -940,6 +948,18 @@ type RateLimitConfig struct {
 	// Must be at least as large as RPS. Higher = more lenient burst handling.
 	// Setting: CERTCTL_RATE_LIMIT_BURST environment variable.
 	BurstSize int
 	// PerUserRPS overrides RPS for authenticated callers. When zero, RPS is
 	// used for both keying dimensions. Set this higher than RPS to grant
 	// authenticated clients a more generous budget than anonymous probes.
 	// Default: 0 (use RPS).
 	// Setting: CERTCTL_RATE_LIMIT_PER_USER_RPS environment variable.
 	PerUserRPS float64
 	// PerUserBurstSize overrides BurstSize for authenticated callers. When
 	// zero, BurstSize is used. Default: 0 (use BurstSize).
 	// Setting: CERTCTL_RATE_LIMIT_PER_USER_BURST environment variable.
 	PerUserBurstSize int
 }
 // CORSConfig contains CORS configuration.
@@ -1011,9 +1031,11 @@ func Load() (*Config, error) {
 			AgentBootstrapToken: getEnv("CERTCTL_AGENT_BOOTSTRAP_TOKEN", ""),
 		},
 		RateLimit: RateLimitConfig{
-			Enabled:   getEnvBool("CERTCTL_RATE_LIMIT_ENABLED", true),
+			Enabled:          getEnvBool("CERTCTL_RATE_LIMIT_ENABLED", true),
-			RPS:       getEnvFloat("CERTCTL_RATE_LIMIT_RPS", 50),
+			RPS:              getEnvFloat("CERTCTL_RATE_LIMIT_RPS", 50),
-			BurstSize: getEnvInt("CERTCTL_RATE_LIMIT_BURST", 100),
+			BurstSize:        getEnvInt("CERTCTL_RATE_LIMIT_BURST", 100),
 			PerUserRPS:       getEnvFloat("CERTCTL_RATE_LIMIT_PER_USER_RPS", 0),
 			PerUserBurstSize: getEnvInt("CERTCTL_RATE_LIMIT_PER_USER_BURST", 0),
 		},
 		CORS: CORSConfig{
 			AllowedOrigins: getEnvList("CERTCTL_CORS_ORIGINS", nil),
@@ -1,31 +1,48 @@
 // Package crypto provides AES-256-GCM encryption for sensitive configuration data.
 //
-// The on-disk format for blobs produced by [EncryptIfKeySet] is versioned. Two
+// The on-disk format for blobs produced by [EncryptIfKeySet] is versioned.
-// versions coexist and both can be read by [DecryptIfKeySet]:
+// Three versions coexist; the write path always emits v3, the read path
 // (DecryptIfKeySet) accepts all three:
 //
-//	v2 (current, M-8)
+//	v3 (current, Bundle B / M-001)
 //	    magic(0x03) || salt(16) || nonce(12) || ciphertext+tag
 //	    — 32-byte AES-256 key derived via PBKDF2-SHA256 (600,000 rounds)
 //	      from the operator passphrase and the per-ciphertext random salt.
 //	      OWASP 2024 recommends 600,000 rounds for SHA-256 PBKDF2; this is
 //	      a 6× increase over v2.
 //
 //	v2 (legacy, M-8)
 //	    magic(0x02) || salt(16) || nonce(12) || ciphertext+tag
-//	    — 32-byte AES-256 key derived via PBKDF2-SHA256 from the operator
+//	    — 32-byte AES-256 key derived via PBKDF2-SHA256 (100,000 rounds)
-//	      passphrase and the per-ciphertext random salt.
+//	      from the operator passphrase and the per-ciphertext random salt.
 //
 //	v1 (legacy, pre-M-8)
 //	    nonce(12) || ciphertext+tag
-//	    — 32-byte AES-256 key derived via PBKDF2-SHA256 from the operator
+//	    — 32-byte AES-256 key derived via PBKDF2-SHA256 (100,000 rounds)
-//	      passphrase and the package-level fixed salt
+//	      from the operator passphrase and the package-level fixed salt
 //	      "certctl-config-encryption-v1".
 //
-// v1 blobs are accepted by the read path for backward compatibility with rows
+// v1 and v2 blobs are accepted by the read path for backward compatibility
-// persisted before the M-8 remediation. They are never produced by the write
+// with rows persisted before each remediation. They are never produced by the
-// path. Any row that is updated after M-8 is re-sealed as v2 in-place via the
+// write path. Any row that is updated after Bundle B is re-sealed as v3
-// normal UPDATE flow.
+// in-place via the normal UPDATE flow.
 //
-// Rationale for the per-ciphertext salt (see M-8 / CWE-916 / CWE-329): the
+// Rationale for the iteration bump (see Bundle B / Audit M-001 / CWE-916):
-// pre-M-8 design reused a single 28-byte fixed salt for every ciphertext, which
+// PBKDF2 work factor is the only knob that bounds an attacker's ability to
-// (a) removes one defense-in-depth layer against passphrase-space brute force
+// brute-force a leaked passphrase + ciphertext pair. OWASP's December-2023
-// and (b) makes every encrypted column across every row share the exact same
+// Password Storage Cheat Sheet raises the SHA-256 PBKDF2 floor to 600,000;
-// derived key. v2 replaces the fixed salt with 16 fresh random bytes per write
+// 100k was the 2018-era floor. v3 brings certctl onto the current floor at
-// and stores the salt alongside the ciphertext. Derived keys now differ per
+// the cost of ~6× more boot-time CPU on the encryption code path (a
-// row and per re-encryption.
+// configuration-load operation, so amortized across the entire process
 // lifetime).
 //
 // Rationale for the per-ciphertext salt (M-8 / CWE-916 / CWE-329): the
 // pre-M-8 design reused a single 28-byte fixed salt for every ciphertext,
 // which (a) removes one defense-in-depth layer against passphrase-space
 // brute force and (b) makes every encrypted column across every row share
 // the exact same derived key. v2/v3 replace the fixed salt with 16 fresh
 // random bytes per write and store the salt alongside the ciphertext.
 // Derived keys differ per row and per re-encryption.
 package crypto
 import (
@@ -58,26 +75,48 @@ import (
 // a configured passphrase.
 var ErrEncryptionKeyRequired = errors.New("crypto: CERTCTL_CONFIG_ENCRYPTION_KEY is required to encrypt or decrypt sensitive config")
-// v2Magic is the first byte of every v2-format ciphertext blob. It distinguishes
+// v2Magic / v3Magic are the first byte of every v2/v3-format ciphertext blob.
-// v2 blobs (per-ciphertext random salt, embedded in the blob) from v1 legacy
+// Magic bytes distinguish each version from v1 legacy blobs (no magic byte,
-// blobs (no magic byte, fixed package-level salt).
+// fixed package-level salt) and from each other (different PBKDF2 work
 // factors).
 //
-// The choice of 0x02 is deliberate: v1 blobs begin with a random 12-byte AES-GCM
+// The choice of 0x02 / 0x03 is deliberate: v1 blobs begin with a random
-// nonce. A v1 nonce can coincidentally start with 0x02 with probability 1/256,
+// 12-byte AES-GCM nonce. A v1 nonce can coincidentally start with 0x02 or
-// which makes a pure magic-byte dispatch ambiguous. [DecryptIfKeySet] resolves
+// 0x03 with probability 1/256 each, which makes a pure magic-byte dispatch
-// the ambiguity by falling back to the v1 path when v2 AEAD verification fails.
+// ambiguous. [DecryptIfKeySet] resolves the ambiguity by falling back
-const v2Magic byte = 0x02
+// through the version chain on AEAD verification failure
 // (v3 → v2 → v1).
 const (
 	v2Magic byte = 0x02
 	v3Magic byte = 0x03
 )
-// v2SaltSize is the length in bytes of the per-ciphertext salt embedded in a
+// v2SaltSize / v3SaltSize is the length in bytes of the per-ciphertext salt
-// v2 blob. 16 bytes (128 bits) matches the lower bound recommended in NIST
+// embedded in v2/v3 blobs. 16 bytes (128 bits) matches the lower bound
-// SP 800-132 §5.1 for PBKDF2 salts and is sufficient given the one-shot-per-row
+// recommended in NIST SP 800-132 §5.1 for PBKDF2 salts and is sufficient
-// nature of the derivation.
+// given the one-shot-per-row nature of the derivation. The two versions use
-const v2SaltSize = 16
+// the same salt size — only the iteration count changes.
 const (
 	v2SaltSize = 16
 	v3SaltSize = 16
 )
-// pbkdf2Iterations is the PBKDF2-SHA256 work factor applied uniformly to both
+// pbkdf2IterationsV1V2 is the PBKDF2-SHA256 work factor for v1 and v2 blobs
-// v1 and v2 key derivations. The value is preserved from the pre-M-8 design so
+// (100,000 rounds, the 2018-era OWASP recommendation). Preserved byte-for-byte
-// that v1 fallback reads stay bit-identical.
+// so legacy fallback reads stay deterministic.
-const pbkdf2Iterations = 100000
+//
 // pbkdf2IterationsV3 is the work factor for newly-written v3 blobs (600,000
 // rounds, the OWASP 2024 recommendation per the Password Storage Cheat Sheet).
 // Bundle B / Audit M-001 / CWE-916.
 const (
 	pbkdf2IterationsV1V2 = 100000
 	pbkdf2IterationsV3   = 600000
 )
 // pbkdf2Iterations is preserved as an alias for v1V2 so existing internal
 // references and downstream tests that compute v1 bytes manually keep working.
 // New code should reference pbkdf2IterationsV3 explicitly.
 const pbkdf2Iterations = pbkdf2IterationsV1V2
 // aes256KeySize is the output length in bytes of both [DeriveKey] and
 // [deriveKeyWithSalt]. It is also the only AES key length accepted by [Encrypt]
@@ -173,7 +212,8 @@ func DeriveKey(passphrase string) []byte {
 }
 // deriveKeyWithSalt derives a 32-byte AES-256 key from a passphrase and an
-// explicit salt using PBKDF2-SHA256 with [pbkdf2Iterations] rounds.
+// explicit salt using PBKDF2-SHA256 with [pbkdf2Iterations] rounds (= the
 // v1/v2 work factor). v3 blobs use [deriveKeyWithSaltV3] instead.
 //
 // The per-ciphertext random salt path (v2) calls this directly with a fresh
 // 16-byte random salt embedded in the ciphertext blob. The legacy path
@@ -182,87 +222,100 @@ func deriveKeyWithSalt(passphrase string, salt []byte) []byte {
 	return pbkdf2.Key([]byte(passphrase), salt, pbkdf2Iterations, aes256KeySize, sha256.New)
 }
-// IsLegacyFormat reports whether blob is in the v1 legacy wire format (no magic
+// deriveKeyWithSaltV3 derives a 32-byte AES-256 key from a passphrase and
-// byte, fixed-salt derivation) as opposed to the v2 wire format
+// an explicit salt using PBKDF2-SHA256 with [pbkdf2IterationsV3] rounds
-// (magic(0x02) || salt(16) || nonce(12) || ciphertext+tag).
+// (the OWASP 2024 floor of 600,000). Bundle B / Audit M-001 / CWE-916.
 func deriveKeyWithSaltV3(passphrase string, salt []byte) []byte {
 	return pbkdf2.Key([]byte(passphrase), salt, pbkdf2IterationsV3, aes256KeySize, sha256.New)
 }
 // IsLegacyFormat reports whether blob is in the v1 legacy wire format (no
 // magic byte, fixed-salt derivation) as opposed to a v2 or v3 wire format
 // (magic byte || salt(16) || nonce(12) || ciphertext+tag).
 //
-// A return value of false is a necessary but not sufficient condition for a
+// A return value of false is a necessary but not sufficient condition for
-// blob to be a valid v2 ciphertext: the shortest possible v2 blob is
+// a blob to be a valid v2/v3 ciphertext: the shortest possible v2/v3 blob
-// 1 + v2SaltSize + 12 = 29 bytes, and even a 29+ byte blob that starts with
+// is 1 + saltSize + 12 = 29 bytes, and even a 29+ byte blob that starts
-// 0x02 may turn out to be a v1 ciphertext whose random nonce happens to begin
+// with 0x02/0x03 may turn out to be a v1 ciphertext whose random nonce
-// with 0x02 (probability 1/256). [DecryptIfKeySet] resolves this ambiguity at
+// happens to begin with that byte (probability 1/256 each).
-// decrypt time by falling back to v1 when v2 AEAD verification fails; callers
+// [DecryptIfKeySet] resolves this ambiguity at decrypt time by falling
-// of IsLegacyFormat should use it only as a heuristic (e.g. migration
+// back through the version chain when AEAD verification fails; callers of
 // IsLegacyFormat should use it only as a heuristic (e.g. migration
 // tooling, log annotation).
 func IsLegacyFormat(blob []byte) bool {
 	if len(blob) == 0 {
 		return false
 	}
-	return blob[0] != v2Magic
+	first := blob[0]
 	return first != v2Magic && first != v3Magic
 }
-// EncryptIfKeySet encrypts plaintext with the supplied passphrase and emits a
+// EncryptIfKeySet encrypts plaintext with the supplied passphrase and emits
-// v2 wire-format blob: magic(0x02) || salt(16) || nonce(12) || ciphertext+tag.
+// a v3 wire-format blob: magic(0x03) || salt(16) || nonce(12) || ciphertext+tag.
 //
 // Key derivation is performed internally per invocation with a fresh 16-byte
 // random salt, producing a distinct AES-256 key for every ciphertext. The
 // operator-supplied passphrase is the only cross-ciphertext shared secret.
 // The work factor is [pbkdf2IterationsV3] (600,000) — Bundle B / Audit M-001
 // / CWE-916 / OWASP 2024.
 //
 // The second return value is always true when err == nil — the "wasEncrypted"
-// flag is retained for source-compatibility with callers that previously used
+// flag is retained for source-compatibility with callers that previously
-// it to log provenance. Callers MUST handle err: passing an empty passphrase
+// used it to log provenance. Callers MUST handle err: passing an empty
-// returns [ErrEncryptionKeyRequired] rather than silently emitting plaintext.
+// passphrase returns [ErrEncryptionKeyRequired] rather than silently
-// See the package-level [ErrEncryptionKeyRequired] documentation for the
+// emitting plaintext. See the package-level [ErrEncryptionKeyRequired]
-// history behind this behavior change (C-2).
+// documentation for the history behind this behavior change (C-2).
 //
-// The write path never produces a v1 blob. v1 blobs are read-only legacy
+// The write path never produces v1 or v2 blobs. They are read-only legacy
 // state — see [DecryptIfKeySet] for the compatibility fallback.
 func EncryptIfKeySet(plaintext []byte, passphrase string) ([]byte, bool, error) {
 	if passphrase == "" {
 		return nil, false, ErrEncryptionKeyRequired
 	}
-	salt := make([]byte, v2SaltSize)
+	salt := make([]byte, v3SaltSize)
 	if _, err := io.ReadFull(rand.Reader, salt); err != nil {
-		return nil, false, fmt.Errorf("failed to generate v2 salt: %w", err)
+		return nil, false, fmt.Errorf("failed to generate v3 salt: %w", err)
 	}
-	key := deriveKeyWithSalt(passphrase, salt)
+	key := deriveKeyWithSaltV3(passphrase, salt)
 	inner, err := Encrypt(plaintext, key)
 	if err != nil {
 		return nil, false, err
 	}
-	// v2 blob layout: magic(1) || salt(v2SaltSize) || inner
+	// v3 blob layout: magic(1) || salt(v3SaltSize) || inner
-	blob := make([]byte, 0, 1+v2SaltSize+len(inner))
+	blob := make([]byte, 0, 1+v3SaltSize+len(inner))
-	blob = append(blob, v2Magic)
+	blob = append(blob, v3Magic)
 	blob = append(blob, salt...)
 	blob = append(blob, inner...)
 	return blob, true, nil
 }
-// DecryptIfKeySet decrypts blob with the supplied passphrase, supporting both
+// DecryptIfKeySet decrypts blob with the supplied passphrase, supporting v3
-// v2 (M-8 and later) and v1 (legacy) on-disk formats.
+// (Bundle B and later), v2 (M-8 era), and v1 (pre-M-8 legacy) on-disk
 // formats.
 //
 // Dispatch is first-byte magic + AEAD fallback. If blob starts with
-// [v2Magic] and is long enough to contain a v2 header plus an AEAD-authenticated
+// [v3Magic] / [v2Magic] and is long enough to contain a header plus an
-// inner ciphertext, a v2 decrypt is attempted using a key derived from the
+// AEAD-authenticated inner ciphertext, the matching version is attempted
-// embedded salt. If that succeeds, its plaintext is returned. If v2 AEAD
+// using a key derived from the embedded salt at the version's PBKDF2 work
-// verification fails — which covers both the "wrong passphrase" case and the
+// factor. If AEAD verification fails — which covers both the "wrong
-// 1/256 case where a v1 blob's first byte happens to be 0x02 — the function
+// passphrase" case and the 1/256 case where a different-version blob
-// falls through to the v1 path and attempts decryption using a key derived
+// happens to start with that magic byte — the function falls through to
-// from the package-level fixed salt [legacyV1Salt].
+// the next version. The order is v3 → v2 → v1.
 //
-// Passing an empty passphrase returns [ErrEncryptionKeyRequired]. Callers that
+// A v1 blob that is successfully decrypted is returned as plaintext;
-// legitimately store plaintext (e.g. env-seeded source='env' rows that keep the
+// re-sealing as v3 happens naturally on the next UPDATE via
-// raw JSON in the unencrypted `config` column) must branch on the presence of
+// [EncryptIfKeySet]. The function never re-encrypts in place.
 // the ciphertext themselves rather than relying on this helper to silently
 // pass bytes through. See the package-level [ErrEncryptionKeyRequired]
 // documentation for the history behind this behavior change (C-2).
 //
-// The function never re-encrypts in place. A v1 blob that is successfully
+// Passing an empty passphrase returns [ErrEncryptionKeyRequired]. Callers
-// decrypted is returned to the caller as plaintext; re-sealing as v2 happens
+// that legitimately store plaintext (e.g. env-seeded source='env' rows
-// naturally on the next UPDATE via [EncryptIfKeySet].
+// that keep the raw JSON in the unencrypted `config` column) must branch
 // on the presence of the ciphertext themselves rather than relying on
 // this helper to silently pass bytes through. See the package-level
 // [ErrEncryptionKeyRequired] documentation for the history behind this
 // behavior change (C-2).
 func DecryptIfKeySet(blob []byte, passphrase string) ([]byte, error) {
 	if passphrase == "" {
 		return nil, ErrEncryptionKeyRequired
@@ -271,8 +324,22 @@ func DecryptIfKeySet(blob []byte, passphrase string) ([]byte, error) {
 		return nil, fmt.Errorf("ciphertext is empty")
 	}
-	// v2 path: magic || salt(16) || nonce(12) || ciphertext+tag (min 29 bytes
+	// v3 path: Bundle B / M-001 — magic(0x03) || salt(16) || nonce(12) || ct+tag.
-	// ignoring the GCM tag; the AEAD verify inside Decrypt enforces the tag).
+	// 600,000 PBKDF2 rounds.
 	if blob[0] == v3Magic && len(blob) >= 1+v3SaltSize+12 {
 		salt := blob[1 : 1+v3SaltSize]
 		sealed := blob[1+v3SaltSize:]
 		key := deriveKeyWithSaltV3(passphrase, salt)
 		if plaintext, err := Decrypt(sealed, key); err == nil {
 			return plaintext, nil
 		}
 		// v3 AEAD failed. Fall through — could be a v2 blob whose first
 		// byte happens to be 0x03 (1/256), or a v1 nonce-prefix collision,
 		// or a wrong-passphrase v3.
 	}
 	// v2 path: M-8 — magic(0x02) || salt(16) || nonce(12) || ct+tag.
 	// 100,000 PBKDF2 rounds.
 	if blob[0] == v2Magic && len(blob) >= 1+v2SaltSize+12 {
 		salt := blob[1 : 1+v2SaltSize]
 		sealed := blob[1+v2SaltSize:]
@@ -280,14 +347,16 @@ func DecryptIfKeySet(blob []byte, passphrase string) ([]byte, error) {
 		if plaintext, err := Decrypt(sealed, key); err == nil {
 			return plaintext, nil
 		}
-		// v2 AEAD verification failed. Fall through to v1 so that a v1 blob
+		// v2 AEAD failed. Fall through to v1.
 		// whose first byte happens to be 0x02 (1/256 probability) is still
 		// decryptable. If this is truly a v2 blob with the wrong passphrase,
 		// the v1 attempt below will also fail and the v1 error is returned.
 	}
 	// v1 legacy path: blob is the full ciphertext with no header and was
-	// sealed with a key derived from (passphrase, legacyV1Salt).
+	// sealed with a key derived from (passphrase, legacyV1Salt) at 100k
 	// rounds. If both v2/v3 attempts above failed and this also fails, the
 	// returned error is the v1 attempt's error — which is the most likely
 	// "wrong passphrase" surface for an operator on a recent install (no
 	// pre-M-8 v1 rows, so the first two paths are the actual write format
 	// and only v1 has a chance to surface a meaningful error).
 	key := DeriveKey(passphrase)
 	return Decrypt(blob, key)
 }
@@ -309,21 +309,23 @@ func TestDeriveKey_DifferentSaltsProduceDifferentKeys(t *testing.T) {
 // TestEncryptIfKeySet_ProducesV2Format asserts the exact v2 wire-format bytes:
 // magic(0x02) || salt(16) || nonce(12) || ciphertext+tag.
-func TestEncryptIfKeySet_ProducesV2Format(t *testing.T) {
+// TestEncryptIfKeySet_ProducesV3Format pins the Bundle B / M-001 write
 // path: every fresh blob carries magic byte 0x03 and the v3 layout.
 func TestEncryptIfKeySet_ProducesV3Format(t *testing.T) {
 	blob, _, err := EncryptIfKeySet([]byte("hello"), "any-passphrase")
 	if err != nil {
 		t.Fatalf("EncryptIfKeySet failed: %v", err)
 	}
-	const minLen = 1 + v2SaltSize + 12 + 16 // magic + salt + nonce + GCM tag (16)
+	const minLen = 1 + v3SaltSize + 12 + 16 // magic + salt + nonce + GCM tag (16)
 	if len(blob) < minLen {
-		t.Fatalf("v2 blob too short: got %d, want >= %d", len(blob), minLen)
+		t.Fatalf("v3 blob too short: got %d, want >= %d", len(blob), minLen)
 	}
-	if blob[0] != v2Magic {
+	if blob[0] != v3Magic {
-		t.Fatalf("v2 blob must start with magic byte 0x%02x, got 0x%02x", v2Magic, blob[0])
+		t.Fatalf("v3 blob must start with magic byte 0x%02x, got 0x%02x", v3Magic, blob[0])
 	}
 	if IsLegacyFormat(blob) {
-		t.Fatal("IsLegacyFormat must return false for a freshly produced v2 blob")
+		t.Fatal("IsLegacyFormat must return false for a freshly produced v3 blob")
 	}
 }
@@ -342,13 +344,13 @@ func TestEncryptIfKeySet_SaltIsRandom(t *testing.T) {
 		t.Fatalf("EncryptIfKeySet #2 failed: %v", err)
 	}
-	salt1 := blob1[1 : 1+v2SaltSize]
+	salt1 := blob1[1 : 1+v3SaltSize]
-	salt2 := blob2[1 : 1+v2SaltSize]
+	salt2 := blob2[1 : 1+v3SaltSize]
 	if bytes.Equal(salt1, salt2) {
 		t.Fatal("two EncryptIfKeySet invocations must produce distinct per-ciphertext salts")
 	}
 	if bytes.Equal(blob1, blob2) {
-		t.Fatal("two v2 blobs with same (passphrase, plaintext) must differ end-to-end")
+		t.Fatal("two v3 blobs with same (passphrase, plaintext) must differ end-to-end")
 	}
 }
@@ -0,0 +1,167 @@
 package crypto
 import (
 	"bytes"
 	"crypto/aes"
 	"crypto/cipher"
 	"testing"
 )
 // Bundle B / Audit M-001 (CWE-916 / OWASP 2024) regression suite.
 //
 // The on-disk blob format is now versioned three ways:
 //   v1 — pre-M-8, fixed-salt, 100k PBKDF2 rounds
 //   v2 — M-8, per-ciphertext salt, 100k rounds, magic 0x02
 //   v3 — Bundle B, per-ciphertext salt, 600k rounds, magic 0x03 (current)
 //
 // EncryptIfKeySet always emits v3. DecryptIfKeySet must accept all three
 // in order v3 → v2 → v1 with AEAD-fallback so wrong-passphrase v3 blobs
 // don't get incorrectly attributed to v1. These tests pin every arm.
 // TestEncryptIfKeySet_V3RoundTrip pins the happy-path round trip under v3.
 func TestEncryptIfKeySet_V3RoundTrip(t *testing.T) {
 	plaintext := []byte(`{"api_key":"acme-prod-2026","scope":"issuer"}`)
 	passphrase := "test-passphrase-bundleB"
 	blob, ok, err := EncryptIfKeySet(plaintext, passphrase)
 	if err != nil {
 		t.Fatalf("EncryptIfKeySet: %v", err)
 	}
 	if !ok {
 		t.Fatal("ok must be true on success")
 	}
 	if blob[0] != v3Magic {
 		t.Fatalf("first byte must be v3Magic 0x%02x, got 0x%02x", v3Magic, blob[0])
 	}
 	got, err := DecryptIfKeySet(blob, passphrase)
 	if err != nil {
 		t.Fatalf("DecryptIfKeySet: %v", err)
 	}
 	if !bytes.Equal(got, plaintext) {
 		t.Fatalf("round trip mismatch: got %q want %q", got, plaintext)
 	}
 }
 // TestDecryptIfKeySet_V2BlobReadFallback constructs a deterministic v2
 // blob using the v1/v2 PBKDF2 work factor and asserts DecryptIfKeySet
 // still reads it correctly (read-time backward compat, no in-place
 // re-encrypt).
 func TestDecryptIfKeySet_V2BlobReadFallback(t *testing.T) {
 	passphrase := "v2-era-passphrase"
 	plaintext := []byte(`{"legacy":"v2"}`)
 	// Hand-build a v2 blob: magic(0x02) || salt(16) || nonce(12) || ct+tag.
 	salt := bytes.Repeat([]byte{0xAB}, v2SaltSize)
 	key := deriveKeyWithSalt(passphrase, salt) // 100k rounds
 	block, err := aes.NewCipher(key)
 	if err != nil {
 		t.Fatalf("aes.NewCipher: %v", err)
 	}
 	gcm, err := cipher.NewGCM(block)
 	if err != nil {
 		t.Fatalf("cipher.NewGCM: %v", err)
 	}
 	nonce := bytes.Repeat([]byte{0xCD}, gcm.NonceSize())
 	inner := gcm.Seal(nonce, nonce, plaintext, nil)
 	v2Blob := make([]byte, 0, 1+v2SaltSize+len(inner))
 	v2Blob = append(v2Blob, v2Magic)
 	v2Blob = append(v2Blob, salt...)
 	v2Blob = append(v2Blob, inner...)
 	got, err := DecryptIfKeySet(v2Blob, passphrase)
 	if err != nil {
 		t.Fatalf("DecryptIfKeySet must read v2 blob: %v", err)
 	}
 	if !bytes.Equal(got, plaintext) {
 		t.Fatalf("v2 round-trip mismatch: got %q want %q", got, plaintext)
 	}
 }
 // TestDecryptIfKeySet_V3WrongPassphraseFails ensures a wrong passphrase
 // against a v3 blob does NOT silently succeed via the v2/v1 fallback.
 func TestDecryptIfKeySet_V3WrongPassphraseFails(t *testing.T) {
 	plaintext := []byte("secret")
 	blob, _, err := EncryptIfKeySet(plaintext, "correct-pw")
 	if err != nil {
 		t.Fatal(err)
 	}
 	if _, err := DecryptIfKeySet(blob, "wrong-pw"); err == nil {
 		t.Fatal("decrypt with wrong passphrase must fail; got nil error")
 	}
 }
 // TestDecryptIfKeySet_V2MagicCollisionWithV3Header pins the AEAD-fallback
 // behavior: a fresh v3 blob whose first byte happens to be 0x02 (would
 // only occur if v3Magic were 0x02 — it is not, but the dispatch must
 // still be robust). We exercise the inverse case explicitly: a real v2
 // blob is correctly read after the v3 attempt fails.
 func TestDecryptIfKeySet_V3VsV2DispatchOrder(t *testing.T) {
 	// Construct a v2 blob whose first byte is v3Magic by forcing the
 	// magic-byte choice. This simulates the 1/256 case where a hostile
 	// or coincidental nonce-prefix collision would otherwise mis-route.
 	passphrase := "ambiguous-pw"
 	plaintext := []byte("payload")
 	salt := bytes.Repeat([]byte{0xFE}, v2SaltSize)
 	key := deriveKeyWithSalt(passphrase, salt)
 	block, err := aes.NewCipher(key)
 	if err != nil {
 		t.Fatalf("aes.NewCipher: %v", err)
 	}
 	gcm, err := cipher.NewGCM(block)
 	if err != nil {
 		t.Fatalf("cipher.NewGCM: %v", err)
 	}
 	nonce := bytes.Repeat([]byte{0xCD}, gcm.NonceSize())
 	inner := gcm.Seal(nonce, nonce, plaintext, nil)
 	// Manually splice: magic(0x02) is correct for v2.
 	v2Blob := append([]byte{v2Magic}, salt...)
 	v2Blob = append(v2Blob, inner...)
 	got, err := DecryptIfKeySet(v2Blob, passphrase)
 	if err != nil {
 		t.Fatalf("v2 blob must be readable: %v", err)
 	}
 	if !bytes.Equal(got, plaintext) {
 		t.Fatalf("v2 fallback mismatch: got %q want %q", got, plaintext)
 	}
 }
 // TestDeriveKeyWithSaltV3_DistinctFromV2 sanity-checks that v2 and v3
 // derive distinct keys for the same (passphrase, salt) — a regression
 // here would mean the iteration count was accidentally identical.
 func TestDeriveKeyWithSaltV3_DistinctFromV2(t *testing.T) {
 	passphrase := "any"
 	salt := bytes.Repeat([]byte{0x42}, 16)
 	v2Key := deriveKeyWithSalt(passphrase, salt)
 	v3Key := deriveKeyWithSaltV3(passphrase, salt)
 	if bytes.Equal(v2Key, v3Key) {
 		t.Fatal("v2 and v3 keys must differ for the same (passphrase, salt) — work factor must differ")
 	}
 }
 // TestPBKDF2Iterations_V3IsOWASP2024Floor pins the iteration count at the
 // OWASP 2024 floor of 600,000. If a future change lowers this number,
 // the test must fail so the change requires an explicit audit-trail
 // update to BOTH the constant AND this assertion.
 func TestPBKDF2Iterations_V3IsOWASP2024Floor(t *testing.T) {
 	const owasp2024MinIterations = 600000
 	if pbkdf2IterationsV3 < owasp2024MinIterations {
 		t.Fatalf("pbkdf2IterationsV3 = %d, below OWASP 2024 floor of %d (Bundle B / M-001 / CWE-916)",
 			pbkdf2IterationsV3, owasp2024MinIterations)
 	}
 }
 // TestIsLegacyFormat_V3IsNotLegacy pins the helper's contract: a v3 blob
 // (magic 0x03) is NOT legacy.
 func TestIsLegacyFormat_V3IsNotLegacy(t *testing.T) {
 	v3Blob, _, err := EncryptIfKeySet([]byte("x"), "p")
 	if err != nil {
 		t.Fatal(err)
 	}
 	if IsLegacyFormat(v3Blob) {
 		t.Fatal("a v3 blob must NOT report as legacy")
 	}
 }