verifyhash 0.1.0

package/cli/registry.js

@@ -0,0 +1,331 @@
+"use strict";
+
+// cli/registry.js — authenticate a deployed ContributionRegistry BEFORE believing any record it
+// returns (T-11.2).
+//
+// WHY THIS EXISTS
+//   Every read command (`vh verify` / `show` / `list` / `lineage` / `verify-proof`) historically
+//   trusted whatever (rpc, address) pair the caller supplied: it just called `getRecord` and reported
+//   the answer. But the answer is only as trustworthy as the assumption that the address really is a
+//   verifyhash registry on the network the caller thinks it is. Two failure modes silently produced a
+//   confident-looking-but-wrong verdict:
+//     * pointed at an address with NO contract (typo'd address, or right address on the WRONG network)
+//       — `getRecord` reverts and is read as "not anchored" (a MISMATCH), so a genuinely-anchored
+//       contribution is mislabeled as tampered/absent;
+//     * pointed at a DEPLOYED but DIFFERENT contract (a look-alike, a fork, an unrelated contract whose
+//       storage happens to decode) — it may answer with garbage records that get reported as truth.
+//   T-11.1 baked an immutable, ownerless `REGISTRY_ID` / `REGISTRY_VERSION` self-identification marker
+//   into the contract precisely so an off-chain verifier can authenticate the bytecode is the right
+//   interface. This module is that verifier: a single, reusable, side-effect-free preflight every read
+//   command runs FIRST, so no record/verdict is reported until the registry is authenticated.
+//
+// WHAT THE PREFLIGHT PROVES (and what it does NOT)
+//   It proves you are talking to a contract that (a) exists at the address, (b) self-identifies as a
+//   verifyhash ContributionRegistry of a version this build understands, and (c) — when an
+//   artifact/receipt records the chain it was anchored on — lives on THAT chain. That closes the
+//   "wrong address / wrong network / wrong contract" gap.
+//   It does NOT make the RECORDS honest beyond the contract's own immutable first-writer-wins +
+//   commit-reveal rules, and (as the contract NatSpec warns) a FORK can reuse the same REGISTRY_ID — so
+//   the marker is a POSITIVE "right interface on the right chain" signal, never a sole root of trust.
+//   See docs/TRUST-BOUNDARIES.md and the contract's "ON-CHAIN IDENTITY MARKER" notice.
+//
+// DISCIPLINE (mirrors verify.js's isNotAnchoredError): a genuine RPC/network error is RE-THROWN as
+// itself, never masqueraded as an identity failure. An identity failure is only ever reported when the
+// chain answered and the answer was wrong (no code / wrong id / wrong version / wrong chain).
+
+const ARTIFACT = require("./core/registryArtifact");
+const ABI = ARTIFACT.abi;
+
+// The DOCUMENTED, frozen identity (T-11.1). Re-derived from the same preimage string the contract's
+// NatSpec pins, so this module and the contract can never silently drift: if the preimage moved, this
+// derived value would move with it AND the pinned digest below would mismatch in tests.
+const REGISTRY_ID_PREIMAGE = "verifyhash.ContributionRegistry.v1";
+// The frozen on-chain digest, pinned literally (same value test/Identity.test.js pins). We compare the
+// contract's REGISTRY_ID against THIS, not against a value we re-derive at call time, so a tampered
+// derivation can't move the goalpost. (deriveRegistryId() lets a test confirm the pin matches the
+// preimage.)
+const EXPECTED_REGISTRY_ID =
+  "0x0395e2ec987e96e51cdf619980638100236c5fc7f7c3646f8b759f3cdceb2df3";
+
+// The maximum REGISTRY_VERSION this build understands. A registry reporting a HIGHER version made a
+// breaking interface change we cannot safely read, so we refuse it rather than mis-decode its records.
+const MAX_SUPPORTED_REGISTRY_VERSION = 1n;
+
+// The "0x" / "0x0" empty-code sentinels eth_getCode returns for an address with no contract. ethers v6
+// returns "0x" for an externally-owned (or non-existent) account.
+const EMPTY_CODE = new Set(["0x", "0x0", ""]);
+
+/**
+ * Re-derive REGISTRY_ID from the documented preimage. Used by tests to confirm the pinned digest above
+ * actually equals keccak256(preimage) — kept here so the preimage lives in exactly one place.
+ * @param {object} ethersLib ethers v6 module
+ * @returns {string} the 0x 32-byte id
+ */
+function deriveRegistryId(ethersLib) {
+  return ethersLib.keccak256(ethersLib.toUtf8Bytes(REGISTRY_ID_PREIMAGE));
+}
+
+/**
+ * Distinguish a genuine RPC/network error (provider down, bad URL, timeout, decode-layer failure on a
+ * malformed response) from a clean negative answer the chain actually gave us. We RE-THROW genuine
+ * errors as themselves so the preflight never masquerades a network problem as an identity failure
+ * (mirroring verify.js's isNotAnchoredError discipline, in the opposite direction).
+ *
+ * A call to a method that does not exist on the target contract (e.g. REGISTRY_ID on a non-registry)
+ * reverts — ethers v6 surfaces that as a CALL_EXCEPTION / BAD_DATA (the function selector found nothing
+ * to decode), which IS a clean "the chain answered, it is not this contract" signal, NOT a network
+ * error. Everything else (NETWORK_ERROR, TIMEOUT, SERVER_ERROR, connection refused, …) is genuine.
+ *
+ * @param {any} err
+ * @returns {boolean} true iff this looks like a real network/RPC failure (re-throw), not an identity miss
+ */
+function isGenuineRpcError(err) {
+  if (!err) return false;
+  const code = err.code;
+  // ethers v6 network/transport failure codes — these are genuine and must be re-thrown.
+  if (
+    code === "NETWORK_ERROR" ||
+    code === "TIMEOUT" ||
+    code === "SERVER_ERROR" ||
+    code === "UNKNOWN_ERROR" ||
+    code === "UNSUPPORTED_OPERATION"
+  ) {
+    return true;
+  }
+  // A reverted/empty call (the method isn't there, or returned no decodable data) is a clean negative,
+  // not a network error: CALL_EXCEPTION / BAD_DATA mean "the chain answered; that contract has no such
+  // function / returned undecodable data". Those are identity misses, handled by the caller.
+  if (code === "CALL_EXCEPTION" || code === "BAD_DATA") return false;
+  // Textual fallbacks for providers that don't set a code: connection-shaped messages are genuine.
+  const msg = String((err && err.message) || "").toLowerCase();
+  if (/econnrefused|enotfound|etimedout|socket hang up|fetch failed|network|timeout|failed to detect/.test(msg)) {
+    return true;
+  }
+  // Default: treat an undecorated failure as an identity miss, NOT a network error — the caller turns
+  // it into the actionable "not a verifyhash registry" message. (A real network error almost always
+  // carries one of the codes/messages above.)
+  return false;
+}
+
+/**
+ * A typed error for an authentication failure, so a caller can distinguish a registry-identity failure
+ * (the chain answered, the answer was wrong) from a re-thrown genuine RPC error.
+ */
+class RegistryAuthError extends Error {
+  constructor(message, detail) {
+    super(message);
+    this.name = "RegistryAuthError";
+    this.code = "REGISTRY_AUTH_FAILED";
+    if (detail) this.detail = detail;
+  }
+}
+
+/**
+ * Authenticate a deployed ContributionRegistry BEFORE any record read. Pure-ish and side-effect-free:
+ * it makes only read-only `eth_call` / `eth_getCode` / `eth_chainId` requests through the supplied
+ * provider, writes nothing, and constructs nothing persistent.
+ *
+ * Checks, in order:
+ *   (a) there IS a contract at `contractAddress` (provider.getCode != "0x"); otherwise hard-error with
+ *       an actionable "no contract at <addr> on this RPC — wrong address or wrong network?" message;
+ *   (b) the contract self-identifies as a verifyhash registry: REGISTRY_ID equals the documented,
+ *       frozen id AND REGISTRY_VERSION is present and <= the max version this build understands;
+ *       otherwise hard-error "the contract at <addr> is not a verifyhash ContributionRegistry
+ *       (identity check failed) — refusing to trust its records";
+ *   (c) if `expectedChainId` is supplied (from a receipt/proof artifact), the provider's chainId equals
+ *       it; otherwise hard-error "artifact/receipt was anchored on chainId X but this RPC is chainId Y —
+ *       refusing to report a verdict against the wrong network".
+ *
+ * A genuine RPC/network error is RE-THROWN as itself (never masqueraded as an identity failure).
+ *
+ * @param {object} opts
+ * @param {object} opts.provider          ethers v6 Provider (read-only)
+ * @param {string} opts.contractAddress   the address to authenticate
+ * @param {number|string|bigint} [opts.expectedChainId] chain the artifact/receipt was anchored on
+ * @param {object} [opts.ethers]          ethers v6 module (defaults to the bundled one)
+ * @returns {Promise<{ chainId: number, registryVersion: number, registryId: string,
+ *                     address: string }>} resolved identity on success
+ */
+async function assertRegistry(opts) {
+  const ethersLib = (opts && opts.ethers) || require("ethers");
+  const provider = opts && opts.provider;
+  const rawAddress = opts && opts.contractAddress;
+
+  if (!provider) {
+    throw new Error("assertRegistry requires a provider");
+  }
+  if (!rawAddress) {
+    throw new Error(
+      "no contract address: pass --contract <address> or set VH_CONTRACT in the environment"
+    );
+  }
+  if (!ethersLib.isAddress(rawAddress)) {
+    throw new Error(`invalid contract address: ${rawAddress}`);
+  }
+  const address = ethersLib.getAddress(rawAddress);
+
+  // (a) Is there a contract at all? An address with NO code answers every call with empty data, which
+  // a naive getRecord reads as "not anchored" — exactly the wrong-address/wrong-network silent failure
+  // we are closing. Check code FIRST so the message is the actionable one, not a downstream decode error.
+  let code;
+  try {
+    code = await provider.getCode(address);
+  } catch (err) {
+    if (isGenuineRpcError(err)) throw err; // never masquerade a network error as an identity failure
+    // A non-network failure to even read code is still genuine-ish; surface it rather than guessing.
+    throw err;
+  }
+  if (typeof code !== "string" || EMPTY_CODE.has(code.toLowerCase())) {
+    throw new RegistryAuthError(
+      `no contract at ${address} on this RPC — wrong address or wrong network? ` +
+        "Nothing is deployed there, so there are no records to trust. " +
+        "Check --contract / VH_CONTRACT and --rpc / VH_RPC_URL.",
+      { reason: "no-code", address }
+    );
+  }
+
+  const contract = new ethersLib.Contract(address, ABI, provider);
+
+  // (b) Does it self-identify as a verifyhash registry? Read REGISTRY_ID and REGISTRY_VERSION. A
+  // contract that lacks these (a non-registry) reverts the call — a CLEAN "not this contract" negative
+  // (CALL_EXCEPTION/BAD_DATA), distinct from a network error, which we re-throw.
+  let registryId;
+  let registryVersion;
+  try {
+    registryId = await contract.REGISTRY_ID();
+  } catch (err) {
+    if (isGenuineRpcError(err)) throw err;
+    throw new RegistryAuthError(
+      identityFailureMessage(address) +
+        " (it has no REGISTRY_ID() — the on-chain identity marker is absent).",
+      { reason: "no-registry-id", address }
+    );
+  }
+  if (String(registryId).toLowerCase() !== EXPECTED_REGISTRY_ID.toLowerCase()) {
+    throw new RegistryAuthError(
+      identityFailureMessage(address) +
+        ` (REGISTRY_ID mismatch: got ${String(registryId)}, expected ${EXPECTED_REGISTRY_ID}).`,
+      { reason: "registry-id-mismatch", address, got: String(registryId) }
+    );
+  }
+
+  try {
+    registryVersion = await contract.REGISTRY_VERSION();
+  } catch (err) {
+    if (isGenuineRpcError(err)) throw err;
+    throw new RegistryAuthError(
+      identityFailureMessage(address) +
+        " (it has no REGISTRY_VERSION() — the on-chain identity marker is incomplete).",
+      { reason: "no-registry-version", address }
+    );
+  }
+  const versionBig = BigInt(registryVersion);
+  if (versionBig > MAX_SUPPORTED_REGISTRY_VERSION) {
+    throw new RegistryAuthError(
+      `the contract at ${address} reports REGISTRY_VERSION ${versionBig}, but this build only ` +
+        `understands up to ${MAX_SUPPORTED_REGISTRY_VERSION} — refusing to mis-read a newer ` +
+        "registry's records. Upgrade your verifyhash CLI.",
+      { reason: "version-too-new", address, version: Number(versionBig) }
+    );
+  }
+
+  // Resolve the provider's chainId once (needed for the cross-check AND surfaced to the caller).
+  let networkChainId;
+  try {
+    const net = await provider.getNetwork();
+    networkChainId = BigInt(net.chainId);
+  } catch (err) {
+    if (isGenuineRpcError(err)) throw err;
+    throw err; // can't read the network — genuine, surface it
+  }
+
+  // (c) Optional chainId cross-check: an artifact/receipt that records WHERE it was anchored must be
+  // verified against THE SAME chain, or the on-chain checks are meaningless (a root anchored on chain X
+  // says nothing about chain Y). This is the portability promise made trustworthy: the consumer no
+  // longer has to trust the prover's RPC blindly.
+  if (opts.expectedChainId !== undefined && opts.expectedChainId !== null) {
+    const want = BigInt(opts.expectedChainId);
+    if (want !== networkChainId) {
+      throw new RegistryAuthError(
+        `artifact/receipt was anchored on chainId ${want} but this RPC is chainId ${networkChainId} ` +
+          "— refusing to report a verdict against the wrong network. " +
+          "Point --rpc / VH_RPC_URL at the chain the artifact was anchored on.",
+        { reason: "chainid-mismatch", expected: Number(want), actual: Number(networkChainId) }
+      );
+    }
+  }
+
+  return {
+    chainId: Number(networkChainId),
+    registryVersion: Number(versionBig),
+    registryId: String(registryId).toLowerCase(),
+    address,
+  };
+}
+
+/** The shared identity-failure lead sentence, reused for every (b)-class failure so callers/tests see
+ * one consistent, actionable message. */
+function identityFailureMessage(address) {
+  return (
+    `the contract at ${address} is not a verifyhash ContributionRegistry ` +
+    "(identity check failed) — refusing to trust its records"
+  );
+}
+
+/**
+ * Format the one-line "registry authenticated" human confirmation a read command prints so a user can
+ * SEE the check ran. Kept in one place so every command's confirmation reads identically.
+ * @param {{registryVersion:number, chainId:number}} auth the assertRegistry result
+ * @returns {string}
+ */
+function formatRegistryLine(auth) {
+  return `  registry authenticated: REGISTRY_ID ok (v${auth.registryVersion}), chainId ${auth.chainId}`;
+}
+
+/**
+ * The loud one-liner printed when the preflight is SKIPPED via --skip-identity-check. It must make
+ * unmistakably clear the verdict is only as trustworthy as the RPC the caller pointed at.
+ * @returns {string}
+ */
+function formatSkippedLine() {
+  return (
+    "  registry authentication: SKIPPED (--skip-identity-check). " +
+    "The verdict is only as trustworthy as the RPC/address you supplied — the contract was NOT " +
+    "confirmed to be a verifyhash registry on the expected network."
+  );
+}
+
+/**
+ * Build the machine-readable `registry` block for `--json` output on success.
+ * @param {{registryId:string, registryVersion:number, chainId:number}} auth
+ * @returns {{id:string, version:number, chainId:number}}
+ */
+function jsonRegistryBlock(auth) {
+  return { id: auth.registryId, version: auth.registryVersion, chainId: auth.chainId };
+}
+
+/** The `registry` block for `--json` when the check was skipped. */
+function jsonSkippedBlock() {
+  return {
+    skipped: true,
+    note:
+      "registry authentication SKIPPED (--skip-identity-check): the contract was NOT confirmed to be " +
+      "a verifyhash registry on the expected network. The verdict is only as trustworthy as the RPC.",
+  };
+}
+
+module.exports = {
+  assertRegistry,
+  RegistryAuthError,
+  isGenuineRpcError,
+  deriveRegistryId,
+  identityFailureMessage,
+  formatRegistryLine,
+  formatSkippedLine,
+  jsonRegistryBlock,
+  jsonSkippedBlock,
+  REGISTRY_ID_PREIMAGE,
+  EXPECTED_REGISTRY_ID,
+  MAX_SUPPORTED_REGISTRY_VERSION,
+  ABI,
+};

package/cli/reputation.js

@@ -0,0 +1,344 @@
+"use strict";
+
+// `vh reputation <addr> [--contract a] [--rpc u] [--json] [--skip-identity-check]` — a read-only,
+// verifiable CONTRIBUTION SCORE for one contributor (T-12.2).
+//
+// WHAT THIS IS
+//   A TRANSPARENT, DOCUMENTED aggregate over the records the registry holds under one address. It is
+//   purely DERIVED from on-chain state and re-derivable by anyone with the same RPC: total records,
+//   the authorBound (proven first claimant / commit-reveal) vs anchor-only (front-runnable "first
+//   anchorer") breakdown, the lineage-root (parent == 0x0) vs revision (parent != 0x0) breakdown, and
+//   the earliest/latest blockNumber + timestamp seen.
+//
+// WHAT THIS IS NOT (the trust posture — see docs/TRUST-BOUNDARIES.md, mirrored from list.js/verify.js)
+//   * It is NOT A TOKEN and NOT TRANSFERABLE. It holds no value, grants no rights; it is a view.
+//   * A score is only as meaningful as the `authorBound` bar. An anchor-only count is EXPLICITLY
+//     WEAKER, because a plain `anchor()` is front-runnable: anyone who saw a contentHash could have
+//     anchored it, so an anchor-only record proves order-of-anchoring, never authorship. The breakdown
+//     therefore reports authorBound and anchor-only SEPARATELY and NEVER collapses them into one number
+//     that would hide the difference.
+//   * It does NOT validate the CONTENT of any record. "This address has N records" says nothing about
+//     whether those records correspond to real, untampered bytes — re-derive the content hash and run
+//     `vh verify` for that.
+//   * Any tradeable/reputation-TOKEN layer is a separate, human-gated decision (D-2 / P-1 in
+//     STRATEGY.md) and is NOT built here.
+//
+// READ-ONLY BY CONSTRUCTION: takes a PROVIDER only, never a signer and never a key. It runs the
+// EPIC-11 `assertRegistry` preflight FIRST (reused from cli/registry.js) so the score is never reported
+// against an unauthenticated/look-alike contract, then pages through the contract's
+// `getRecordsByContributor` clamped view (the T-12.1 per-contributor index).
+
+const ARTIFACT = require("./core/registryArtifact");
+const ABI = ARTIFACT.abi;
+
+// Reuse the lineage-root predicate so reputation, show and list never disagree about what a "root"
+// (parent == bytes32(0)) is. T-10.1.
+const { isRoot } = require("./show");
+const { isoFromUnix, ATTRIBUTION_PROVEN, ATTRIBUTION_ANCHOR_ONLY } = require("./list");
+const {
+  assertRegistry,
+  formatRegistryLine,
+  formatSkippedLine,
+  jsonRegistryBlock,
+  jsonSkippedBlock,
+} = require("./registry");
+
+// Default page size for walking getRecordsByContributor(). The contract clamps a window to what that
+// contributor actually owns, so this is purely a request-batching knob; it never affects which records
+// come back. Mirrors list.js's DEFAULT_PAGE.
+const DEFAULT_PAGE = 100;
+
+// The trust caveat that LEADS every human-readable run. It is the load-bearing part of this command:
+// a reader must see, before any number, that the score is only as meaningful as the authorBound bar,
+// that it does not validate content, and that it is not a token. Wording is kept consistent with
+// cli/list.js's TRUST_CAVEAT and cli/verify.js's attribution language so the read commands never drift.
+const TRUST_CAVEAT = [
+  "NOTE: this score is a TRANSPARENT, on-chain-DERIVED aggregate — NOT a reputation token, NOT",
+  "transferable, and re-derivable by anyone from the same registry. It is only as meaningful as the",
+  "authorBound bar: authorBound records are proven first claimants (commit-reveal); anchor-only records",
+  "are merely the FIRST ANCHORER and are WEAKER, because a plain anchor() is front-runnable (anyone who",
+  "saw the contentHash could have anchored it). The two are reported SEPARATELY and never collapsed into",
+  "one number. The score does NOT validate the CONTENT of any record — re-derive the hash and run",
+  "`vh verify` for that. Any tradeable/reputation-token layer is gated on a human decision (D-2 / P-1).",
+].join("\n");
+
+/**
+ * Page through ONE contributor's records using the clamped getRecordsByContributor read (T-12.1).
+ * Read-only: uses only the provider. Walks fixed-size pages and stops on a short/empty page, exactly
+ * as the contract's NatSpec documents (no need to know the count up front, never a boundary revert).
+ * Returns normalized record objects in that contributor's own insertion order.
+ *
+ * @param {object} contract  an ethers v6 Contract bound to a provider
+ * @param {string} contributor  the 20-byte address (already validated/checksummed by the caller)
+ * @param {number} [pageSize]
+ * @returns {Promise<Array<{
+ *   contentHash:string, contributor:string, authorBound:boolean,
+ *   timestamp:bigint, blockNumber:bigint, uri:string, parent:string
+ * }>>}
+ */
+async function readContributorRecords(contract, contributor, pageSize = DEFAULT_PAGE) {
+  const out = [];
+  for (let start = 0; ; start += pageSize) {
+    const [contentHashes, records] = await contract.getRecordsByContributor(
+      contributor,
+      start,
+      pageSize
+    );
+    // The contract clamps to what this contributor owns: a window at/past the end returns empty arrays
+    // (never a revert), so an empty/short page is the stop signal.
+    if (contentHashes.length === 0) break;
+    for (let i = 0; i < contentHashes.length; i++) {
+      const r = records[i];
+      out.push({
+        contentHash: contentHashes[i],
+        contributor: r.contributor,
+        authorBound: Boolean(r.authorBound),
+        timestamp: BigInt(r.timestamp),
+        blockNumber: BigInt(r.blockNumber),
+        uri: r.uri,
+        // The immutable lineage edge (T-10.1). Normalized to a lowercase 0x string; a root reads back
+        // as the 32-byte zero hash (isRoot() flags it below).
+        parent: String(r.parent).toLowerCase(),
+      });
+    }
+    // A short page (fewer than requested) also means we reached the end; stop without an extra read.
+    if (contentHashes.length < pageSize) break;
+  }
+  return out;
+}
+
+/**
+ * Compute the TRANSPARENT aggregate score over a contributor's normalized records. Pure: no I/O, fully
+ * re-derivable from the same input. Returns the documented breakdowns and block/time bounds. The
+ * authorBound and anchor-only counts are kept SEPARATE (never summed into a single opaque number).
+ *
+ * @param {Array} records  normalized records from readContributorRecords (any order)
+ * @returns {{
+ *   total:number,
+ *   authorBound:number, anchorOnly:number,
+ *   lineageRoots:number, revisions:number,
+ *   earliest:{blockNumber:bigint, timestamp:bigint}|null,
+ *   latest:{blockNumber:bigint, timestamp:bigint}|null
+ * }}
+ */
+function computeScore(records) {
+  let authorBound = 0;
+  let anchorOnly = 0;
+  let lineageRoots = 0;
+  let revisions = 0;
+  let earliest = null; // by blockNumber (on-chain ordering), tie-broken by timestamp
+  let latest = null;
+
+  for (const r of records) {
+    if (r.authorBound) authorBound++;
+    else anchorOnly++;
+
+    if (isRoot(r.parent)) lineageRoots++;
+    else revisions++;
+
+    const point = { blockNumber: r.blockNumber, timestamp: r.timestamp };
+    if (earliest === null || r.blockNumber < earliest.blockNumber) earliest = point;
+    if (latest === null || r.blockNumber > latest.blockNumber) latest = point;
+  }
+
+  return {
+    total: records.length,
+    authorBound,
+    anchorOnly,
+    lineageRoots,
+    revisions,
+    earliest,
+    latest,
+  };
+}
+
+/**
+ * Shape the score + bounds for `--json`: BigInts become Numbers (unix seconds / block heights fit
+ * safely), block/time bounds carry an ISO string, and a zero-record address serializes with total: 0
+ * and null bounds (distinguishable from an error). The breakdowns stay separate fields.
+ */
+function jsonScore(addr, score, registryBlock) {
+  const bound = (b) =>
+    b === null
+      ? null
+      : {
+          blockNumber: Number(b.blockNumber),
+          timestamp: Number(b.timestamp),
+          timestampISO: isoFromUnix(b.timestamp),
+        };
+  return {
+    address: addr,
+    registry: registryBlock,
+    total: score.total,
+    // Reported SEPARATELY and never collapsed: a consumer that wants a single number must decide how to
+    // weight a front-runnable anchor-only record itself.
+    authorBound: score.authorBound,
+    anchorOnly: score.anchorOnly,
+    attribution: {
+      authorBound: ATTRIBUTION_PROVEN,
+      anchorOnly: ATTRIBUTION_ANCHOR_ONLY,
+    },
+    lineageRoots: score.lineageRoots,
+    revisions: score.revisions,
+    earliest: bound(score.earliest),
+    latest: bound(score.latest),
+  };
+}
+
+/** Render the score as the human-readable block the CLI prints (after the trust caveat + registry line). */
+function formatScore(addr, score, opts = {}) {
+  const lines = [];
+  lines.push(`  contributor:   ${addr}`);
+  if (opts.identitySkipped) {
+    lines.push(formatSkippedLine());
+  } else if (opts.registryAuth) {
+    lines.push(formatRegistryLine(opts.registryAuth));
+  }
+
+  if (score.total === 0) {
+    lines.push("  no contributions: this address has no records in the registry.");
+    return lines.join("\n");
+  }
+
+  lines.push(`  total records: ${score.total}`);
+  lines.push("  attribution breakdown (reported SEPARATELY — never summed):");
+  lines.push(`    authorBound:   ${score.authorBound}  (${ATTRIBUTION_PROVEN})`);
+  lines.push(`    anchor-only:   ${score.anchorOnly}  (${ATTRIBUTION_ANCHOR_ONLY})`);
+  lines.push("  lineage breakdown:");
+  lines.push(`    lineage roots: ${score.lineageRoots}  (parent == 0x0)`);
+  lines.push(`    revisions:     ${score.revisions}  (parent != 0x0 — a CLAIMED predecessor edge)`);
+  const e = score.earliest;
+  const l = score.latest;
+  lines.push(
+    `  earliest:      block ${e.blockNumber}, ts ${e.timestamp} (${isoFromUnix(e.timestamp)})`
+  );
+  lines.push(
+    `  latest:        block ${l.blockNumber}, ts ${l.timestamp} (${isoFromUnix(l.timestamp)})`
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Compute and report a contributor's verifiable contribution score, read-only. Validates `<addr>` is a
+ * 20-byte hex address BEFORE any network call, runs the assertRegistry preflight, pages through
+ * getRecordsByContributor, then emits either a human block (led by the trust caveat) or a
+ * machine-readable JSON object (`--json`). Requires a provider; NEVER a signer or key.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.address           the contributor address to score
+ * @param {string}  opts.contractAddress   deployed ContributionRegistry address to read from
+ * @param {object}  opts.provider          ethers v6 Provider (read-only RPC connection)
+ * @param {boolean} [opts.json]            emit a JSON object instead of the human block
+ * @param {boolean} [opts.skipIdentityCheck] loudly skip the registry preflight (KNOWN local target only)
+ * @param {object}  [opts.ethers]          ethers v6 module (defaults to the bundled one)
+ * @param {(s:string)=>void} [opts.log]    sink for output (defaults to process.stdout)
+ * @returns {Promise<{ address:string, total:number, authorBound:number, anchorOnly:number,
+ *   lineageRoots:number, revisions:number, earliest:object|null, latest:object|null,
+ *   registry:object|null, json:boolean }>}
+ */
+async function runReputation(opts) {
+  const ethersLib = opts.ethers || require("ethers");
+  const log = opts.log || ((s) => process.stdout.write(s));
+
+  const { address: rawAddress, contractAddress, provider } = opts;
+
+  // Validate the address shape FIRST — before touching env, the provider, or the network. A malformed
+  // value must hard-error with a usage-grade message and never hit the network (parser parity with the
+  // existing read commands; mirrors show.js's normalizeContentHash precedence).
+  if (!rawAddress) throw new Error("reputation requires an <addr>");
+  if (!ethersLib.isAddress(rawAddress)) {
+    throw new Error(`invalid address: ${rawAddress} (expected a 20-byte 0x-hex address)`);
+  }
+  const address = ethersLib.getAddress(rawAddress);
+
+  if (!contractAddress) {
+    throw new Error(
+      "no contract address: pass --contract <address> or set VH_CONTRACT in the environment"
+    );
+  }
+  if (!ethersLib.isAddress(contractAddress)) {
+    throw new Error(`invalid contract address: ${contractAddress}`);
+  }
+  if (!provider) {
+    throw new Error("no provider: pass --rpc <url> or set VH_RPC_URL / AMOY_RPC_URL");
+  }
+
+  // T-11.2 preflight: authenticate the registry BEFORE reading any record — the score is never reported
+  // against an unauthenticated/look-alike contract (unless the caller explicitly, loudly opts out with
+  // skipIdentityCheck for a KNOWN not-yet-deployed/local-dev target).
+  let registryAuth = null;
+  if (!opts.skipIdentityCheck) {
+    registryAuth = await assertRegistry({ provider, contractAddress, ethers: ethersLib });
+  }
+
+  const contract = new ethersLib.Contract(
+    ethersLib.getAddress(contractAddress),
+    ABI,
+    provider
+  );
+
+  const records = await readContributorRecords(contract, address);
+  const score = computeScore(records);
+
+  // T-11.2: the machine-readable registry block — the same identity a UI/indexer can depend on to know
+  // the score was derived from an authenticated registry (or that the check was skipped).
+  const registryBlock = opts.skipIdentityCheck
+    ? jsonSkippedBlock()
+    : registryAuth
+    ? jsonRegistryBlock(registryAuth)
+    : null;
+
+  if (opts.json) {
+    log(JSON.stringify(jsonScore(address, score, registryBlock), null, 2) + "\n");
+  } else {
+    // Human-readable: LEAD with the trust caveat, then the score block (which carries the registry-auth
+    // confirmation or the loud skip warning, then the breakdowns / bounds).
+    log(TRUST_CAVEAT + "\n\n");
+    log(
+      formatScore(address, score, {
+        registryAuth,
+        identitySkipped: Boolean(opts.skipIdentityCheck),
+      }) + "\n"
+    );
+  }
+
+  return {
+    address,
+    total: score.total,
+    authorBound: score.authorBound,
+    anchorOnly: score.anchorOnly,
+    lineageRoots: score.lineageRoots,
+    revisions: score.revisions,
+    // BigInts normalized to JSON-safe numbers in the structured result too, so a programmatic caller
+    // gets the same shape as --json.
+    earliest:
+      score.earliest === null
+        ? null
+        : {
+            blockNumber: Number(score.earliest.blockNumber),
+            timestamp: Number(score.earliest.timestamp),
+            timestampISO: isoFromUnix(score.earliest.timestamp),
+          },
+    latest:
+      score.latest === null
+        ? null
+        : {
+            blockNumber: Number(score.latest.blockNumber),
+            timestamp: Number(score.latest.timestamp),
+            timestampISO: isoFromUnix(score.latest.timestamp),
+          },
+    registry: registryBlock,
+    json: Boolean(opts.json),
+  };
+}
+
+module.exports = {
+  runReputation,
+  readContributorRecords,
+  computeScore,
+  jsonScore,
+  formatScore,
+  TRUST_CAVEAT,
+  DEFAULT_PAGE,
+  ABI,
+};