verifyhash 0.1.0

package/docs/DECIDE.md

@@ -0,0 +1,47 @@
+# DECIDE — the one human decision
+
+This is the **only** page a human needs to read to unblock the loop. Everything below is BUILT and
+locally TESTED; the loop cannot take the one remaining step for you, because it must never provision a
+key, set a price, or contact a buyer. There is exactly one open human item, and it is `needs-human` P-8
+(see [`docs/MORNING.md`](MORNING.md) § Needs-human). This page does not add a new ask — it just makes P-8
+legible on one screen. **It is GENERATED from the P-8 block in MORNING.md (`scripts/sync-decide.cjs`), so
+it can never silently drift from the real ask.**
+
+## The decision (pick this)
+
+**Run ONE time-boxed design-partner pilot of the EVIDENCE vertical (P-7).** EVIDENCE is the
+lighter-gated path: no CPA, no counsel, no per-state liability layer, no real-funds deploy — just a
+vendor key, a price, and one partner. (The heavier TrustLedger vertical, P-5, is the fallback channel.)
+
+## The 3 first actions (verbatim from P-8)
+
+1. **Pick the lighter-gated vertical FIRST: EVIDENCE (P-7), not TrustLedger (P-5)** — no CPA/legal/per-state
+2. **One concrete first target this week:** an incident-response / digital-forensics team OR an
+3. **3-step first contact (no slide deck):** (a) `vh identity publish` once the vendor key exists; (b) hand
+
+## The one command to run on their folder
+
+```
+node pilot/run-pilot.js --certificate <path>
+```
+
+Add `--evidence-dir /path/to/their/folder` to seal THEIR files; the result is a single, forwardable
+`*.vhevidence.json` certificate their security team verifies independently with `verify-vh` — offline, no
+key, no network. The full runbook is [`docs/PILOT.md`](PILOT.md).
+
+## Time box / stop criterion
+
+3–5 prospects over ~2 weeks. **Success = ONE** who keeps using the free verify/challenge weekly OR agrees
+to a paid pilot. **Zero after the box → stop**: the signal is "wrong buyer archetype" → switch to the
+TrustLedger broker channel, NOT "build more product."
+
+## Revenue-integrity boundary
+
+Income is a subscription / license / meter for delivered software value; the license is an
+ACCESS credential, NOT a token/coin/NFT, not tradeable, not an appreciating asset. The loop ships only the
+mechanism + ephemeral test keys and must NEVER provision a key, set a price, contact a prospect, host,
+take payment, or run the pilot itself — those are the human steps in P-8.
+
+
+---
+<sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>

package/docs/DECISIONS-PENDING.md

@@ -0,0 +1,27 @@
+# The 3 decisions that unblock everything (one page)
+
+Audit 2026-07-03: the ~11 stacked `needs-human` proposals in STRATEGY.md reduce to THREE distinct
+decisions. Each has a pre-filled recommended default — **replying "accept all defaults" is a valid,
+complete answer.** Everything else in the queue is a duplicate or depends on these.
+
+## 1. Reputation unit: soulbound or tradeable? (P-1 / D-2)
+**Default: (A) soulbound, non-transferable contribution score.** Zero securities exposure, matches the
+project goal, buildable immediately. Option (B) tradeable token requires securities counsel BEFORE any
+design work and pulls the project toward being a token project. → One word unblocks EPIC-3.
+
+## 2. First-dollar config: price + vendor key (collapses P-3/P-5/P-6/P-7/P-9/P-10)
+**Default:** self-serve **evidence license** at **$29/month or $290/year** (draft catalog price),
+vendor key provisioned by YOU on your machine (never the loop):
+`node -e "const {Wallet}=require('ethers');const w=Wallet.createRandom();console.log(w.address, w.privateKey)"`
+— keep the private key in your password manager; publish only the address. The whole mint→deliver→verify
+pipeline is already built and gated (`npm run go-live` proves it end-to-end). → A price + a key = sellable.
+
+## 3. Distribution: put the free tool in front of real people (the audit's #1 finding)
+**Default:** (a) publish the package to npm (`npm publish` from your logged-in account — the package is
+ready), (b) show the zero-install browser verifier (verifyhash.com/verify-vh-standalone.html) to ~10
+people in ONE segment — recommended: AI-agent builders (AGENTTRACE angle) or property managers
+(TrustLedger angle) — and count who uses it twice. That count becomes `docs/ADOPTION.json`, the loop's
+first external signal. **No new product epics until it is non-zero.**
+
+---
+*Answering #2 + #3 makes the first dollar mechanically possible. #1 just unblocks a parked epic.*

package/docs/DEPLOY-PUBLIC-SITE.md

@@ -0,0 +1,301 @@
+# verifyhash.com — Public Static Site Deployment Runbook (REPLACE mode)
+
+> **Audience:** a Claude instance (or operator) with privileges this repo's autonomous loop does
+> **not** have — i.e. can write to `/var/www/`, edit files under `/etc/nginx/`, and `sudo systemctl
+> reload nginx`. Hand this whole file over; it is self-contained.
+>
+> **This file is an internal ops/deploy doc — do NOT serve it.** It is not in the publish set.
+>
+> Generated by the verifyhash loop supervisor, 2026-06-26. Hash source of truth = the committed
+> `*.sha256` sidecars in `verifier/dist/`; the build script re-verifies, so don't trust this doc's copy.
+
+## ENVIRONMENT — already in place (confirmed 2026-06-26 19:49Z)
+
+- **Domain `verifyhash.com`** (+`www`) → resolves to **this host** (85.215.206.196). DNS done.
+- **TLS done** — Let's Encrypt cert live at `/etc/letsencrypt/live/verifyhash.com/`; HTTPS serves HTTP/2 200.
+- **nginx vhost exists**: `/etc/nginx/conf.d/verifyhash.com.conf` (http→https redirect, `root /var/www/verifyhash.com/html`, a static-asset cache `location`, a `location /api/ → localhost:3005` proxy, and a `.git` deny).
+- **The webroot already holds a DIFFERENT, older site** — *"VerifyHash — Decentralized JSON Storage Network"* (`index.html` + `js/`) with a Node backend proxied at `/api/ → :3005` that is currently **down (502)**. **Decision: REPLACE it.** This runbook retires that old site and serves the provenance product at the `verifyhash.com` root.
+
+So there is **no DNS, no certbot, no nginx install** to do. The job is: (1) swap the webroot contents, (2) two small vhost edits, (3) reload, (4) verify.
+
+---
+
+## 0. What you are deploying (and what you are NOT)
+
+A **static, read-only** site publishing verifyhash's independent-verification artifacts:
+- the single-file, zero-dependency, **offline** verifier `verify-vh-standalone.js` + its `sha256`,
+- the companion offline **sealer** `seal-vh-standalone.js` + `sha256`,
+- the **build-provenance manifest** `build-provenance.json`,
+- the version-controlled **landing page** (`site/index.html` — download links, verify one-liner, reproduce-from-source steps, honest boundary),
+- the **prospect-facing docs** (CONFORMANCE, PILOT, KEY-LIFECYCLE, INDEPENDENT-VERIFICATION, …),
+- a generated **`RELEASE-MANIFEST.json`** (sorted paths, per-file sha256 + source, total bytes) so the upload can be verified file-by-file.
+
+The exact publish set is the committed allowlist **`site/publish-set.json`** (published path → committed
+repo source). `scripts/site-release.js` assembles the webroot from EXACTLY that mapping — nothing outside
+it can enter `public/`, which makes the "must NEVER be served" table below *structural*, not just prose.
+
+**NOT** in scope (deliberately): no backend, no uploads, no API, no DB, no key, no payment, no token.
+The product's trust model is *offline* verification — a server that "verifies for you" would weaken it.
+(The repo's one server, `trustledger/server.js`, is a separate localhost-only broker demo, not part of this site.)
+
+---
+
+## 1. ⚠️ CRITICAL SAFETY RULES — read before touching anything
+
+The nginx `root` for verifyhash.com must stay **`/var/www/verifyhash.com/html`** and that directory
+must contain **only** the allowlisted static files below. A scan of this box found **real secrets** that
+would be catastrophic to expose if the webroot were ever pointed at the repo or home dir.
+
+**NEVER set `root`/`alias`/`try_files` to** `/home/loopdev/verifyhash` (repo), `/home/loopdev` (home),
+or anything but the dedicated webroot. **Deploy by copying real files — never symlink into the repo.**
+
+**Must NEVER be served:**
+
+| Path | Why |
+|---|---|
+| `/home/loopdev/.claude/.credentials.json` | **LIVE Claude.ai OAuth token** — the single most dangerous file on the box. |
+| `/home/loopdev/.claude.json`, `/home/loopdev/.claude/` | CLI config + full transcripts / session history / memory. |
+| `/home/loopdev/verifyhash/.git/` | 38 MB history — clonable = the whole repo incl. every internal doc. |
+| `test/cli.commit.parent.test.js`, `test/cli.claim.test.js` | committed `0x…` **private keys** (Hardhat dev keys; no real funds, but scanners flag them). |
+| `.env` (none today; pre-deny), `**/*.vhclaim.json` (secret salt; pre-deny) | would leak keys/salts. |
+| `STRATEGY.md`, `BACKLOG.md`, `HANDOFF.md`, `AGENT_TEAM.md`, `team.json` | internal roadmap / ops. |
+| `build-loop.workflow.js`, `build-loop.prev.js` | the autonomous loop engine + guardrails. |
+| `docs/USAGE-BUDGET.json`, `docs/METRICS.jsonl`, `docs/MORNING.md`, `docs/AUDIT.md`, `docs/DEPLOY-PUBLIC-SITE.md` | internal ops telemetry + this runbook. |
+| `node_modules/`, `artifacts/`, `cache/`, `scripts/`, `hardhat.config.js`, `.scope-baseline.json` | build internals. |
+
+The safe pattern below `rsync --delete`s a vetted, allowlist-only tree into the webroot — nothing else
+can leak because nothing else is ever copied there. (Scan also confirmed: no real `.env`, no PEM/SSH
+keys, no mnemonics, no API keys anywhere. The only risk is *where nginx points*.)
+
+---
+
+## 2. Prerequisites (most are already satisfied)
+
+- ✅ Domain, DNS, TLS, nginx — all already in place for verifyhash.com (see ENVIRONMENT).
+- You need: `sudo` (to write `/var/www/verifyhash.com/html` and edit the vhost), `rsync`, and `node`
+  (only to run the one-time `--check` integrity gate; the site needs no node at runtime).
+- Read access to `/home/loopdev/verifyhash` (to copy the artifacts from).
+
+---
+
+## 3. Deploy the webroot (replaces the old site)
+
+**The upload step is:** run `node scripts/site-release.js`, upload `public/`, verify against
+`RELEASE-MANIFEST.json`. The assembler regenerates `public/` **deterministically** from the committed
+allowlist `site/publish-set.json` (nothing outside the allowlist can enter the webroot), and
+`--check` re-proves byte-for-byte integrity before you copy anything.
+
+### 3a — assemble + integrity gate, then atomic replace
+
+```bash
+set -euo pipefail
+REPO=/home/loopdev/verifyhash
+SRC="$REPO/public"                      # the assembled, allowlist-only webroot
+WEBROOT=/var/www/verifyhash.com/html
+
+# 1) ASSEMBLE the webroot from the committed publish set (deterministic; writes only inside the repo)
+node "$REPO/scripts/site-release.js"
+
+# 2) INTEGRITY GATE — refuse to deploy a tampered/stale webroot (offline, writes nothing)
+node "$REPO/scripts/site-release.js" --check               # MUST print OK and exit 0
+( cd "$REPO/verifier/dist" && sha256sum -c verify-vh-standalone.js.sha256 && sha256sum -c seal-vh-standalone.js.sha256 )
+node "$REPO/verifier/build-standalone.js" --check          # MUST print all-MATCH and exit 0
+( cd "$SRC" && sha256sum -c verify-vh-standalone.js.sha256 && sha256sum -c seal-vh-standalone.js.sha256 )
+
+# 3) back up the OLD site once, then REPLACE it (—delete removes anything not in the publish set)
+sudo cp -a "$WEBROOT" "/var/www/verifyhash.com/html.bak.$(date +%Y%m%d-%H%M%S)" || true
+sudo rsync -a --delete "$SRC"/ "$WEBROOT"/
+
+# 4) ownership nginx expects
+sudo chown -R www-data:www-data "$WEBROOT"
+
+# 5) VERIFY THE UPLOAD against the manifest that shipped inside it (per-file sha256, all must match)
+( cd "$WEBROOT" && node -e '
+  const fs=require("fs"),c=require("crypto");
+  const m=JSON.parse(fs.readFileSync("RELEASE-MANIFEST.json","utf8"));let bad=0;
+  for(const f of m.files){const h=c.createHash("sha256").update(fs.readFileSync(f.path)).digest("hex");
+    if(h!==f.sha256){bad++;console.error("MISMATCH "+f.path);}}
+  console.log(bad?"UPLOAD BROKEN — do not announce":"upload verified: "+m.files.length+" files match RELEASE-MANIFEST.json");
+  process.exit(bad?1:0);' )
+
+echo "Deployed. Old site backed up to /var/www/verifyhash.com/html.bak.*"
+```
+
+> There is no hand-copy recipe anymore — the publish set lives in **`site/publish-set.json`**
+> (published path → committed source, incl. the renames like `challenge/README.md` →
+> `docs/challenge-README.md`) and `scripts/site-release.js` is the only generator. To change what the
+> site serves, edit the allowlist, re-run the assembler, and commit the regenerated
+> `site/RELEASE-MANIFEST.json`. **Never glob `docs/*.md` into the webroot — it contains internal files;
+> the assembler refuses forbidden entries (`.git*`, env/key-shaped names, this runbook, ops telemetry) by construction.**
+> After the upload, record what went live: `node scripts/site-release.js --mark-deployed` rewrites
+> `site/DEPLOYED.json` (the drift baseline) — see §3c.
+
+### 3b — the landing page
+
+The landing page is **version-controlled at `site/index.html`** (the assembler stages it as
+`public/index.html`). It carries the verifyhash.com URLs, the published sha256, the verify one-liner,
+the reproduce-from-source steps, and the honest boundary. To change it, edit `site/index.html`,
+re-run `node scripts/site-release.js`, and commit. If you want to set a real producer address in the
+example, edit the `0x<…>` placeholder in §2 of that page (in `site/index.html`, then re-assemble).
+
+> ⚠️ **Whenever the verifier bundle changes, update the page's `Published SHA-256:` to match.** The
+> page's whole pitch is "don't trust us — download `verify-vh-standalone.js` and compare its hash
+> yourself", so its advertised hash must equal the sha256 of the `verify-vh-standalone.js` this release
+> ships (and the `.sha256` sidecar). If you rebuild the bundle but forget the page, the assembled
+> webroot would fail its own cross-check — a false "tampered?" signal for buyers. **`node
+> scripts/site-release.js` now REFUSES to assemble (and `--check` goes RED, naming `LANDING PAGE DRIFT`)
+> when the page's `Published SHA-256:` ≠ the shipped bundle's sha256**, so this drift can never ship
+> silently — but fix it at the source by editing `site/index.html`'s `Published SHA-256:` value.
+
+### 3c — close the loop: `--mark-deployed`, then keep `--diff` clean (the P-11 refresh)
+
+The full refresh flow is: **release → upload → `--mark-deployed` → `--diff` clean.**
+
+1. **release** — `node scripts/site-release.js` assembles `public/` + writes both manifests (§3a step 1),
+   and `--check` gates it (§3a step 2).
+2. **upload** — the rsync + upload-verify of §3a steps 3–5. This is the human-owned step.
+3. **`--mark-deployed`** — `node scripts/site-release.js --mark-deployed` rewrites `site/DEPLOYED.json`
+   to the manifest you just uploaded + an ISO date note (`markedDeployedAt`). **Commit it.** This is the
+   ONE command you run AFTER uploading — it records what went live so the next `--diff` is truthful.
+   It records only; it never uploads anything.
+4. **`--diff` clean** — `node scripts/site-release.js --diff` compares `site/DEPLOYED.json` (what is
+   believed LIVE) against a fresh assembly and prints a per-file `ADDED`/`CHANGED`/`REMOVED`/`UNCHANGED`
+   table + a one-line verdict. Right after a correct upload + `--mark-deployed` it must print
+   `live site matches the current release`. From then on, whenever it prints
+   `live site is stale: N of M published files differ — refresh per P-11`, redo this section.
+   Staleness is a HUMAN decision signal, not a CI failure: `--diff` exits `0` whether stale or clean;
+   only a malformed/missing `site/DEPLOYED.json` exits `3` (with a named error). The standing test
+   suite pins the committed `site/RELEASE-MANIFEST.json` to a fresh assembly (so the drift signal can
+   never itself go stale), but a stale `site/DEPLOYED.json` never fails the suite.
+
+**Boundary (verbatim):** the loop assembles and diffs INSIDE the repo only; uploading to the live host
+is the human-owned P-11 step — never auto-executed. (P-11 in `STRATEGY.md` is the recurring ~10-minute
+refresh action this section implements.)
+
+---
+
+## 4. nginx vhost — two small edits to the EXISTING block
+
+Edit `/etc/nginx/conf.d/verifyhash.com.conf`. Keep the `listen`/`server_name`/`ssl_*`/redirect lines.
+Make these changes inside the `server { … }` that serves 443:
+
+**(a) Remove the dead backend proxy** (the old JSON-storage app):
+```nginx
+# DELETE this whole block — there is no backend in the provenance product:
+#   location /api/ { proxy_pass http://localhost:3005/api/; ... }
+```
+
+**(b) Make `/` 404 on missing files (not an SPA fallback), and serve the verifier as a named download.**
+Replace the existing `location /` and the static-asset cache block with:
+```nginx
+    autoindex off;
+    server_tokens off;
+    add_header X-Content-Type-Options "nosniff" always;
+
+    # never serve dotfiles even if one ever lands in the webroot
+    location ~ /\.  { deny all; return 404; }
+
+    # verifier + sealer: force download under the EXACT pinned filename so `sha256sum -c` works verbatim
+    location = /verify-vh-standalone.js {
+        default_type application/javascript;
+        add_header Content-Disposition 'attachment; filename="verify-vh-standalone.js"';
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+    location = /seal-vh-standalone.js {
+        default_type application/javascript;
+        add_header Content-Disposition 'attachment; filename="seal-vh-standalone.js"';
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+    location ~ \.sha256$              { default_type text/plain; }
+    location = /build-provenance.json { default_type application/json; }
+    location ~ \.md$                 { default_type "text/markdown; charset=utf-8"; }
+
+    location / { try_files $uri $uri/ =404; }   # NOT `/index.html` — a real 404 for missing paths
+```
+Keep `root /var/www/verifyhash.com/html;` and `index index.html;` as they are.
+
+**Apply:**
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+---
+
+## 5. DNS + TLS — already done
+
+Nothing to do. DNS resolves here and the Let's Encrypt cert is live (certbot's renewal timer already
+covers it). If you ever add a `verify.verifyhash.com` second origin (§7), that one needs its own cert.
+
+---
+
+## 6. Pre-go-live verification checklist
+
+Run **all**; every line must pass before you announce it.
+
+```bash
+D=https://verifyhash.com
+
+# a) verifier downloads and its published hash checks out end-to-end
+curl -fsS -o /tmp/v.js "$D/verify-vh-standalone.js"
+curl -fsS -o /tmp/v.js.sha256 "$D/verify-vh-standalone.js.sha256"
+( cd /tmp && sha256sum -c v.js.sha256 )            # must say: verify-vh-standalone.js: OK
+
+# b) landing page is the NEW site (provenance), not the old JSON-storage one, and its advertised
+#    Published SHA-256 matches the bundle you just uploaded (read the served sidecar's hash and
+#    confirm the landing page advertises that exact string — no hard-coded hash to go stale)
+VERIFY_SHA=$(curl -fsS "$D/verify-vh-standalone.js.sha256" | cut -d' ' -f1)
+curl -fsS "$D/" | grep -q "$VERIFY_SHA" && echo "landing OK (advertises the shipped bundle hash)" || echo "STOP: landing page hash != shipped bundle"
+curl -fsS "$D/" | grep -qi "JSON Storage Network" && echo "STOP: old site still served" || echo "old site gone OK"
+
+# c) the dead backend is detached — /api/ must NOT proxy anymore
+curl -s -o /dev/null -w 'api/ -> %{http_code} (expect 404)\n' "$D/api/health"
+
+# d) NONE of the forbidden paths are reachable (expect 404/403 for ALL)
+for p in .git/HEAD .git/config .env ../STRATEGY.md ../BACKLOG.md \
+         ../build-loop.workflow.js ../../.claude/.credentials.json \
+         ../docs/USAGE-BUDGET.json ../test/cli.claim.test.js; do
+  echo "$(curl -s -o /dev/null -w '%{http_code}' "$D/$p")  $p"   # a 200 anywhere is STOP-SHIP
+done
+
+# e) no directory listing
+curl -s "$D/docs/" | grep -qi "index of" && echo "FAIL: autoindex on" || echo "no listing OK"
+```
+
+Any forbidden path returning `200`, or the old "JSON Storage Network" string still present → **stop**,
+fix, re-run. Once clean, the old-site backup `/var/www/verifyhash.com/html.bak.*` can be deleted.
+
+---
+
+## 7. Optional: retire the old `:3005` backend + a second download origin
+
+- **The old Node backend** on `localhost:3005` (the JSON-storage app) is already down and now detached
+  from the domain (§4a). Stopping/disabling its service + deleting its files is the owner's call — it is
+  unrelated to this site and **not** required for go-live. Don't delete anything you can't identify.
+- **Second origin (nice-to-have):** serving the verifier from `verify.verifyhash.com` (its own vhost +
+  cert) makes the "don't trust the vendor" pitch literally true at the network layer. The hash is the
+  trust anchor, so same-origin is already safe — this is a fast-follow, not a blocker.
+
+---
+
+## 8. Guardrail boundary — division of labor
+
+- **The loop (unprivileged) builds artifacts in-tree** — the `verifier/dist/*` bundles and the prebuilt
+  `public/` webroot — as local commits. It **did not** and **cannot** write to `/var/www`, edit nginx,
+  bind a port, hold a key, or touch the `:3005` service. (`public/` is git-ignored; rebuild it anytime.)
+- **You (privileged agent / human) do the outward-facing steps** — `rsync` into `/var/www`, edit the
+  vhost, reload nginx. That is the human action the loop is forbidden from taking.
+- **Nothing here is a deployed service.** Static publication of already-public, git-tracked files crosses
+  no no-deploy / no-funds / no-token line: no key, no payment, no data custody, no token issuance.
+
+---
+
+## Appendix — file inventory & hashes
+
+The canonical inventory is **generated, not hand-typed**: `site/RELEASE-MANIFEST.json` (committed twin;
+the same bytes ship inside the webroot as `public/RELEASE-MANIFEST.json`) lists every published path,
+its committed source path, its byte count, and its SHA-256, in sorted order. The allowlist it is built
+from is `site/publish-set.json`; the snapshot of what is believed live is `site/DEPLOYED.json`.
+
+**Always re-derive hashes from `node scripts/site-release.js --check` + the committed sidecars; never
+trust a hand-copied table.** Assembled webroot to deploy: **`/home/loopdev/verifyhash/public/`** →
+**`/var/www/verifyhash.com/html`**.

package/docs/ENGINE-LEDGER.json

@@ -0,0 +1,12 @@
+{
+  "_doc": "Append-only ledger of engine md5s that passed BOTH self-upgrade gates at launch time (scripts/pre-run-gate.cjs). The supervisor refuses to launch an engine not gated here. Never rewrite prior entries.",
+  "engines": [
+    {
+      "md5": "88bf8ee0db9038b8847a8e7468428457",
+      "gatedAt": "2026-07-03T04:33:10.820Z",
+      "prevMd5": "db5b3aceda33973e6be0df366caebd93",
+      "validate": "PASS",
+      "smoke": "SMOKE-PASS (4 scenarios: all-pass commits with verify-before-commit [20 calls]; FAILING verdict BLOCKs with NO commit; t"
+    }
+  ]
+}