@bounded-systems/conformance-kit 0.2.0

package/integrity/structure-audit/audit.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// integrity · structure-audit — a deterministic, whole-page structure gate.
+//
+//   node integrity/structure-audit/audit.mjs <distDir> [--check]
+//
+// Validates the document STRUCTURE + reader survivability + the internal link
+// graph, and extracts a content-addressed `structure.json` so the page skeleton is
+// a pure function of source (drift fails CI under --check).
+//
+// Checks (errors fail the gate):
+//   1. reader survivability (articles) — run Mozilla Readability (what Firefox
+//      Reader runs); it must extract an article that still contains the <h1> and
+//      isn't mostly-empty. The free test of "do the semantics survive the CSS being
+//      stripped." Scoped to articles; list/error pages aren't reader targets.
+//   2. outline — exactly one <h1>, no skipped heading levels (all pages).
+//   3. landmarks — at most one <main>; a content page with none is a warning.
+//   4. internal link-graph — every internal href resolves to a served file, an
+//      in-page anchor, or a known deploy-time sidecar; dead links error, and a
+//      served page reachable from nothing is an orphan (warn).
+//
+// Deterministic: same dist → byte-identical structure.json (sorted, hashed).
+//
+// Site-agnostic injection points (all optional, neutral defaults):
+//   $STRUCTURE_AUDIT_SIDECARS  comma-separated deploy-time paths to treat as live
+//                              (e.g. /resume.pdf), beyond the built-in set.
+//   $STRUCTURE_ARTICLE_PREFIX  dir prefix whose pages are "articles" for the reader
+//                              check (default "blog/"); its own index is excluded.
+//   $STRUCTURE_ERROR_PAGE      the error page exempt from the <main>/orphan rules
+//                              (default "404.html").
+//   $STRUCTURE_BASELINE        path to the committed structure.json baseline
+//                              (default: structure.json next to this script — so a
+//                              vendored, hash-pinned copy keeps the baseline in the
+//                              CONSUMER, not in the kit file).
+import { readdir, readFile, writeFile, access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, relative, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseHTML } from "linkedom";
+import { Readability } from "@mozilla/readability";
+
+const dist = resolve(process.argv[2] || process.env.DIST || "dist");
+const CHECK = process.argv.includes("--check");
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+
+const ARTICLE_PREFIX = process.env.STRUCTURE_ARTICLE_PREFIX || "blog/";
+const ERROR_PAGE = process.env.STRUCTURE_ERROR_PAGE || "404.html";
+
+// Generated at deploy, so absent from a local build — treat as resolvable rather
+// than dead. (The post-deploy edge check verifies they serve.) Consumers add their
+// own deploy-time assets via STRUCTURE_AUDIT_SIDECARS (comma-separated), e.g.
+// bd-site's /resume.pdf, which is print-to-pdf'd during deploy.
+const DEPLOY_SIDECARS = ["/rekor", "/provenance.json", "/site.sha256",
+  ...(process.env.STRUCTURE_AUDIT_SIDECARS || "").split(",").map((s) => s.trim()).filter(Boolean)];
+
+async function walk(dir, ext) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const abs = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walk(abs, ext));
+    else if (e.name.endsWith(ext)) out.push(abs);
+  }
+  return out;
+}
+
+// Normalise a served path to a canonical key (drop index.html / .html / trailing /).
+const canon = (p) => {
+  let s = p.replace(/\\/g, "/");
+  if (!s.startsWith("/")) s = "/" + s;
+  s = s.replace(/\/index\.html$/, "/").replace(/\.html$/, "");
+  if (s.length > 1) s = s.replace(/\/$/, "");
+  return s || "/";
+};
+
+const pages = (await walk(dist, ".html")).sort();
+const servedCanon = new Set(pages.map((p) => canon("/" + relative(dist, p))));
+let errors = 0, warns = 0;
+const err = (m) => { console.error(`  ✗ ${m}`); errors++; };
+const warn = (m) => { console.error(`  ⚠ ${m}`); warns++; };
+
+// Resolve an internal href to a canonical served key, or "ok"/"dead".
+async function resolveHref(pageAbs, href) {
+  if (!href || /^(https?:|mailto:|tel:|#|data:)/i.test(href)) return { kind: "skip" };
+  const clean = href.split("#")[0].split("?")[0];
+  if (!clean) return { kind: "skip" };
+  if (DEPLOY_SIDECARS.some((s) => clean === s || clean.startsWith(s + "/"))) return { kind: "ok", key: canon(clean) };
+  const base = clean.startsWith("/") ? join(dist, clean) : resolve(dirname(pageAbs), clean);
+  for (const cand of [base, base + ".html", join(base, "index.html")]) {
+    if (await exists(cand)) return { kind: "ok", key: canon("/" + relative(dist, cand)) };
+  }
+  return { kind: "dead" };
+}
+
+const structure = {};
+const reachable = new Set();
+
+for (const pageAbs of pages) {
+  const rel = relative(dist, pageAbs).replace(/\\/g, "/");
+  const html = await readFile(pageAbs, "utf8");
+  const { document } = parseHTML(html);
+
+  const hs = [...document.querySelectorAll("h1,h2,h3,h4,h5,h6")].map((h) => +h.tagName[1]);
+  const h1s = hs.filter((l) => l === 1).length;
+  if (h1s !== 1) err(`${rel}: ${h1s} <h1> (want exactly 1)`);
+  for (let i = 1; i < hs.length; i++) if (hs[i] - hs[i - 1] > 1) { err(`${rel}: heading jump h${hs[i - 1]}→h${hs[i]} (skipped level)`); break; }
+
+  const mains = document.querySelectorAll("main").length;
+  if (mains > 1) err(`${rel}: ${mains} <main> (want at most 1)`);
+  else if (mains === 0 && rel !== ERROR_PAGE) warn(`${rel}: no <main> landmark`);
+
+  // reader survivability — articles only
+  const isArticle = rel.startsWith(ARTICLE_PREFIX) && rel !== `${ARTICLE_PREFIX}index.html`;
+  let readerOk = null;
+  if (isArticle) {
+    const h1text = (document.querySelector("h1")?.textContent || "").trim();
+    try {
+      const article = new Readability(parseHTML(html).document).parse();
+      const txt = (article?.textContent || "").replace(/\s+/g, " ").trim();
+      readerOk = !!article && txt.length > 200 && (!h1text || article.title?.includes(h1text.slice(0, 24)) || txt.includes(h1text.slice(0, 24)));
+      if (!readerOk) err(`${rel}: reader view didn't extract the article + its <h1> (semantics may be CSS-only)`);
+    } catch (e) { err(`${rel}: Readability threw (${e.message})`); readerOk = false; }
+  }
+
+  const links = [];
+  for (const a of document.querySelectorAll("a[href]")) {
+    const href = a.getAttribute("href");
+    const r = await resolveHref(pageAbs, href);
+    if (r.kind === "dead") err(`${rel}: dead internal link → ${href}`);
+    if (r.kind === "ok") reachable.add(r.key);
+    if (href && href.startsWith("/")) links.push(href);
+  }
+
+  structure[rel] = { h1: (document.querySelector("h1")?.textContent || "").trim().slice(0, 80), outline: hs.join(""), mains, readerOk, internalLinks: links.sort() };
+}
+
+// orphans — served pages reachable from nothing (home + error page are legit roots)
+const errorKey = canon("/" + ERROR_PAGE);
+for (const key of servedCanon) {
+  if (key === "/" || key === errorKey) continue;
+  if (!reachable.has(key)) warn(`orphan: ${key} is not linked from any page`);
+}
+
+const json = JSON.stringify(Object.fromEntries(Object.keys(structure).sort().map((k) => [k, structure[k]])), null, 2) + "\n";
+const digest = createHash("sha256").update(json).digest("hex").slice(0, 12);
+// Baseline lives in the CONSUMER (default: next to this script), so a vendored,
+// hash-pinned copy of the kit isn't mutated by --check. Override with $STRUCTURE_BASELINE.
+const outPath = process.env.STRUCTURE_BASELINE
+  ? resolve(process.env.STRUCTURE_BASELINE)
+  : join(dirname(fileURLToPath(import.meta.url)), "structure.json");
+
+if (CHECK) {
+  const current = (await exists(outPath)) ? await readFile(outPath, "utf8") : "";
+  if (current !== json) { console.error("✗ structure.json is stale — regenerate and commit."); errors++; }
+} else {
+  await writeFile(outPath, json);
+}
+
+console.log(`structure-audit: ${pages.length} pages · sha256:${digest} · ${errors} error(s) · ${warns} warn(s)`);
+if (errors) { console.error(`✗ structure-audit failed (${errors})`); process.exit(1); }
+console.log("✓ structure-audit passed");

package/integrity/structure-audit/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@bounded-systems/structure-audit",
+  "version": "0.1.0",
+  "description": "Deterministic whole-page structure gate: reader survivability + outline + landmarks + internal link-graph.",
+  "type": "module",
+  "bin": { "structure-audit": "./audit.mjs" },
+  "dependencies": {
+    "@mozilla/readability": "^0.5.0",
+    "linkedom": "^0.18.0"
+  },
+  "license": "MIT"
+}

package/integrity/verify/README.md

@@ -0,0 +1,40 @@
+# @bounded-systems/verify
+
+Standalone, out-of-page verifier. Given a deployed site URL (or a local `dist/`
+directory) carrying a published Sigstore **bundle**, it proves **out of band** that
+the served bytes are exactly what an allowed identity built and logged — offline,
+no trust in the page itself.
+
+What it checks, in-process via [`sigstore-js`](https://github.com/sigstore/sigstore-js):
+
+- signature over the whole-site manifest;
+- certificate chain to the Fulcio root (bundled trusted root — **no network**);
+- Rekor inclusion proof (offline; not the deprecated Rekor query API);
+- issuer + certificate SAN matched against the site's declared builder identity;
+- then re-hashes every served file against the signed manifest, tolerating known,
+  named CDN edge transforms (the signed body must still be intact underneath).
+
+## Usage
+
+```sh
+# against a deployed site
+deno run -A jsr:@bounded-systems/verify https://bounded.tools
+
+# against a local build directory
+deno run -A jsr:@bounded-systems/verify ./dist
+```
+
+Inputs are read from the target: `provenance.json` (the builder identity — nothing
+is hardcoded), the whole-site `site.sha256` manifest, and the `.sigstore.json`
+bundle. Exit code `0` on success, `1` on any verification failure.
+
+## Provenance
+
+This is a **vendored** copy of the Sigstore verifier, kept here so sites can pull it
+into a hermetic build. The **canonical, published** source of the
+[`@bounded-systems/verify`](https://jsr.io/@bounded-systems/verify) JSR package now
+lives in its own repo, [`bounded-systems/verify`](https://github.com/bounded-systems/verify)
+— that repo owns the package manifest and the keyless GitHub Actions OIDC release.
+The copy here is kept byte-for-byte in sync with it; cut releases there, not here.
+
+MIT

package/integrity/verify/verify.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// integrity · verify — the standalone, out-of-page verifier (the "real" one from
+// integrity/verifier-decision.md). Takes a URL (or local dist) and proves, OUT OF
+// BAND, that the served site is exactly what an allowed identity built and logged.
+//
+//   node integrity/verify/verify.mjs https://bounded.tools
+//   node integrity/verify/verify.mjs ./dist
+//
+// Unlike the zero-dep verify-site.mjs (which shells out to cosign and SKIPS the
+// signature step when cosign is absent), this verifies the published Sigstore
+// BUNDLE cryptographically IN-PROCESS via sigstore-js:
+//   - signature over the whole-site manifest
+//   - certificate chain to the Fulcio root (bundled trusted root — no network)
+//   - Rekor inclusion proof (offline; NOT the deprecated Rekor query API)
+//   - issuer enforced by sigstore-js; the cert SAN regex-matched here (cosign-style)
+// then re-hashes every served file against the signed manifest (tolerating known,
+// named CDN edge transforms — the signed body must still be intact underneath).
+//
+// Why a bundle, not a Rekor query: Rekor v2 removed get-by-index/leaf-hash, so the
+// query path is a dead end. The bundle we publish carries its own inclusion proof,
+// so verification is offline and survives the v2 transition. SRI-pinnable and
+// npm-publishable (with its own Sigstore provenance) — the same core a browser
+// extension or CI policy would consume.
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { verify as sigstoreVerify } from "sigstore";
+
+const target = process.argv[2];
+if (!target) { console.error("usage: verify <https://site | ./dist>"); process.exit(2); }
+const isUrl = /^https?:\/\//.test(target);
+const base = isUrl ? target.replace(/\/$/, "") : target;
+const ISSUER = "https://token.actions.githubusercontent.com";
+const sha256hex = (buf) => createHash("sha256").update(buf).digest("hex");
+
+async function load(path) {
+  if (isUrl) {
+    const res = await fetch(`${base}/${path}`, { cache: "no-store" });
+    if (!res.ok) throw new Error(`GET /${path} → ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+  return readFile(join(base, path));
+}
+
+// Known, named CDN edge transforms (see verify-site.mjs): a legitimate edge may
+// rewrite a response; if stripping a NAMED transform restores the signed hash, the
+// body is intact and only the edge added markup. Anything else is a real mismatch.
+const KNOWN_EDGE_INJECTIONS = [
+  { name: "cloudflare-js-detections", applies: (p) => /\.html$/.test(p),
+    re: /<script\b[^>]*>(?:(?!<\/script>)[\s\S])*?(?:__CF\$cv\$params|cdn-cgi\/challenge-platform)(?:(?!<\/script>)[\s\S])*?<\/script>/g },
+  { name: "cloudflare-managed-robots", applies: (p) => /(^|\/)robots\.txt$/.test(p),
+    re: /^[\s\S]*?# END Cloudflare Managed Content\n+/ },
+];
+const stripKnownEdge = (buf, path) => {
+  let s = buf.toString("utf8"); const hit = [];
+  for (const r of KNOWN_EDGE_INJECTIONS) { if (!r.applies(path)) continue; const n = s.replace(r.re, ""); if (n !== s) { hit.push(r.name); s = n; } }
+  return { stripped: Buffer.from(s, "utf8"), hit };
+};
+
+let failures = 0;
+const log = (ok, msg) => { console.log(`${ok ? "✓" : "✗"} ${msg}`); if (!ok) failures++; };
+
+// load provenance + the signed manifest + its bundle
+const provenance = JSON.parse((await load("provenance.json")).toString("utf8"));
+const repo = provenance?.builder?.repository || "";
+const identityRe = `^https://github.com/${repo}/`;
+const manifest = await load("site.sha256");
+const bundle = JSON.parse((await load("site.sha256.sigstore.json")).toString("utf8"));
+
+console.log(`· site: ${base}`);
+console.log(`· builder: ${repo} @ ${(provenance?.builder?.commit || "").slice(0, 7)} · rekor#${provenance?.siteManifest?.rekorLogIndex ?? "?"}`);
+if (provenance?.builtAt) {
+  const ms = Date.now() - Date.parse(provenance.builtAt);
+  const age = Number.isFinite(ms) ? (ms < 36e5 ? `${Math.round(ms / 6e4)}m` : ms < 864e5 ? `${Math.round(ms / 36e5)}h` : `${Math.round(ms / 864e5)}d`) : "?";
+  console.log(`· built: ${provenance.builtAt} (${age} ago)`);
+}
+
+// 1: cryptographic bundle verification, in-process, offline
+try {
+  const signer = await sigstoreVerify(bundle, manifest, { certificateIssuer: ISSUER });
+  const san = signer?.identity?.subjectAlternativeName || "";
+  if (!new RegExp(identityRe).test(san)) throw new Error(`cert identity ${san} !~ ${identityRe}`);
+  log(true, `bundle verified — signature + Fulcio cert + Rekor inclusion (offline), identity ${san}`);
+} catch (e) {
+  log(false, `bundle verification FAILED: ${e.message}`);
+}
+
+// 2: byte-for-byte integrity of every served file (edge-transform tolerant)
+const entries = manifest.toString("utf8").trim().split("\n").filter(Boolean).map((l) => {
+  const i = l.indexOf("  "); return { hash: l.slice(0, i), path: l.slice(i + 2) };
+});
+let mismatches = 0, edged = 0; const edgeNames = new Set();
+for (const { hash, path } of entries) {
+  try {
+    const bytes = await load(path);
+    if (sha256hex(bytes) === hash) continue;
+    if (isUrl) {
+      const { stripped, hit } = stripKnownEdge(bytes, path);
+      if (hit.length && sha256hex(stripped) === hash) { edged++; hit.forEach((n) => edgeNames.add(n)); continue; }
+    }
+    mismatches++; console.log(`  ✗ ${path}: ${sha256hex(bytes).slice(0, 12)}… ≠ ${hash.slice(0, 12)}…`);
+  } catch (e) { mismatches++; console.log(`  ✗ ${path}: ${e.message}`); }
+}
+log(mismatches === 0, `${entries.length} served files match the signed manifest${mismatches ? ` (${mismatches} mismatch)` : edged ? ` (${edged} after stripping known edge injections: ${[...edgeNames].join(", ")})` : ""}`);
+
+console.log(failures ? `\n✗ verification FAILED (${failures})` : `\n✓ verified: ${base} is exactly what ${repo} built and logged`);
+process.exit(failures ? 1 : 0);

package/integrity/verify-site.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// integrity · verify-site — independently verify a deployed site against its own
+// signed, whole-site provenance. The honest counterpart to the in-page badge:
+// run this from OUTSIDE the page (your shell, CI, an extension) so trust doesn't
+// come from anything the page itself computes.
+//
+//   node integrity/verify-site.mjs https://bounded.tools
+//   node integrity/verify-site.mjs ./dist            # a local build dir
+//
+// What it does:
+//   1. loads /provenance.json (identity, Rekor index, OCI ref)
+//   2. loads /site.sha256 + /site.sha256.sigstore.json (the signed manifest)
+//   3. if `cosign` is on PATH: `cosign verify-blob` the manifest against the
+//      builder's OIDC identity + Rekor (the real cryptographic check). Otherwise
+//      prints the exact recipe and marks the signature step SKIPPED.
+//   4. re-hashes every file the manifest lists (fetched live, or read locally) and
+//      checks it byte-for-byte — integrity of the actual served bytes. In live-URL
+//      mode it tolerates ONE known, benign CDN transform (Cloudflare's JS-detection
+//      beacon injected into HTML): if stripping it makes the file match, that's a
+//      pass-with-note, since the signed body is intact and only the edge added a
+//      named script. The edge-independent ground truth is the signed OCI artifact.
+// Exit 0 iff every checked file matches (directly or after a known edge strip) AND
+// (cosign verified OR was skipped with a printed recipe). Exit 1 on any real
+// mismatch or a failed cosign verify.
+//
+// Dependency-free: node:crypto + fetch + cosign (optional, shelled out). Designed
+// to later publish to npm with Sigstore provenance and be consumed by a CLI, a
+// browser extension, or CI policy.
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { readFile, mkdtemp, writeFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const target = process.argv[2];
+if (!target) {
+  console.error("usage: verify-site <https://site | ./dist>");
+  process.exit(2);
+}
+const isUrl = /^https?:\/\//.test(target);
+const base = isUrl ? target.replace(/\/$/, "") : target;
+const sha256hex = (buf) => createHash("sha256").update(buf).digest("hex");
+
+async function load(path) {
+  if (isUrl) {
+    const res = await fetch(`${base}/${path}`);
+    if (!res.ok) throw new Error(`GET /${path} → ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+  return readFile(join(base, path));
+}
+
+let failures = 0;
+const log = (ok, msg) => { console.log(`${ok ? "✓" : "✗"} ${msg}`); if (!ok) failures++; };
+
+// 1 + 2: provenance + signed manifest
+const provenance = JSON.parse((await load("provenance.json")).toString("utf8"));
+const repo = provenance?.builder?.repository || "";
+const manifest = (await load("site.sha256")).toString("utf8");
+const bundle = (await load("site.sha256.sigstore.json")).toString("utf8");
+console.log(`· site: ${base}`);
+console.log(`· builder: ${repo} @ ${(provenance?.builder?.commit || "").slice(0, 7)} · rekor#${provenance?.siteManifest?.rekorLogIndex ?? "?"}`);
+if (provenance?.builtAt) {
+  const ms = Date.now() - Date.parse(provenance.builtAt);
+  const age = Number.isFinite(ms)
+    ? (ms < 36e5 ? `${Math.round(ms / 6e4)}m` : ms < 864e5 ? `${Math.round(ms / 36e5)}h` : `${Math.round(ms / 864e5)}d`)
+    : "?";
+  console.log(`· built: ${provenance.builtAt} (${age} ago) — authoritative time is the Rekor entry's integratedTime at /rekor`);
+}
+
+// 3: signature (cosign if available)
+const cosign = spawnSync("cosign", ["version"], { stdio: "ignore" });
+if (cosign.status === 0) {
+  const dir = await mkdtemp(join(tmpdir(), "verify-site-"));
+  await writeFile(join(dir, "site.sha256"), manifest);
+  await writeFile(join(dir, "site.sha256.sigstore.json"), bundle);
+  const r = spawnSync("cosign", [
+    "verify-blob",
+    "--bundle", join(dir, "site.sha256.sigstore.json"),
+    "--certificate-identity-regexp", `^https://github.com/${repo}/`,
+    "--certificate-oidc-issuer", "https://token.actions.githubusercontent.com",
+    join(dir, "site.sha256"),
+  ], { encoding: "utf8" });
+  log(r.status === 0, `cosign verify-blob (identity ^github.com/${repo}/ + Rekor)`);
+  if (r.status !== 0) console.error((r.stderr || "").trim());
+} else {
+  console.log("· cosign not found — signature check SKIPPED. Verify it out-of-band:");
+  console.log(`    ${(provenance?.siteManifest?.verify || "").split("\n").join("\n    ")}`);
+}
+
+// 4: byte-for-byte integrity of every listed file.
+//
+// Honesty caveat for live-URL mode: a CDN may inject markup into HTML responses,
+// so served HTML can differ from the signed bytes on a perfectly legitimate deploy.
+// Cloudflare's "JavaScript Detections" adds a bot beacon (`__CF$cv$params` /
+// `cdn-cgi/challenge-platform`) before </body>. We detect that ONE known, benign
+// transform, strip it, and re-hash: if it then matches, the signed body is intact
+// and only the edge added a named script — reported as a PASS WITH NOTE, not a
+// silent pass and not a false alarm. Anything else is a real mismatch. The
+// edge-independent ground truth is the signed OCI artifact (see provenance.json
+// `ociArtifact.verify`), which no CDN sits in front of.
+const KNOWN_EDGE_INJECTIONS = [
+  {
+    // Cloudflare "JavaScript Detections": one <script> naming the challenge beacon,
+    // injected before </body> on HTML responses.
+    name: "cloudflare-js-detections",
+    applies: (p) => /\.html$/.test(p),
+    re: /<script\b[^>]*>(?:(?!<\/script>)[\s\S])*?(?:__CF\$cv\$params|cdn-cgi\/challenge-platform)(?:(?!<\/script>)[\s\S])*?<\/script>/g,
+  },
+  {
+    // Cloudflare "Managed robots.txt" / AI-crawler control: a managed block prepended
+    // to robots.txt; our signed file survives intact as the tail after the END marker.
+    name: "cloudflare-managed-robots",
+    applies: (p) => /(^|\/)robots\.txt$/.test(p),
+    re: /^[\s\S]*?# END Cloudflare Managed Content\n+/,
+  },
+];
+const stripKnownEdge = (buf, path) => {
+  let s = buf.toString("utf8");
+  const hit = [];
+  for (const rule of KNOWN_EDGE_INJECTIONS) {
+    if (!rule.applies(path)) continue;
+    const next = s.replace(rule.re, "");
+    if (next !== s) { hit.push(rule.name); s = next; }
+  }
+  return { stripped: Buffer.from(s, "utf8"), hit };
+};
+
+const entries = manifest.trim().split("\n").filter(Boolean).map((l) => {
+  const [hash, ...rest] = l.split("  ");
+  return { hash, path: rest.join("  ") };
+});
+let mismatches = 0;
+let edgeAdjusted = 0;
+const edgeNames = new Set();
+for (const { hash, path } of entries) {
+  try {
+    const bytes = await load(path);
+    if (sha256hex(bytes) === hash) continue;
+    // mismatch — in live mode, try removing known, named edge injections before failing
+    if (isUrl) {
+      const { stripped, hit } = stripKnownEdge(bytes, path);
+      if (hit.length && sha256hex(stripped) === hash) {
+        edgeAdjusted++; hit.forEach((n) => edgeNames.add(n));
+        console.log(`  ~ ${path}: matches after removing edge injection (${hit.join(", ")})`);
+        continue;
+      }
+    }
+    mismatches++;
+    console.log(`  ✗ ${path}: ${sha256hex(bytes).slice(0, 12)}… ≠ ${hash.slice(0, 12)}…`);
+  } catch (e) { mismatches++; console.log(`  ✗ ${path}: ${e.message}`); }
+}
+const note = edgeAdjusted ? ` (${edgeAdjusted} matched only after stripping a known edge injection: ${[...edgeNames].join(", ")})` : "";
+log(mismatches === 0, `${entries.length} files match the signed manifest${mismatches ? ` (${mismatches} mismatch)` : note}`);
+if (edgeAdjusted && mismatches === 0) {
+  console.log(`  · the signed body is intact; your CDN rewrites these files on serve. For byte-exact serving, disable it, or verify the signed OCI artifact (edge-independent).`);
+}
+
+console.log(failures ? `\n✗ verification FAILED (${failures})` : `\n✓ verified: served bytes match this build's signed provenance`);
+process.exit(failures ? 1 : 0);

package/lib/config.mjs

@@ -0,0 +1,36 @@
+// lib/config — tiny, dependency-free helpers for injecting site values into the
+// kit's tools via env vars / CLI args. NOTHING here is site-specific; every value
+// has a neutral default and is overridden by the consumer.
+import { resolve } from "node:path";
+
+// Read an env var with a fallback. Empty string counts as "set" only if keepEmpty.
+export const env = (name, fallback = undefined, { keepEmpty = false } = {}) => {
+  const v = process.env[name];
+  if (v == null) return fallback;
+  if (v === "" && !keepEmpty) return fallback;
+  return v;
+};
+
+// Parse a comma-separated env var into a trimmed, non-empty string[].
+export const envList = (name, fallback = []) => {
+  const v = process.env[name];
+  if (v == null || v === "") return fallback;
+  return v.split(",").map((s) => s.trim()).filter(Boolean);
+};
+
+// Parse a numeric env var; fall back if missing/NaN.
+export const envNum = (name, fallback) => {
+  const v = process.env[name];
+  if (v == null || v === "") return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+// Resolve a "dist" / build-output dir from (argv slot, then $DIST, then default),
+// absolute against the current working directory.
+export const resolveDist = ({ arg, envName = "DIST", fallback = "dist" } = {}) =>
+  resolve(arg || process.env[envName] || fallback);
+
+// Positional argv (after `node script.mjs`), excluding --flags.
+export const positionals = () => process.argv.slice(2).filter((a) => !a.startsWith("--"));
+export const hasFlag = (flag) => process.argv.includes(flag);

package/lib/schema-validate.mjs

@@ -0,0 +1,68 @@
+// Minimal, dependency-free JSON Schema validator — enough for the keywords the
+// kit's contracts use: type, properties, items, required, enum, pattern,
+// additionalProperties (bool/schema), and $ref into #/definitions. `format` is
+// accepted but not enforced (advisory). Returns an array of error strings (empty
+// = valid). No-dependency, hand-rolled — usable in hermetic CI.
+//
+// Site-agnostic: a pure function (schema, data) → string[]. Extracted verbatim
+// from bdelanghe/site/schema-validate.mjs.
+
+const typeOk = (t, v) => {
+  switch (t) {
+    case "string": return typeof v === "string";
+    case "number": return typeof v === "number";
+    case "integer": return Number.isInteger(v);
+    case "boolean": return typeof v === "boolean";
+    case "object": return v !== null && typeof v === "object" && !Array.isArray(v);
+    case "array": return Array.isArray(v);
+    case "null": return v === null;
+    default: return true;
+  }
+};
+const kindOf = (v) => Array.isArray(v) ? "array" : v === null ? "null" : typeof v;
+
+export function validateSchema(rootSchema, data) {
+  const errors = [];
+  const resolve = (schema) => {
+    let s = schema, guard = 0;
+    while (s && s.$ref && guard++ < 16) {
+      const path = s.$ref.replace(/^#\//, "").split("/");
+      s = path.reduce((node, p) => node?.[p], rootSchema) ?? {};
+    }
+    return s;
+  };
+
+  const walk = (schema, v, path) => {
+    schema = resolve(schema);
+    if (!schema || typeof schema !== "object") return;
+    const at = path || "/";
+
+    if (schema.type) {
+      const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+      if (!types.some((t) => typeOk(t, v))) {
+        errors.push(`${at}: expected ${types.join("|")}, got ${kindOf(v)}`);
+        return; // type wrong — deeper checks would be noise
+      }
+    }
+    if (schema.enum && !schema.enum.some((e) => e === v)) errors.push(`${at}: ${JSON.stringify(v)} not in enum`);
+    if (typeof v === "string" && schema.pattern && !new RegExp(schema.pattern).test(v)) {
+      errors.push(`${at}: "${v}" does not match pattern ${schema.pattern}`);
+    }
+
+    if (typeOk("object", v)) {
+      const props = schema.properties || {};
+      for (const req of schema.required || []) if (!(req in v)) errors.push(`${at}: missing required "${req}"`);
+      for (const [k, val] of Object.entries(v)) {
+        if (props[k]) walk(props[k], val, `${at === "/" ? "" : at}/${k}`);
+        else if (schema.additionalProperties === false) errors.push(`${at}: unexpected property "${k}"`);
+        else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+          walk(schema.additionalProperties, val, `${at === "/" ? "" : at}/${k}`);
+        }
+      }
+    }
+    if (typeOk("array", v) && schema.items) v.forEach((item, i) => walk(schema.items, item, `${at === "/" ? "" : at}[${i}]`));
+  };
+
+  walk(rootSchema, data, "");
+  return errors;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@bounded-systems/conformance-kit",
+  "version": "0.2.0",
+  "description": "Standalone, site-agnostic web-conformance toolkit: integrity tooling + build gates + provenance generators, all parameterized so a site vendors one kit instead of duplicating scripts.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bounded-systems/conformance-kit.git"
+  },
+  "bin": {
+    "ck-gen-sitemanifest": "./integrity/gen-sitemanifest.mjs",
+    "ck-gen-provenance": "./integrity/gen-provenance.mjs",
+    "ck-verify-site": "./integrity/verify-site.mjs",
+    "ck-http-probe": "./integrity/http-probe.mjs",
+    "ck-structure-audit": "./integrity/structure-audit/audit.mjs",
+    "ck-gen-sbom": "./gates/sbom/gen-sbom.mjs",
+    "ck-check-sbom": "./gates/sbom/check-sbom.mjs",
+    "ck-shacl-runner": "./gates/shacl-runner.mjs",
+    "ck-seo-gate": "./gates/seo-gate.mjs",
+    "ck-axe-gate": "./gates/axe-gate.mjs",
+    "ck-vuln-gate": "./gates/vuln-gate.mjs",
+    "ck-html-validator-gate": "./gates/html-validator-gate.mjs",
+    "ck-baseline-gate": "./gates/baseline-gate.mjs",
+    "ck-readability-gate": "./gates/readability-gate.mjs",
+    "ck-commonmark-runner": "./gates/commonmark-runner.mjs",
+    "ck-gen-cid": "./generators/gen-cid.mjs",
+    "ck-gen-identity": "./generators/gen-identity.mjs",
+    "ck-gen-snapshots": "./generators/gen-snapshots.mjs"
+  },
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
+  "files": [
+    "gates",
+    "generators",
+    "integrity",
+    "emitters",
+    "lib",
+    "provenance.json",
+    "vendor.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./gates/*": "./gates/*",
+    "./gates/conformance/*": "./gates/conformance/*",
+    "./generators/*": "./generators/*",
+    "./integrity/*": "./integrity/*",
+    "./emitters/*": "./emitters/*",
+    "./lib/*": "./lib/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.5.0",
+    "@zazuko/env-node": "^2.1.5",
+    "axe-core": "^4.10.0",
+    "jsonld": "^9.0.0",
+    "linkedom": "^0.18.0",
+    "n3": "^1.17.3",
+    "rdf-validate-shacl": "^0.5.10",
+    "sigstore": "^5.0.0",
+    "stylelint": "^17.14.0",
+    "stylelint-plugin-use-baseline": "^1.4.4",
+    "turndown": "^7.2.4",
+    "vnu-jar": "^26.6.24"
+  }
+}