@intentsolutions/audit-harness 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes are recorded here. Format follows [Keep a Changelog](https:/
 
 ## [Unreleased]
 
+### Added — golden-master suite for gherkin-lint + crap-score stdout shapes (iah-golden-master)
+
+A fitness function that pins the raw stdout of the two scorers whose output is a downstream contract.
+
+- **`tests/golden/run-golden.sh`** captures `gherkin-lint.sh` (text rubric) and `crap-score.py --json` (gate-result envelope) stdout against a `tests/fixtures/deliberate-failure/` corpus and diffs each against a checked-in golden, failing on any drift. Environment-volatile bytes are normalized out (gherkin-lint's installed-vs-awk-fallback first line; crap-score's absolute `summary_path`) so the golden is byte-stable across machines. CI installs no complexity provider, so the crap golden captures the deterministic no-provider envelope shape.
+- **Why this and not the per-row schema gate:** the schema gate validates the *augmented* predicate that `emit-evidence` produces, not the raw scorer stdout. A silent reshape of the scorer stdout — a renamed field, a dropped WARN line, changed summary wording — is a backward-compat break the schema gate cannot see. This suite is that missing guard.
+- Regenerate intentional changes with `bash tests/golden/run-golden.sh --update` and review the golden diff in the PR. Wired into `.github/workflows/ci.yml` as the `golden` job.
+
+### Changed — `install.sh` vendors NOTICE + the Node dispatcher (iah-install-sh-completeness)
+
+The vendored-install path (non-Node repos) now ships a complete, traceable copy.
+
+- **`NOTICE`** is copied into `.audit-harness/` — Apache-2.0 §4(d) requires the NOTICE file to travel with any distribution, and vendoring is a distribution.
+- **`bin/audit-harness.js`** (the Node CLI dispatcher) and **`package.json`** are copied into `.audit-harness/bin/` + `.audit-harness/` so the canonical dispatcher surface is present and its `--version` (which reads `../package.json`) resolves in the vendored tree.
+- A **`PROVENANCE`** file records the source repo, version, tarball URL, and install timestamp so a vendored tree is traceable back to the exact release it came from.
+
 ### Added — CI-only signed evidence emit for the intent-eval-dashboard (nr75.12)
 
 The dashboard reports hub (labs.intentsolutions.io) ingests a signed `report-manifest.json` of kernel `gate-result/v1` rows per repo. This adds audit-harness's own emit, lighting up its row.
@@ -73,6 +89,30 @@ The first piece of the "comprehensive audit, on any repo" build: the read-only b
 
 Scope boundary: no `conform` verb, no gate execution yet (Phase 2+). `classify` is read-only and emits a profile only.
 
+## [1.1.8] - 2026-06-18
+
+Ships the iah-E06 production-signing pre-flight gate to downstream consumers.
+
+### Added — DNSSEC + CAA production-signing pre-flight (iah-E06)
+
+Before a production-mode `emit-evidence` run signs canonical bytes, two deterministic pre-flight scripts assert the signing domain is cryptographically sound. Both fail closed: any error, missing record, or unreachable resolver blocks the signing path rather than emitting an unverifiable attestation.
+
+- **`scripts/dnssec-check.sh`** — verifies the signing domain's DNSSEC chain is present and validates.
+- **`scripts/caa-check.sh`** — verifies the domain's CAA records authorize the signing certificate authority.
+- The `emit-evidence` production path gates on both before signing; staging/draft emit is unaffected.
+
+### Fixed — query a trusted validating resolver in the DNSSEC + CAA pre-flight (PR #75)
+
+The pre-flight previously trusted the ambient resolver, which may not validate DNSSEC. Both scripts now query known validating resolvers (`1.1.1.1`, `8.8.8.8`) and require the authenticated-data (AD) flag plus an `RRSIG` on the answer. A resolver that does not set AD, or an answer with no RRSIG, is treated as a validation failure (fail-closed) rather than a pass.
+
+### Changed — Version bumped to 1.1.8 across all manifests
+
+Per the `version-canonical-check` CI gate. `package.json` (canonical), `version.txt`, `python/pyproject.toml`, `python/src/intent_audit_harness/__init__.py`, and `rust/Cargo.toml` all report `1.1.8`.
+
+### Why patch, not minor
+
+The pre-flight scripts shipped to the repo in earlier PRs (#70, #75); this patch propagates them to npm consumers via a version bump. No new public CLI commands or flag changes in this release boundary.
+
 ## [v1.1.5] - 2026-06-03
 
 ### Added — npm release pipeline (closes the publish-pipeline gap)

package/bin/audit-harness.js

@@ -7,7 +7,7 @@
  * and language-portable. The CLI just adds discoverability + cross-platform-ish shell resolution.
  */
 const { spawn } = require('node:child_process');
-const { resolve, dirname } = require('node:path');
+const { resolve } = require('node:path');
 const { existsSync } = require('node:fs');
 
 const SCRIPTS = resolve(__dirname, '..', 'scripts');
@@ -85,11 +85,12 @@ Commands:
                            should flag). The metric that gates advisory->blocking
                            promotion. --max-fp-rate X exits 1 if any gate exceeds X.
                            See docs/gate-promotion.md.
-  currency                 Advisory upstream-currency report. Reads the per-upstream
+  currency                 Advisory poll-freshness report. Reads the per-upstream
                            pin relation (schemas/currency/pins.v1.json) and flags
-                           pins whose checked_at is past their staleness window.
-                           NO exit-code authority (always exit 0), no live-fetch,
-                           no auto-fix — it reports; /sync-testing-harness acts.
+                           pins whose checked_at is past their poll-freshness SLA
+                           (the SLA gates nothing but human attention). NO exit-code
+                           authority (always exit 0), no live-fetch, no auto-fix —
+                           it reports; /sync-testing-harness acts.
   gen-layer-applicability  Project schemas/audit-profile/registry.v1.json into
                            schemas/audit-profile/layer-applicability.md. --write to
                            regenerate, --check to fail on drift (CI gate). The doc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutions/audit-harness",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Deterministic test-enforcement harness — escape-scan, hash-pinning, CRAP, architecture checks, bias detection, Gherkin lint. Companion to the audit-tests and implement-tests Claude Code skills.",
   "license": "Apache-2.0",
   "author": "Jeremy Longshore <jeremy@intentsolutions.io>",
@@ -40,8 +40,15 @@
   ],
   "scripts": {
     "test": "bash scripts/escape-scan.sh --staged || true",
+    "lint": "eslint \"bin/**/*.js\"",
+    "lint:fix": "eslint --fix \"bin/**/*.js\"",
     "prepublishOnly": "node bin/audit-harness.js --version"
   },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.39.4",
+    "lefthook": "^1.13.6"
+  },
   "publishConfig": {
     "access": "public"
   },

package/schemas/currency/pins.v1.json

@@ -1,34 +1,183 @@
 {
   "pins_version": "currency-pins/v1",
-  "description": "Per-upstream-identity pin relation. Each upstream the harness/skills depend on carries ITS OWN pinned version + the date it was last verified against upstream (checked_at) + a staleness window. The `currency` advisory report reads this datum and flags pins whose checked_at is older than their window — i.e. it makes the PIN'S OWN STALENESS detectable, without ever live-fetching. Currency is advisory-only: it reports + (in /sync-testing-harness) opens PRs; it has no exit-code authority and never auto-fixes. Updating a pin (after a human re-verifies against upstream) is an engineer edit to this file + a fresh checked_at.",
+  "description": "Per-upstream-identity pin relation. Each upstream the harness/skills depend on carries ITS OWN pinned version + the date it was last verified against upstream (checked_at) + an advisory poll-freshness SLA (staleness_window_days, resolvable from the pin's class). The `currency` advisory report reads this datum and flags pins whose checked_at is older than their SLA — i.e. it makes the PIN'S OWN STALENESS detectable, without ever live-fetching. The SLA gates NOTHING except human attention: currency is advisory-only — it reports + (in /sync-testing-harness) opens PRs; it has no exit-code authority and never auto-fixes. Updating a pin (after a human re-verifies against upstream) is an engineer edit to this file + a fresh checked_at. Pins whose identity matches a surface in the intent-eval-lab upstream-surface registry (specs/upstream-surface-registry.v1.json, 16 monitored surfaces) use the registry surface id as their identity; where the registry declares no version, pinned_version is the sha256 prefix of the lab's vendored snapshot baseline (intent-eval-lab specs/snapshots/.sha/<surface>.sha).",
+  "$comment": "2026-06-12 [9k5h.10]: terminology — the former 'bounded-staleness window' framing is now the advisory 'poll-freshness SLA' (same datum, honest name: it is a polling-attention SLA, not a consistency bound, and it gates nothing). Renamed pins to lab-registry surface ids: 'mcp-spec' -> 'mcp-spec-docs', 'claude-code' -> 'claude-code-changelog' ('agentskills-spec' already matched). Added one pin per remaining registry surface (13 new; 16 registry pins total) + kept the 3 internal-contract pins (skill-md-schema, gate-result-predicate, anthropic-sdk). The per-pin 'class' field is an additive, backward-compatible v1 extension (window resolution: explicit staleness_window_days > class SLA > default_staleness_window_days), so no pins.v2.json bump is needed.",
   "default_staleness_window_days": 90,
+  "staleness_classes": {
+    "spec-page": {
+      "staleness_window_days": 7,
+      "description": "Human-readable spec / reference doc pages (agentskills.io, modelcontextprotocol.io, code.claude.com + platform.claude.com .md shims). Re-verify weekly."
+    },
+    "schema-file": {
+      "staleness_window_days": 7,
+      "description": "Machine-readable schema files (e.g. the MCP schema.ts) — exact field-level diff possible upstream. Re-verify weekly."
+    },
+    "release-feed": {
+      "staleness_window_days": 3,
+      "description": "Release/version signals (GH releases.atom, commits.atom, npm version probes, changelogs, engineering-blog index) — earliest material-change signal, so the tightest SLA. Re-verify every 3 days."
+    },
+    "internal-contract": {
+      "staleness_window_days": null,
+      "description": "Intent Solutions internal contracts (not lab-registry surfaces). No shared class SLA; each pin carries its own staleness_window_days."
+    }
+  },
   "pins": [
     {
-      "identity": "mcp-spec",
+      "identity": "agentskills-spec",
+      "class": "spec-page",
+      "pinned_version": "1.0.0",
+      "source": "https://agentskills.io/specification.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Open SKILL.md standard (compatibility/metadata/license fields). Lab-registry surface (wave 0, official-spec)."
+    },
+    {
+      "identity": "platform-skills-overview",
+      "class": "spec-page",
+      "pinned_version": "sha256:0bd9758afca5",
+      "source": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Anthropic doc page about agent skills. Lab-registry surface (wave 0, anthropic-doc); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "mcp-spec-docs",
+      "class": "spec-page",
       "pinned_version": "2025-06-18",
-      "source": "https://spec.modelcontextprotocol.io/ (protocol revision)",
-      "checked_at": "2026-06-06",
-      "staleness_window_days": 90,
-      "notes": "MCP protocol spec revision the .mcp.json conform schema targets."
+      "source": "https://modelcontextprotocol.io/specification/draft",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "MCP protocol spec revision the .mcp.json conform schema targets. Lab-registry surface (wave 1, official-spec); renamed from 'mcp-spec' 2026-06-12."
+    },
+    {
+      "identity": "claude-hooks",
+      "class": "spec-page",
+      "pinned_version": "sha256:0b644e2208f8",
+      "source": "https://code.claude.com/docs/en/hooks.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code hooks reference (hook-config contract). Lab-registry surface (wave 1, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "claude-settings",
+      "class": "spec-page",
+      "pinned_version": "sha256:491b623ae274",
+      "source": "https://code.claude.com/docs/en/settings.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code settings reference (hook-config contract). Lab-registry surface (wave 1, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "claude-slash-commands",
+      "class": "spec-page",
+      "pinned_version": "sha256:d7d367c7d004",
+      "source": "https://code.claude.com/docs/en/slash-commands.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code slash-commands reference. Lab-registry surface (wave 1, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "plugins-reference",
+      "class": "spec-page",
+      "pinned_version": "sha256:bbb4618ec8b1",
+      "source": "https://code.claude.com/docs/en/plugins-reference.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code plugin-manifest reference. Lab-registry surface (wave 2, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "sub-agents",
+      "class": "spec-page",
+      "pinned_version": "sha256:824162201ae4",
+      "source": "https://code.claude.com/docs/en/sub-agents.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code sub-agents reference (agent-definition contract). Lab-registry surface (wave 2, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "plugin-marketplaces",
+      "class": "spec-page",
+      "pinned_version": "sha256:1f37e87ff344",
+      "source": "https://code.claude.com/docs/en/plugin-marketplaces.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "Claude Code marketplace-catalog reference. Lab-registry surface (wave 2, reference); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "mcp-schema-ts",
+      "class": "schema-file",
+      "pinned_version": "sha256:1bf94a601817",
+      "source": "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/draft/schema.ts",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 7,
+      "notes": "MCP machine-readable schema (mcp-config contract; exact field-level diff possible). Lab-registry surface (wave 1, official-spec-machine-readable); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "skills-releases",
+      "class": "release-feed",
+      "pinned_version": "sha256:8ab0fc2a54fa",
+      "source": "https://github.com/anthropics/skills/releases.atom + commits/main.atom",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "anthropics/skills release + commit feeds (skill-frontmatter contract). Lab-registry surface (wave 0, release-feed); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "mcp-releases",
+      "class": "release-feed",
+      "pinned_version": "sha256:1b180712c47f",
+      "source": "https://github.com/modelcontextprotocol/modelcontextprotocol/releases.atom",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "MCP spec-repo release feed (mcp-config contract). Lab-registry surface (wave 2, release-feed); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "claude-code-changelog",
+      "class": "release-feed",
+      "pinned_version": "2.1.152",
+      "source": "https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "Claude Code release changelog (version-signal contract; 2.1.152 added disallowed-tools frontmatter). Lab-registry surface (wave 0, changelog); renamed from 'claude-code' 2026-06-12."
+    },
+    {
+      "identity": "claude-code-npm",
+      "class": "release-feed",
+      "pinned_version": "2.1.152",
+      "source": "npm view @anthropic-ai/claude-code version",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "Claude Code npm version probe (version-signal contract). Lab-registry surface (wave 0, changelog); version mirrors the last verified npm version."
+    },
+    {
+      "identity": "claude-code-releases",
+      "class": "release-feed",
+      "pinned_version": "sha256:556b4faba702",
+      "source": "https://github.com/anthropics/claude-code/releases.atom",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "Claude Code GH release feed (version-signal contract). Lab-registry surface (wave 2, release-feed); version = vendored snapshot sha prefix."
+    },
+    {
+      "identity": "anthropic-engineering",
+      "class": "release-feed",
+      "pinned_version": "sha256:f99507064aeb",
+      "source": "https://www.anthropic.com/engineering",
+      "checked_at": "2026-06-12",
+      "staleness_window_days": 3,
+      "notes": "Anthropic engineering-blog index (cross-cutting-signal contract). Lab-registry surface (wave 0, release-feed); version = vendored snapshot sha prefix."
     },
     {
       "identity": "skill-md-schema",
+      "class": "internal-contract",
       "pinned_version": "3.7.0",
       "source": "claude-code-plugins 000-docs/SCHEMA_CHANGELOG.md",
       "checked_at": "2026-06-06",
       "staleness_window_days": 90,
       "notes": "IS SKILL.md schema the conform skillmd-frontmatter floor tracks (full rubric stays in /validate-skillmd)."
     },
-    {
-      "identity": "claude-code",
-      "pinned_version": "2.1.152",
-      "source": "https://code.claude.com/docs/en/changelog",
-      "checked_at": "2026-06-06",
-      "staleness_window_days": 60,
-      "notes": "Claude Code release (added disallowed-tools frontmatter at 2.1.152)."
-    },
     {
       "identity": "gate-result-predicate",
+      "class": "internal-contract",
       "pinned_version": "v1",
       "source": "@intentsolutions/core gate-result/v1 (https://evals.intentsolutions.io/gate-result/v1)",
       "checked_at": "2026-06-06",
@@ -37,19 +186,12 @@
     },
     {
       "identity": "anthropic-sdk",
+      "class": "internal-contract",
       "pinned_version": "unverified",
       "source": "https://github.com/anthropics/anthropic-sdk-python (+ -typescript)",
       "checked_at": "2026-06-06",
       "staleness_window_days": 90,
       "notes": "Anthropic SDK surface referenced by downstream skills; pinned_version=unverified until first deliberate verification."
-    },
-    {
-      "identity": "agentskills-spec",
-      "pinned_version": "1.0.0",
-      "source": "https://agentskills.io/specification",
-      "checked_at": "2026-06-06",
-      "staleness_window_days": 90,
-      "notes": "Open SKILL.md standard (compatibility/metadata/license fields)."
     }
   ]
 }

package/scripts/arch-check.sh

@@ -17,6 +17,24 @@
 
 set -euo pipefail
 
+# Bash version floor: these gates rely on bash 4+ features. Refuse early with a
+# clear message on bash 3.x (e.g. macOS system bash) instead of failing later
+# with a cryptic syntax error (jcgw).
+[ "${BASH_VERSINFO:-0}" -ge 4 ] || { echo 'audit-harness requires bash >= 4' >&2; exit 3; }
+
+# Cross-platform SHA-256: `sha256sum` ships with GNU coreutils (Linux);
+# macOS only has `shasum -a 256`. Both produce identical `<hash>  <file>`
+# output, so downstream awk parsing is unchanged. Same pattern as
+# harness-hash.sh / escape-scan.sh / bias-count.sh.
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256_CMD=(sha256sum)
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256_CMD=(shasum -a 256)
+else
+  echo "arch-check: neither sha256sum nor shasum found in PATH" >&2
+  exit 2
+fi
+
 ROOT="${ROOT:-$(pwd)}"
 JSON_OUT=0
 REPORT_DIR="${ROOT}/reports/arch"
@@ -51,12 +69,12 @@ emit_result() {
     local policy_hash="sha256:0000000000000000000000000000000000000000000000000000000000000000"
     # Best-effort: input_hash is the source tree fingerprint when running against ROOT/src
     if [[ -d "${ROOT}/src" ]]; then
-      input_hash=$(find "${ROOT}/src" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" \) -exec sha256sum {} \; 2>/dev/null | sort | sha256sum | awk '{print "sha256:"$1}')
+      input_hash=$(find "${ROOT}/src" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" \) -exec "${SHA256_CMD[@]}" {} \; 2>/dev/null | sort | "${SHA256_CMD[@]}" | awk '{print "sha256:"$1}')
     fi
     # Hash the architecture rule config (whichever tool's config was used)
     for cfg in .dependency-cruiser.js .dependency-cruiser.cjs .importlinter deptrac.yaml arch-go.yml; do
       if [[ -f "${ROOT}/${cfg}" ]]; then
-        policy_hash=$(sha256sum "${ROOT}/${cfg}" | awk '{print "sha256:"$1}')
+        policy_hash=$("${SHA256_CMD[@]}" "${ROOT}/${cfg}" | awk '{print "sha256:"$1}')
         break
       fi
     done

package/scripts/bias-count.sh

@@ -12,6 +12,23 @@
 
 set -euo pipefail
 
+# Bash version floor: these gates rely on bash 4+ features. Refuse early with a
+# clear message on bash 3.x (e.g. macOS system bash) instead of failing later
+# with a cryptic syntax error (jcgw).
+[ "${BASH_VERSINFO:-0}" -ge 4 ] || { echo 'audit-harness requires bash >= 4' >&2; exit 3; }
+
+# Cross-platform SHA-256: `sha256sum` ships with GNU coreutils (Linux);
+# macOS only has `shasum -a 256`. Both produce identical `<hash>  <file>`
+# output, so downstream awk parsing is unchanged. Mirrors harness-hash.sh.
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256_CMD=(sha256sum)
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256_CMD=(shasum -a 256)
+else
+  echo "bias-count: neither sha256sum nor shasum found in PATH" >&2
+  exit 2
+fi
+
 JSON_OUT=0
 TEST_DIR="tests"
 
@@ -36,7 +53,7 @@ if [ ! -d "$TEST_DIR" ]; then
 fi
 
 # Hash the test directory tree as the "input"
-INPUT_HASH=$(find "$TEST_DIR" -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" -o -name "*.rb" \) -exec sha256sum {} + 2>/dev/null | sort | sha256sum | awk '{print "sha256:"$1}')
+INPUT_HASH=$(find "$TEST_DIR" -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" -o -name "*.rb" \) -exec "${SHA256_CMD[@]}" {} + 2>/dev/null | sort | "${SHA256_CMD[@]}" | awk '{print "sha256:"$1}')
 
 if [[ "$JSON_OUT" -eq 1 ]]; then
   exec 3>&1   # save stdout for the JSON object

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