verifyhash 0.1.0 → 0.1.2

package/verifier/action/README.md

@@ -0,0 +1,87 @@
+# verify-vh — sealed-artifact merge gate (GitHub Action)
+
+A composite GitHub Action that **fails your build the instant a sealed verifyhash artifact is tampered,
+forged, or signed by the wrong key.** It installs ONLY the standalone, offline `verify-vh` verifier
+(`js-sha3` — no ethers, no hardhat, no network) and runs it over your release artifact(s).
+
+**What a green check means depends on `vendor:`:**
+
+- With **`vendor:` set** — a green check means *"every sealed artifact still matches the bytes the key
+  you pinned signed."* An artifact signed by any other key is **REJECTED** (exit 3).
+- With **`vendor:` omitted** — a green check means **tamper-evidence ONLY**: the bytes match the seal,
+  but it does **NOT** prove **WHO** signed. See the security warning below before omitting `vendor:`.
+
+> ⚠️ **Pin `vendor:` for any SIGNED release.** A signed artifact gated **without** `vendor:` is accepted
+> as long as its signature recovers to the signer the packet **self-asserts** — so an attacker who
+> re-signs a tampered release with **their own key** passes this gate. `vendor:` is what makes the green
+> check mean "signed by the producer **I** pinned" rather than "signed by **whoever** built this packet."
+> Leave `vendor:` empty **only** for genuinely unsigned evidence seals (where there is no signer to pin).
+
+Adoption is **one line**:
+
+```yaml
+# .github/workflows/verify-vh.yml
+name: verify-vh merge gate
+on: [push, pull_request]
+jobs:
+  verify-vh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: verifyhash/verifyhash/verifier/action@17696eff5d910b496b8935052ff42ee2e7c6a85a
+        with:
+          vendor: "0xYOUR_PRODUCER_SIGNER_ADDRESS"   # the key that must have signed (omit to check tamper only)
+          manifest: "release.manifest"               # OR set `artifacts:` instead
+```
+
+> The `uses:` line is pre-pinned to this repository's real slug (`verifyhash/verifyhash`) and a full
+> 40-hex commit SHA reachable from `main` — it works exactly as pasted. Supply-chain hygiene: re-pin
+> `@<sha>` to a commit SHA **you** have audited and trust (keep the full-SHA form; a mutable ref like
+> `@main` can change under you). GitHub fetches this action's own tree when you reference it with
+> `uses:`, and the action resolves the bundled `verifier/` via `${{ github.action_path }}` at run time
+> (it does NOT run from your `$GITHUB_WORKSPACE`). So you do **not** need to vendor `verifier/` into your
+> repo — your `actions/checkout` brings only your artifacts, not the verifier.
+
+## Inputs
+
+| input          | required | default                     | what it is |
+|----------------|----------|-----------------------------|------------|
+| `vendor`       | no       | `""`                        | The producer's signer address (`0x` + 20 bytes), obtained out-of-band, that **every signed artifact must verify against**. When set, an artifact signed by any other key is **REJECTED** (exit 3). Leave empty to verify tamper-evidence only (e.g. an unsigned evidence seal). **⚠️ Leaving this empty on a SIGNED artifact accepts an attacker-re-signed release — pin it for any signed release** (see warning above). |
+| `manifest`     | no       | `""`                        | Path to a release manifest (newline list or JSON array of artifact paths, each entry may carry its own `--vendor`/`--dir`) that gates the **whole release in one invocation**. Set this **OR** `artifacts`. |
+| `artifacts`    | no       | `""`                        | Space-separated artifact path(s) when no `manifest` is given (e.g. `"dist/a.vhevidence.json dist/b.vhseal"`). Set this **OR** `manifest`. |
+| `dir`          | no       | `""`                        | Directory holding the files the artifact(s) reference (the sealed packet). Defaults to each artifact's own directory (sibling resolution). |
+| `verify-vh`    | no       | _(action's bundled tree)_   | Path to the standalone `verify-vh.js` (advanced/testing override). Defaults to the verifier tree **bundled with this action**, resolved at run time via `${{ github.action_path }}` — so you do **not** vendor `verifier/` into your repo. |
+| `node-version` | no       | `"20"`                      | Node.js version to set up for the verifier (`>= 18`). |
+
+## Exit-code contract (the job status is meaningful)
+
+The action propagates `verify-vh`'s own exit code, so any non-zero verdict fails the job and **blocks the merge**:
+
+| exit | meaning      | gate result |
+|------|--------------|-------------|
+| `0`  | OK           | every artifact verified — allow the merge |
+| `3`  | REJECTED     | an artifact was tampered/forged/wrong-issuer — **block** (the report names which) |
+| `2`  | USAGE        | misconfiguration (no `manifest`/`artifacts`, bad flag/address) |
+| `1`  | IO           | an artifact or the manifest could not be read — never reported as "passed" |
+
+## Single source of truth — no drift
+
+The verifier-invocation the gate step runs is **byte-identical** to the one shipped in
+[`verifier/ci/verify-vh.generic.sh`](../ci/verify-vh.generic.sh) (the portable shell gate for any CI).
+A test (`test/verifier.action.test.js`) parses this `action.yml`, extracts the gate `run:` block, runs
+it over the committed sample sealed packet (asserting exit `0`) and over a one-byte-tampered copy
+(asserting exit `3`), and asserts that invocation has not drifted from `verify-vh.generic.sh`. So this
+Action, the generic shell gate, and the GitHub Actions YAML example all run the **same** gate.
+
+## What it installs (and what it does NOT)
+
+The install step runs `npm ci --omit=dev || npm install --omit=dev` inside `verifier/`, whose
+`package.json` declares exactly one runtime dependency — `js-sha3`. It pulls **no** `ethers`, **no**
+`hardhat`, **no** `@nomicfoundation`, and opens no network beyond the registry fetch. The verifier is
+read-only: it holds no key and writes nothing.
+
+## Related
+
+- [`verifier/ci/verify-vh.generic.sh`](../ci/verify-vh.generic.sh) — the same gate as a portable `set -e` shell snippet (GitLab CI / Makefile / git hook / cron box), configured by `VH_*` env vars.
+- [`verifier/ci/verify-vh.github-actions.yml`](../ci/verify-vh.github-actions.yml) — a hand-rolled GitHub Actions **workflow** example (this Action is the one-line replacement for it).
+- [`verifier/README.md`](../README.md) — the standalone verifier itself: how to vendor or `npm install` just this tree and audit it in an afternoon.

package/verifier/action/action.yml

@@ -0,0 +1,146 @@
+name: "verify-vh — sealed-artifact merge gate"
+description: >-
+  Fail the build the instant a sealed verifyhash artifact is tampered, forged, or signed by the wrong
+  key. This composite action installs ONLY the standalone, offline verify-vh verifier (js-sha3 — no
+  ethers, no hardhat, no network) and runs it over your release artifact(s). With `vendor:` set, a green
+  check means "every sealed artifact still matches the bytes the key you pinned signed"; with `vendor:`
+  omitted it is tamper-evidence ONLY and does NOT prove WHO signed. Adoption is one line:
+  `uses: verifyhash/verifyhash/verifier/action@17696eff5d910b496b8935052ff42ee2e7c6a85a` (re-pin to a
+  full-40-hex commit SHA you trust).
+author: "verifyhash"
+
+# Marketplace branding (shown on the GitHub Marketplace listing).
+branding:
+  icon: "shield"
+  color: "green"
+
+# ---------------------------------------------------------------------------------------------------
+# INPUTS — the three knobs a consumer sets. `vendor` pins WHO must have signed (omit for an unsigned
+# evidence seal, which is checked for tamper-evidence only). Provide EITHER `manifest` (gate a whole
+# release in one shot) OR `artifacts` (a space-separated list); `dir` resolves the referenced files.
+# ---------------------------------------------------------------------------------------------------
+inputs:
+  vendor:
+    description: >-
+      The producer's signer address (0x + 20 bytes), obtained out-of-band, that EVERY signed artifact
+      must verify against. Leave empty to verify tamper-evidence only (e.g. an unsigned evidence seal);
+      when set, an artifact signed by any other key is REJECTED (exit 3). SECURITY: gating a SIGNED
+      release artifact WITHOUT `vendor:` accepts an attacker who re-signed a tampered release with their
+      OWN key — a green check then proves only that the bytes match WHATEVER signer the packet
+      self-asserts, NOT who. ALWAYS pin `vendor:` for any signed release.
+    required: false
+    default: ""
+  manifest:
+    description: >-
+      Path to a release manifest (a newline list or JSON array of artifact paths, each entry may carry
+      its own --vendor/--dir) that gates the WHOLE release in one invocation. Set this OR `artifacts`.
+    required: false
+    default: ""
+  artifacts:
+    description: >-
+      Space-separated artifact path(s) to verify when no `manifest` is given (e.g.
+      "dist/a.vhevidence.json dist/b.vhseal"). Set this OR `manifest`.
+    required: false
+    default: ""
+  dir:
+    description: >-
+      Directory holding the files the artifact(s) reference (the sealed packet). Optional; defaults to
+      each artifact's own directory (sibling resolution).
+    required: false
+    default: ""
+  verify-vh:
+    description: >-
+      Path to the standalone verify-vh.js (advanced/testing override). Defaults to the verifier tree
+      BUNDLED WITH this action — resolved at run time via ${{ github.action_path }}, so the consumer
+      NEVER has to vendor `verifier/` into their own repo. Leave empty to use the bundled verifier.
+    required: false
+    default: ""
+  node-version:
+    description: "Node.js version to set up for the offline verifier (>= 18)."
+    required: false
+    default: "20"
+
+# ---------------------------------------------------------------------------------------------------
+# COMPOSITE STEPS — ordered: set up Node, install ONLY the standalone verifier (js-sha3), then run the
+# gate. The action fetches/installs the verifier itself; the consumer NEVER has to vendor the tree.
+#
+# PATH RESOLUTION (load-bearing for a published action): a composite action's `run:` steps execute with
+# the CONSUMER's $GITHUB_WORKSPACE as the working directory, NOT the action's own checkout. So every
+# reference to the bundled verifier tree is resolved against ${{ github.action_path }} (the directory of
+# THIS action, i.e. verifier/action/) — its parent ${{ github.action_path }}/.. is the verifier/ tree.
+# Without this, `working-directory: verifier` and `./verifier/verify-vh.js` would resolve against the
+# consumer's repo (which has no verifier/ tree) and the action would fail to even start the verifier.
+# ---------------------------------------------------------------------------------------------------
+runs:
+  using: "composite"
+  steps:
+    # 1. Node for the offline verifier (no producer toolchain).
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    # 2. Install ONLY the standalone verifier — pulls js-sha3 and NOTHING else (no ethers, no hardhat,
+    #    no @nomicfoundation, no network beyond the registry fetch of js-sha3). Runs in the action's OWN
+    #    bundled verifier tree (${{ github.action_path }}/.. == verifier/), NOT the consumer's workspace.
+    - name: Install standalone verify-vh (js-sha3 only)
+      shell: bash
+      working-directory: ${{ github.action_path }}/..
+      run: npm ci --omit=dev || npm install --omit=dev
+
+    # 3. THE GATE. One invocation, one exit code. The verifier-invocation line below is BYTE-IDENTICAL
+    #    to the one in verifier/ci/verify-vh.generic.sh (the single source of truth — a test asserts
+    #    no drift). verify-vh exits 0 only if EVERY artifact verifies; 3 if any is tampered/forged/
+    #    wrong-issuer; 2 on misconfig; 1 on IO. We propagate that exit code so GitHub Actions fails the
+    #    job on any non-zero — blocking the merge.
+    #
+    #    VERIFY_VH defaults to the action's OWN bundled verify-vh.js, resolved via ${{ github.action_path }}
+    #    so it points at the verifier tree this action shipped — NOT a path in the consumer's workspace.
+    - name: Verify sealed artifacts (fails the build on a bad seal)
+      shell: bash
+      env:
+        VERIFY_VH: ${{ inputs.verify-vh != '' && inputs.verify-vh || format('{0}/../verify-vh.js', github.action_path) }}
+        VH_VENDOR: ${{ inputs.vendor }}
+        VH_MANIFEST: ${{ inputs.manifest }}
+        VH_ARTIFACTS: ${{ inputs.artifacts }}
+        VH_DIR: ${{ inputs.dir }}
+      run: |
+        set -euo pipefail
+        VERIFY_VH="${VERIFY_VH:-./verifier/verify-vh.js}"
+
+        # 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.
+        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 gate: set 'manifest' or '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
+
+        # `vendor` is OPTIONAL: pin the signer only when one is supplied (an unsigned evidence seal has
+        # no signer to pin, so verifying tamper-evidence alone must NOT force a vendor). SECURITY NOTE:
+        # without --vendor a SIGNED artifact is accepted on its OWN self-claimed signer — pin the
+        # producer's signer for any signed release (see the README warning + the `vendor` input doc).
+        if [ -n "${VH_VENDOR:-}" ]; then
+          set -- "$@" --vendor "$VH_VENDOR"
+        fi
+        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 gate: FAILED (exit $code) — blocking the merge." >&2
+        fi
+        exit "$code"