@bounded-systems/conformance-kit 0.2.0

package/generators/gen-identity.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// gen-identity — emit a did:web identity + a résumé (or any JSON subject) as a W3C
+// Verifiable Credential 2.0.
+//
+//   IDENTITY_DOMAIN=example.com IDENTITY_REPO=owner/repo \
+//     node generators/gen-identity.mjs
+//
+// Writes:
+//   $DIST/.well-known/did.json     — minimal did:web:<DOMAIN> document
+//   $DIST/api/v1/resume.vc.json    — the subject as a W3C VC 2.0; credentialSubject
+//                                    is the input JSON verbatim, issuer is the did
+//
+// Keyless by design: there is no held signing key. The VC's proof is an ENVELOPING
+// Sigstore bundle minted in CI (cosign sign-blob → Fulcio cert from the GitHub
+// Actions OIDC identity → Rekor), served alongside as resume.vc.json.sigstore.json.
+// So the did:web document advertises the Sigstore verification path as a service
+// rather than a static public key — bound to $IDENTITY_REPO's OIDC identity.
+//
+// Site-agnostic injection:
+//   $IDENTITY_DOMAIN          domain for the DID + site origin (required).
+//   $IDENTITY_REPO            "owner/repo" for the cert-identity regexp (required).
+//   $DIST                     output dir (default: cwd/dist).
+//   $IDENTITY_SUBJECT         path to the credentialSubject JSON (default:
+//                             $DIST/resume.json).
+//   $IDENTITY_SUBJECT_SCHEMA  optional JSON Schema the subject must satisfy
+//                             (validated with the kit's schema-validate.mjs).
+//   $IDENTITY_VC_NAME         VC `name` (default: "<subject.basics.name> — Résumé").
+//   $IDENTITY_VC_DESCRIPTION  VC `description` (default: generic).
+//   $IDENTITY_VALID_FROM_PATH dotted path into the subject for validFrom (default:
+//                             "meta.lastModified"); omitted if absent.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { validateSchema } from "../lib/schema-validate.mjs";
+
+const DOMAIN = process.env.IDENTITY_DOMAIN;
+const REPO = process.env.IDENTITY_REPO;
+if (!DOMAIN || !REPO) { console.error("✗ gen-identity: IDENTITY_DOMAIN and IDENTITY_REPO are required"); process.exit(2); }
+
+const dist = resolve(process.cwd(), process.env.DIST || "dist");
+const SITE = `https://${DOMAIN}`;
+const DID = `did:web:${DOMAIN}`;
+const subjectPath = process.env.IDENTITY_SUBJECT || join(dist, "resume.json");
+const validFromPath = process.env.IDENTITY_VALID_FROM_PATH || "meta.lastModified";
+
+const readJson = async (p) => JSON.parse(await readFile(p, "utf8"));
+const writeJson = async (p, obj) => { await mkdir(dirname(p), { recursive: true }); await writeFile(p, JSON.stringify(obj, null, 2) + "\n"); };
+const dotGet = (obj, path) => path.split(".").reduce((o, k) => o?.[k], obj);
+
+const subject = await readJson(subjectPath);
+const subjectName = subject?.basics?.name || DOMAIN;
+const vcName = process.env.IDENTITY_VC_NAME || `${subjectName} — Résumé`;
+const vcDescription = process.env.IDENTITY_VC_DESCRIPTION ||
+  `Issued as a Verifiable Credential. The cryptographic proof is an enveloping Sigstore bundle served alongside (resume.vc.json.sigstore.json), keyless and bound to the source repo's GitHub Actions OIDC identity.`;
+
+// ---- did:web document --------------------------------------------------------
+// Minimal + honest: no verificationMethod, because there is no held key. The
+// assertion path is keyless Sigstore (Fulcio/Rekor), surfaced as a service so a
+// verifier knows exactly how to check a credential this DID issues.
+const did = {
+  "@context": [
+    "https://www.w3.org/ns/did/v1",
+    "https://w3id.org/security/suites/jws-2020/v1",
+  ],
+  id: DID,
+  controller: DID,
+  alsoKnownAs: [SITE, `${SITE}/`],
+  service: [
+    { id: `${DID}#resume`, type: "VerifiableCredentialService", serviceEndpoint: `${SITE}/api/v1/resume.vc.json` },
+    { id: `${DID}#profile`, type: "LinkedDomains", serviceEndpoint: SITE },
+    {
+      id: `${DID}#sigstore`,
+      type: "SigstoreKeylessVerification",
+      serviceEndpoint: {
+        oidcIssuer: "https://token.actions.githubusercontent.com",
+        certificateIdentityRegexp: `^https://github.com/${REPO}/`,
+        transparencyLog: "https://rekor.sigstore.dev",
+        note: "Credentials are signed with an enveloping Sigstore bundle (e.g. resume.vc.json.sigstore.json), not an embedded key proof.",
+      },
+    },
+  ],
+};
+
+// ---- subject as a Verifiable Credential 2.0 ---------------------------------
+// credentialSubject is the input JSON VERBATIM (so it keeps satisfying any schema
+// it was built against). validFrom is a content fact (a dotted path into the
+// subject), never a wall clock — keeps the VC deterministic.
+const validFrom = dotGet(subject, validFromPath);
+const vc = {
+  "@context": ["https://www.w3.org/ns/credentials/v2"],
+  id: `${SITE}/api/v1/resume.vc.json`,
+  type: ["VerifiableCredential"],
+  issuer: DID,
+  ...(validFrom ? { validFrom } : {}),
+  name: vcName,
+  description: vcDescription,
+  credentialSubject: subject,
+};
+
+await writeJson(join(dist, ".well-known", "did.json"), did);
+await writeJson(join(dist, "api", "v1", "resume.vc.json"), vc);
+
+// ---- self-checks -------------------------------------------------------------
+if (process.env.IDENTITY_SUBJECT_SCHEMA) {
+  const schema = await readJson(process.env.IDENTITY_SUBJECT_SCHEMA);
+  const errs = validateSchema(schema, vc.credentialSubject);
+  if (errs.length) {
+    console.error("✗ VC credentialSubject no longer satisfies its schema:");
+    for (const e of errs) console.error(`    ${e}`);
+    process.exit(1);
+  }
+}
+const vcErrs = [];
+if (vc["@context"]?.[0] !== "https://www.w3.org/ns/credentials/v2") vcErrs.push("missing/!first VC 2.0 @context");
+if (!Array.isArray(vc.type) || !vc.type.includes("VerifiableCredential")) vcErrs.push("type must include VerifiableCredential");
+if (!vc.issuer) vcErrs.push("missing issuer");
+if (!vc.credentialSubject) vcErrs.push("missing credentialSubject");
+if (did.id !== DID) vcErrs.push("did id mismatch");
+if (vcErrs.length) { console.error("✗ identity documents malformed:"); for (const e of vcErrs) console.error(`    ${e}`); process.exit(1); }
+
+console.log(`✓ identity: ${DID} → .well-known/did.json · VC 2.0 → api/v1/resume.vc.json (keyless-signed in CI)`);

package/generators/gen-snapshots.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Reader-view snapshot generator — for every built page, emit a clean READER
+// extraction (the same Readability engine that powers Firefox/Safari Reader) as
+// both HTML and Markdown. The Markdown is the durable, analysis-friendly twin of
+// the page: machine-readable, diffable, and far easier to run NLP / LLM analysis
+// over than scraping live HTML — and it doubles as the AI-readable Markdown sibling
+// (`semantic.ai-readability`). A non-empty extraction is also the PROOF of the
+// "reader survivability" the structure-audit grades (`readerOk`).
+//
+//   node generators/gen-snapshots.mjs [distDir]    # write <page>.reader.{html,md}
+//
+// Pure (no browser, no network): linkedom parses the DOM, @mozilla/readability
+// extracts the article, turndown renders Markdown. (The PRINTED/PDF view needs a
+// real print-CSS renderer — tezcatl --pdf locally — and is a separate generator.)
+//
+// Config-driven; NOTHING about any one site is hard-coded:
+//   argv[2] / $SNAPSHOT_DIST   built output dir                  (default: "dist")
+//   $SNAPSHOT_PAGES           comma list of page paths under dist (default: every *.html)
+//   $SNAPSHOT_BASE_URL        site origin, recorded as `source` in the front-matter
+//   $SNAPSHOT_SUFFIX          output basename suffix              (default: ".reader")
+//
+// The pure extract/markdown functions are exported for unit testing.
+import { writeFile, readFile, readdir, access } from "node:fs/promises";
+import { resolve, join, relative, dirname, basename, extname } from "node:path";
+import { parseHTML } from "linkedom";
+import { Readability } from "@mozilla/readability";
+import TurndownService from "turndown";
+
+// ── Pure core (browser-free; unit-testable) ──────────────────────────────────
+
+/** Extract the reader view of an HTML document. Returns null when Readability
+ *  cannot find article content (e.g. a nav-only or empty page). */
+export function extractReader(html, { url = "" } = {}) {
+  const { document } = parseHTML(html);
+  const article = new Readability(document).parse();
+  if (!article || !article.content) return null;
+  return {
+    url,
+    title: article.title || "",
+    byline: article.byline || "",
+    excerpt: article.excerpt || "",
+    siteName: article.siteName || "",
+    length: article.length || 0,
+    contentHtml: article.content,
+    text: article.textContent || "",
+  };
+}
+
+const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced", bulletListMarker: "-" });
+
+/** Render a reader extraction to Markdown with a small YAML front-matter (title,
+ *  byline, excerpt, source) so the snapshot is self-describing for analysis. */
+export function toMarkdown(reader) {
+  const q = (s) => JSON.stringify(String(s));
+  const fm = [
+    "---",
+    `title: ${q(reader.title)}`,
+    reader.byline ? `byline: ${q(reader.byline)}` : null,
+    reader.excerpt ? `excerpt: ${q(reader.excerpt)}` : null,
+    reader.url ? `source: ${reader.url}` : null,
+    "---",
+  ].filter((x) => x != null).join("\n");
+  return `${fm}\n\n${turndown.turndown(reader.contentHtml).trim()}\n`;
+}
+
+// ── Impure runner ────────────────────────────────────────────────────────────
+
+async function walkHtml(dir, base = dir) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkHtml(p, base));
+    else if (e.name.endsWith(".html")) out.push(p);
+  }
+  return out;
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const dist = resolve(process.argv[2] && !process.argv[2].startsWith("--") ? process.argv[2] : process.env.SNAPSHOT_DIST || "dist");
+  const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+  if (!(await exists(dist))) { console.error(`✗ gen-snapshots: ${dist} not found — build first.`); process.exit(2); }
+
+  const suffix = process.env.SNAPSHOT_SUFFIX || ".reader";
+  const baseUrl = (process.env.SNAPSHOT_BASE_URL || "").replace(/\/$/, "");
+  let pages = (process.env.SNAPSHOT_PAGES || "").split(",").map((s) => s.trim().replace(/^\//, "")).filter(Boolean);
+  pages = pages.length ? pages.map((p) => resolve(dist, p)) : (await walkHtml(dist)).sort();
+
+  let wrote = 0, skipped = 0;
+  for (const file of pages) {
+    const rel = relative(dist, file);
+    const url = baseUrl ? `${baseUrl}/${rel.replace(/index\.html$/, "").replace(/\.html$/, "")}` : "";
+    const reader = extractReader(await readFile(file, "utf8"), { url });
+    if (!reader) { console.error(`  · skipped ${rel} (no article content)`); skipped++; continue; }
+    const stem = join(dirname(file), basename(file, extname(file)) + suffix);
+    await writeFile(`${stem}.html`, reader.contentHtml.trim() + "\n");
+    await writeFile(`${stem}.md`, toMarkdown(reader));
+    console.log(`  ✓ ${rel} → ${relative(dist, stem)}.{html,md} (${reader.length} chars)`);
+    wrote++;
+  }
+  console.log(`✓ gen-snapshots: ${wrote} reader snapshot(s) written${skipped ? `, ${skipped} skipped` : ""}.`);
+}
+
+// Only run the CLI when invoked directly (not when imported by a test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ gen-snapshots: error —", e.stack || e.message); process.exit(1); });
+}

package/generators/openapi.mjs

@@ -0,0 +1,61 @@
+// generators/openapi.mjs — the GENERIC, reusable core of a static-API generator.
+//
+// A site's static JSON API is intrinsically site-specific (its endpoints project
+// THAT site's contracts: profile, posts, corpus, a résumé VC, …). So the per-endpoint
+// projection stays in the consuming site's build. What IS reusable — and lives here —
+// is the machinery around it:
+//
+//   sortKeys(value)              deterministic byte output: recursively sort object
+//                                keys (arrays keep order).
+//   writeApiFile(apiDir, rel, obj, {sort})
+//                                write a JSON file under the API tree (mkdir -p),
+//                                key-sorted by default, with a trailing newline.
+//   embedSchema(schema)          strip $schema/$id so a JSON-Schema component can be
+//                                embedded under an OpenAPI components/schemas entry
+//                                whose internal "#/…" refs resolve at the document root.
+//   jsonResponse(ref)            a 200 application/json response referencing a schema.
+//   validateOpenapi(openapi)     OpenAPI 3.1/3.2 well-formedness: version, info, ≥1
+//                                path, every operation carries responses, every local
+//                                "#/components/…" $ref resolves. Returns string[]
+//                                (empty = well-formed).
+//
+// Pair with lib/schema-validate.mjs to self-check that each emitted document
+// validates against the schema its OpenAPI operation advertises. Zero deps.
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const sortKeys = (v) =>
+  Array.isArray(v) ? v.map(sortKeys)
+  : (v && typeof v === "object") ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])])) : v;
+
+export const writeApiFile = async (apiDir, rel, obj, { sort = true } = {}) => {
+  const p = join(apiDir, rel);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(sort ? sortKeys(obj) : obj, null, 2) + "\n");
+  return p;
+};
+
+// Strip the dialect ($schema) + identity ($id) keys so an embedded component's own
+// "#/…" pointers resolve against the OpenAPI document root. Resources with internal
+// JSON-pointer refs (e.g. draft-04 "#/definitions/…") should re-add an $id by the
+// caller so those refs resolve WITHIN the embedded resource.
+export const embedSchema = (s) => { const { $schema, $id, ...rest } = s; return rest; };
+
+export const jsonResponse = (ref) => ({ description: "OK", content: { "application/json": { schema: { $ref: ref } } } });
+
+export function validateOpenapi(openapi) {
+  const errs = [];
+  if (!/^3\.[12]\.\d+$/.test(openapi.openapi || "")) errs.push(`openapi version ${openapi.openapi} is not 3.1/3.2`);
+  if (!openapi.info?.title || !openapi.info?.version) errs.push("info.title/version missing");
+  if (!openapi.paths || !Object.keys(openapi.paths).length) errs.push("no paths");
+  const refs = new Set();
+  JSON.stringify(openapi, (k, v) => { if (k === "$ref" && typeof v === "string" && v.startsWith("#/")) refs.add(v); return v; });
+  for (const [p, ops] of Object.entries(openapi.paths || {})) for (const [m, op] of Object.entries(ops)) if (!op.responses) errs.push(`${m.toUpperCase()} ${p} has no responses`);
+  // Only OpenAPI-level component refs resolve against the document root; schema-internal
+  // JSON-pointer refs (e.g. "#/definitions/…") resolve within their own $id'd resource.
+  for (const ref of [...refs].filter((r) => r.startsWith("#/components/"))) {
+    const node = ref.replace(/^#\//, "").split("/").reduce((o, seg) => o?.[seg], openapi);
+    if (node == null) errs.push(`dangling $ref ${ref}`);
+  }
+  return errs;
+}

package/integrity/gen-provenance.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// integrity · gen-provenance — emit $DIST/provenance.json (+ the /rekor sidecar)
+// for the ENTIRE site. Run at deploy time, after the keyless signing steps, with
+// the GitHub Actions OIDC env in scope.
+//
+//   node integrity/gen-provenance.mjs
+//
+// Keyless attestations (GitHub Actions OIDC → Fulcio → Rekor, no stored key):
+//   1. site manifest     — cosign sign-blob over $DIST/site.sha256 (the whole
+//      served site). Verify the live bytes in place.
+//   2. in-toto statement — cosign sign-blob over $DIST/attestation.intoto.json
+//      (the SLSA predicate), IF present (some sites emit one, some don't).
+//   3. OCI artifact      — the built site pushed to GHCR + cosign-signed by digest.
+// Proves WHO built the site and that it is intact — not that the build was safe or
+// authorized. The signatures + Rekor entries are ground truth; this file is a
+// convenience view, and the `verify` recipes confirm it independently.
+//
+// Site-agnostic: every site value comes from the GitHub Actions env (GITHUB_*),
+// the OCI_* env, $PROVENANCE_DOC_URL (the caveat link), and $DIST. The emitted
+// builder.repository becomes the identity verify-site.mjs / verify.mjs enforce —
+// nothing is hardcoded.
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+
+// $DIST may be absolute or relative-to-cwd (resolve handles both); default ./dist.
+const dist = resolve(process.cwd(), process.env.DIST || "dist");
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+
+const repo = process.env.GITHUB_REPOSITORY || "";
+const sha = process.env.GITHUB_SHA || "";
+const ref = process.env.GITHUB_REF || "";
+const runId = process.env.GITHUB_RUN_ID || "";
+const workflowRef = process.env.GITHUB_WORKFLOW_REF || "";
+const ociRef = process.env.OCI_REF || "";
+const ociDigest = process.env.OCI_DIGEST || "";
+const docUrl = process.env.PROVENANCE_DOC_URL || "";
+
+const idFlags =
+  `  --certificate-identity-regexp '^https://github.com/${repo}/' \\\n` +
+  `  --certificate-oidc-issuer https://token.actions.githubusercontent.com`;
+
+async function rekorIndex(bundleName) {
+  const p = join(dist, bundleName);
+  if (!(await exists(p))) return null;
+  try {
+    const b = JSON.parse(await readFile(p, "utf8"));
+    const e = b?.verificationMaterial?.tlogEntries?.[0];
+    return e?.logIndex != null ? String(e.logIndex) : null;
+  } catch { return null; }
+}
+
+const manifestBytes = await readFile(join(dist, "site.sha256"));
+const manifestSha256 = createHash("sha256").update(manifestBytes).digest("hex");
+const fileCount = manifestBytes.toString("utf8").trim().split("\n").filter(Boolean).length;
+const manifestIdx = await rekorIndex("site.sha256.sigstore.json");
+const attIdx = await rekorIndex("attestation.intoto.json.sigstore.json");
+
+const provenance = {
+  scope: "entire-site",
+  fileCount,
+  // Machine-readable freshness. The authoritative timestamp is the Rekor entry's
+  // integratedTime (one click away at /rekor) — this is when the build that
+  // produced these bytes ran, surfaced so a verifier can report build age.
+  builtAt: new Date().toISOString(),
+  builder: {
+    repository: repo,
+    commit: sha,
+    ref,
+    runId,
+    workflowRef,
+    issuer: "https://token.actions.githubusercontent.com",
+  },
+  siteManifest: {
+    file: "site.sha256",
+    sha256: manifestSha256,
+    bundle: "site.sha256.sigstore.json",
+    transparencyLog: "rekor.sigstore.dev",
+    rekorLogIndex: manifestIdx,
+    rekorEntry: manifestIdx ? `https://search.sigstore.dev/?logIndex=${manifestIdx}` : null,
+    verify:
+      `cosign verify-blob \\\n  --bundle site.sha256.sigstore.json \\\n${idFlags} \\\n  site.sha256\n` +
+      `# then check the live bytes against the signed manifest:\nsha256sum -c site.sha256`,
+  },
+  intotoStatement: (await exists(join(dist, "attestation.intoto.json")))
+    ? {
+        file: "attestation.intoto.json",
+        bundle: "attestation.intoto.json.sigstore.json",
+        predicateType: "https://slsa.dev/provenance/v1",
+        rekorLogIndex: attIdx,
+        rekorEntry: attIdx ? `https://search.sigstore.dev/?logIndex=${attIdx}` : null,
+        verify: `cosign verify-blob \\\n  --bundle attestation.intoto.json.sigstore.json \\\n${idFlags} \\\n  attestation.intoto.json`,
+      }
+    : null,
+  ociArtifact: ociRef
+    ? {
+        registry: "ghcr.io",
+        ref: ociRef,
+        digest: ociDigest || null,
+        pull: `oras pull ${ociRef}`,
+        verify: `cosign verify ${ociDigest ? ociRef.split(":")[0] + "@" + ociDigest : ociRef} \\\n${idFlags}`,
+      }
+    : null,
+  caveat:
+    "Provenance proves who built this site and that it is intact — not that the build was safe or authorized. Identity and integrity, not legitimacy." +
+    (docUrl ? ` ${docUrl}` : ""),
+};
+
+await writeFile(join(dist, "provenance.json"), JSON.stringify(provenance, null, 2) + "\n");
+
+// /rekor — a stable, one-click redirect to THIS build's real Rekor entry (the
+// whole-site manifest signature). The signed HTML can't bake the per-version
+// logIndex without circularity, so this unsigned sidecar carries it (excluded
+// from site.sha256). The target is the real search.sigstore.dev entry showing the
+// cert identity + digest — a wrong index wouldn't match, so it degrades detectably.
+if (manifestIdx) {
+  const rekorUrl = `https://search.sigstore.dev/?logIndex=${manifestIdx}`;
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex">
+<meta http-equiv="refresh" content="0;url=${rekorUrl}">
+<title>This build's Rekor entry</title>
+<script>location.replace(${JSON.stringify(rekorUrl)})</script>
+</head>
+<body style="font-family:system-ui,sans-serif;margin:2rem;line-height:1.5;">
+<p>Redirecting to this build's entry in the public Rekor transparency log…</p>
+<p><a href="${rekorUrl}">${rekorUrl}</a></p>
+</body>
+</html>
+`;
+  await mkdir(join(dist, "rekor"), { recursive: true });
+  await writeFile(join(dist, "rekor", "index.html"), html);
+}
+
+console.log(`✓ provenance: entire site (${fileCount} files) · manifest sha256:${manifestSha256.slice(0, 12)}… · rekor#${manifestIdx ?? "?"}${manifestIdx ? " · /rekor → entry" : ""}${ociRef ? ` · oci ${ociRef}` : ""} → provenance.json`);

package/integrity/gen-sitemanifest.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// integrity · gen-sitemanifest — content-address the ENTIRE built site.
+//
+// Walk $DIST (default ./dist relative to the working directory) and emit
+// `$DIST/site.sha256`: one `sha256␠␠relpath` line per served file, sorted, in the
+// exact format `sha256sum -c` accepts. This single file is the whole-site digest
+// the deploy keyless-signs (cosign sign-blob), so provenance covers every asset.
+// A visitor verifies the signature on this manifest, then checks the live bytes.
+//
+//   node integrity/gen-sitemanifest.mjs            # uses ./dist
+//   DIST=out node integrity/gen-sitemanifest.mjs
+//   MANIFEST_EXCLUDE=_worker.js,_extra node integrity/gen-sitemanifest.mjs
+//
+// Site-agnostic: dist resolved from cwd (not the file's location), so it runs
+// identically whether invoked in-repo or vendored. The provenance sidecars are
+// excluded — they describe the site, they are not the site, and the manifest can't
+// hash its own signature. EXCLUDE is a superset of both reference sites' sidecars
+// (a name that doesn't exist in a given site is simply never matched); a consumer
+// adds platform control files of its own via $MANIFEST_EXCLUDE (comma-separated).
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+
+// $DIST may be absolute or relative-to-cwd (resolve handles both); default ./dist.
+const dist = resolve(process.cwd(), process.env.DIST || "dist");
+
+const EXCLUDE = new Set([
+  "site.sha256",
+  "site.sha256.sigstore.json",
+  "provenance.json",
+  "rekor/index.html",
+  "attestation.intoto.json",
+  "attestation.intoto.json.sigstore.json",
+  // Platform control files: consumed by the host (e.g. Cloudflare Pages), never
+  // served as content — so they don't belong in a manifest of SERVED bytes (a
+  // verifier re-hashing the live site 404s on them). Still covered by the OCI
+  // artifact signature, which packs the whole dist.
+  "_headers",
+  "_redirects",
+  "_routes.json",
+  ...(process.env.MANIFEST_EXCLUDE || "").split(",").map((s) => s.trim()).filter(Boolean),
+]);
+
+async function walk(dir) {
+  const out = [];
+  for (const ent of await readdir(dir, { withFileTypes: true })) {
+    const abs = join(dir, ent.name);
+    const rel = relative(dist, abs);
+    if (ent.isDirectory()) { out.push(...await walk(abs)); continue; }
+    if (EXCLUDE.has(rel)) continue;
+    out.push(rel);
+  }
+  return out;
+}
+
+const files = (await walk(dist)).sort();
+const lines = [];
+for (const rel of files) {
+  const sha256 = createHash("sha256").update(await readFile(join(dist, rel))).digest("hex");
+  lines.push(`${sha256}  ${rel}`);
+}
+const manifest = lines.join("\n") + "\n";
+await writeFile(join(dist, "site.sha256"), manifest);
+
+const siteDigest = createHash("sha256").update(manifest).digest("hex");
+console.log(`✓ site manifest: ${files.length} files → ${process.env.DIST || "dist"}/site.sha256 (site digest sha256:${siteDigest.slice(0, 12)}…)`);

package/integrity/http-probe.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// integrity · http-probe — a post-deploy RFC 9110 HTTP-correctness probe.
+//
+//   node integrity/http-probe.mjs https://your-site.example
+//   PROBE_CONFIG=probe.json node integrity/http-probe.mjs https://your-site.example
+//
+// Sibling to verify-site.mjs (which checks the SIGNED BYTES) — this checks the EDGE'S
+// HTTP SEMANTICS: that the deployed origin speaks HTTP correctly per RFC 9110/9111.
+// It runs AFTER the site is live; it is a post-deploy probe, NOT a build gate (it
+// needs a live URL). Fail-closed: any wrong status / type / parity / conditional
+// behaviour exits 1. Dependency-free (node fetch only).
+//
+// What it asserts (RFC 9110, and 9111 for conditional caching):
+//   1. status    — each indexable route returns 200; a known-missing path returns 404.
+//   2. type      — Content-Type is correct + carries a charset for text.
+//   3. HEAD parity — HEAD mirrors GET's status + Content-Type and returns no body (§9.3.2).
+//   4. conditional — when GET returns an ETag, a follow-up If-None-Match yields 304 with
+//                  no body (§13.1.2 / RFC 9111). Skipped (with a note) if no ETag is served.
+//   5. 404 page  — the unknown path serves the site's 404 document.
+//   6. redirects terminate — routes that 3xx must reach a terminal 2xx within a hop cap
+//                  (no loops); the canonical apex host must not itself redirect.
+//
+// Site-agnostic: the routes to probe come from a config (NO hardcoded paths). Supply
+// EITHER a JSON file via $PROBE_CONFIG / 2nd positional arg, OR the env vars
+// $PROBE_HTML_ROUTES + $PROBE_MISSING (comma lists). Config shape:
+//   { "htmlRoutes": ["/", "/about"],
+//     "typed": [ { "path": "/robots.txt", "type": "text/plain", "charset": true },
+//                { "path": "/sitemap.xml", "type": "xml" } ],
+//     "missing": "/this-should-404" }
+// With no config at all, only the apex (/) is probed (status + type + HEAD parity).
+import { argv, exit, env } from "node:process";
+import { readFile } from "node:fs/promises";
+
+const target = argv[2];
+if (!target || !/^https?:\/\//.test(target)) {
+  console.error("usage: http-probe <https://site> [config.json]");
+  exit(2);
+}
+const base = target.replace(/\/$/, "");
+
+async function loadConfig() {
+  const path = argv[3] || env.PROBE_CONFIG;
+  if (path) {
+    try { return JSON.parse(await readFile(path, "utf8")); }
+    catch (e) { console.error(`✗ http-probe: cannot read config ${path}: ${e.message}`); exit(2); }
+  }
+  const list = (v) => (v || "").split(",").map((s) => s.trim()).filter(Boolean);
+  return {
+    htmlRoutes: list(env.PROBE_HTML_ROUTES).length ? list(env.PROBE_HTML_ROUTES) : ["/"],
+    typed: [],
+    missing: env.PROBE_MISSING || "/this-path-should-never-exist-12345",
+  };
+}
+const cfg = await loadConfig();
+const HTML_ROUTES = cfg.htmlRoutes || ["/"];
+const TYPED = cfg.typed || [];
+const MISSING = cfg.missing || "/this-path-should-never-exist-12345";
+
+let failures = 0;
+const ok = (cond, msg) => { console.log(`${cond ? "✓" : "✗"} ${msg}`); if (!cond) failures++; };
+const note = (msg) => console.log(`  · ${msg}`);
+const ct = (res) => (res.headers.get("content-type") || "").toLowerCase();
+
+async function main() {
+  console.log(`· http-probe: ${base} (RFC 9110 correctness)`);
+
+  // 1 + 2 + 3 + 4: HTML routes — status, type, HEAD parity, conditional request.
+  for (const path of HTML_ROUTES) {
+    const url = `${base}${path}`;
+    const get = await fetch(url, { redirect: "follow" });
+    ok(get.status === 200, `GET ${path} → ${get.status} (want 200)`);
+    ok(/text\/html/.test(ct(get)), `GET ${path} Content-Type ${ct(get) || "(none)"} (want text/html)`);
+    // charset on HTML is RECOMMENDED, not required — HTML declares it in-band via
+    // <meta charset>, and some asset edges omit it on text/html. Note, don't fail.
+    if (!/charset=/.test(ct(get))) note(`GET ${path}: no charset in Content-Type (HTML declares it via <meta charset>)`);
+
+    // HEAD parity (§9.3.2): same status + Content-Type, empty body.
+    const head = await fetch(url, { method: "HEAD", redirect: "follow" });
+    ok(head.status === get.status, `HEAD ${path} status ${head.status} == GET ${get.status}`);
+    ok(ct(head) === ct(get), `HEAD ${path} Content-Type matches GET`);
+    const headBody = await head.text();
+    ok(headBody.length === 0, `HEAD ${path} returns no body (${headBody.length} bytes)`);
+
+    // Conditional request (§13.1.2 / RFC 9111): ETag → If-None-Match → 304.
+    const etag = get.headers.get("etag");
+    if (etag) {
+      const inm = await fetch(url, { headers: { "If-None-Match": etag }, redirect: "follow" });
+      ok(inm.status === 304, `GET ${path} If-None-Match(${etag.slice(0, 12)}…) → ${inm.status} (want 304)`);
+      const body304 = await inm.text();
+      ok(body304.length === 0, `304 ${path} carries no body`);
+    } else {
+      note(`GET ${path}: no ETag served — conditional-request check skipped`);
+    }
+  }
+
+  // 2: typed non-HTML assets.
+  for (const { path, type, charset, skip } of TYPED) {
+    if (skip) continue;
+    const res = await fetch(`${base}${path}`, { redirect: "follow" });
+    ok(res.status === 200, `GET ${path} → ${res.status} (want 200)`);
+    if (type) ok(ct(res).includes(type), `GET ${path} Content-Type ${ct(res) || "(none)"} (want *${type}*)`);
+    if (charset) ok(/charset=/.test(ct(res)), `GET ${path} declares a charset`);
+  }
+
+  // 5: 404 handling — unknown path → 404, serving the site's 404 document.
+  const miss = await fetch(`${base}${MISSING}`, { redirect: "follow" });
+  ok(miss.status === 404, `GET ${MISSING} → ${miss.status} (want 404)`);
+  ok(/text\/html/.test(ct(miss)), `404 Content-Type ${ct(miss) || "(none)"} (want text/html)`);
+
+  // 6: redirects terminate (no loops) within a small hop cap; the apex must not redirect.
+  const HOP_CAP = 5;
+  const apex = await fetch(base + "/", { redirect: "manual" });
+  ok(apex.status < 300 || apex.status >= 400, `apex / does not redirect (status ${apex.status})`);
+  let hops = 0, cur = base + "/", terminal = null;
+  while (hops <= HOP_CAP) {
+    const r = await fetch(cur, { redirect: "manual" });
+    if (r.status >= 300 && r.status < 400 && r.headers.get("location")) {
+      cur = new URL(r.headers.get("location"), cur).toString();
+      hops++;
+      continue;
+    }
+    terminal = r.status;
+    break;
+  }
+  ok(terminal !== null && hops <= HOP_CAP, `redirect chain from / terminates in ${hops} hop(s) → ${terminal ?? "(loop)"}`);
+
+  console.log(failures ? `\n✗ http-probe FAILED (${failures})` : `\n✓ http-probe: edge HTTP semantics conform to RFC 9110`);
+  exit(failures ? 1 : 0);
+}
+
+main().catch((e) => { console.error("✗ http-probe: error —", e.message); exit(1); });