@xfuel/verify 0.3.5 → 0.4.1

package/README.md

@@ -1,269 +1,82 @@
-# @xfuel/verify
-
-Offline verification for Chit402 receipts — verify payment binding and output commitment without calling the API.
-
-npm: `@xfuel/verify` · License: Apache-2.0 · Docs: https://chit402.com
-
-## Installation
-
-```bash
-npm install @xfuel/verify
-```
-
-## Usage
-
-### Library
-
-```typescript
-import { verifyReceipt, verifyBinding, verifyNullifier } from '@xfuel/verify';
-
-// Verify a receipt offline (binding only, no network)
-const receipt = { /* Chit402 receipt JSON */ };
-const result = verifyBinding(receipt);
-console.log(result.matches); // true if binding verified
-
-// Full verification including on-chain nullifier check
-const fullResult = await verifyReceipt(receipt, { checkNullifier: true });
-console.log(fullResult.overall); // 'verified' | 'partial' | 'failed'
-console.log(fullResult.receipt_lane.freeze); // unsigned; does not change overall
-```
-
-### CLI
-
-```bash
-# Local binding verification.
-# Issuer history is fetched unless you pass --issuer-history-file or --no-issuer-history.
-# A payload v10 receipt fails offline (exit 1) when that fetch cannot run.
-npx xfuel-verify receipt.json
-
-# Explicit offline. --no-issuer-history skips the kid window.
-npx xfuel-verify receipt.json --no-issuer-history
-
-# Hash the canonical object (must match signed payload_hash) and read not_after
-# from a pinned issuer-history snapshot. Both flags are offline.
-npx xfuel-verify receipt.json --canonical-preimage preimage.json --issuer-history-file issuer-history.json
-
-# A signed refusal (schema chit402.refusal.v1) is not a payment.
-# The check proves the issuer refused, at the signed anchor, for that code.
-# It does not prove a payment or that the block still stands.
-npx xfuel-verify refusal.json
-
-# With on-chain nullifier check (requires network)
-npx xfuel-verify receipt.json --check-nullifier
-
-# Output as JSON
-npx xfuel-verify receipt.json --json
-
-# From stdin
-curl -s https://api.chit402.com/receipt/task-123?format=json | npx xfuel-verify -
-
-# Dual anchor: inclusion, Solana memo, Base calldata
-npx xfuel-verify receipt.json inclusion.json head.json --rpc
-```
-
-## What This Verifies
-
-| Check | Requires Network? | Description |
-|-------|-------------------|-------------|
-| Payment binding | No | Recompute commitment from receipt fields |
-| Issuer signature | No, unless `--fetch-jwks` | ES256. Trusted only via JWKS (by kid) or a pinned RFC 7638 kid |
-| Output hash | No | Hash is on the receipt |
-| On-chain settlement | Yes | Query Base RPC for tx |
-| Nullifier anchor | Yes | Query ZKVerifierSP1 contract |
-| Tree head and inclusion | No | Head ES256 signature over size and root, then an index-and-size-bound inclusion proof |
-| Anchored receipt root | Yes, with `--rpc` | The offline head and inclusion checks, then Solana memo and fee payer and Base calldata and sender |
-| Canonical preimage | No | SHA-256 of `--canonical-preimage`, or the stored canonical object, matches signed `payload_hash` |
-| Issuer history | Yes, unless `--no-issuer-history` or `--issuer-history-file` | `iat` is inside the kid's `not_before` / `not_after`. A payload v10 pin must match the snapshot hash. Offline v10 fails if the fetch cannot run |
-
-## Issuer Signature Verification (ES256)
-
-Receipts include `issuer_signature.jws` (compact ES256 / P-256). The signature
-counts only when the verifying key is trusted:
-
-1. **JWKS by kid** — a key in `--jwks-file`, `--jwks-url`, or `--fetch-jwks`
-   (allowlisted host, default `api.chit402.com`) whose `kid` matches the JWS.
-2. **Pinned thumbprint** — the embedded `issuer_jwk` is used only when its
-   RFC 7638 thumbprint equals a trusted kid. The default offline pin is the
-   production kid `IvFpmC-vPhkY_v0vidsrWVT9uzlE5XWKZgAEOeJTq1Q`. Override with
-   `--trusted-kid`, or disable with `--no-trusted-kid`.
-
-The epoch record and the tree head use those same sources, with or without `--rpc`. `xfuel-verify receipt.json inclusion.json head.json` checks the head signature and the inclusion proof offline. `--rpc` adds the chain checks. An embedded key still has to match the trusted-kid pin, or the kid has to be in a verified issuer-history entry. The head's signed `anchors.base.from` and `anchors.solana.fee_payer` must be on the anchor-wallet list (the package pin, or a verified `/.well-known/anchor-wallets.json`). The chain sender and fee payer must be those wallets. `--version` prints the package version.
-
-Anchor mode also checks a content-addressed issuer pin when the receipt or the head carries `issuer_key_pin`, or when you pass `--issuer-pin`. The pin is a 40-hex commit plus the SHA-256 of `docs/well-known/issuer-key.json`. A branch name is not fetched. A claimed pin requires `issuer_signature.jws` verified under that key. Unsigned envelope kids do not satisfy the check. The registration self-signature is checked when the file has one. A claimed era with no pin fails `ISSUER_PIN_DOWNGRADE`. Receipts that do not claim the era skip this check. The pin chain is Base Sepolia (`eip155:84532`). See [issuer-key-pin.md](../../docs/product/issuer-key-pin.md).
-
-`issuer_jwk` on the receipt is not a trust root. A copy re-signed with an
-arbitrary P-256 key reports `key untrusted` (`issuer_signature.valid === false`),
-including when `--jwks-file` points at the real JWKS.
-
-```bash
-# Explicit offline. The default command fetches issuer history.
-npx xfuel-verify receipt.json --no-issuer-history
-
-# Recompute a published canonical preimage and check the kid window.
-# curl -f stops on HTTP errors. Most receipts have no /preimage (a 404).
-# A missing preimage is not a verification failure: omit --canonical-preimage.
-curl -fsS "https://api.chit402.com/receipt/RECEIPT_ID?format=json" -o receipt.json
-curl -fsS "https://api.chit402.com/.well-known/issuer-history.json?version=1" -o issuer-history.json
-if curl -fsS "https://api.chit402.com/receipt/RECEIPT_ID/preimage" -o preimage.json; then
-  npx xfuel-verify receipt.json --canonical-preimage preimage.json --issuer-history-file issuer-history.json
-else
-  npx xfuel-verify receipt.json --issuer-history-file issuer-history.json
-fi
-
-# Trust the published JWKS instead of (or in addition to) the pin
-curl -o issuer-jwks.json https://api.chit402.com/.well-known/jwks.json
-npx xfuel-verify receipt.json --jwks-file issuer-jwks.json --no-trusted-kid
-
-# Fetch the issuer JWKS (https://api.chit402.com/.well-known/jwks.json)
-npx xfuel-verify receipt.json --fetch-jwks
-```
-
-```typescript
-import { verifyReceipt } from '@xfuel/verify';
-
-const result = await verifyReceipt(receipt);
-console.log(result.issuer_signature.valid);      // true only for a trusted key
-console.log(result.issuer_signature.key_trusted);
-console.log(result.amount_usdc);                 // from verified claims, not the outer copy
-console.log(result.claim_mismatches);            // any signed path whose outer copy disagrees
-console.log(result.unsigned_fields);             // outer paths the signature does not cover
-console.log(result.verified_scope);              // 'signed_claims'
-```
-
-Amount, payer, payee, asset, and tx are read from the verified JWS claims.
-Every signed path is compared with the outer receipt. A mismatch fails.
-Paths the signature does not cover are `unsigned_fields` and are printed as
-`UNVERIFIED`. Overall does not verify them. The outer document `schema` is
-not a copy of the JWS `schema`. `--check-payer` on Base confirms payer, payee,
-asset, and amount in the USDC `Transfer` log.
-
-`xfuel-verify receipt.json inclusion.json head.json` also runs those receipt
-checks. A matching inclusion proof does not make a tampered receipt VERIFIED.
-
-A paid USDC receipt whose signed `binding.expected_commitment` is null is
-reported as “No payment-binding commitment”, not as an unmetered or TFUEL receipt.
-
-The CLI does **not** fetch JWKS unless `--fetch-jwks` or `--jwks-url` is set.
-Exit code 1 is returned when the key is untrusted, the signature is invalid, or
-a signed claim disagrees with the outer copy.
-
-## Frozen Fields
-
-These fields are immutable once set and verifiable by any third party:
-
-- `task_id` — unique task identifier
-- `route.provider` — compute hub (theta-edgecloud, akash-network)
-- `route.model` — model that served the request
-- `payment.gross_amount` — total charged in USDC atomic units
-- `payment.ref` — settlement reference (network:txHash)
-- `output.hash` — commitment to model output
-- `proof.nullifier` — single-use nullifier anchored on-chain
-
-## Verification Algorithm
-
-The binding commitment is computed as:
-
-```solidity
-// Payment-only binding
-keccak256(abi.encodePacked(
-  keccak256(payment_ref),
-  keccak256(task_id),
-  rail_discriminant,  // 1=usdc, 2=tfuel
-  amount
-))
-
-// PBR (Payment-Bound Receipt) — includes model + output
-keccak256(abi.encodePacked(
-  keccak256(payment_ref),
-  keccak256(task_id),
-  rail_discriminant,
-  amount,
-  model_commitment,
-  output_hash
-))
-```
-
-This matches `SP1ProofHooks.computePaymentCommitment` on-chain.
-
-## Exit Codes (CLI)
-
-| Code | Meaning |
-|------|---------|
-| 0 | Verified |
-| 1 | Verification failed |
-| 2 | Partial (binding ok, nullifier not checked) |
-| 3 | Input error |
-
-`unsupported_version` uses exit 1. No flag (`--check-payer`, `--rpc`, `--fetch-jwks`, `--no-issuer-history`, `--no-preimage`, `--no-trusted-kid`, `--accept-shell`) turns an unknown version into a pass. The check runs before any chain RPC.
-
-## Receipt versions
-
-The signed JWS payload is the version. It is an exact JSON number. Strings, booleans, arrays, null, and non-integers are `unsupported_version`. `11.0` and `1.1e1` are the number 11.
-
-| Signed field | Accepted |
-|---|---|
-| `v` | `11`, and the claims must not contain `payload_version` |
-| `payload_version` | integers `1` through `10`, and `11` only when `issuer_root` is signed |
-| refusal `payload_version` | integers `1`, `2`, `3` |
-| neither field | outer version `4` or `5`, and no field introduced at v6 or later (`version_source: inferred`) |
-
-An outer `v` or `issuer_signature.payload_version` that differs in value or type is `version_mismatch`. A `v` or `payload_version` in the JWS protected header is ignored.
-
-Receipts issued after 2026-10-08 require `@xfuel/verify` >= 0.3.5. Older versions may print VERIFIED for formats they do not understand. `--help` and `--version` print this list.
-
-## API Reference
-
-### `verifyBinding(receipt)`
-
-Verify payment binding locally. Returns:
-
-```typescript
-{
-  verified: boolean;
-  expected: string | null;
-  recomputed: string | null;
-  matches: boolean;
-  covers: string[];
-  reason?: string;
-}
-```
-
-### `verifyNullifier(receipt, options?)`
-
-Verify nullifier is anchored on-chain. Requires network access.
-
-```typescript
-{
-  verified: boolean;
-  nullifier: string | null;
-  anchored: boolean | null;
-  reason?: string;
-}
-```
-
-### `verifyReceipt(receipt, options?)`
-
-Full verification combining binding and optional nullifier check.
-
-```typescript
-{
-  receipt_id: string;
-  binding: BindingVerification;
-  nullifier: NullifierVerification;
-  output_hash: string | null;
-  hub: string | null;
-  model: string | null;
-  amount_usdc: string | null;
-  tx: string | null;
-  overall: 'verified' | 'partial' | 'failed';
-  errors: string[];
-}
-```
-
-## Build digest
-
-`npm run digest` writes `BUILD_DIGEST.txt`. That file is the SHA-256 of the sorted `src/**/*.ts` listing, not a bit-reproducible `tsc` binary. The same sources produce the same digest. The receipt-tree genesis leaf copies this digest so a holder can see which verifier source the issuer vouches for. It does not prove the process that served the receipt ran that exact binary.
-
-## License
-
-Apache-2.0
+# chit402-verify
+
+Offline verification for Chit402 receipts — verify payment binding and output commitment without calling the API.
+
+npm: `chit402-verify` · License: Apache-2.0 · Docs: https://chit402.com
+
+## Installation
+
+```bash
+npm install chit402-verify
+```
+
+## Usage
+
+### Library
+
+```typescript
+import { verifyReceipt, verifyBinding, verifyNullifier } from 'chit402-verify';
+
+// Verify a receipt offline (binding only, no network)
+const receipt = { /* Chit402 receipt JSON */ };
+const result = verifyBinding(receipt);
+console.log(result.matches); // true if binding verified
+
+// Full verification including on-chain nullifier check
+const fullResult = await verifyReceipt(receipt, { checkNullifier: true });
+console.log(fullResult.overall); // 'verified' | 'partial' | 'failed'
+```
+
+### CLI
+
+```bash
+# Local binding verification (no network required)
+npx chit402-verify receipt.json
+
+# Hash the canonical object (must match signed payload_hash) and read not_after
+# from a pinned issuer-history snapshot. Both flags are offline.
+npx chit402-verify receipt.json --canonical-preimage preimage.json --issuer-history issuer-history.json
+
+# With on-chain nullifier check (requires network)
+npx chit402-verify receipt.json --check-nullifier
+
+# Output as JSON
+npx chit402-verify receipt.json --json
+
+# From stdin
+curl -s https://api.chit402.com/receipt/task-123?format=json | npx chit402-verify -
+```
+
+## What This Verifies
+
+| Check | Requires Network? | Description |
+|-------|-------------------|-------------|
+| Payment binding | No | Recompute commitment from receipt fields |
+| Issuer signature | No, unless `--fetch-jwks` | ES256. Trusted via JWKS (by kid) or the pinned production kid. Embedded `issuer_jwk` alone is not enough. |
+| Output hash | No | Hash is on the receipt |
+| On-chain settlement | Yes | Query Base RPC for tx |
+| Nullifier anchor | Yes | Query ZKVerifierSP1 contract |
+| Canonical preimage | No | `--canonical-preimage` is SHA-256'd and matched to signed `payload_hash` |
+| Issuer history | No, with `--issuer-history` | `iat` is inside the kid's `not_before` / `not_after`. A payload v10 pin must match |
+
+## Exit Codes (CLI)
+
+| Code | Meaning |
+|------|---------|
+| 0 | Verified |
+| 1 | Verification failed |
+| 2 | Partial (binding ok, nullifier not checked) |
+| 3 | Input error |
+
+## Publish
+
+`publishConfig` sets `access` to `public` and does not name an owner. On the registry, `chit402-verify` (latest `0.2.0`) and `@xfuel/verify` (latest `0.2.1`) are both maintained by the npm user `xfuel`. Publish `@xfuel/verify` first. `npm whoami` must print `xfuel`. A `404` on `PUT https://registry.npmjs.org/chit402-verify` is that login, not a missing package and not a new scope: the name already exists.
+
+## Documentation
+
+- [Chit402 Docs](https://chit402.com)
+- [API Reference](https://api.chit402.com)
+
+## License
+
+Apache-2.0

package/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * chit402-verify CLI — Chit402 receipt verification
+ *
+ * @xfuel/verify is a thin alias. The verifier is chit402-verify.
+ */
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+
+const require = createRequire(import.meta.url);
+const verifyCliPath = require.resolve('chit402-verify/dist/cli.js');
+
+const child = spawn(process.execPath, [verifyCliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+// Forward termination signals so killing the wrapper (CI timeout, supervisor) also stops the verifier.
+const FORWARDED = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+for (const sig of FORWARDED) {
+  process.on(sig, () => {
+    try { child.kill(sig); } catch { /* child already gone */ }
+  });
+}
+
+// Mirror the verifier's result exactly. A verifier killed by a signal (crash, heap-OOM abort,
+// timeout) must never look like success: exit 128 + signal number, as a shell would report it.
+child.on('exit', (code, signal) => {
+  if (signal) {
+    const n = osConstants.signals[signal];
+    process.exit(typeof n === 'number' ? 128 + n : 1);
+  }
+  process.exit(typeof code === 'number' ? code : 1);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start chit402-verify:', err.message);
+  process.exit(1);
+});

package/index.cjs

@@ -0,0 +1,8 @@
+/**
+ * chit402-verify — Chit402 receipt verification re-export (CommonJS)
+ */
+'use strict';
+
+const verify = require('chit402-verify');
+module.exports = verify;
+module.exports.default = verify.default;

package/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * chit402-verify — Chit402 receipt verification type re-exports
+ */
+export * from 'chit402-verify';
+export { default } from 'chit402-verify';

package/index.js

@@ -0,0 +1,7 @@
+/**
+ * chit402-verify — Chit402 receipt verification re-export
+ *
+ * Verify payment binding and output commitment offline.
+ */
+export * from 'chit402-verify';
+export { default } from 'chit402-verify';

package/package.json

@@ -1,67 +1,61 @@
-{
-  "name": "@xfuel/verify",
-  "version": "0.3.5",
-  "description": "Offline verification for Chit402 receipts — verify payment binding and output hash without calling the API",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "xfuel-verify": "dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    },
-    "./cli": "./dist/cli.js",
-    "./dist/cli.js": "./dist/cli.js"
-  },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://github.com/XFuel-Lab/chit402/tree/main/packages/verify#readme",
-  "bugs": {
-    "url": "https://github.com/XFuel-Lab/chit402/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "digest": "node scripts/build-digest.mjs",
-    "test": "npm run build && node --test --test-concurrency=1 test/*.test.mjs",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "keywords": [
-    "chit402",
-    "xfuel",
-    "verify",
-    "receipt",
-    "x402",
-    "usdc",
-    "base",
-    "offline",
-    "zk"
-  ],
-  "author": "XFuel Lab",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/XFuel-Lab/chit402.git",
-    "directory": "packages/verify"
-  },
-  "dependencies": {
-    "ethers": "^6.16.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@xfuel/verify",
+  "version": "0.4.1",
+  "description": "Alias of chit402-verify. The xfuel-verify bin stays.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "xfuel-verify": "cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  },
+  "keywords": [
+    "chit402",
+    "verify",
+    "receipt",
+    "x402",
+    "usdc",
+    "base",
+    "offline",
+    "zk"
+  ],
+  "author": "XFuel Lab",
+  "license": "Apache-2.0",
+  "homepage": "https://chit402.com",
+  "bugs": {
+    "url": "https://github.com/XFuel-Lab/chit402/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XFuel-Lab/chit402.git",
+    "directory": "packages/aliases/chit402-verify"
+  },
+  "dependencies": {
+    "chit402-verify": "0.4.1"
+  }
+}