@agenticstechnologies/verify 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Agentics, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @agenticstechnologies/verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline checks for an Agentics evidence export. The tool recomputes receipt
+leaves and the `prev_hash` chain from the JSON file. It does not call
+Agentics, and it does not trust the `verification` summary inside the file.
+
+## Install
+
+```bash
+npm install -g @agenticstechnologies/verify
+agentics-verify bundle.json
+```
+
+The package binary is `agentics-verify`. Pass `-` to read JSON from stdin, and `--help` to print usage.
+
+## Version bump policy
+
+Versions follow semver. A fix increments the patch number, a backwards-compatible addition increments the minor number, and a breaking change increments the major number. Update `version` in this package's `package.json` in the same commit as the change. Publishing uses the founder's npm token and does not run on merge.
+
+`scripts/verify-evidence.mjs` is a thin wrapper around the same leaf and chain
+code. From a checkout of this repo:
+
+```bash
+node scripts/verify-evidence.mjs bundle.json
+node packages/agentics-verify/bin/verify.mjs bundle.json
+```
+
+The package binary is `agentics-verify` (`./bin/verify.mjs`). Pass `-` to read
+JSON from stdin.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Leaf and chain match. Merkle, when present, folds. A devnet or testnet memo, when present, matches or the public RPC was skipped. |
+| 1 | A check failed, or the file is not JSON. The reason is on stderr. |
+| 2 | No bundle path was given. |
+
+A passing package run prints three lines:
+
+```text
+pass  checked 2 receipt(s)
+merkle  not-present  batch/merkle fields are not in this export
+solana  not-present  tx/cluster are not in this export
+```
+
+`not-present` means that block was skipped. It is not a failure. `warn` (RPC
+timeout or a cluster this tool does not query) is also not a failure.
+
+## What is checked
+
+**Leaf and chain.** Same algorithm as `lib/gateway/proof.ts` `leafHash` and
+the date-range export from `GET /api/proof/export`:
+
+```text
+sha256Hex(JSON.stringify(canonicalize(canonical minus {receipt_id, batch_id})))
+```
+
+`canonicalize` sorts object keys and drops null and undefined. Each receipt
+after the first must set `prev_hash` to the previous `receipt_hash`. The first
+`prev_hash` must be 64 hex characters. `verification.truncated: true` fails
+the file, including a single-receipt proof bundle.
+
+If a receipt sets `text_cleared_at`, the stored hash covers the cleared fields.
+Older leaves still check every other canonical field by trying the historical
+outcome labels in memory. The label is not printed. An older outcome that is
+not in that list, and every version 4 receipt, must carry `uncleared_digest`.
+Version 4 checks the leaf with `reason`, `target`, `outcome`, and
+`error_message` removed against that digest. An older unlisted outcome checks
+the leaf with `outcome` removed. Without the digest those leaves fail. The
+chain link is unchanged. A changed amount, agent, or `prev_hash` still fails.
+
+A proof bundle from `GET /api/proof/bundle` has one `receipt` plus
+`receipt_hash` instead of `receipts`. The leaf is recomputed the same way.
+`chain` is checked as hash links (oldest-first or the newest-first order
+`chainFor` returns). Ancestor bodies are not in that bundle, so only the
+included receipt is re-hashed.
+
+**Merkle.** When the export includes a proof, the fold is the sorted-pair
+Merkle in `netlify/edge-functions/lib/ledger.js` (`hashPair` hashes the two
+digests in sorted order, an odd node is duplicated, an empty list is null).
+That is the same fold `lib/gateway/proof.ts` uses for a batch. It is tree rule
+`v1`, and every batch anchored before v2 stays v1.
+
+**Tree rule v2 (1.0.0).** A claim with `tree_rule: "v2"` uses RFC 9162
+section 2.1 (RFC 6962) over the 32 bytes of each leaf:
+
+- leaf = SHA-256(0x00 || leaf)
+- node = SHA-256(0x01 || left || right), in position order
+- an odd last node is promoted unchanged
+- a one-leaf root is its leaf hash
+
+A v2 proof is the RFC audit path, so it also needs `index` (or `leaf_index`)
+and `leaf_count` (or `tree_size`). Without them the claim fails rather than
+guessing. With no `tree_rule`, the claim is v1. Any other value is refused,
+never folded as v1. `merkleRootV2`, `merkleProofV2`, `verifyProofV2`,
+`leafHashV2` and `treeRuleOf` are exported.
+
+Recognized fields, and no others:
+
+- `merkle.siblings` or `merkle.proof`, with `merkle.root` or `merkle.merkle_root`
+- `merkle.leaves` with a root (full leaf list, receipt-hash order)
+- the same fields on a receipt row's `merkle` object
+- `batches[].merkle_root` with `batches[].leaves` or `batches[].siblings`
+- `tree_rule` and `leaf_count` on any of the above (v2 only)
+
+The proof bundle published by `bundle()` uses `merkle.siblings` and
+`merkle.root`. If none of these fields are present, the line is
+`merkle  not-present`. A root with neither siblings nor a leaf list fails:
+the export claimed a root and this tool cannot recompute it.
+
+**Solana memo.** Only when the bundle has both a transaction id and a cluster
+(`anchor.txid` and `anchor.chain` or `anchor.cluster`, or top-level `tx` and
+`cluster`). Devnet (`solana-devnet`, `devnet`, Solscan `?cluster=devnet`) uses
+`https://api.devnet.solana.com`. Testnet uses `https://api.testnet.solana.com`.
+The public `getTransaction` response is read for a Memo program instruction
+(`MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr`) and compared to the recomputed
+Merkle root, or to `anchor.memo` when the export has no root. No private key
+is read and nothing is signed. Mainnet is not queried. If `anchor.memo` is
+present and a Merkle root was recomputed, the two must match before any
+network read; a missing transaction id still skips the public RPC. If the RPC
+does not answer within 8 seconds, the line is `solana  warn` and the process
+still exits 0 when every other check passed.
+
+## Agent record
+
+`GET /api/record/:handle/export` is a signed record (`typ` `agentics.record.v1`).
+Check it with the public keys from `https://agentics.you/.well-known/jwks.json`.
+The tool does not call Agentics.
+
+```bash
+node packages/agentics-verify/bin/verify.mjs record.json --jwks jwks.json
+```
+
+Exit 0 prints the handle, the label, and the counts. Exit 1 is `fail`, the
+reason code, and a sentence. A changed count, a changed score, or a flipped
+signature byte fails. A record does not expire by clock. A previous signing
+key still verifies old exports while it remains in the published key set.
+`New, no record yet` is a real label: the file had no settlement and no claim.
+
+## Tests
+
+```bash
+node --test packages/agentics-verify/test/verify.test.mjs
+```
+
+The fixture `test/fixtures/evidence-export.json` is an unmodified
+`agentics.evidence.v1` export. Tampering with `receipt_hash` or a leaf field
+exits 1.
+
+## License
+
+Apache-2.0 — © Agentics Technologies LLC.

package/bin/verify.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Offline check of an Agentics evidence export.
+//
+//   agentics-verify bundle.json
+//   agentics-verify -     # JSON on stdin
+//
+// Exit 0 when the leaf and prev_hash checks pass, any included Merkle proof
+// folds, and a devnet/testnet memo (if present) matches or the RPC is skipped.
+// Exit 1 when a check fails. Exit 2 when no path is given.
+
+import fs from "node:fs";
+import { verifyBundle } from "../src/bundle.mjs";
+import { isRecordBundle, verifyRecord } from "../src/record.mjs";
+
+function statusLine(label, part) {
+  return `${label}  ${part.status}${part.reason ? "  " + part.reason : ""}`;
+}
+
+const USAGE = "usage: agentics-verify <bundle.json | -> [--jwks jwks.json]";
+
+function packageVersion() {
+  return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+}
+
+function printHelp() {
+  console.log([
+    "agentics-verify — check an Agentics evidence export offline",
+    "",
+    USAGE,
+    "",
+    "  agentics-verify bundle.json",
+    "  agentics-verify - --jwks jwks.json",
+    "",
+    "Exit 0 when the checks pass. Exit 1 when a check fails. Exit 2 when no file is given.",
+  ].join("\n"));
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+  console.log("agentics-verify " + packageVersion());
+  process.exit(0);
+}
+
+let jwksPath = null;
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--jwks") {
+    jwksPath = args[i + 1] ?? "";
+    i += 1;
+    continue;
+  }
+  positional.push(args[i]);
+}
+const arg = positional[0];
+if (!arg) {
+  console.error(USAGE);
+  process.exit(2);
+}
+
+let text;
+try {
+  text = arg === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(arg, "utf8");
+} catch (e) {
+  console.error("cannot read bundle:", e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+
+let bundle;
+try {
+  bundle = JSON.parse(text);
+} catch (e) {
+  console.error("invalid JSON:", e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+
+if (isRecordBundle(bundle)) {
+  if (!jwksPath) {
+    console.error("fail  jwks required  pass --jwks with the keys from /.well-known/jwks.json");
+    process.exit(1);
+  }
+  let jwksText;
+  try {
+    jwksText = fs.readFileSync(jwksPath, "utf8");
+  } catch (e) {
+    console.error("cannot read jwks:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  let jwks;
+  try {
+    jwks = JSON.parse(jwksText);
+  } catch (e) {
+    console.error("invalid jwks JSON:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const checked = await verifyRecord(bundle, jwks);
+  if (!checked.ok) {
+    console.error(`fail  ${checked.reason}${checked.message ? "  " + checked.message : ""}`);
+    process.exit(1);
+  }
+  const record = checked.record ?? {};
+  console.log(`pass  record ${checked.handle}`);
+  console.log(`label  ${record.label}`);
+  console.log(`paid on time  ${record.paid_on_time}`);
+  console.log(`claims filed  ${record.claims_filed}`);
+  console.log(`claims paid  ${record.claims_paid}`);
+  console.log(`sellers  ${record.distinct_sellers}`);
+  console.log(`age  ${record.age_days == null ? "none" : record.age_days + " days"}`);
+  process.exit(0);
+}
+
+const result = await verifyBundle(bundle);
+const merkleLine = statusLine("merkle", result.merkle);
+const solanaLine = statusLine("solana", result.solana);
+
+if (result.ok) {
+  console.log(`pass  checked ${result.checked} receipt(s)`);
+  console.log(merkleLine);
+  if (result.solana.status === "warn") console.error(solanaLine);
+  else console.log(solanaLine);
+  process.exit(0);
+}
+
+console.error(`fail  checked ${result.checked}`);
+for (const f of result.failures) {
+  console.error(`- ${f.reason}  hash=${f.receipt_hash} prev=${f.prev_hash}`);
+}
+console.error(merkleLine);
+console.error(solanaLine);
+process.exit(1);

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@agenticstechnologies/verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Offline verifier for Agentics evidence export bundles. Recomputes receipt leaves and the prev_hash chain, and folds a Merkle proof when the export includes one.",
+  "license": "Apache-2.0",
+  "author": "Agentics Technologies LLC",
+  "homepage": "https://agentics.you/docs/",
+  "bugs": {
+    "url": "https://agentics.you/contact/",
+    "email": "support@agentics.you"
+  },
+  "type": "module",
+  "bin": {
+    "agentics-verify": "./bin/verify.mjs"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./cleared": {
+      "types": "./src/cleared.d.ts",
+      "import": "./src/cleared.mjs"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/verify.test.mjs"
+  },
+  "engines": { "node": ">=18" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "keywords": ["agentics", "evidence", "receipts", "merkle", "verify"]
+}