@atcn/verify-cli 1.4.1 → 1.5.1

package/README.md

@@ -1,31 +1,39 @@
 # @atcn/verify-cli
 
-`atcn-verify` checks ATCN documents offline, without contacting anyone. It accepts these documents:
+`atcn-verify` checks a signed [ATCN](https://github.com/fadnisnikhil/atcn) document on your machine, without contacting anyone. Use it when someone sends you a task closure, a receipt or a closure package and you want to know whether it's genuine and whether its numbers add up.
 
-- subledger task closures;
-- provider receipts;
-- obligation closure packages.
+It checks the signatures, recomputes the totals and exceptions from the records inside, and prints each check with its result. It accepts:
+
+- task closures (the signed summary of an agent job and its costs);
+- provider receipts (what one provider sees of a task);
+- obligation closure packages (the signed record of paid work and how it was accepted);
+- clearing verdicts (an obligation's decision, for a payment rail to read).
 
 ```bash
-npx @atcn/verify-cli task-closure.json --keys keys.json --obligation-package obligation.json
+npx @atcn/verify-cli task-closure.json --keys keys.json
 ```
 
-Options:
+To try it, run `npx @atcn/local-runner demo`: it writes a closure, its keys and its closure packages, and prints the exact `atcn-verify` command to check them.
+
+## Options
 
-- **`--keys`:** a JSON array of public key records, or `{"items": [...]}`.
-- **`--previous`:** checks the chain link to the previous revision.
+- **`--keys`:** the signer's public keys, as a JSON array of key records or `{"items": [...]}`.
+- **`--obligation-package`:** cross-checks a closure's linked obligations against their closure packages. You can repeat it. For a clearing verdict, pass the one package it was read from.
+- **`--previous`:** checks the link to the previous version of a closure or revision of a receipt.
 - **`--operator-keys` and `--require-operator-signature`:** check operator countersignatures.
-- **`--obligation-package`:** cross-checks a closure's linked obligations against their closure packages. You can repeat it.
-- **`--at <ISO-8601 time>`:** checks a provider receipt's `expires_at` against that time instead of now, for example the time you received it.
+- **`--trace <trace.json>`:** supplies an agent trace file. You can repeat it. For a closure package, each trace is rechecked against the declared runs and every `usage_cost` result is recomputed from the terms' pricing. For a receipt or closure, each recorded usage summary is recomputed from its trace. Usage whose trace you did not supply is reported as `NOT INSPECTED`, which is neither a pass nor a failure.
+- **`--at <ISO-8601 time>`:** checks a receipt's `expires_at` against that time instead of now, for example the time you received it.
 - **`--json`:** prints the report as JSON.
 
-Exit codes:
+## Exit codes
 
 - `0`: valid.
 - `1`: invalid.
 - `2`: usage or input error.
 - `3`: unsupported schema version, so upgrade `atcn-verify`.
 
-Supported subledger schema versions are `1.2` and `1.3`; see [COMPATIBILITY.md](../schema/COMPATIBILITY.md).
+Supported subledger schema versions are `1.2` to `1.5`; see [compatibility](https://github.com/fadnisnikhil/atcn/blob/main/packages/schema/COMPATIBILITY.md).
+
+A valid signature shows who stated something and that it hasn't changed since. It doesn't prove the work or payment really happened; each claim carries a label saying who stands behind it.
 
-A valid signature attests to what the signer stated, not to the truth of the underlying work or payment. Part of [ATCN](../../README.md). Apache-2.0.
+Part of [ATCN](https://github.com/fadnisnikhil/atcn). Apache-2.0.

package/dist/cli.js

@@ -1,11 +1,12 @@
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { verifyClosurePackage } from "@atcn/core";
-import { PublicKeyRecordSchema } from "@atcn/schema";
+import { verifyClearingVerdict, verifyClosurePackage } from "@atcn/core";
+import { CLEARING_VERDICT_TYPE, PublicKeyRecordSchema } from "@atcn/schema";
 import { OperatorKeyRecordSchema, SUBLEDGER_VERIFIER_VERSION, SUPPORTED_SUBLEDGER_SCHEMA_VERSIONS, verifySubledgerDocument, } from "@atcn/subledger";
 const USAGE = `usage: atcn-verify <document.json> --keys <published-keys.json> [--previous <previous-revision.json>]
                    [--operator-keys <operator-keys.json>] [--require-operator-signature]
-                   [--obligation-package <closure-package.json> ...] [--at <ISO-8601 time>] [--json]
+                   [--obligation-package <closure-package.json> ...] [--trace <trace.json> ...]
+                   [--at <ISO-8601 time>] [--json]
 
 Verifies offline, without contacting the service:
   - ATCN closure packages (obligations): signatures, key validity, event references,
@@ -15,6 +16,9 @@ Verifies offline, without contacting the service:
     provider response signatures, and the version chain.
   - Subledger provider receipts (atcn.subledger.receipt): signature, schema, reversals,
     totals, field disclosure, the revision chain, and expiry.
+  - Clearing verdicts (atcn.clearing.verdict): the service signature and, with --obligation-package, that
+    the package verifies and the verdict states the decision in effect in it. ATCN only publishes a verdict;
+    an escrow rail decides whether to release.
 --keys accepts a JSON array of public key records or the /v1/service/keys response ({"items": [...]}).
 --previous checks the chain link to the prior receipt revision or closure version.
 --operator-keys checks countersignatures made with the operator's own keys
@@ -22,6 +26,11 @@ Verifies offline, without contacting the service:
 --obligation-package (repeatable) cross-checks a task closure's obligation-backed delegations against
   the obligations' closure packages (GET /v1/exports/{obligation_id}): each package must verify, and its
   journal must produce exactly the costs the closure recorded from the clearing network.
+  For a clearing verdict, pass the one package it was read from.
+--trace (repeatable) supplies agent trace files. For a closure package it rechecks agent_trace evidence
+  against the declared runs and recomputes usage_cost results from the terms' pricing; for a subledger
+  receipt or closure it recomputes each recorded usage summary from its trace. Evidence or usage whose
+  trace was not supplied is reported as NOT INSPECTED, which is neither a pass nor a failure.
 --at checks a provider receipt's expires_at against that time instead of now.
 Subledger schema versions supported: ${SUPPORTED_SUBLEDGER_SCHEMA_VERSIONS.join(", ")} (atcn-verify ${SUBLEDGER_VERIFIER_VERSION}).
 Exit code 0 = valid, 1 = invalid, 2 = usage or input error, 3 = unsupported schema version (upgrade atcn-verify).`;
@@ -56,6 +65,7 @@ function main() {
                 "operator-keys": { type: "string" },
                 "require-operator-signature": { type: "boolean" },
                 "obligation-package": { type: "string", multiple: true },
+                trace: { type: "string", multiple: true },
                 at: { type: "string" },
                 json: { type: "boolean" },
                 help: { type: "boolean" },
@@ -80,7 +90,18 @@ function main() {
     try {
         const doc = readJson(parsed.positionals[0]);
         const trustedKeys = loadKeys(parsed.values.keys);
-        if (isSubledgerDocument(doc)) {
+        const traces = parsed.values.trace?.map((path) => new Uint8Array(readFileSync(path)));
+        const documentType = doc?.payload?.document_type;
+        if (documentType === CLEARING_VERDICT_TYPE) {
+            const packages = parsed.values["obligation-package"]?.map(readJson) ?? [];
+            if (packages.length > 1) {
+                console.error(`a clearing verdict is checked against one --obligation-package, got ${packages.length}\n\n${USAGE}`);
+                return 2;
+            }
+            report = verifyClearingVerdict(doc, { trustedKeys, closurePackage: packages[0] });
+            label = "clearing verdict";
+        }
+        else if (isSubledgerDocument(doc)) {
             const previous = parsed.values.previous ? readJson(parsed.values.previous) : undefined;
             const operatorKeysPath = parsed.values["operator-keys"];
             const operatorKeys = operatorKeysPath ? loadOperatorKeys(operatorKeysPath) : undefined;
@@ -91,13 +112,14 @@ function main() {
                 operatorKeys,
                 requireOperatorSignature: parsed.values["require-operator-signature"],
                 obligationPackages,
+                traces,
                 at: at === undefined ? undefined : new Date(at).toISOString(),
             });
             report = result;
             label = result.document_type === "atcn.subledger.receipt" ? "provider receipt" : "task closure";
         }
         else {
-            report = verifyClosurePackage(doc, { trustedKeys });
+            report = verifyClosurePackage(doc, { trustedKeys, traces });
             label = "closure package";
         }
     }
@@ -113,7 +135,8 @@ function main() {
     }
     else {
         for (const check of report.checks) {
-            console.log(`${check.ok ? "PASS" : "FAIL"}  ${check.name}`);
+            const status = !check.ok ? "FAIL" : check.state === "not_inspected" ? "NOT INSPECTED" : "PASS";
+            console.log(`${status}  ${check.name}`);
             for (const detail of check.details)
                 console.log(`      ${detail}`);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atcn/verify-cli",
-  "version": "1.4.1",
-  "description": "Offline verifier for ATCN closure packages, subledger task closures, and provider receipts: atcn-verify <document.json> --keys <keys.json>",
+  "version": "1.5.1",
+  "description": "atcn-verify: check a signed ATCN closure, receipt, closure package or clearing verdict offline, without contacting anyone",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -27,8 +27,8 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@atcn/core": "1.4.1",
-    "@atcn/schema": "1.4.1",
-    "@atcn/subledger": "1.4.1"
+    "@atcn/core": "1.5.1",
+    "@atcn/schema": "1.5.1",
+    "@atcn/subledger": "1.5.1"
   }
 }