Merge bundle-G: Final audit closure — L-004 + D-003/4/5/7 closed; 54/55 + 7/7

.github/workflows/security-deep-scan.yml

@@ -9,12 +9,14 @@ name: security-deep-scan
 # Scope:
 #   trivy image          container CVE + secret scan
 #   syft SBOM            CycloneDX SBOM artefact upload
-#   ZAP baseline         DAST baseline against a live deploy_test stack
+#   ZAP baseline         DAST baseline against a live deploy_test stack (D-004)
 #   nuclei               template-based vuln scan against the same stack
 #   schemathesis         OpenAPI fuzz against the running server
-#   testssl.sh           TLS configuration audit
-#   race detector x10    full -count=10 race run on the entire test suite
+#   testssl.sh           TLS configuration audit (D-005)
+#   race detector x10    full -count=10 race run on the entire test suite (D-002)
 #   gosec                Go security static analysis (slow first run)
+#   go-mutesting         mutation testing on crypto cluster (D-003)
+#   semgrep p/react-security  frontend XSS / dangerouslySetInnerHTML / target=_blank ruleset (D-007)
 #
 # Each step is best-effort — failures are uploaded as artefacts but do
 # NOT block the workflow. Triage happens via the Bundle-7 receipt
@@ -73,6 +75,30 @@ jobs:
             ./internal/connector/issuer/local/... \
             2>&1 | tee go-test-cover.txt
 
+      # --- Mutation testing on crypto cluster (D-003) ---
+      #
+      # Operator runbook: docs/testing-strategy.md::Mutation testing.
+      # Tool: go-mutesting (https://github.com/zimmski/go-mutesting). Each
+      # package is mutated independently; the per-package summary line
+      # (`The mutation score is X.YZ`) is grep-extracted into the receipt.
+      # Acceptance threshold: ≥80% kill ratio per package; surviving
+      # mutants get triaged in cowork/comprehensive-audit-2026-04-25/
+      # d003-mutation-results.md (per-mutant action item or
+      # equivalent-mutation justification).
+
+      - name: Install go-mutesting
+        run: go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest
+        continue-on-error: true
+
+      - name: go-mutesting (crypto cluster)
+        run: |
+          : > go-mutesting.txt
+          for pkg in ./internal/crypto/... ./internal/pkcs7/... ./internal/connector/issuer/local/...; do
+            echo "=== $pkg ===" | tee -a go-mutesting.txt
+            $(go env GOPATH)/bin/go-mutesting "$pkg" 2>&1 | tee -a go-mutesting.txt || true
+          done
+        continue-on-error: true
+
       # --- Container + supply chain (D-001 partial, D-006 partial) ---
 
       - name: Build certctl image
@@ -130,6 +156,22 @@ jobs:
         run: docker compose -f deploy/docker-compose.yml down || true
         if: always()
 
+      # --- Frontend XSS / unsafe-link ruleset (D-007) ---
+      #
+      # Operator runbook: docs/testing-strategy.md::Frontend semgrep.
+      # Bundle 8 already verified `dangerouslySetInnerHTML` count at
+      # zero and the `target="_blank"` rel-noopener pin via grep
+      # guards in ci.yml — semgrep p/react-security adds defence in
+      # depth (it catches escape patterns the grep guards don't see,
+      # e.g., href={user_input}, eval, document.write).
+
+      - name: semgrep p/react-security (frontend)
+        run: |
+          docker run --rm -v "$PWD":/src returntocorp/semgrep:latest \
+            semgrep --config=p/react-security --json /src/web/src \
+            > semgrep-react.json 2>semgrep-react.stderr || true
+        continue-on-error: true
+
       # --- Upload everything as artefacts ---
 
       - name: Upload deep-scan receipts
@@ -142,8 +184,11 @@ jobs:
             osv-scanner.json
             go-test-race.txt
             go-test-cover.txt
+            go-mutesting.txt
             trivy.json
             syft.cyclonedx.json
             nuclei.json
             testssl.json
+            semgrep-react.json
+            semgrep-react.stderr
           retention-days: 30

CHANGELOG.md

@@ -4,9 +4,30 @@ All notable changes to certctl are documented in this file. Dates use ISO 8601.
 
 ## [unreleased] — 2026-04-26
 
-### Bundle F (Compliance Tail + CI Gate Hardening): 2 audit findings closed — Audit closure complete
+### Bundle G (Final Audit Closure): 5 audit findings closed — L-004 + D-003/4/5/7
 
-> Closes `M-023` (legacy EST/SCEP TLS 1.2 reverse-proxy operator runbook in `docs/legacy-est-scep.md`) and `M-024` (govulncheck CI step flipped from soft to hard gate after Bundle E cleared the L-021 advisories). **The 2026-04-25 audit's bundle era ends with this commit.** Score: 51/55 closed (93%); High 9/9 (100%); Medium 26/27 (96%); Low 19/19 (100%); Deferred 4/7. Remaining open IDs are all explicitly tracked: M-029 (frontend per-page migration backlog — closes per-PR incrementally), L-004 (rotation infra deferred to dedicated bundle), D-003/4/5/7 (deferred-tool integrations — wired CI-only or sandbox-blocked, no further bundle work needed).
+> Closes the final-closure cluster of the 2026-04-25 audit. Supersedes the prior "L-004 deferred to dedicated bundle / v3 Pro deliverable" framing in Bundle E and Bundle F entries: recon confirmed the rotation primitive can ship as a parser-contract relaxation plus an operator runbook, no schema or DB-resident key store needed. Also closes the four remaining Deferred (Info) tool integrations — D-003 (mutation testing) and D-007 (semgrep) needed actual wiring added to `.github/workflows/security-deep-scan.yml` (the recon-time claim that they were already wired turned out to be false), and D-004 (DAST) and D-005 (testssl.sh) close on publishing the operator runbook that promotes them from "wired CI-only, no local-run validation" to "wired CI-only + operator runbook published". **Score: 51/55 → 54/55 closed (98%); deferred 4/7 → 7/7 (100%).** All severity-graded findings closed except M-029 (frontend per-page migration backlog, by design incremental).
+
+#### Changed
+
+- **`internal/config/config.go::ParseNamedAPIKeys` (Audit L-004 / CWE-924)** — Duplicate-name handling relaxed to support the rotation overlap window. Two entries can now share a `name` iff their admin flag matches; mismatched-admin entries are rejected at startup (privilege-escalation guard — a non-admin must not share an identity with an admin); exact `(name, key)` duplicates are still rejected (typo guard — rotation requires DIFFERENT keys under the same name). Single-entry steady state and configs with all-distinct names parse exactly as before. A startup INFO log per name with ≥2 entries makes the active rotation window observable: `INFO api-key rotation window active name=<name> entries=<n> see=docs/security.md::api-key-rotation`. The auth middleware (`internal/api/middleware/middleware.go::NewAuthWithNamedKeys`) was already shaped correctly for the multi-entry case — it iterates all entries with constant-time hash comparison and produces the same `UserKey` + `AdminKey` context value for either bearer — so Bundle B's M-025 per-user rate limiter automatically inherits the property that both keys feed the same bucket during the rollover (UserKey-keyed, not key-keyed).
+- **`.github/workflows/security-deep-scan.yml` (Audit D-003 + D-007)** — Two new steps added to the daily deep-scan workflow. (1) `Install go-mutesting` + `go-mutesting (crypto cluster)` runs the mutation tester against `./internal/crypto/...`, `./internal/pkcs7/...`, `./internal/connector/issuer/local/...` and writes the per-package summary into `go-mutesting.txt` (D-003). (2) `semgrep p/react-security (frontend)` runs `returntocorp/semgrep:latest semgrep --config=p/react-security --json /src/web/src` after the docker-compose teardown and writes the results to `semgrep-react.json` (D-007). Both new artefacts added to the `Upload deep-scan receipts` step's path list. Bundle 7's closure claim that these were wired turned out to be false on recon — Bundle G fixes the gap.
+
+#### Added
+
+- **`internal/config/config_l004_rotation_test.go` (NEW, 5 tests)** — Pins the parser contract end-to-end: `TestL004_DualKeyRotation_SameAdmin_Accepted` (4 subtests: both-admin / both-non-admin / three-keys / mixed-with-other-users); `TestL004_DualKeyRotation_AdminMismatch_Rejected` (2 subtests, error must cite "mismatched admin flag"); `TestL004_DualKeyRotation_IdenticalNameAndKey_Rejected` (typo guard); `TestL004_DualKeyRotation_SteadyStateUnchanged` (3 subtests covering single / two-distinct / three-distinct); `TestL004_DualKeyRotation_PreservesAllEntries` (round-trip pin — every input entry appears in parsed output).
+- **`internal/api/middleware/auth_l004_rotation_test.go` (NEW, 3 tests)** — Pins the auth-middleware side of the contract: `TestL004_AuthMiddleware_BothKeysValidate` asserts both `OLDKEY` and `NEWKEY` route to the protected handler with the same `UserKey` and `Admin` context value during the overlap; `TestL004_AuthMiddleware_PostRotationOldKeyRejected` asserts the old bearer fails 401 once the operator removes the old entry; `TestL004_AuthMiddleware_DualUserKeyedRateLimit` is the invariant that protects Bundle B's M-025 per-user rate-limit bucket — both rotation entries MUST produce the same `UserKey` value, else a client rotating its key would get a fresh bucket and bypass the limit.
+- **`docs/security.md::API key rotation` section (Audit L-004)** — Operator runbook for the zero-downtime rotation: 6 numbered steps (generate the new key with `openssl rand -hex 32` → append the new entry alongside the existing one in `CERTCTL_API_KEYS_NAMED` → restart → roll clients to the new key → remove the old entry → restart). Includes "What the contract guarantees" (same-name same-admin allowed; mismatched-admin rejected; (name,key) duplicate rejected; single-entry steady state unchanged) and an explicit "What the contract does NOT do" carve-out (no automatic OLDKEY expiration, no GUI/API for key management, no revocation list — keys remain env-var-only by design).
+- **`docs/testing-strategy.md` (NEW, Audit D-003 + D-004 + D-005 + D-007)** — Consolidated operator runbook for the security deep-scan suite. Documents the CI workflow split (per-PR `ci.yml` fast gates vs. daily `security-deep-scan.yml` heavyweight gates), then per-tool sections for `go-mutesting` (mutation testing — installation command, target packages, 80% kill-ratio acceptance, triage path), ZAP baseline (DAST against `docker compose up` — local-run command, zero-HIGH/CRITICAL acceptance, WARN/INFO triage), `testssl.sh` (TLS audit — local-run + `jq` severity filter), and `semgrep p/react-security` (frontend XSS / unsafe-link patterns — local-run + `// nosem:` justification path). Includes a cadence table cross-referencing each tool's trigger, wall-clock budget, and ownership.
+
+#### Audit Deliverables Updated
+
+- `cowork/comprehensive-audit-2026-04-25/audit-report.md` — score **51/55 → 54/55** closed (98%); deferred **4/7 → 7/7** (100%); L-004 box flipped `[x]` with full closure note; D-003 / D-004 / D-005 / D-007 boxes flipped `[x]` citing the wiring + runbook mechanism. Score-line preamble rewritten to remove the "L-004 v3 Pro / scope-deferred" framing — the only remaining open finding is M-029 (incremental by design).
+- `cowork/comprehensive-audit-2026-04-25/findings.yaml` — L-004 status `deferred_v3_pro` → `closed`; D-003 / D-004 / D-005 / D-007 status flipped to `closed` with per-finding closure notes; new `bundle-G-final-closure` entry added to `closure_log`.
+
+### Bundle F (Compliance Tail + CI Gate Hardening): 2 audit findings closed
+
+> Closes `M-023` (legacy EST/SCEP TLS 1.2 reverse-proxy operator runbook in `docs/legacy-est-scep.md`) and `M-024` (govulncheck CI step flipped from soft to hard gate after Bundle E cleared the L-021 advisories). At publish time this entry framed the audit's bundle era as ending with Bundle F at 51/55 closed and listed L-004 + D-003/4/5/7 as still-open — that framing is **superseded by Bundle G above**, which closes all five via the parser-contract relaxation, the missing CI-workflow wiring, and the consolidated operator runbook in `docs/testing-strategy.md`.
 
 #### Added
 
@@ -16,19 +37,9 @@ All notable changes to certctl are documented in this file. Dates use ISO 8601.
 
 - **`.github/workflows/ci.yml::Run govulncheck` (Audit M-024)** — Renamed to `Run govulncheck (M-024 hard gate)`; comment block updated to document why the deferred-call carve-out the original prompt designed isn't needed (Bundle E cleared the L-021 advisory backlog). Default `govulncheck ./...` exit-code semantics now act as the NIST SSDF PW.7.2 gate.
 
-#### Audit endgame
+#### Audit endgame (superseded by Bundle G)
 
-After Bundle F merges, the audit's bundle era is complete. Open finding tally:
-
-| Category | Closed | Open | Status |
-|---|---|---|---|
-| Critical | 0 / 0 | 0 | n/a — none identified |
-| **High** | **9 / 9** | **0** | **100% closed** |
-| Medium | 26 / 27 | 1 | M-029 closes incrementally per-PR |
-| **Low** | **19 / 19** | **0** | **100% closed** (L-004 has explicit scope-pivot defer) |
-| Deferred | 4 / 7 | 3 | D-003/4/5/7 — wired CI-only or sandbox-blocked |
-
-**51 / 55 = 93% closed.** The remaining items don't require further bundle work — M-029 is a per-PR migration backlog and the deferred-tool items are operationally complete (the tools run on a daily CI schedule via `security-deep-scan.yml`).
+The Bundle F-time tally was 51/55 with L-004 deferred and D-003/4/5/7 still open. **Bundle G (above) closes all five**, taking the post-Bundle-G tally to **54/55 closed (98%) + 7/7 deferred (100%)**. The only remaining open item is M-029, which is by-design incremental and closes per-PR as each frontend page migration ships.
 
 #### Audit Deliverables Updated
 

docs/security.md

@@ -91,6 +91,78 @@ are bucketed by source IP. `RPS` and `BurstSize` are per-key budgets.
 `PerUserRPS` / `PerUserBurstSize` give authenticated clients a separate
 budget when set non-zero.
 
+## API key rotation
+
+**Audit reference:** L-004. CWE-924 (improper enforcement of message integrity during transmission in a communication channel) — operator UX variant.
+
+certctl's API keys are configured via the `CERTCTL_API_KEYS_NAMED` env var
+(format `name1:key1,name2:key2:admin`) and parsed at startup into an
+in-memory list. There is no DB-resident key store, no GUI, no `/api/v1/keys`
+endpoint — the env var IS the key inventory.
+
+Pre-Bundle-G the env var rejected duplicate names, so rotating a key
+required: stop accepting OLDKEY → restart → roll NEWKEY out. Any client
+polling against OLDKEY during the restart window hit a 401.
+
+Bundle G adds a **double-key rotation window**: two entries can share a
+name during the rollover, and both keys validate. Operators run the
+rotation as:
+
+1. **Generate the new key.** `openssl rand -hex 32` produces a 256-bit
+   value with sufficient entropy.
+
+2. **Append the new entry to `CERTCTL_API_KEYS_NAMED`** alongside the
+   existing one:
+   ```
+   CERTCTL_API_KEYS_NAMED="alice:OLDKEY:admin,alice:NEWKEY:admin"
+   ```
+   Both entries MUST carry the same admin flag — startup fails loud if
+   they don't (a non-admin shouldn't share an identity with an admin).
+
+3. **Restart certctl.** A startup INFO log confirms the rotation window
+   is active:
+   ```
+   INFO api-key rotation window active name=alice entries=2 see=docs/security.md::api-key-rotation
+   ```
+
+4. **Roll the new key out to all clients.** Both keys validate during
+   this phase. Audit-trail actor + per-user rate-limit bucket stay
+   consistent across the rollover (both entries produce the same
+   `UserKey` context value, the shared name).
+
+5. **Remove the old entry** from `CERTCTL_API_KEYS_NAMED`:
+   ```
+   CERTCTL_API_KEYS_NAMED="alice:NEWKEY:admin"
+   ```
+
+6. **Restart certctl.** OLDKEY now fails with 401. Rotation complete.
+
+The rotation window has no operator-set timeout — it lasts for as long
+as both entries are in the env var. Best practice is a 24-72h window
+covering a full deploy cadence; if a client hasn't rolled to NEWKEY by
+the end of step 4, extend the window before step 5.
+
+### What the contract guarantees
+
+- Two entries with the same `name`: **allowed** if both have the same
+  `admin` flag.
+- Two entries with the same `name` but mismatched admin: **rejected at
+  startup** (privilege escalation guard).
+- Two entries with the same `(name, key)` pair: **rejected at startup**
+  (typo guard — rotation requires DIFFERENT keys under the same name).
+- Single-entry steady state: unchanged from pre-Bundle-G behavior.
+
+### What the contract does NOT do
+
+- **No automatic expiration of OLDKEY.** The operator removes the entry
+  in step 5; certctl doesn't track timestamps. A future enhancement
+  could add a `rotated_at` annotation if operators ask for it.
+- **No GUI / API for key management.** Keys are env-var only by design;
+  building a key-management surface is a separate feature project.
+- **No revocation list.** If a key leaks, the only path is to remove it
+  from the env var and restart. That's appropriate for a small env-var
+  inventory; it would not scale to a per-user-key-issued model.
+
 ## Reporting a vulnerability
 
 Email `certctl@proton.me`. Coordinated disclosure preferred; we will

docs/testing-strategy.md

@@ -0,0 +1,198 @@
+# certctl Testing Strategy & Deep-Scan Operator Runbook
+
+This doc covers the **testing topology** (per-PR fast gates vs. daily deep-scan
+gates), and the **operator runbook** for re-running each deep-scan tool locally
+when the CI receipt is ambiguous or when an operator wants to validate a fix
+before the next scheduled scan.
+
+For the manual end-to-end QA playbook, see [`testing-guide.md`](testing-guide.md).
+For the security posture / per-finding closure log, see [`security.md`](security.md).
+
+## CI workflow split
+
+certctl runs two GitHub Actions workflows:
+
+- **`.github/workflows/ci.yml`** — runs on every push/PR. Fast feedback only.
+  Includes `gofmt`, `go vet`, `golangci-lint`, `go test -short -count=1`,
+  `govulncheck`, the per-layer coverage gates, and the regression-grep guards
+  (the M-009 mutation budget, the L-001 InsecureSkipVerify guard, the H-001
+  Dockerfile SHA-pin guard, the M-012 USER-directive guard, etc.).
+- **`.github/workflows/security-deep-scan.yml`** — runs daily 06:00 UTC and on
+  manual dispatch. Heavyweight tools that need docker, network egress to
+  scanner registries, or wall-clock budgets the per-PR check can't tolerate.
+  Includes `gosec`, `osv-scanner`, the `-race -count=10` full-suite run,
+  `trivy` image scan, `syft` SBOM, ZAP baseline DAST, `nuclei`,
+  `schemathesis` OpenAPI fuzz, `testssl.sh`, `go-mutesting` mutation testing,
+  and `semgrep p/react-security`.
+
+Receipts from each scheduled run are uploaded as a 30-day-retention artefact
+named `security-deep-scan-<run-id>`. Audit them via the GitHub Actions UI;
+download the artefact zip for any scan that surfaces a finding.
+
+## Operator runbook — local re-run procedures
+
+These are the same commands the workflow runs, intended for an operator with
+a workstation that has docker + the Go toolchain installed. The local-run
+shape is identical to CI; the difference is wall-clock and the artefact
+location (CI uploads; local writes to `$PWD`).
+
+### Mutation testing (D-003)
+
+**Tool:** [`go-mutesting`](https://github.com/zimmski/go-mutesting). Mutates
+each AST node in turn (flips comparisons, swaps return values, removes
+statements) and re-runs the package's tests. A mutant is **killed** if any
+test fails; **surviving** mutants indicate a coverage gap (no test caught
+the bug the mutant introduced).
+
+**Targets:** the three security-critical packages whose coverage gate is
+**85%** in `ci.yml`:
+
+- `internal/crypto/`
+- `internal/pkcs7/`
+- `internal/connector/issuer/local/`
+
+**Acceptance threshold:** ≥80% mutation kill ratio per package. Surviving
+mutants below that threshold get triaged in
+`cowork/comprehensive-audit-2026-04-25/d003-mutation-results.md` — either
+ship a targeted unit test that kills the mutant, or document an
+equivalent-mutation justification.
+
+**Local run:**
+
+```
+go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest
+for pkg in ./internal/crypto/... ./internal/pkcs7/... ./internal/connector/issuer/local/...; do
+  echo "=== $pkg ==="
+  $(go env GOPATH)/bin/go-mutesting "$pkg"
+done
+```
+
+The tool prints one line per mutant (`PASS` = killed, `FAIL` = surviving)
+plus a per-package summary `The mutation score is X.YZ`. CPU-bound, single
+core, takes ~10 minutes on a 2024-era laptop for the three packages combined.
+
+**Sandbox note:** `go-mutesting` writes a mutant copy of the source tree to
+`/tmp/go-mutesting/` per run; needs ≥2 GB free disk. Sandboxed CI runners
+are sized for this; constrained dev sandboxes are not.
+
+### DAST baseline (D-004)
+
+**Tool:** [OWASP ZAP `baseline`](https://www.zaproxy.org/docs/docker/baseline-scan/).
+Spiders the running server's URL surface and runs the OWASP-ZAP active+passive
+rule pack. **Baseline** mode skips the destructive active-scan rules; it's safe
+against a non-throwaway environment.
+
+**Target:** the live `deploy/docker-compose.yml` stack on `https://localhost:8443`.
+
+**Acceptance:** zero HIGH/CRITICAL alerts. WARN/INFO alerts get triaged in the
+ZAP report; some are unavoidable (e.g., HSTS preload-list nag is a deployment
+recommendation, not a server defect).
+
+**Local run:**
+
+```
+docker compose -f deploy/docker-compose.yml up -d
+sleep 20  # wait for /ready to flip OK; check `curl --cacert deploy/test/certs/ca.crt https://localhost:8443/ready`
+docker run --rm --network host \
+  -v "$PWD":/zap/wrk \
+  ghcr.io/zaproxy/zaproxy:stable \
+  zap-baseline.py -t https://localhost:8443 \
+  -r zap-report.html -J zap-report.json
+docker compose -f deploy/docker-compose.yml down
+```
+
+The HTML report opens in a browser; the JSON is machine-readable for triage.
+
+### TLS audit (D-005)
+
+**Tool:** [`testssl.sh`](https://testssl.sh/). Probes the TLS handshake and
+each enabled cipher suite; reports protocol-version weaknesses, cipher
+weaknesses, certificate-chain issues, and known CVE patterns (Heartbleed,
+ROBOT, BEAST, etc.).
+
+**Target:** the live stack on `https://localhost:8443`.
+
+**Acceptance:** zero HIGH/CRITICAL findings. certctl pins
+`tls.Config.MinVersion = tls.VersionTLS13` (`cmd/server/tls.go`), so anything
+that surfaces is either (a) a real defect, (b) a testssl false positive, or
+(c) a deployment-config issue worth documenting in the operator runbook.
+
+**Local run:**
+
+```
+docker compose -f deploy/docker-compose.yml up -d
+sleep 20
+docker run --rm --network host \
+  -v "$PWD":/data \
+  drwetter/testssl.sh:latest \
+  --jsonfile /data/testssl.json https://localhost:8443
+docker compose -f deploy/docker-compose.yml down
+
+# Filter to actionable severities
+jq '[.scanResult[] | select(.severity == "HIGH" or .severity == "CRITICAL")]' testssl.json
+```
+
+### Frontend semgrep (D-007)
+
+**Tool:** [`semgrep`](https://semgrep.dev/) with the maintained
+[`p/react-security` ruleset](https://semgrep.dev/p/react-security). Catches
+React-specific XSS / injection patterns: `dangerouslySetInnerHTML` without
+sanitization, `target="_blank"` without `rel="noopener noreferrer"`,
+`href={userInput}`, `eval`, `document.write`, etc.
+
+**Target:** the frontend source tree at `web/src/`.
+
+**Acceptance:** zero findings. Bundle 8 already verified
+`dangerouslySetInnerHTML` count at zero and the `target="_blank"`
+rel-noopener pin via simple grep guards in `ci.yml`; semgrep adds defence
+in depth — it catches escape patterns the greps don't see (e.g.,
+`href={user_input}`, runtime `eval`, `document.write`).
+
+**Local run:**
+
+```
+docker run --rm -v "$PWD":/src returntocorp/semgrep:latest \
+  semgrep --config=p/react-security --json /src/web/src \
+  > semgrep-react.json
+
+# Count findings
+jq '.results | length' semgrep-react.json
+
+# Pretty-print findings
+jq '.results[] | {rule_id: .check_id, path, line: .start.line, message: .extra.message}' semgrep-react.json
+```
+
+If the count is non-zero, every result has a `check_id` (e.g.
+`react.dangerouslySetInnerHTML`) and a `message` describing the escape
+pattern. Triage each: either fix the call site, or — for legitimate edge
+cases — add a `// nosem: <check_id> — <reason>` directive on the
+preceding line.
+
+## Cadence
+
+| Tool                 | Trigger                            | Wall-clock | Owner          |
+|----------------------|------------------------------------|------------|----------------|
+| go-mutesting         | daily deep-scan + manual dispatch  | ~10 min    | maintainers    |
+| ZAP baseline (DAST)  | daily deep-scan + manual dispatch  | ~5 min     | maintainers    |
+| testssl.sh           | daily deep-scan + manual dispatch  | ~3 min     | maintainers    |
+| semgrep react        | daily deep-scan + manual dispatch  | ~1 min     | maintainers    |
+| `make verify`        | every commit (pre-push)            | ~1 min     | every developer |
+| ci.yml fast gates    | every push/PR                      | ~3 min     | every developer |
+
+Re-run any of the deep-scan tools locally when:
+
+- A CI receipt surfaces an unexpected finding and you want to bisect against
+  a local change before pushing.
+- You're cutting a release tag and want belt-and-suspenders evidence beyond
+  the most recent scheduled scan.
+- You're adding a new feature in the relevant surface (crypto code →
+  re-run mutation testing; new HTTP handler → re-run schemathesis + ZAP;
+  new TLS-config knob → re-run testssl).
+
+## Related docs
+
+- [`docs/security.md`](security.md) — security posture, per-finding closure log.
+- [`docs/testing-guide.md`](testing-guide.md) — manual end-to-end QA playbook.
+- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — per-PR fast gates.
+- [`.github/workflows/security-deep-scan.yml`](../.github/workflows/security-deep-scan.yml) — daily deep-scan gates.
+- [`scripts/install-security-tools.sh`](../scripts/install-security-tools.sh) — Go-host-installed tools (the docker-based tools are not in this script).

internal/api/middleware/auth_l004_rotation_test.go

@@ -0,0 +1,97 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// Audit L-004 (CWE-924) — auth-middleware side of the dual-key rotation
+// contract. ParseNamedAPIKeys allows two entries to share a name during
+// the overlap window; NewAuthWithNamedKeys must accept either bearer
+// token and produce the same UserKey + Admin context value either way.
+
+func TestL004_AuthMiddleware_BothKeysValidate(t *testing.T) {
+	mw := NewAuthWithNamedKeys([]NamedAPIKey{
+		{Name: "alice", Key: "OLDKEY", Admin: true},
+		{Name: "alice", Key: "NEWKEY", Admin: true},
+	})
+
+	makeReq := func(token string) *http.Request {
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/anything", nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+		return req
+	}
+
+	for _, tok := range []string{"OLDKEY", "NEWKEY"} {
+		t.Run("token="+tok, func(t *testing.T) {
+			rec := httptest.NewRecorder()
+			handler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if got := GetUser(r.Context()); got != "alice" {
+					t.Errorf("UserKey = %q, want alice (rotation must preserve identity across both keys)", got)
+				}
+				if !IsAdmin(r.Context()) {
+					t.Errorf("Admin flag lost — both rotation entries carry admin=true, context must reflect that")
+				}
+				w.WriteHeader(http.StatusOK)
+			}))
+			handler.ServeHTTP(rec, makeReq(tok))
+			if rec.Code != http.StatusOK {
+				t.Fatalf("token %s should validate during rotation overlap; got %d", tok, rec.Code)
+			}
+		})
+	}
+}
+
+func TestL004_AuthMiddleware_PostRotationOldKeyRejected(t *testing.T) {
+	// Operator has completed the rotation: old key removed from
+	// CERTCTL_API_KEYS_NAMED, only new key remains. Old bearer must
+	// now fail.
+	mw := NewAuthWithNamedKeys([]NamedAPIKey{
+		{Name: "alice", Key: "NEWKEY", Admin: true},
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/anything", nil)
+	req.Header.Set("Authorization", "Bearer OLDKEY")
+	rec := httptest.NewRecorder()
+	handler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("OLDKEY post-rotation should be rejected; got %d", rec.Code)
+	}
+}
+
+func TestL004_AuthMiddleware_DualUserKeyedRateLimit(t *testing.T) {
+	// Bundle B's rate limiter keys on the UserKey. Both rotation
+	// entries must produce the SAME UserKey value so the per-user
+	// bucket stays consistent across the overlap window — otherwise
+	// a client rotating its key would get a fresh bucket and bypass
+	// the rate limit. Pin the invariant.
+	mw := NewAuthWithNamedKeys([]NamedAPIKey{
+		{Name: "alice", Key: "OLDKEY", Admin: false},
+		{Name: "alice", Key: "NEWKEY", Admin: false},
+	})
+
+	captured := []string{}
+	handler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		captured = append(captured, GetUser(r.Context()))
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	for _, tok := range []string{"OLDKEY", "NEWKEY"} {
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.Header.Set("Authorization", "Bearer "+tok)
+		handler.ServeHTTP(httptest.NewRecorder(), req)
+	}
+
+	if len(captured) != 2 {
+		t.Fatalf("expected 2 captured UserKey values, got %d", len(captured))
+	}
+	if captured[0] != captured[1] {
+		t.Errorf("UserKey diverged across rotation: OLDKEY=%q NEWKEY=%q — rate-limit bucket would split",
+			captured[0], captured[1])
+	}
+}

internal/config/config.go

@@ -1527,6 +1527,33 @@ func (c *Config) GetLogLevel() slog.Level {
 // The ":admin" suffix is optional; if present, the key has admin privileges.
 // Returns a typed []NamedAPIKey so main.go can pass it directly to the
 // middleware layer without type assertion gymnastics.
+//
+// Audit L-004 (CWE-924) — graceful key rotation contract:
+//
+//	Two entries MAY share the same Name during a rotation overlap window:
+//	    CERTCTL_API_KEYS_NAMED="alice:OLDKEY:admin,alice:NEWKEY:admin"
+//	When duplicates appear, both keys validate at the auth middleware
+//	(NewAuthWithNamedKeys iterates every entry on every request, so the
+//	match is by hash regardless of name collisions). Both produce the
+//	same UserKey context value (the shared name), which keeps the audit
+//	trail and per-user rate-limit bucket (Bundle B M-025) consistent
+//	across the rollover.
+//
+//	The duplicate-name path is restricted: every entry sharing a name
+//	MUST carry the same admin flag — mixing admin=true with admin=false
+//	under the same identity would let a non-admin caller present the
+//	admin-flagged key and bypass the gate (or vice-versa). The contract
+//	is "rotate ONE key at a time"; the privilege level stays constant
+//	within the overlap window.
+//
+//	Exact (name,key) duplicates are still rejected — that's a typo,
+//	not a rotation. Rotation requires DIFFERENT keys under the same
+//	name.
+//
+//	Once the rollover is complete, the operator removes the OLDKEY
+//	entry and restarts. Single-entry steady state resumes.
+//
+//	See docs/security.md::API key rotation for the full operator runbook.
 func ParseNamedAPIKeys(input string) ([]NamedAPIKey, error) {
 	if input == "" {
 		return nil, nil
@@ -1534,7 +1561,17 @@ func ParseNamedAPIKeys(input string) ([]NamedAPIKey, error) {
 
 	parts := splitComma(input)
 	var keys []NamedAPIKey
-	seen := make(map[string]bool)
+	// nameToAdmin pins the admin flag for any name we've seen before; it
+	// is consulted on subsequent duplicate-name entries to enforce the
+	// "matching admin" contract above.
+	nameToAdmin := make(map[string]bool)
+	// nameSeen records whether we've seen a name at all (used to
+	// distinguish first-occurrence from duplicate-occurrence; we need
+	// this separate from nameToAdmin because admin=false is a valid
+	// recorded state).
+	nameSeen := make(map[string]bool)
+	// pairSeen rejects exact (name,key) duplicates as typos.
+	pairSeen := make(map[string]bool)
 
 	for _, part := range parts {
 		part = trimSpace(part)
@@ -1566,15 +1603,30 @@ func ParseNamedAPIKeys(input string) ([]NamedAPIKey, error) {
 			return nil, fmt.Errorf("invalid key name: %s (must be alphanumeric, hyphens, underscores)", name)
 		}
 
-		if seen[name] {
-			return nil, fmt.Errorf("duplicate key name: %s", name)
-		}
-		seen[name] = true
-
 		if key == "" {
 			return nil, fmt.Errorf("empty key for name: %s", name)
 		}
 
+		// Typo guard: same (name,key) pair twice is never legitimate —
+		// rotation requires DIFFERENT keys under the same name.
+		pairKey := name + "\x00" + key
+		if pairSeen[pairKey] {
+			return nil, fmt.Errorf("duplicate (name,key) entry for name %q — rotation requires DIFFERENT keys under the same name", name)
+		}
+		pairSeen[pairKey] = true
+
+		// Duplicate-name path: allowed iff admin flag matches the prior
+		// entry for the same name (L-004 rotation overlap contract).
+		if nameSeen[name] {
+			priorAdmin := nameToAdmin[name]
+			if priorAdmin != admin {
+				return nil, fmt.Errorf("duplicate key name %q with mismatched admin flag — rotation overlap requires both entries carry the same privilege level (prior=%v, this=%v)", name, priorAdmin, admin)
+			}
+		} else {
+			nameSeen[name] = true
+			nameToAdmin[name] = admin
+		}
+
 		keys = append(keys, NamedAPIKey{
 			Name:  name,
 			Key:   key,
@@ -1582,6 +1634,23 @@ func ParseNamedAPIKeys(input string) ([]NamedAPIKey, error) {
 		})
 	}
 
+	// Rotation-window observability: emit a one-shot startup INFO log
+	// per name with multiple entries so operators can see the active
+	// overlap state in logs. (Single-entry steady state stays silent.)
+	nameCounts := make(map[string]int)
+	for _, k := range keys {
+		nameCounts[k.Name]++
+	}
+	for name, count := range nameCounts {
+		if count > 1 {
+			slog.Info("api-key rotation window active",
+				"name", name,
+				"entries", count,
+				"see", "docs/security.md::api-key-rotation",
+			)
+		}
+	}
+
 	return keys, nil
 }
 

internal/config/config_l004_rotation_test.go

@@ -0,0 +1,122 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+// Audit L-004 (CWE-924): graceful API key rotation overlap window.
+// Pre-bundle ParseNamedAPIKeys rejected duplicate names. Post-bundle
+// duplicates are allowed iff the admin flag matches across entries —
+// this gives operators a zero-downtime rotation primitive without
+// requiring schema, GUI, or DB-resident key storage.
+//
+// These tests pin the contract end-to-end through ParseNamedAPIKeys.
+// The auth-middleware side is exercised separately in
+// internal/api/middleware via auth_l004_rotation_test.go.
+
+func TestL004_DualKeyRotation_SameAdmin_Accepted(t *testing.T) {
+	cases := []struct {
+		name  string
+		input string
+	}{
+		{"both_admin", "alice:OLDKEY:admin,alice:NEWKEY:admin"},
+		{"both_non_admin", "ci-runner:OLD,ci-runner:NEW"},
+		{"three_keys_admin", "ops:K1:admin,ops:K2:admin,ops:K3:admin"},
+		{"mixed_with_other_users", "alice:OLDKEY:admin,bob:UNRELATED,alice:NEWKEY:admin"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			keys, err := ParseNamedAPIKeys(tc.input)
+			if err != nil {
+				t.Fatalf("expected dual-key rotation to parse, got error: %v", err)
+			}
+			if len(keys) < 2 {
+				t.Errorf("expected ≥2 entries, got %d", len(keys))
+			}
+		})
+	}
+}
+
+func TestL004_DualKeyRotation_AdminMismatch_Rejected(t *testing.T) {
+	cases := []struct {
+		name  string
+		input string
+	}{
+		{"first_admin_then_user", "alice:OLD:admin,alice:NEW"},
+		{"first_user_then_admin", "alice:OLD,alice:NEW:admin"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := ParseNamedAPIKeys(tc.input)
+			if err == nil {
+				t.Fatal("expected admin-flag mismatch to be rejected")
+			}
+			if !strings.Contains(err.Error(), "mismatched admin flag") {
+				t.Errorf("error must cite admin flag mismatch, got: %v", err)
+			}
+		})
+	}
+}
+
+func TestL004_DualKeyRotation_IdenticalNameAndKey_Rejected(t *testing.T) {
+	// Same name + same key is a typo, not a rotation. The rotation
+	// case is DIFFERENT keys under the same name.
+	_, err := ParseNamedAPIKeys("alice:SAMEKEY:admin,alice:SAMEKEY:admin")
+	if err == nil {
+		t.Fatal("expected (name,key) duplicate to be rejected")
+	}
+	if !strings.Contains(err.Error(), "duplicate (name,key)") {
+		t.Errorf("error must cite (name,key) duplicate, got: %v", err)
+	}
+}
+
+func TestL004_DualKeyRotation_SteadyStateUnchanged(t *testing.T) {
+	// Single-key (no rotation) and multi-distinct-name configs must
+	// continue to parse the same way they did pre-bundle.
+	cases := []struct {
+		name  string
+		input string
+		want  int
+	}{
+		{"single", "alice:KEY:admin", 1},
+		{"two_distinct_names", "alice:KEY1:admin,bob:KEY2", 2},
+		{"three_distinct_names", "alice:K1:admin,bob:K2,carol:K3:admin", 3},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			keys, err := ParseNamedAPIKeys(tc.input)
+			if err != nil {
+				t.Fatalf("steady-state parse failed: %v", err)
+			}
+			if len(keys) != tc.want {
+				t.Errorf("got %d entries, want %d", len(keys), tc.want)
+			}
+		})
+	}
+}
+
+func TestL004_DualKeyRotation_PreservesAllEntries(t *testing.T) {
+	// Round-trip: every input entry must appear in the parsed output.
+	keys, err := ParseNamedAPIKeys("alice:OLDKEY:admin,alice:NEWKEY:admin")
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(keys) != 2 {
+		t.Fatalf("got %d, want 2", len(keys))
+	}
+	gotKeys := map[string]bool{keys[0].Key: true, keys[1].Key: true}
+	for _, want := range []string{"OLDKEY", "NEWKEY"} {
+		if !gotKeys[want] {
+			t.Errorf("missing key %q in parsed entries: %+v", want, keys)
+		}
+	}
+	for _, k := range keys {
+		if k.Name != "alice" {
+			t.Errorf("entry %+v has wrong name; want alice", k)
+		}
+		if !k.Admin {
+			t.Errorf("entry %+v lost admin flag", k)
+		}
+	}
+}