@intentsolutions/audit-harness 1.1.7 → 1.2.0

package/scripts/caa-check.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# caa-check.sh — verify a namespace publishes CAA records (and, when configured,
+# pins the EXPECTED certificate authority) before a production signed attestation
+# is anchored against it.
+#
+# WHY THIS EXISTS (CISO binding, DR-010 Q5 / ISEDC v1 Q1 2026-05-10):
+#   CAA (RFC 8659) records constrain which CAs may issue certificates for a
+#   namespace. Pinning the CA on evals.intentsolutions.io closes the mis-issuance
+#   path an attacker could otherwise use to obtain a look-alike cert and present
+#   forged attestation infrastructure. This must be verified BEFORE the first
+#   production attestation. This script is that gate — read-only, fail-closed.
+#
+# WHY IT QUERIES AN EXPLICIT RESOLVER (the bug this version fixes):
+#   Querying the LOCAL STUB RESOLVER (plain `dig`, no `@server`) FALSE-NEGATIVES
+#   on hosts whose stub resolver lags CAA propagation or strips the record type
+#   (systemd-resolved, many CI runners, dev boxes). On such a host a correctly
+#   CAA-pinned zone looks like it has no CAA, and the gate refuses a legitimate
+#   production sign. The fix is to query a TRUSTED PUBLIC resolver. The gate
+#   stays fail-closed: PASS only on a positive matching CAA record from a trusted
+#   resolver; absence / mismatch / unreachable => non-zero.
+#
+# Usage:
+#   bash scripts/caa-check.sh [DOMAIN]
+#   EXPECTED_CAA_ISSUER=letsencrypt.org bash scripts/caa-check.sh evals.intentsolutions.io
+#
+# Resolution order for the domain:
+#   1. $1 (positional)
+#   2. $CAA_CHECK_DOMAIN
+#   3. default: evals.intentsolutions.io
+#
+# Issuer policy:
+#   - EXPECTED_CAA_ISSUER (env) — when set, at least one CAA `issue` (or
+#     `issuewild`) record MUST name this CA, else the check FAILS (exit 1).
+#     Default: letsencrypt.org (the CA the IS public-namespace certs are issued
+#     by). Override per-deployment.
+#   - EXPECTED_CAA_ISSUER=ANY (case-insensitive) — relax to "any CAA record is
+#     acceptable"; presence of ANY CAA record passes, absence fails, and a
+#     warning is emitted that no specific CA is being pinned.
+#
+# Exit codes:
+#   0 — CAA verified (present at a trusted resolver, and matches
+#       EXPECTED_CAA_ISSUER when a specific issuer is required)
+#   1 — CAA NOT verified (no CAA records, or expected issuer not present, from
+#       any trusted resolver)
+#   2 — UNKNOWN/UNREACHABLE (no resolver tool installed)
+#
+# Override knobs:
+#   CAA_CHECK_RESOLVERS — space-separated list of trusted public resolvers to
+#                         query in order (default: "1.1.1.1 8.8.8.8").
+#   CAA_CHECK_DIG_CMD   — command used in place of `dig` (default: dig)
+
+set -euo pipefail
+
+DOMAIN="${1:-${CAA_CHECK_DOMAIN:-evals.intentsolutions.io}}"
+EXPECTED_CAA_ISSUER="${EXPECTED_CAA_ISSUER:-letsencrypt.org}"
+DIG_CMD="${CAA_CHECK_DIG_CMD:-dig}"
+# Trusted public resolvers, queried in order, until one returns a CAA record.
+RESOLVERS="${CAA_CHECK_RESOLVERS:-1.1.1.1 8.8.8.8}"
+
+log() { printf 'caa-check: %s\n' "$1" >&2; }
+
+if [[ "$DOMAIN" == "-h" || "$DOMAIN" == "--help" ]]; then
+  sed -n '2,60p' "$0"
+  exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+if ! have "$DIG_CMD"; then
+  log "UNKNOWN/UNREACHABLE — '$DIG_CMD' is not installed; cannot look up CAA for '$DOMAIN'"
+  log "  failing closed (production must not sign on UNKNOWN)"
+  log "  remediation: install bind9-dnsutils (provides dig) on the signing host"
+  exit 2
+fi
+
+# issuer_matches CAA_TEXT -> 0 if a matching issue/issuewild record is present.
+# Match any `issue` or `issuewild` property whose value contains the expected
+# CA. CAA values are quoted; we match case-insensitively on the issuer substring.
+issuer_matches() {
+  printf '%s\n' "$1" \
+    | grep -iE '[[:space:]]issue(wild)?[[:space:]]' \
+    | grep -iqF "$EXPECTED_CAA_ISSUER"
+}
+
+# is_blank CAA_TEXT -> 0 if the text is empty after stripping whitespace.
+is_blank() {
+  [[ -z "${1//[$' \t\r\n']/}" ]]
+}
+
+last_caa_out=""   # records from the last resolver that returned ANY CAA records
+saw_records=0     # at least one trusted resolver returned CAA records
+
+shopt -s nocasematch
+relax_any=0
+[[ "$EXPECTED_CAA_ISSUER" == "ANY" ]] && relax_any=1
+shopt -u nocasematch
+
+for resolver in $RESOLVERS; do
+  log "looking up CAA records for '$DOMAIN' via $DIG_CMD @$resolver"
+  # `dig @resolver +short CAA` prints one line per record, e.g.:
+  #   0 issue "letsencrypt.org"
+  #   0 issuewild ";"
+  caa_out="$("$DIG_CMD" "@$resolver" +short CAA "$DOMAIN" 2>/dev/null || true)"
+
+  if is_blank "$caa_out"; then
+    log "  no CAA records returned by @$resolver"
+    continue
+  fi
+
+  saw_records=1
+  last_caa_out="$caa_out"
+
+  # --- ANY-issuer relaxation: any CAA record present passes ---
+  if [[ "$relax_any" -eq 1 ]]; then
+    log "VERIFIED (presence only) — CAA records exist for '$DOMAIN' (via @$resolver)"
+    log "  WARNING: EXPECTED_CAA_ISSUER=ANY — no specific CA is being pinned."
+    log "  Records found:"
+    printf '%s\n' "$caa_out" | sed 's/^/    /' >&2
+    exit 0
+  fi
+
+  # --- Specific-issuer pinning ---
+  if issuer_matches "$caa_out"; then
+    log "VERIFIED — '$DOMAIN' pins issuance to '$EXPECTED_CAA_ISSUER' (via @$resolver)"
+    exit 0
+  fi
+
+  log "  CAA records exist at @$resolver but none pin '$EXPECTED_CAA_ISSUER'; trying next resolver"
+done
+
+# No trusted resolver yielded a matching CAA record -> fail-closed (exit 1).
+if [[ "$saw_records" -eq 1 ]]; then
+  log "NOT VERIFIED — CAA records exist for '$DOMAIN' but none pin '$EXPECTED_CAA_ISSUER'"
+  log "  Records found:"
+  printf '%s\n' "$last_caa_out" | sed 's/^/    /' >&2
+  log "  remediation: add a CAA record pinning the expected CA, or set"
+  log "  EXPECTED_CAA_ISSUER to the CA actually published (or ANY to accept any CAA)."
+else
+  log "NOT VERIFIED — no CAA records found for '$DOMAIN' (resolvers tried: $RESOLVERS)"
+  log "  remediation: publish a CAA record pinning the issuing CA, e.g.:"
+  log "    $DOMAIN. CAA 0 issue \"$EXPECTED_CAA_ISSUER\""
+fi
+exit 1

package/scripts/check-wrapper-sync.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# check-wrapper-sync.sh — assert the bundled wrapper-script mirrors are byte-identical
+# to their canonical source under scripts/.
+#
+# WHY THIS EXISTS
+# ---------------
+# The Node package (bin/audit-harness.js) dispatches to the CANONICAL scripts under
+# scripts/. The Python wrapper (intent-audit-harness on PyPI) and the Rust wrapper
+# (intent-audit-harness on crates.io) cannot reach those canonical files at install
+# time, so each BUNDLES a copy:
+#
+#   * python/src/intent_audit_harness/scripts/<name>   (packaged into the wheel)
+#   * rust/scripts/<name>                              (include_bytes!'d into the binary)
+#
+# Those copies are hand-maintained. On 2026-05-24 they were found ~1 month stale:
+# the bundled crap-score.py was missing v1.1.1's --json evidence envelope, the
+# `which_or_none("go")` PATH guard (silent crash on Go-less hosts), and the
+# rglob->os.walk directory pruning. A user running
+# `pip install intent-audit-harness && audit-harness crap` got the OLD gate.
+# (Tracking bead: iah-python-wrapper-scripts-sync / bd_000-projects-65k4.)
+#
+# This gate makes that class of drift IMPOSSIBLE to merge silently: every bundled
+# mirror MUST be a byte-for-byte copy of its canonical source. There is no
+# wrapper-only delta — both wrappers invoke the script verbatim via bash/python3.
+#
+# RESYNC (when this gate REDs)
+# ----------------------------
+#   bash scripts/check-wrapper-sync.sh --fix     # copy canonical -> both mirrors
+# then review + commit the result.
+#
+# Exit codes:
+#   0  all mirrors in sync (or --fix completed)
+#   1  drift detected (and not in --fix mode)
+set -euo pipefail
+
+# Resolve repo root from this script's own location so the gate works regardless
+# of the caller's CWD (CI runs it from the repo root; a dev may run it elsewhere).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CANONICAL_DIR="${REPO_ROOT}/scripts"
+
+# The set of scripts the Python + Rust wrappers DISPATCH. Keep this in lock-step
+# with:
+#   * python/src/intent_audit_harness/cli.py     (COMMANDS dict)
+#   * rust/src/main.rs                           (SCRIPTS array)
+# If a wrapper starts dispatching a new canonical script, add it here AND to both
+# wrapper sources, and copy it into both mirror dirs.
+MIRRORED_SCRIPTS=(
+  "harness-hash.sh"
+  "escape-scan.sh"
+  "arch-check.sh"
+  "bias-count.sh"
+  "gherkin-lint.sh"
+  "crap-score.py"
+)
+
+# Each mirror directory that bundles a copy of the canonical scripts.
+MIRROR_DIRS=(
+  "python/src/intent_audit_harness/scripts"
+  "rust/scripts"
+)
+
+FIX=0
+if [[ "${1:-}" == "--fix" ]]; then
+  FIX=1
+fi
+
+drift_found=0
+missing_canonical=0
+
+for name in "${MIRRORED_SCRIPTS[@]}"; do
+  canonical="${CANONICAL_DIR}/${name}"
+  if [[ ! -f "${canonical}" ]]; then
+    echo "ERROR: canonical source missing: scripts/${name}" >&2
+    missing_canonical=1
+    continue
+  fi
+  for mdir in "${MIRROR_DIRS[@]}"; do
+    mirror="${REPO_ROOT}/${mdir}/${name}"
+    if [[ ! -f "${mirror}" ]]; then
+      echo "DRIFT: missing mirror ${mdir}/${name} (expected a copy of scripts/${name})" >&2
+      drift_found=1
+      if [[ "${FIX}" -eq 1 ]]; then
+        cp -f "${canonical}" "${mirror}"
+        echo "  fixed: created ${mdir}/${name}"
+      fi
+      continue
+    fi
+    if ! diff -q "${canonical}" "${mirror}" >/dev/null 2>&1; then
+      echo "DRIFT: ${mdir}/${name} differs from canonical scripts/${name}" >&2
+      drift_found=1
+      if [[ "${FIX}" -eq 1 ]]; then
+        cp -f "${canonical}" "${mirror}"
+        echo "  fixed: resynced ${mdir}/${name}"
+      fi
+    fi
+  done
+done
+
+if [[ "${missing_canonical}" -eq 1 ]]; then
+  echo "FAIL: one or more canonical scripts are missing — cannot verify mirror sync." >&2
+  exit 1
+fi
+
+if [[ "${FIX}" -eq 1 ]]; then
+  echo "check-wrapper-sync: --fix complete. Review + commit the resynced mirrors."
+  exit 0
+fi
+
+if [[ "${drift_found}" -eq 1 ]]; then
+  echo "" >&2
+  echo "FAIL: bundled wrapper mirrors are out of sync with canonical scripts/." >&2
+  echo "      The Python (PyPI) and Rust (crates.io) packages would ship STALE gates." >&2
+  echo "      Resync with:  bash scripts/check-wrapper-sync.sh --fix" >&2
+  echo "      then review + commit the result." >&2
+  exit 1
+fi
+
+echo "check-wrapper-sync: OK — all ${#MIRRORED_SCRIPTS[@]} bundled mirrors match canonical in ${#MIRROR_DIRS[@]} wrapper dirs."
+exit 0

package/scripts/crap-score.py

@@ -50,6 +50,22 @@ EXCLUDED_DIRS = {
 }
 
 
+def is_excluded_dir(name: str) -> bool:
+    """Single exclusion predicate shared by the candidate-discovery walk and
+    the --json input-hash walk.
+
+    Both walks MUST agree on which directories they descend into; otherwise the
+    set of files that feed the CRAP score can diverge from the set that feeds
+    the input_hash, and the score/hash desync (a hash that claims to cover
+    files the score never saw, or vice versa). The rule is: skip any dot-dir
+    (e.g. `.idea`, `.svn`, `.git`) OR any explicitly-named build/vendor dir in
+    EXCLUDED_DIRS. Previously discovery dropped all dot-dirs while the hash walk
+    dropped only the named subset, so a dot-dir not in EXCLUDED_DIRS was hashed
+    but never scored.
+    """
+    return name.startswith(".") or name in EXCLUDED_DIRS
+
+
 def crap(complexity: int, coverage_pct: float) -> float:
     cov = max(0.0, min(100.0, coverage_pct)) / 100.0
     return (complexity ** 2) * ((1.0 - cov) ** 3) + complexity
@@ -98,8 +114,7 @@ def score_python(root: Path, kind: str) -> list[MethodScore]:
             scanned = [
                 p.name for p in root.iterdir()
                 if p.is_dir()
-                and not p.name.startswith(".")
-                and p.name not in EXCLUDED_DIRS
+                and not is_excluded_dir(p.name)
                 and p.name not in test_dirs
                 and any(p.rglob("*.py"))
             ]
@@ -165,7 +180,15 @@ def score_go(root: Path, kind: str) -> list[MethodScore]:
         print("[crap-score] gocyclo not installed", file=sys.stderr)
         return []
 
-    rc, out, _ = run(["gocyclo", "-ignore", "_test.go" if kind == "src" else ".*\\.go$", "."], root)
+    # For kind="src", ignore *_test.go at the gocyclo level. For kind="test",
+    # do NOT pass -ignore: a pattern like `.*\.go$` matches every analyzable
+    # file (gocyclo only reads .go files), which silenced all test-kind output.
+    # The include-filter below keeps only *_test.go rows for kind="test".
+    gocyclo_cmd = ["gocyclo"]
+    if kind == "src":
+        gocyclo_cmd += ["-ignore", "_test.go"]
+    gocyclo_cmd.append(".")
+    rc, out, _ = run(gocyclo_cmd, root)
     complexity: list[tuple[str, str, int]] = []
     for line in out.splitlines():
         parts = line.strip().split()
@@ -187,11 +210,28 @@ def score_go(root: Path, kind: str) -> list[MethodScore]:
     if not cov_out.is_file() and which_or_none("go"):
         run(["go", "test", "-coverprofile=coverage.out", "-covermode=atomic", "./..."], root)
     if cov_out.is_file() and which_or_none("go"):
+        # `go tool cover -func` reports module-qualified paths
+        # (github.com/user/repo/pkg/file.go) while gocyclo reports repo-relative
+        # paths (pkg/file.go). Strip the module prefix read from go.mod so the
+        # coverage keys join the complexity keys.
+        module_prefix = ""
+        go_mod = root / "go.mod"
+        if go_mod.is_file():
+            try:
+                for mod_line in go_mod.read_text().splitlines():
+                    mod_line = mod_line.strip()
+                    if mod_line.startswith("module ") or mod_line.startswith("module\t"):
+                        module_prefix = mod_line.split(None, 1)[1].strip() + "/"
+                        break
+            except OSError:
+                pass
         rc, out, _ = run(["go", "tool", "cover", "-func=coverage.out"], root)
         for line in out.splitlines():
             parts = line.split()
             if len(parts) >= 3 and parts[-1].endswith("%"):
                 fpath = parts[0].split(":", 1)[0]
+                if module_prefix and fpath.startswith(module_prefix):
+                    fpath = fpath[len(module_prefix):]
                 try:
                     pct = float(parts[-1].rstrip("%"))
                 except ValueError:
@@ -228,6 +268,17 @@ def score_js(root: Path, kind: str) -> list[MethodScore]:
     except json.JSONDecodeError:
         return []
 
+    # c8/istanbul's json-summary reporter keys files by ABSOLUTE path while
+    # complexity-report (run with a repo-relative target) reports repo-relative
+    # paths. Normalize both sides to repo-relative so the coverage join works.
+    def _rel_to_root(p: str) -> str:
+        if os.path.isabs(p):
+            try:
+                return os.path.relpath(p, str(root))
+            except ValueError:
+                return p  # e.g. different drive on Windows — keep as-is
+        return p
+
     cov_path = root / "coverage" / "coverage-summary.json"
     coverage: dict[str, float] = {}
     if cov_path.is_file():
@@ -237,14 +288,14 @@ def score_js(root: Path, kind: str) -> list[MethodScore]:
                 if fpath == "total":
                     continue
                 lines_pct = summary.get("lines", {}).get("pct", 0.0)
-                coverage[fpath] = float(lines_pct)
+                coverage[_rel_to_root(fpath)] = float(lines_pct)
         except (OSError, json.JSONDecodeError):
             pass
 
     scores: list[MethodScore] = []
     for report in data.get("reports", []):
         fpath = report.get("path", "")
-        cov = coverage.get(fpath, 0.0)
+        cov = coverage.get(_rel_to_root(fpath), 0.0)
         for func in report.get("functions", []):
             c = int(func.get("cyclomatic", 1))
             scores.append(
@@ -403,7 +454,7 @@ def main() -> int:
         exts = (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt", ".cs", ".php", ".rb")
         collected: list[Path] = []
         for dirpath, dirs, files in os.walk(root):
-            dirs[:] = [d for d in dirs if d not in EXCLUDED_DIRS]
+            dirs[:] = [d for d in dirs if not is_excluded_dir(d)]
             for fn in files:
                 if fn.endswith(exts):
                     collected.append(Path(dirpath) / fn)

package/scripts/cred-gate.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# cred-gate.sh — Provider credential PASS/FAIL gate (iah-E08).
+#
+# CISO non-negotiable per DR-010 S1Q5: before any provider abstraction is allowed
+# to flow data into an Evidence Bundle / OTel signal / gate-result envelope, two
+# things MUST hold and are gated here, deterministically and offline:
+#
+#   1. CREDENTIAL REDACTION — no provider secret VALUE appears verbatim in the
+#      candidate artifact (the JSON the runner is about to sign, the OTel line it
+#      is about to emit, any log it captures). A leaked API key in a signed,
+#      Rekor-anchored Statement is irreversible.
+#
+#   2. ENV-VAR SPILLOVER — the candidate artifact does not blindly serialize the
+#      process environment (e.g. an `env` dump, a `process.env` spread, or a
+#      "context": {<all env>} block). A provider key need not be named to leak:
+#      a wholesale env dump spills every secret at once.
+#
+# This gate is READ-ONLY and OFFLINE. It never contacts a provider, never reads
+# a real key from disk, and never writes. It inspects the candidate artifact you
+# hand it (stdin or --input) against the secret values present in the environment
+# (referenced by NAME via --secret-env, so the values never appear on the command
+# line) plus a built-in catalog of provider-key SHAPES.
+#
+# It emits a gate-result/v1 envelope on stdout (--json) suitable for piping to
+# emit-evidence, OR a human-readable PASS/FAIL summary (default).
+#
+# Usage:
+#   bash cred-gate.sh --input candidate.json
+#   <producer> | bash cred-gate.sh                      # candidate on stdin
+#   bash cred-gate.sh --secret-env ANTHROPIC_API_KEY --secret-env OPENAI_API_KEY < cand.json
+#   bash cred-gate.sh --json < candidate.json | bash emit-evidence.sh
+#
+# Flags:
+#   --input PATH       Read the candidate artifact from PATH instead of stdin.
+#   --secret-env NAME  Treat $NAME's VALUE as a secret that must NOT appear in the
+#                      candidate. Repeatable. The value is read from the
+#                      environment by name — it is never passed on argv.
+#   --json             Emit a gate-result/v1 envelope (JSON) instead of text.
+#   --gate-id ID       Override the gate_id in the envelope (default: provider-cred-gate).
+#   --help, -h         Print help.
+#
+# Exit codes:
+#   0 — PASS (no secret value present; no env-var spillover detected)
+#   1 — FAIL (a secret value leaked OR an env-var spillover pattern matched)
+#   2 — usage / input error (no candidate, unreadable --input)
+#
+# Failure-mode docs (iah-E08d): see docs/cred-gate.md for the catalog of detected
+# shapes, the spillover heuristics, the false-positive posture, and remediation.
+
+set -euo pipefail
+
+# Bash version floor: align with the rest of the harness (jcgw).
+[ "${BASH_VERSINFO:-0}" -ge 4 ] || { echo 'audit-harness requires bash >= 4' >&2; exit 2; }
+
+INPUT="-"
+EMIT_JSON=0
+GATE_ID="provider-cred-gate"
+SECRET_ENVS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --input)       INPUT="$2"; shift 2 ;;
+    --secret-env)  SECRET_ENVS+=("$2"); shift 2 ;;
+    --json)        EMIT_JSON=1; shift ;;
+    --gate-id)     GATE_ID="$2"; shift 2 ;;
+    --help|-h)     sed -n '2,46p' "$0"; exit 0 ;;
+    *) echo "cred-gate: unknown flag $1" >&2; exit 2 ;;
+  esac
+done
+
+# --- Read the candidate artifact ---
+if [[ "$INPUT" == "-" ]]; then
+  CANDIDATE=$(cat)
+else
+  if [[ ! -r "$INPUT" ]]; then
+    echo "cred-gate: cannot read $INPUT" >&2
+    exit 2
+  fi
+  CANDIDATE=$(cat "$INPUT")
+fi
+
+if [[ -z "$CANDIDATE" ]]; then
+  echo "cred-gate: empty candidate artifact" >&2
+  exit 2
+fi
+
+# Resolve the gate input hash (sha256 of the candidate bytes) so the emitted
+# envelope's input_hash is coherent with what was actually inspected.
+INPUT_HASH="sha256:$(printf '%s' "$CANDIDATE" | sha256sum | cut -d' ' -f1)"
+# The policy is this script's own bytes — a content address of the gate logic.
+POLICY_HASH="sha256:$(sha256sum "$0" | cut -d' ' -f1)"
+
+# --- Collect the secret VALUES to redaction-check (by env-var name) ---
+# Built as a NUL-delimited blob so values with newlines/spaces stay intact and
+# never touch argv.
+SECRET_VALUES_BLOB=""
+for name in "${SECRET_ENVS[@]:-}"; do
+  [[ -z "$name" ]] && continue
+  # Indirect expansion: read $name's value without it ever appearing on argv.
+  val="${!name:-}"
+  # Skip empty / trivially short values: a 1-char "secret" would false-positive
+  # on virtually any artifact and is not a real credential.
+  [[ ${#val} -lt 8 ]] && continue
+  SECRET_VALUES_BLOB+="$val"$'\0'
+done
+
+# --- Deterministic analysis in python (offline; values via env, not argv) ---
+# We pass the candidate + the secret blob + the catalog knobs through the
+# environment so no secret value is ever visible in `ps`.
+RESULT=$(
+  CANDIDATE="$CANDIDATE" \
+  SECRET_VALUES_BLOB="$SECRET_VALUES_BLOB" \
+  GATE_ID="$GATE_ID" \
+  python3 - <<'PY'
+import json
+import os
+import re
+import sys
+
+candidate = os.environ["CANDIDATE"]
+
+findings = []  # list of {"kind": ..., "detail": ...}
+
+# --- 1. Credential redaction: explicit secret VALUES must not appear verbatim ---
+blob = os.environ.get("SECRET_VALUES_BLOB", "")
+secret_values = [v for v in blob.split("\0") if v]
+for val in secret_values:
+    if val in candidate:
+        # NEVER echo the secret. Report only its length + a non-reversible
+        # fingerprint so the finding is actionable without re-leaking.
+        import hashlib
+
+        fp = hashlib.sha256(val.encode("utf-8")).hexdigest()[:12]
+        findings.append(
+            {
+                "kind": "secret-value-leak",
+                "detail": (
+                    "a declared secret value (len=%d, sha256:%s...) appears "
+                    "verbatim in the candidate artifact" % (len(val), fp)
+                ),
+            }
+        )
+
+# --- 2. Credential redaction: provider-key SHAPES (value-agnostic catalog) ---
+# Each pattern matches the literal on-the-wire shape of a known provider key.
+# A match means a raw key is embedded even if it was not declared via
+# --secret-env. Patterns are intentionally specific to keep the FP rate low.
+SHAPE_PATTERNS = [
+    ("anthropic-key", r"sk-ant-[A-Za-z0-9_-]{20,}"),
+    # OpenAI keys start sk- but NOT sk-ant- (that's anthropic, matched above).
+    # The negative lookahead keeps the two findings disjoint.
+    ("openai-key", r"sk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}"),
+    ("groq-key", r"gsk_[A-Za-z0-9]{20,}"),
+    ("nvidia-key", r"nvapi-[A-Za-z0-9_-]{20,}"),
+    ("aws-access-key-id", r"AKIA[0-9A-Z]{16}"),
+    ("google-api-key", r"AIza[0-9A-Za-z_-]{35}"),
+    ("github-token", r"gh[posru]_[A-Za-z0-9]{36,}"),
+    ("slack-token", r"xox[baprs]-[A-Za-z0-9-]{10,}"),
+    ("private-key-block", r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
+]
+for name, pattern in SHAPE_PATTERNS:
+    if re.search(pattern, candidate):
+        findings.append(
+            {
+                "kind": "secret-shape-match",
+                "detail": "candidate contains a value matching the %s key shape"
+                % name,
+            }
+        )
+
+# --- 3. Env-var spillover: wholesale environment serialization ---
+# A provider key need not be NAMED to leak — a blanket env dump spills every
+# secret at once. We flag the structural patterns that serialize the whole
+# environment into the artifact.
+SPILLOVER_PATTERNS = [
+    ("process-env-spread", r"\.\.\.\s*process\.env\b"),
+    ("os-environ-dump", r"\bdict\(\s*os\.environ\s*\)|\bos\.environ\b\s*[,}\]]"),
+    ("env-block-key", r'"(?:env|environ|environment)"\s*:\s*\{'),
+    ("printenv-capture", r"\b(?:printenv|/usr/bin/env)\b"),
+]
+# These are heuristics: matching one is an ADVISORY-grade structural smell, but
+# combined with an actual secret leak it is a hard FAIL. We treat any spillover
+# match as a finding so the gate FAILs — an env dump in a to-be-signed artifact
+# is exactly the irreversible leak this gate exists to stop.
+for name, pattern in SPILLOVER_PATTERNS:
+    if re.search(pattern, candidate):
+        findings.append(
+            {
+                "kind": "env-spillover",
+                "detail": "candidate serializes the process environment via "
+                "the %s pattern" % name,
+            }
+        )
+
+result = "FAIL" if findings else "PASS"
+print(json.dumps({"result": result, "findings": findings}))
+PY
+)
+
+# --- Parse the python result ---
+GATE_RESULT=$(printf '%s' "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['result'])")
+FINDINGS_JSON=$(printf '%s' "$RESULT" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin)['findings']))")
+FINDING_COUNT=$(printf '%s' "$RESULT" | python3 -c "import json,sys; print(len(json.load(sys.stdin)['findings']))")
+
+# --- Emit ---
+if [[ "$EMIT_JSON" -eq 1 ]]; then
+  GATE_ID="$GATE_ID" GATE_RESULT="$GATE_RESULT" INPUT_HASH="$INPUT_HASH" \
+  POLICY_HASH="$POLICY_HASH" FINDINGS_JSON="$FINDINGS_JSON" \
+  python3 - <<'PY'
+import json
+import os
+
+env = {
+    "gate_id": os.environ["GATE_ID"],
+    "result": os.environ["GATE_RESULT"],
+    "input_hash": os.environ["INPUT_HASH"],
+    "policy_hash": os.environ["POLICY_HASH"],
+    "metadata": {"findings": json.loads(os.environ["FINDINGS_JSON"])},
+}
+if env["result"] == "FAIL":
+    env["failure_mode"] = "provider_credential_leak"
+print(json.dumps(env, separators=(",", ":")))
+PY
+else
+  if [[ "$GATE_RESULT" == "PASS" ]]; then
+    echo "cred-gate: PASS — no provider secret value present, no env-var spillover detected"
+  else
+    echo "cred-gate: FAIL — $FINDING_COUNT credential finding(s):" >&2
+    printf '%s' "$FINDINGS_JSON" | python3 -c "
+import json, sys
+for f in json.load(sys.stdin):
+    sys.stderr.write('  ⛔ [%s] %s\n' % (f['kind'], f['detail']))
+"
+    echo "cred-gate: see docs/cred-gate.md for remediation (iah-E08d)." >&2
+  fi
+fi
+
+[[ "$GATE_RESULT" == "PASS" ]] && exit 0 || exit 1