fix(security): require signed tenant claims on admin endpoints

.github/workflows/ci.yml

@@ -3,8 +3,9 @@ name: CI
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
+  # Every pull request target, including immutable stack branches, receives the
+  # same exact-head, synthetic-merge, and buyer-readiness acceptance evidence.
+  pull_request: {}
 
 permissions:
   contents: read
@@ -17,14 +18,86 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
       - name: Use preinstalled Temurin JDK 21
         # Uses the runner image's bundled JDK instead of actions/setup-java to
         # keep every workflow dependency hash-pinned (Scorecard Pinned-Dependencies).
         run: |
           echo "JAVA_HOME=$JAVA_HOME_21_X64" >> "$GITHUB_ENV"
           echo "$JAVA_HOME_21_X64/bin" >> "$GITHUB_PATH"
-      - name: Run tests
-        run: mvn -B --no-transfer-progress test
+      - name: Run tests and coverage acceptance gates
+        shell: bash
+        run: |
+          if ! mvn -B --no-transfer-progress verify; then
+            if [[ -f target/site/jacoco/jacoco.csv ]]; then
+              echo "::group::JaCoCo CSV diagnostics"
+              cat target/site/jacoco/jacoco.csv
+              echo "::endgroup::"
+            fi
+            if [[ -f target/site/jacoco/jacoco.xml ]]; then
+              echo "::group::JaCoCo uncovered line diagnostics"
+              python3 - <<'PY'
+          import xml.etree.ElementTree as ET
+          from pathlib import Path
+
+          report = Path("target/site/jacoco/jacoco.xml")
+          root = ET.parse(report).getroot()
+          gaps = []
+          for package in root.findall("package"):
+              package_name = package.get("name", "")
+              for source_file in package.findall("sourcefile"):
+                  source_name = source_file.get("name", "")
+                  source_path = f"{package_name}/{source_name}" if package_name else source_name
+                  for line in source_file.findall("line"):
+                      missed_instructions = int(line.get("mi", "0"))
+                      missed_branches = int(line.get("mb", "0"))
+                      if missed_instructions or missed_branches:
+                          gaps.append(
+                              (
+                                  source_path,
+                                  int(line.get("nr", "0")),
+                                  missed_instructions,
+                                  missed_branches,
+                              )
+                          )
+
+          for source_path, line_number, missed_instructions, missed_branches in gaps:
+              print(
+                  f"{source_path}:{line_number}: "
+                  f"missed_instructions={missed_instructions} "
+                  f"missed_branches={missed_branches}"
+              )
+          PY
+              echo "::endgroup::"
+            fi
+            exit 1
+          fi
+          python3 scripts/verify_maven_test_reports.py
+
+  merge-compatibility:
+    name: Maven merge compatibility
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Verify merge revision
+        env:
+          EXPECTED_SHA: ${{ github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+      - name: Use preinstalled Temurin JDK 21
+        run: |
+          echo "JAVA_HOME=$JAVA_HOME_21_X64" >> "$GITHUB_ENV"
+          echo "$JAVA_HOME_21_X64/bin" >> "$GITHUB_PATH"
+      - name: Verify merged result
+        run: |
+          mvn -B --no-transfer-progress verify
+          python3 scripts/verify_maven_test_reports.py
 
   script-checks:
     name: Buyer-readiness script tests
@@ -33,6 +106,11 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'

.github/workflows/fuzz.yml

@@ -45,6 +45,14 @@ jobs:
           - TenantClaimsFuzzTest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
 
       - name: Set up JDK 21
         uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961

AGENTS.md

@@ -7,10 +7,19 @@ including mandatory quality and security merge gates.
 
 ## Mandatory merge gates
 
-- `mvn -DskipTests compile` must pass with warning/deprecated budget = 0.
-- `mvn test` must pass.
-- JaCoCo coverage for production package must remain 100% line/branch.
-- JavaDoc gate must pass (`mvn -q -DskipTests javadoc:javadoc`) with no warnings/errors.
+- `mvn -B --no-transfer-progress verify` is the authoritative local and CI
+  acceptance command. Do not substitute `compile`, `test`, or a predecessor
+  head result for this exact-head lifecycle.
+- Java 21 compilation must pass with warning and deprecation budget = 0.
+- Every test must pass with zero failures, errors, and skips.
+- JaCoCo coverage for the `com.clearfolio.viewer.*` production package must
+  remain 100% statement/line and branch coverage, expressed as zero missed
+  production lines and branches.
+- The verify lifecycle must generate public Javadocs with Maven Javadoc Plugin
+  3.12.0, `doclint=all`, `failOnError=true`, and `failOnWarnings=true`. Public
+  record components, constructors, methods, enum values, fields, parameters,
+  return values, and thrown failures must be understandable without reading the
+  implementation.
 - Markdown lint for changed docs must pass.
 - Security evidence must be attached on PR (SAST/code-scanning checks).
 - CodeQL Java/Kotlin analysis must remain enabled through repository default
@@ -31,10 +40,15 @@ including mandatory quality and security merge gates.
   `python3 scripts/summarize_buyer_readiness.py --manifest docs/diligence/2026-07-03-buyer-data-room-manifest.json --output docs/diligence/2026-07-03-buyer-readiness-scorecard.md --summary docs/qa/evidence/2026-07-02-krw2b-sale-readiness/buyer-readiness-scorecard-summary.json --check`.
 - Figma Slides generation payload check must pass:
   `python3 scripts/check_figma_deck_payload.py --payload docs/design/2026-07-03-buyer-diligence-slides-generation-payload.json --summary docs/qa/evidence/2026-07-02-krw2b-sale-readiness/figma-deck-payload-check.json`.
-- `mvn test` includes `DependencyPolicyTest`, which prevents reintroducing the
-  broad `tika-parsers-standard-package`, default Logback starter, or excluded
-  Jakarta annotation dependency unless a future PR updates the license policy,
-  SBOM evidence, attribution package, and buyer diligence docs together.
+- `mvn verify` includes `DependencyPolicyTest`, which prevents reintroducing the
+  broad `tika-parsers-standard-package`, default Logback starter, excluded
+  Jakarta annotation dependency, an unreviewed Netty version, or a weakened
+  public-Javadoc gate unless a future PR updates the corresponding security,
+  license, SBOM, attribution, acceptance, and buyer-diligence evidence together.
+- CI, Security Scan, SAST Semgrep, every fuzz target, required organization
+  reviews, and branch protection must all pass on the exact current PR head.
+  Queued, pending, cancelled, skipped-required, stale-head, or predecessor-head
+  evidence is not passing.
 
 ## Change management rule
 
@@ -58,7 +72,7 @@ Codex, Cursor, opencode, …) working in this repo.
   then **remediate**:
   - This is a Maven / Spring Boot app — findings are almost always vulnerable
     Java dependencies. Fix by bumping the offending artifact (or its managed
-    version) in `pom.xml`; re-run `mvn -DskipTests compile` and `mvn test`.
+    version) in `pom.xml`; re-run `mvn -B --no-transfer-progress verify`.
   - There is currently no `Dockerfile` or k8s manifest here; if one is added,
     trivy will also flag image/IaC misconfigs — fix those at the source.
   - For a genuine false positive only, add a narrow, **documented**
@@ -82,15 +96,32 @@ Codex, Cursor, opencode, …) working in this repo.
 - Reference implementation: xtrmLLMBatchPython's pgcrypto-encrypted Postgres
   credential registry (`get_credential(name)`). Reuse that pattern (a DB-backed
   KV is fine) unless a dedicated KV is adopted.
-- **This repo applies** — it is a Spring Boot service with real runtime secrets
-  (artifact-token HMAC secret, tenant-claims HMAC secret). **Known deviation to
-  migrate:** those secrets are currently injected straight from env via Spring
-  placeholders in `application-buyer-demo.yml`
-  (`clearfolio.artifact-token.secret: ${CLEARFOLIO_ARTIFACT_TOKEN_SECRET:}`,
-  `clearfolio.tenant-claims.hmac-secret: ${CLEARFOLIO_TENANT_CLAIMS_HMAC_SECRET:}`,
-  consumed by `ArtifactLinkService` / `TenantAccessService`). Move these to a
-  KV-backed lookup so env is only the bootstrap transport into the KV. New
-  secrets/credentials must go through the KV from the start, not new env reads.
+- **This repo applies** — it is a Spring Boot service with real runtime secrets.
+  Tenant-claim and artifact-token HMAC secrets are loaded respectively as
+  `clearfolio.tenant-claims.hmac-secret` and
+  `clearfolio.artifact-token.secret` from the Spring config-tree credential
+  mount selected by the non-secret `CLEARFOLIO_SECRET_CONFIG_DIR` bootstrap
+  setting. Do not restore direct runtime environment binding for either key.
+  New secrets and credentials must enter through the mounted credential source,
+  not new process-environment reads.
+
+### Durable cleanup boundary
+
+- This slice integrates a single-process, receipt-first cleanup worker. It
+  forces deletion intent before the first artifact read, binds an exact digest
+  before metadata tombstoning, retries incomplete cleanup after startup and on
+  a bounded fixed-delay schedule, and exposes only low-cardinality aggregate
+  evidence. The filesystem-backed receipt ledger is restart-replayable; the
+  in-memory adapter remains available for standalone tests and ephemeral use.
+- Do not overstate that reference boundary. It does not provide a cross-resource
+  transactional outbox, a distributed generation fence, or remote-object-store
+  atomicity across multiple service instances. Production adapters must provide
+  equivalent durable uniqueness, object-version preconditions, idempotent
+  retries, and operator recovery evidence before distributed cutover.
+- Issue #263 remains the umbrella for the distributed adapter and later truthful
+  API/UI lifecycle work. Do not describe durable cleanup as absent, and do not
+  describe the current single-process implementation as a distributed deletion
+  transaction.
 
 ### Code exploration
 
@@ -108,11 +139,11 @@ Codex, Cursor, opencode, …) working in this repo.
   DOM-decomposes emails and files into a persisted knowledge graph. Each
   component is a standalone program that must ALSO work as a git submodule of
   the hub, grown separately and together.
-- Sibling components: **waf-ids-ai-soc** (WAF / IDS / AI SOC / LB / APIM),
+- Sibling components: **wardnet** (WAF / IDS / AI SOC / LB / APIM),
   **pg-erd-cloud** (ERD tool), **contextual-orchestrator** (LLM
   cost/perf/upstream-LB gateway, beyond LiteLLM), **codec-carver** (STT /
   omni-modal speech-video codec), **fast-mlsirm** (LLM-as-a-Judge calibration +
-  evaluation-item quality, using aFIPC FIPC + kaefa item-fit), **feelanet-adfs**
+  evaluation-item quality, using aFIPC FIPC + kaefa item-fit), **keyverse**
   (passwordless SSO — OIDC/SCIM/ADFS/LDAP/FIDO2/OAuth2.1, eliminate passwords),
   **newsdom-api** (PDF→DOM sidecar), and **semantic-data-portal** (upper
   ontology / catalog / governance plane with its own graph engine).