verifyhash 0.1.0 → 0.1.2

package/verifier/ci/journal.generic.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# journal.generic.sh — a portable, copy-paste CI CONTINUOUS-INTEGRITY gate built on the `vh journal`
+# append-only, hash-chained integrity journal (T-60.3).
+#
+# WHAT THIS IS
+#   Drop this into ANY CI that can run a shell step (GitLab CI, CircleCI, Jenkins, a Makefile recipe, a
+#   git pre-push hook, a bare cron box). On every run it APPENDS this build's verify verdict to a STANDING
+#   append-only journal, then VERIFIES the whole chain and FAILS THE BUILD (non-zero exit) unless the chain
+#   is UNBROKEN and every recorded observation was ACCEPTED. Unlike a one-shot verify (does it match RIGHT
+#   NOW?), a green pipeline here MEANS "the artifact has verified CONTINUOUSLY across every recorded run, and
+#   the record itself is tamper-evident" — the standing, re-runnable integrity trail a one-shot verify cannot
+#   produce.
+#
+# WHY APPEND-THEN-VERIFY (the continuous-integrity shape)
+#   `vh journal append` records THIS run's verdict as ONE new hash-chained line — STRICTLY ADDITIVELY (prior
+#   lines are never rewritten). Recording a REJECTED verdict is a SUCCESSFUL append (the journal's job is to
+#   faithfully record what it saw); the drift then surfaces at `vh journal verify` time. So the gate's verdict
+#   is the VERIFY exit code: a tampered artifact records a REJECT this run, and verify reports the chain as
+#   DRIFTED (exit 3) — blocking the merge. A deleted / reordered / inserted / hand-edited PAST line BREAKS
+#   the chain and verify LOCALIZES the first break (also exit 3).
+#
+# TRUST BOUNDARY (this gate will not let you overclaim)
+#   A PASS proves ORDERING + CONTINUITY of the verifier's OWN observations + tamper-evidence of the record.
+#   The `ts` on each entry is SELF-ASSERTED (the verifier's own wall clock), NOT a trusted timestamp — so the
+#   journal NEVER claims "unaltered since date T" on its own; that claim needs a trust-root that signs/
+#   timestamps the `ts` (STRATEGY.md P-3). See docs/INTEGRITY-JOURNAL.md.
+#
+# PERSIST THE JOURNAL BETWEEN RUNS
+#   The continuous value comes from the SAME journal file GROWING across runs. Persist VH_JOURNAL between CI
+#   runs (a cache, a committed file, or a stored build artifact) so the chain accumulates; a fresh journal
+#   each run only ever proves a single observation. `append` creates the file on the first run.
+#
+# DEPENDENCIES
+#   The full verifyhash package (from `npm i verifyhash` / `npx vh`, which brings in ethers as a runtime
+#   dependency) plus a POSIX shell — NO ADDITIONAL dependencies, no hardhat (a devDep, never installed for
+#   consumers), and no network (append/verify are pure-local file ops).
+#   INDEPENDENCE NOTE: unlike the ZERO-DEPENDENCY standalone `verify-vh` bundle in verifier/ (which vendors its
+#   own keccak and needs no ethers), the `vh journal` gate runs the PRODUCER package. Journal verification is
+#   not YET available in the standalone independent verifier, so re-verifying a journal today requires the
+#   producer stack. See docs/INTEGRITY-JOURNAL.md ("Independence scope").
+#
+# CONFIGURE VIA ENVIRONMENT (so this file is literal copy-paste; no in-file editing required):
+#   VH_BIN       the `vh` command                          (default: vh — on PATH via npm; or a path)
+#   VH_JOURNAL   path to the append-only journal file       (REQUIRED; created on first append)
+#   VH_ARTIFACT  a *.vhevidence.json seal / signed container to record this run (optional; when unset the
+#                gate ONLY re-verifies the standing chain without appending)
+#   VH_DIR       dir holding the seal's referenced files     (optional; defaults to the artifact's own dir)
+#   VH_TS        a self-asserted timestamp for the entry     (optional; defaults to the vh wall clock, ISO)
+#
+# EXIT CODES (passed straight through from `vh journal verify`, so the job status is meaningful):
+#   0  PASS      — unbroken chain, every recorded observation ACCEPTED; allow the merge.
+#   3  BROKEN/DRIFTED — the chain was tampered OR a recorded observation was REJECTED; BLOCK the merge.
+#   2  USAGE     — misconfiguration (missing VH_JOURNAL / bad flag); never reported as "passed".
+#   1  IO        — a file could not be read/written; never reported as "passed".
+#
+# Usage:
+#   VH_JOURNAL=./integrity.jsonl VH_ARTIFACT=./dist/release.vhevidence.json ./journal.generic.sh
+set -euo pipefail
+
+VH_BIN="${VH_BIN:-vh}"
+
+if [ -z "${VH_JOURNAL:-}" ]; then
+  echo "journal CI gate: set VH_JOURNAL to the path of the append-only journal file." >&2
+  exit 2
+fi
+
+# 1) APPEND this run's observation (the normal path). Skipped only when VH_ARTIFACT is unset (re-verify the
+#    standing chain without recording a new entry). Recording a REJECT is a SUCCESSFUL append (exit 0) — the
+#    drift surfaces at verify time below. A usage/IO failure of append (exit 2/1) is a real gate failure
+#    (we could not even record), passed straight through.
+if [ -n "${VH_ARTIFACT:-}" ]; then
+  set -- journal append "$VH_ARTIFACT" --to "$VH_JOURNAL"
+  if [ -n "${VH_DIR:-}" ]; then set -- "$@" --dir "$VH_DIR"; fi
+  if [ -n "${VH_TS:-}" ]; then set -- "$@" --ts "$VH_TS"; fi
+
+  set +e
+  "$VH_BIN" "$@"
+  append_code=$?
+  set -e
+  if [ "$append_code" -ne 0 ]; then
+    echo "journal CI gate: append FAILED (exit $append_code) — could not record this run's observation." >&2
+    exit "$append_code"
+  fi
+fi
+
+# 2) VERIFY the whole standing chain. This is the gate's verdict — the SHARED 0/3 verify contract, passed
+#    straight through so the CI job status is meaningful.
+set +e
+"$VH_BIN" journal verify "$VH_JOURNAL"
+code=$?
+set -e
+
+if [ "$code" -ne 0 ]; then
+  echo "journal CI gate: FAILED (exit $code) — the integrity journal is BROKEN or recorded a DRIFT; blocking the merge." >&2
+fi
+exit "$code"

package/verifier/ci/journal.github-actions.yml

@@ -0,0 +1,99 @@
+# journal.github-actions.yml — copy-paste GitHub Actions CONTINUOUS-INTEGRITY gate built on the `vh journal`
+# append-only, hash-chained integrity journal (T-60.3).
+#
+# WHAT THIS IS
+#   Drop this file at `.github/workflows/integrity-journal.yml` in the repo that produces sealed verifyhash
+#   artifacts. On every push / pull request it APPENDS this build's verify verdict to a STANDING append-only
+#   journal, then VERIFIES the whole chain and FAILS the job unless the chain is UNBROKEN and every recorded
+#   observation was ACCEPTED. A green check now MEANS "the artifact has verified CONTINUOUSLY across every
+#   recorded run, and the record itself is tamper-evident."
+#
+# WHY APPEND-THEN-VERIFY (the continuous-integrity shape, not a one-shot verify)
+#   `vh journal append` records THIS run's verdict as ONE new hash-chained line — STRICTLY ADDITIVELY (prior
+#   lines are never rewritten). Recording a REJECTED verdict is a SUCCESSFUL append; the drift then surfaces
+#   at `vh journal verify` time. So a tampered artifact records a REJECT this run and `vh journal verify`
+#   reports the chain as DRIFTED (exit 3) — failing the job. A deleted / reordered / inserted / hand-edited
+#   PAST line BREAKS the chain and verify LOCALIZES the first break (also exit 3).
+#
+# PERSIST THE JOURNAL BETWEEN RUNS (where the continuous value lives)
+#   The chain only GROWS if the SAME journal file survives across runs. The step below persists it with
+#   actions/cache using a ROLLING key (`…-${{ github.run_id }}`) + a `restore-keys` prefix fallback: each run
+#   RESTORES the most-recent prior journal and SAVES a fresh immutable cache under its own key, so the chain
+#   truly accumulates. A STATIC key would be a trap — GitHub caches are immutable, so a static-key HIT after
+#   run 1 SKIPS the post-job save and the journal would silently never grow past its first entry while the job
+#   stayed green. Alternatively commit the journal file to the repo or upload/download it as a build artifact.
+#   A fresh journal each run only ever proves a single observation. `append` creates the file on the first run.
+#
+# TRUST BOUNDARY: a PASS proves ORDERING + CONTINUITY of the verifier's OWN observations + tamper-evidence of
+#   the record. The `ts` on each entry is SELF-ASSERTED (the verifier's own wall clock), NOT a trusted
+#   timestamp — the journal NEVER claims "unaltered since date T" on its own; that claim needs a trust-root
+#   that signs/timestamps the `ts` (STRATEGY.md P-3). See docs/INTEGRITY-JOURNAL.md.
+#
+# WHAT YOU EDIT (near the top of the run steps):
+#   - how the seal ARTIFACT is produced for your release (the SDK's buildSeal/serializeSeal, or your tooling).
+#     The example below writes a tiny in-line one. Replace with your real artifacts + their referenced files.
+#
+# NOTE: the loop NEVER runs this file. It is a shipped EXAMPLE. The exact gate (append then verify, exit-code
+# passthrough) is the SAME logic verifier/ci/journal.generic.sh ships, and a test drives that gate against the
+# real `vh journal` command to prove it exits 0 on an unbroken chain and non-zero (3) after a tampered artifact
+# appends a REJECT.
+
+name: integrity-journal continuous-integrity gate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  integrity-journal:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Your repo (containing the sealed artifacts + the verifyhash package, or add a download/install
+      #    step for however your release publishes them).
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # 2. Install verifyhash (provides the `vh journal` command + the SDK to build the seal artifact).
+      - name: Install verifyhash
+        run: npm ci || npm install
+
+      # 3. PERSIST the standing journal across runs so the hash-chain GROWS. Without this the chain restarts
+      #    every build and can only ever prove a single observation. (Commit the file or use an artifact
+      #    upload/download instead, if a cache does not fit your flow.)
+      #    The key MUST rotate per run: `key` embeds ${{ github.run_id }} so every run is a cache MISS and
+      #    therefore SAVES a new immutable cache; `restore-keys` (a prefix) then RESTORES the most-recent
+      #    prior journal so the chain accumulates. A static key would HIT every run after the first and,
+      #    caches being immutable, SKIP the save — leaving the journal frozen at one entry while staying green.
+      - name: Restore the standing integrity journal
+        uses: actions/cache@v4
+        with:
+          path: integrity.jsonl
+          key: vh-integrity-journal-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            vh-integrity-journal-${{ github.ref_name }}-
+
+      # 4. Produce THIS build's seal artifact. Here we build a tiny seal with the SDK and write its referenced
+      #    file to disk (append RE-DERIVES the root from these bytes). Replace with your real release artifacts.
+      - name: Build the seal artifact for this run
+        run: |
+          mkdir -p dist
+          node -e '
+            const vh = require("verifyhash");
+            const fs = require("fs");
+            const path = require("path");
+            const entries = [{ relPath: "dist/app.js", bytes: Buffer.from("console.log(1)\n") }];
+            for (const e of entries) { fs.mkdirSync(path.dirname(e.relPath), { recursive: true }); fs.writeFileSync(e.relPath, e.bytes); }
+            fs.writeFileSync("dist/release.vhevidence.json", vh.serializeSeal(vh.buildSeal(entries)));
+          '
+
+      # 5. THE GATE. APPEND this run's verdict to the standing journal (strictly additive), then VERIFY the
+      #    whole chain. Exit 0 PASS (unbroken + every observation ACCEPTED) -> the job passes; exit 3 (broken
+      #    chain OR a recorded REJECT) -> the job FAILS -> the merge is blocked. This is the SAME append-then-
+      #    verify logic verifier/ci/journal.generic.sh ships; the last command's exit code is the gate verdict.
+      - name: Record + verify continuous integrity (fails the build on a broken chain or a recorded drift)
+        run: |
+          npx vh journal append dist/release.vhevidence.json --to integrity.jsonl --dir .
+          npx vh journal verify integrity.jsonl

package/verifier/ci/reproduce-vh.generic.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# reproduce-vh.generic.sh — a portable, copy-paste CI gate that answers "WHO VERIFIES THE VERIFIER?"
+# on EVERY build, by reproducing the standalone verifier byte-for-byte from the source you audited.
+#
+# WHAT THIS IS (and why it is different from verify-vh.generic.sh)
+#   verify-vh.generic.sh gates your SEALS — it fails the build when a sealed artifact is tampered.
+#   THIS gate watches the VERIFIER ITSELF. A security/procurement reviewer who audited the standalone
+#   verifier once does not want to re-audit it by hand on every release; they want a pinned, automatable
+#   control that re-confirms — offline, with no network, trusting no checksum we ship — that the
+#   committed `verify-vh-standalone.js` / `seal-vh-standalone.js` bundles, their `.sha256` sidecars, the
+#   build-provenance manifest, AND every inlined `lib/*.js` source file STILL reproduce byte-for-byte
+#   from the in-tree source they read. The instant a supply-chain swap, a stale bundle, or a one-byte
+#   source edit slips in, `node build-standalone.js --check` exits non-zero and THIS gate FAILS THE BUILD.
+#
+#   This turns the §0b "reproduce-from-source" answer from a one-time read into a RENEWING dependency:
+#   a green pipeline now MEANS "the verifier we depend on is still the source we audited."
+#
+# WHY A SHELL SNIPPET (not just the node call)
+#   `set -e` + an explicit exit-code passthrough is the difference between a gate that BLOCKS a merge
+#   and a step that prints red but lets the pipeline go green. Any non-zero verdict from `--check`
+#   becomes a non-zero exit of this script, which every CI treats as a failed job.
+#
+# DEPENDENCIES
+#   Node >= 18 and the in-tree `verifier/` source (build-standalone.js + lib/ + dist/). NOTHING ELSE —
+#   no `npm install`, no ethers, no hardhat, no network. `--check` is read-only: it writes nothing.
+#
+# CONFIGURE VIA ENVIRONMENT (so this file is literal copy-paste; no in-file editing required):
+#   BUILD_STANDALONE   path to build-standalone.js   (default: ./verifier/build-standalone.js)
+#
+# EXIT CODES (passed straight through from `--check`, so the job status is meaningful):
+#   0  ALL MATCH   — every bundle, sidecar, manifest AND inlined source reproduces; the verifier is the
+#                    source you audited. Allow the merge.
+#   1  MISMATCH    — something does NOT reproduce (the report NAMES the offending bundle/sidecar/manifest
+#                    or the exact lib/*.js source file); BLOCK the merge and distrust this checkout.
+#
+# Usage:
+#   ./reproduce-vh.generic.sh
+#   BUILD_STANDALONE=path/to/verifier/build-standalone.js ./reproduce-vh.generic.sh
+set -euo pipefail
+
+BUILD_STANDALONE="${BUILD_STANDALONE:-./verifier/build-standalone.js}"
+
+if [ ! -f "$BUILD_STANDALONE" ]; then
+  echo "reproduce-vh CI gate: build-standalone.js not found at '$BUILD_STANDALONE'." >&2
+  echo "  Set BUILD_STANDALONE to the path of verifier/build-standalone.js in your checkout." >&2
+  exit 1
+fi
+
+# Run the read-only reproduce-and-attest pass. `set -e` would abort on the non-zero exit before we could
+# echo a clear message, so we capture the code explicitly and pass it through verbatim.
+set +e
+node "$BUILD_STANDALONE" --check
+code=$?
+set -e
+
+if [ "$code" -ne 0 ]; then
+  echo "reproduce-vh CI gate: FAILED (exit $code) — the verifier does NOT reproduce from source; blocking the merge." >&2
+fi
+exit "$code"

package/verifier/ci/reproduce-vh.github-actions.yml

@@ -0,0 +1,49 @@
+# reproduce-vh.github-actions.yml — copy-paste GitHub Actions gate that answers "WHO VERIFIES THE
+# VERIFIER?" on every build, by reproducing the standalone verifier byte-for-byte from source.
+#
+# WHAT THIS IS
+#   Drop this file at `.github/workflows/reproduce-vh.yml` in the repo that VENDORS the verifyhash
+#   `verifier/` tree. On every push / pull request it runs `node verifier/build-standalone.js --check`,
+#   which RE-COMPILES each standalone bundle from the in-tree source, recomputes its published checksum
+#   and the build-provenance manifest, and cross-checks every inlined lib/*.js source file against the
+#   manifest-pinned sha256 — offline, no network, trusting no checksum we ship. If ANY bundle, sidecar,
+#   manifest, or source file no longer reproduces (a supply-chain swap, a stale bundle, a one-byte
+#   source edit), `--check` exits non-zero and the job FAILS — blocking the merge. A green check now
+#   MEANS "the verifier we depend on is still the exact source we audited."
+#
+#   This is the verifier-integrity twin of verify-vh.github-actions.yml: that one gates your SEALS;
+#   THIS one gates the VERIFIER ITSELF, turning the §0b reproduce-from-source answer into a renewing
+#   control instead of a one-time read.
+#
+# WHAT YOU EDIT: nothing — `--check` is self-contained and reads only the committed verifier/ tree.
+#   (Needs no `npm install`: it depends on nothing but Node core.)
+#
+# NOTE: the loop NEVER runs this file. It is a shipped EXAMPLE. The exact gate command in the `run:`
+# block below is the SAME command verifier/ci/reproduce-vh.generic.sh runs, and a test extracts and
+# executes it to prove it passes on a clean tree and fails (exit 1) when a source byte is flipped.
+
+name: reproduce-vh — who verifies the verifier
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  reproduce-vh:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Your repo, containing the vendored `verifier/` tree (build-standalone.js + lib/ + dist/).
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # 2. THE GATE. No install step: `--check` depends on nothing but Node core. It re-compiles every
+      #    bundle from source, recomputes every checksum + the manifest, and cross-checks every inlined
+      #    source file's hash. Exit 0 = ALL MATCH (the verifier is the source you audited); exit 1 =
+      #    MISMATCH (the report names the offending bundle/sidecar/manifest/source). `node` propagates
+      #    that exit code, and GitHub Actions fails the job on any non-zero — blocking the merge.
+      - name: Reproduce the standalone verifier from source (fails the build on any drift)
+        run: |
+          node verifier/build-standalone.js --check

package/verifier/ci/verify-service.generic.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# verify-service.generic.sh — a portable, copy-paste CI MERGE GATE that calls the `vh serve-verify` HTTP
+# endpoint (T-59.3).
+#
+# WHAT THIS IS
+#   Drop this into ANY CI that can run a shell step (GitLab CI, CircleCI, Jenkins, a Makefile recipe, a
+#   git pre-push hook). Instead of shelling out to the `vh` binary per-artifact, it POSTs a prepared verify
+#   REQUEST BODY to a BOOTED `vh serve-verify` service and FAILS THE BUILD (non-zero exit) unless the
+#   service answers 200 ACCEPTED. A tampered / forged / unknown seal answers 422 / 400 / 413 and the gate
+#   exits non-zero — so the merge is blocked. A green pipeline now MEANS "the verify service ACCEPTED every
+#   sealed artifact."
+#
+# WHY A SHELL SNIPPET (not just the curl call)
+#   `set -e` + an explicit HTTP-status passthrough is the difference between a gate that BLOCKS a merge and
+#   a step that prints red but still lets the pipeline go green. This wrapper makes the failure path the
+#   DEFAULT: anything other than 200 ACCEPTED from the service becomes a non-zero exit of this script, which
+#   every CI treats as a failed job.
+#
+# HOW THE REQUEST BODY IS PRODUCED (out of band — this gate does not build it)
+#   The request body is the exact JSON the service expects (see docs/VERIFY-SERVICE.md), e.g.
+#     { "kind": "verify-seal", "seal": <seal-object-or-json-string>,
+#       "entries": [ { "relPath": "dist/app.js", "content": "<base64>", "encoding": "base64" } ] }
+#   Produce it however your release flow does (the SDK's buildSeal/serializeSeal, or your own tooling) and
+#   hand its PATH to this gate. This keeps the gate a pure, dependency-light HTTP client.
+#
+# DEPENDENCIES
+#   `curl` and a POSIX shell. NOTHING ELSE — no node, no ethers, no hardhat in the gate itself (the SERVICE
+#   is booted separately; see verify-service.github-actions.yml for a full boot+gate recipe).
+#
+# CONFIGURE VIA ENVIRONMENT (so this file is literal copy-paste; no in-file editing required):
+#   VH_VERIFY_URL    base URL of the booted service   (default: http://127.0.0.1:4180)
+#   VH_REQUEST       path to the verify request-body JSON file   (REQUIRED)
+#
+# EXIT CODES (so the job status is meaningful):
+#   0  ACCEPTED  — HTTP 200; the service verified the seal; allow the merge.
+#   3  REJECTED  — HTTP 422; a well-formed request that did NOT verify (tamper/forge/wrong signer); BLOCK.
+#   2  BAD_REQ   — HTTP 400/413; the request itself was malformed/unknown/too large; BLOCK (never a pass).
+#   1  IO        — the service was unreachable or the request file was missing; never reported as "passed".
+#
+# Usage:
+#   VH_VERIFY_URL=http://127.0.0.1:4180 VH_REQUEST=./verify-request.json ./verify-service.generic.sh
+set -euo pipefail
+
+VH_VERIFY_URL="${VH_VERIFY_URL:-http://127.0.0.1:4180}"
+
+if [ -z "${VH_REQUEST:-}" ]; then
+  echo "verify-service CI gate: set VH_REQUEST to the path of the verify request-body JSON file." >&2
+  exit 2
+fi
+if [ ! -f "$VH_REQUEST" ]; then
+  echo "verify-service CI gate: request file not found: $VH_REQUEST" >&2
+  exit 1
+fi
+
+# POST the request body to /verify. `-w` appends the HTTP status on its own trailing line so we can read it
+# WITHOUT a JSON parser; `-s -S` stays quiet but still prints transport errors; `--fail` is NOT used (we want
+# the body + status even on a 4xx so we can report the verdict). A connection failure makes curl exit
+# non-zero, which we map to the IO(1) class rather than a silent pass.
+set +e
+RESPONSE="$(curl -s -S -o - -w $'\n%{http_code}' \
+  -H 'content-type: application/json' \
+  --data-binary "@${VH_REQUEST}" \
+  "${VH_VERIFY_URL%/}/verify")"
+curl_code=$?
+set -e
+
+if [ "$curl_code" -ne 0 ]; then
+  echo "verify-service CI gate: could not reach ${VH_VERIFY_URL} (curl exit ${curl_code})." >&2
+  exit 1
+fi
+
+# The last line is the HTTP status; everything before it is the JSON verdict body.
+http_status="$(printf '%s\n' "$RESPONSE" | tail -n1)"
+body="$(printf '%s\n' "$RESPONSE" | sed '$d')"
+
+echo "verify-service CI gate: ${VH_VERIFY_URL%/}/verify -> HTTP ${http_status}"
+echo "$body"
+
+case "$http_status" in
+  200)
+    echo "verify-service CI gate: ACCEPTED — allowing the merge." >&2
+    exit 0
+    ;;
+  422)
+    echo "verify-service CI gate: REJECTED (HTTP 422) — blocking the merge." >&2
+    exit 3
+    ;;
+  400 | 413)
+    echo "verify-service CI gate: BAD REQUEST (HTTP ${http_status}) — blocking the merge." >&2
+    exit 2
+    ;;
+  *)
+    echo "verify-service CI gate: unexpected HTTP ${http_status} — blocking the merge." >&2
+    exit 1
+    ;;
+esac

package/verifier/ci/verify-service.github-actions.yml

@@ -0,0 +1,88 @@
+# verify-service.github-actions.yml — copy-paste GitHub Actions MERGE GATE that calls the `vh serve-verify`
+# HTTP endpoint (T-59.3).
+#
+# WHAT THIS IS
+#   Drop this file at `.github/workflows/verify-service.yml` in the repo that produces sealed verifyhash
+#   artifacts. On every push / pull request it BOOTS the `vh serve-verify` service (loopback-only, on a
+#   fixed port), POSTs a prepared verify REQUEST BODY to it, and FAILS the job unless the service answers
+#   200 ACCEPTED. If the sealed bytes were tampered/forged, the service answers 422 / 400 and the gate
+#   exits non-zero — so the merge is blocked. A green check now MEANS "the verify service ACCEPTED the
+#   sealed artifact."
+#
+# WHY BOOT-THEN-POST (the "CI plugin that imports rather than shells out")
+#   Unlike verify-vh.generic.sh (which runs the standalone binary per artifact), this recipe stands the
+#   verifier UP as a SERVICE once and gates by HTTP. That is the drop-in shape another microservice or a
+#   fan-out CI matrix consumes: boot once, POST many seals, read ACCEPT/REJECT — no per-artifact process
+#   spawn. The service is VERIFY-ONLY (it never signs, holds no key, writes nothing) and binds LOOPBACK.
+#
+# WHAT YOU EDIT (near the top of the run steps):
+#   - how the verify REQUEST BODY (verify-request.json) is produced for your release (the SDK's
+#     buildSeal/serializeSeal, or your own tooling). The example below writes a tiny in-line one.
+#   - the artifacts / checkout for your release flow.
+#
+# NOTE: the loop NEVER runs this file. It is a shipped EXAMPLE. The exact gate command in the `run:` block
+# below is the SAME command verifier/ci/verify-service.generic.sh runs (curl POST -> HTTP-status exit code),
+# and a test boots the real service and executes that gate to prove it passes on a clean seal and fails
+# (exit 3) on a tampered one.
+
+name: verify-service merge gate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify-service:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Your repo (containing the sealed artifacts + the verifyhash package, or add a download/install
+      #    step for however your release publishes them).
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # 2. Install verifyhash (provides the `vh serve-verify` service + the SDK to build the request body).
+      - name: Install verifyhash
+        run: npm ci || npm install
+
+      # 3. BOOT the verify service on loopback (a fixed port), in the background. It is verify-only, holds
+      #    no key, and writes nothing. We wait for /healthz to answer before gating.
+      - name: Boot vh serve-verify (loopback-only)
+        run: |
+          npx vh serve-verify --port 4180 --host 127.0.0.1 &
+          for i in $(seq 1 50); do
+            if curl -sf http://127.0.0.1:4180/healthz >/dev/null; then break; fi
+            sleep 0.2
+          done
+          curl -sf http://127.0.0.1:4180/healthz
+
+      # 4. Produce the verify REQUEST BODY for your release. Here we build a tiny seal with the SDK and write
+      #    the request body the service expects (see docs/VERIFY-SERVICE.md). Replace with your real artifacts.
+      - name: Build the verify request body
+        run: |
+          node -e '
+            const vh = require("verifyhash");
+            const fs = require("fs");
+            const entries = [{ relPath: "dist/app.js", bytes: Buffer.from("console.log(1)\n") }];
+            const seal = vh.serializeSeal(vh.buildSeal(entries));
+            const wire = entries.map(e => ({ relPath: e.relPath, content: Buffer.from(e.bytes).toString("base64"), encoding: "base64" }));
+            fs.writeFileSync("verify-request.json", JSON.stringify({ kind: "verify-seal", seal, entries: wire }));
+          '
+
+      # 5. THE GATE. POST the request body to the booted service; map the HTTP status to an exit code. 200
+      #    ACCEPTED -> pass; 422 REJECTED / 400 bad request -> non-zero -> the job FAILS -> the merge is
+      #    blocked. This is the SAME logic verifier/ci/verify-service.generic.sh ships.
+      - name: Verify the sealed artifact via the service (fails the build on a bad seal)
+        env:
+          VH_VERIFY_URL: "http://127.0.0.1:4180"
+          VH_REQUEST: "verify-request.json"
+        run: |
+          status=$(curl -s -o /tmp/vh-verify-body.json -w '%{http_code}' \
+            -H 'content-type: application/json' \
+            --data-binary "@${VH_REQUEST}" \
+            "${VH_VERIFY_URL%/}/verify")
+          echo "verify-service gate: HTTP ${status}"
+          cat /tmp/vh-verify-body.json
+          test "${status}" = "200"

package/verifier/ci/verify-vh.generic.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# verify-vh.generic.sh — a portable, copy-paste CI MERGE GATE for verifyhash artifacts.
+#
+# WHAT THIS IS
+#   Drop this into ANY CI that can run a shell step (GitLab CI, CircleCI, Jenkins, a Makefile recipe,
+#   a git pre-push hook, a bare cron box). It runs the STANDALONE, OFFLINE `verify-vh` verifier over a
+#   release's artifact(s) and FAILS THE BUILD (non-zero exit) the instant any artifact is tampered,
+#   forged, or signed by the wrong key. A green pipeline now MEANS "every sealed artifact still matches
+#   the bytes the producer signed."
+#
+# WHY A SHELL SNIPPET (not just the node call)
+#   `set -e` + an explicit exit-code passthrough is the difference between a gate that BLOCKS a merge
+#   and a step that prints red but still lets the pipeline go green. This wrapper makes the failure
+#   path the DEFAULT: any non-zero verdict from verify-vh becomes a non-zero exit of this script, which
+#   every CI treats as a failed job.
+#
+# DEPENDENCIES
+#   Node >= 18 and the standalone `verifier/` tree (verify-vh.js + lib/ + js-sha3). NOTHING ELSE — no
+#   ethers, no hardhat, no network. See verifier/README.md to vendor or `npm install` just this tree.
+#
+# CONFIGURE VIA ENVIRONMENT (so this file is literal copy-paste; no in-file editing required):
+#   VERIFY_VH       path to verify-vh.js               (default: ./verifier/verify-vh.js)
+#   VH_VENDOR       producer signer address 0x..(20B)  (REQUIRED — pin who is allowed to have signed)
+#   VH_MANIFEST     a release manifest file            (gate EVERY artifact in one shot; optional)
+#   VH_ARTIFACTS    space-separated artifact paths     (used when VH_MANIFEST is unset)
+#   VH_DIR          dir holding the referenced files   (optional; defaults to each artifact's own dir)
+#
+# EXIT CODES (passed straight through from verify-vh, so the job status is meaningful):
+#   0  OK        — every artifact verified; allow the merge.
+#   3  REJECTED  — an artifact was tampered/forged/wrong-issuer; BLOCK the merge (report names which).
+#   2  USAGE     — misconfiguration (bad flag / bad address / empty manifest).
+#   1  IO        — an artifact or the manifest could not be read; never reported as "passed".
+#
+# Usage:
+#   VH_VENDOR=0xabc... VH_ARTIFACTS="dist/a.vhevidence.json" ./verify-vh.generic.sh
+#   VH_VENDOR=0xabc... VH_MANIFEST=release.manifest         ./verify-vh.generic.sh
+set -euo pipefail
+
+VERIFY_VH="${VERIFY_VH:-./verifier/verify-vh.js}"
+
+if [ -z "${VH_VENDOR:-}" ]; then
+  echo "verify-vh CI gate: set VH_VENDOR to the producer's signer address (0x + 20 bytes)." >&2
+  exit 2
+fi
+
+# Build the verify-vh argument list. A MANIFEST gates the whole release in one invocation; otherwise we
+# pass the artifact list positionally. Either way it is ONE call -> ONE exit code the CI gates on.
+set -- # reset positional params we will hand to verify-vh
+if [ -n "${VH_MANIFEST:-}" ]; then
+  set -- --manifest "$VH_MANIFEST"
+else
+  if [ -z "${VH_ARTIFACTS:-}" ]; then
+    echo "verify-vh CI gate: set VH_MANIFEST or VH_ARTIFACTS (the artifact(s) to verify)." >&2
+    exit 2
+  fi
+  # shellcheck disable=SC2086  # word-splitting VH_ARTIFACTS into separate args is intentional.
+  set -- $VH_ARTIFACTS
+fi
+
+set -- "$@" --vendor "$VH_VENDOR"
+if [ -n "${VH_DIR:-}" ]; then
+  set -- "$@" --dir "$VH_DIR"
+fi
+
+# Run the gate. `set -e` would abort on the non-zero exit before we could echo a clear message, so we
+# capture the code explicitly and pass it through verbatim — preserving the 0/3/2/1 contract for CI.
+set +e
+node "$VERIFY_VH" "$@"
+code=$?
+set -e
+
+if [ "$code" -ne 0 ]; then
+  echo "verify-vh CI gate: FAILED (exit $code) — blocking the merge." >&2
+fi
+exit "$code"

package/verifier/ci/verify-vh.github-actions.yml

@@ -0,0 +1,56 @@
+# verify-vh.github-actions.yml — copy-paste GitHub Actions MERGE GATE for verifyhash artifacts.
+#
+# WHAT THIS IS
+#   Drop this file at `.github/workflows/verify-vh.yml` in the repo that RECEIVES sealed verifyhash
+#   artifacts. On every push / pull request it installs ONLY the standalone, offline `verify-vh`
+#   verifier (no ethers, no hardhat, no network) and runs it over your release artifact(s). If any
+#   artifact is tampered, forged, or signed by the wrong key, `verify-vh` exits non-zero and the job
+#   FAILS — so the merge is blocked. A green check now MEANS "every sealed artifact still matches the
+#   bytes the producer signed."
+#
+# WHAT YOU EDIT (three things, all near the top of the run step):
+#   - VH_VENDOR     : the producer's signer address (0x + 20 bytes), obtained out-of-band.
+#   - VH_MANIFEST   : a release manifest listing every artifact (gate the whole release in one shot),
+#                     OR set VH_ARTIFACTS to a space-separated list of artifact paths instead.
+#   - the checkout / paths to your artifacts (this example assumes they are committed in the repo;
+#     adapt the `actions/checkout` or add an artifact-download step for your release flow).
+#
+# NOTE: the loop NEVER runs this file. It is a shipped EXAMPLE. The exact gate command in the `run:`
+# block below is the SAME command verifier/ci/verify-vh.generic.sh runs, and a test extracts and
+# executes it to prove it passes on good input and fails (exit 3) on tampered input.
+
+name: verify-vh merge gate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify-vh:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Your repo (containing the sealed artifacts + the vendored `verifier/` tree, or add a
+      #    download step for however your release publishes them).
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # 2. Install ONLY the standalone verifier. This pulls js-sha3 and NOTHING else — no ethers,
+      #    no hardhat, no producer stack. (If you vendor `verifier/` into your repo, you can drop
+      #    this step entirely; it is self-contained.)
+      - name: Install standalone verify-vh (js-sha3 only)
+        working-directory: verifier
+        run: npm ci --omit=dev || npm install --omit=dev
+
+      # 3. THE GATE. One invocation, one exit code. verify-vh exits 0 only if EVERY artifact verifies;
+      #    3 if any is tampered/forged/wrong-issuer; 2 on misconfig; 1 on IO. `node` propagates that
+      #    exit code, and GitHub Actions fails the job on any non-zero — blocking the merge.
+      - name: Verify sealed artifacts (fails the build on a bad seal)
+        env:
+          # EDIT THESE for your release:
+          VH_VENDOR: "0x0000000000000000000000000000000000000000"   # producer signer address (out-of-band)
+          VH_MANIFEST: "release.manifest"                            # or set VH_ARTIFACTS instead
+        run: |
+          node verifier/verify-vh.js --manifest "$VH_MANIFEST" --vendor "$VH_VENDOR"