@parmana/verifier 2.0.0 → 2.0.3

package/README.md

@@ -33,11 +33,17 @@ node bin/parmana-verify.mjs test/vectors/record-whole-record-v3.json test/vector
     "trustRecordHash": true,
     "signature": true,
     "hybridSignatures": true
+  },
+  "correspondence": {
+    "status": "not_checked",
+    "executions": [
+      { "executionId": "ex_1", "result": { "status": "not_checked", "reason": "no authorization is embedded in the trust record" } }
+    ]
   }
 }
 ```
 
-The exit code is `0`. A record that has been changed is rejected:
+The exit code is `0`. The `correspondence` field is a separate report, described in [Execution correspondence](#execution-correspondence). It does not change `valid` or the exit code. This sample record is a trimmed test vector that does not embed its authorization, so there is nothing to compare and its correspondence is reported as `not_checked`, not as a mismatch. A complete record from Parmana embeds the authorization and is checked. A record that has been changed is rejected:
 
 ```sh
 node bin/parmana-verify.mjs test/vectors/record-tampered-amount.json test/vectors/trust.json
@@ -102,6 +108,18 @@ The verify command prints one line of JSON and exits with `0` (valid), `1` (inva
 
 On Windows PowerShell, use the same commands with Windows paths, for example `node bin\parmana-verify.mjs proof.json trust.json`.
 
+## Execution correspondence
+
+The output also carries a `correspondence` report: whether what was dispatched is what was authorized. It is checked from the record alone, the same way as the signatures, and it uses the same rules as Parmana's own offline check.
+
+For each execution, the record's authorization (its nonce, business transaction hash, policy content hash and authority grant) is compared with the execution's `evidence.correspondence`. Every field must be present and must match, and the dispatched content hash must equal the authorized one. The statuses are:
+
+- `passed`: every field is present and matches the authorization.
+- `failed`: a field is missing or different. This is a mismatch that was observed.
+- `not_checked`: the execution has no correspondence fields, no evidence, or the record embeds no authorization to compare with. Nothing was compared, so this is not a mismatch. It is never reported as passed.
+
+The report is `passed` only when every execution is checked and corresponds. The verifier reports it and does not decide what it means for your system: a `failed` or `not_checked` report is for you to act on. It is meaningful only for a record whose signatures also verify, so read it together with `valid`.
+
 ## Pinning a key
 
 A signature proves only that a key made it. Before you trust a record, decide which keys you trust, and check that each key is the one its owner published.
@@ -163,11 +181,15 @@ Run the tests on Node 24. On Node 22 or any runtime without ML-DSA-65, the hybri
 
 The suite covers the legacy signature and hash, hybrid signatures, schema version 3 coverage, the trust rules, the test vectors, and the command-line exit codes. Each area has its own file under `test/`.
 
+Records from parmana-core are tested in `test/parmana-core-records.test.mjs` and `python/tests/test_parmana_core_records.py`. They use `test/vectors/parmana-core-generated/cases.json`: 22 cases over records exported at parmana-core `7e9a54fb`, with tampered copies and trust-file edits. Both verifiers must agree on every case. The quick-start record in `python/README.md` is tested in `test/quickstart.test.mjs` and `python/tests/test_quickstart.py`.
+
 ## Limitations
 
 - The verifier can only check that a record was signed by the key you pinned. It cannot prove that the key belongs to Parmana. That depends on how you obtained and compared the fingerprint.
 - For records with `schemaVersion` 2, or with no `schemaVersion`, only the fields listed in [docs/FORMAT.md](docs/FORMAT.md) are protected. Any other field can be changed without the verifier noticing. Read decisions only from covered fields. See "Fields not covered by any signature" in that document.
-- For records with `schemaVersion` 3, every field except the signature envelope, `verifications` and `receipts` is protected. Check that `coverage` is `full` when that matters.
+- For records with `schemaVersion` 3, every field except the signature envelope, `verifications` and `receipts` is protected.
+- `coverage` is `full` only when the hybrid signatures also verify. It does not report the schema version. A schema version 3 record that fails the hybrid check reports `legacy`, and an Ed25519-only failure can report `full` alongside `valid: false`. Read `valid` for the verdict.
+- `checks.signature` is the legacy top-level signature, which covers only the seven legacy fields. A change to `updatedAt` in a schema version 3 record is caught by the hybrid signatures alone, so `checks.signature` stays `true` (pinned by `test/parmana-core-records.test.mjs`).
 - A record with `schemaVersion` 2 can be downgraded by someone who can write to storage, since `schemaVersion` is unsigned. Set `hybridRequiredFrom` in the trust file to reject downgraded records created after a cutover. Records before the cutover stay open to this. With no cutover set, a record with no hybrid envelope is refused unless the trust file sets `allowLegacyOnly` to `true` (see "Records with no hybrid envelope" above).
 - The validity window is checked against the record's `createdAt`, not against the signing time. A record that carries a false `createdAt` is checked against the window for that false time.
 - Keys and fingerprints must be kept current. The verifier does not know about rotations or revocations that you have not written into the trust file.

package/bin/parmana-verify.mjs

@@ -9,6 +9,7 @@
 import { readFileSync } from "node:fs";
 import { verifyExecutionTrustRecord } from "../src/verify.mjs";
 import { keyFingerprint, parseTrustPolicy } from "../src/trust.mjs";
+import { checkTrustRecordCorrespondence } from "../src/correspondence.mjs";
 
 const args = process.argv.slice(2);
 const USAGE = "usage: parmana-verify <proof.json> <trust.json>\n       parmana-verify key-fingerprint <public-key.pem>";
@@ -48,6 +49,7 @@ try {
 
 const result = verifyExecutionTrustRecord(proof, policy.keys, { hybridRequiredFrom: policy.hybridRequiredFrom ?? undefined, allowLegacyOnly: policy.allowLegacyOnly, allowLegacyV2: policy.allowLegacyV2 });
 
-console.log(JSON.stringify(result));
+// The correspondence report does not change `valid` or the exit code (see src/correspondence.mjs).
+console.log(JSON.stringify({ ...result, correspondence: checkTrustRecordCorrespondence(proof) }));
 
 process.exit(result.valid ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmana/verifier",
-  "version": "2.0.0",
+  "version": "2.0.3",
   "description": "Offline verifier for Parmana Execution Trust Records.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,7 +14,7 @@
     "NOTICE"
   ],
   "scripts": {
-    "test": "node --test test/verify.test.mjs test/hybrid.test.mjs test/trust.test.mjs test/vectors.test.mjs test/whole-record.test.mjs test/agentrust-fixture.test.mjs test/timestamp.test.mjs",
+    "test": "node --test test/verify.test.mjs test/hybrid.test.mjs test/trust.test.mjs test/vectors.test.mjs test/whole-record.test.mjs test/agentrust-fixture.test.mjs test/timestamp.test.mjs test/correspondence.test.mjs test/parmana-core-records.test.mjs test/quickstart.test.mjs",
     "examples": "node examples/run-all.mjs"
   },
   "engines": {

package/src/correspondence.mjs

@@ -0,0 +1,138 @@
+// Execution correspondence: an offline check that what was dispatched is what
+// was authorized. It is a separate report from verifyExecutionTrustRecord: it
+// does not change `valid`, and it means something only for a record whose
+// signatures also verify. Run both.
+//
+// Mirrors parmana-core's checkExecutionCorrespondence and
+// checkTrustRecordCorrespondenceOffline (packages/shared and packages/crypto).
+// Pure string comparison; the caller's record is not modified.
+//
+// Statuses:
+//   "passed"      every required field is present and matches the authorization.
+//   "failed"      a field is missing, malformed or different, or the record
+//                 embeds no authorization.
+//   "not_checked" the record carries no correspondence fields, or an execution
+//                 has no evidence. Never reported as passed.
+//
+// The report's status: "failed" if any execution failed; "not_checked" if no
+// execution was checked or any could not be checked; "passed" only when every
+// execution was checked and corresponds.
+
+const SUPPORTED_SCHEMA_VERSION = 1;
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+export function checkExecutionCorrespondence(correspondence, authorization) {
+  if (correspondence === undefined || correspondence === null) {
+    return { status: "not_checked", reason: "record predates the correspondence fields" };
+  }
+
+  const failures = [];
+
+  if (correspondence.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+    failures.push(`unsupported correspondence schemaVersion ${String(correspondence.schemaVersion)}`);
+  }
+
+  if (!isNonEmptyString(correspondence.authorizationNonce)) {
+    failures.push("authorizationNonce is missing");
+  } else if (correspondence.authorizationNonce !== authorization.nonce) {
+    failures.push("authorizationNonce differs from the authorization");
+  }
+
+  if (!isNonEmptyString(correspondence.authorizedContentHash)) {
+    failures.push("authorizedContentHash is missing");
+  } else if (correspondence.authorizedContentHash !== authorization.businessTransactionHash) {
+    failures.push("authorizedContentHash differs from the authorization");
+  }
+
+  if (!isNonEmptyString(correspondence.dispatchedContentHash)) {
+    failures.push("dispatchedContentHash is missing");
+  } else if (correspondence.dispatchedContentHash !== correspondence.authorizedContentHash) {
+    failures.push("dispatched content differs from the authorized content");
+  }
+
+  // The source of the dispatched hash is recorded for review. Only the two known values are accepted when the field
+  // is present. Whether the two sources must agree is an owner decision; this check does not compare them.
+  if (
+    correspondence.dispatchedHashSource !== undefined &&
+    correspondence.dispatchedHashSource !== "gateway" &&
+    correspondence.dispatchedHashSource !== "connector-wire"
+  ) {
+    failures.push(`dispatchedHashSource ${String(correspondence.dispatchedHashSource)} is not a known source`);
+  }
+
+  if (authorization.policyContentHash !== undefined && correspondence.policyContentHash !== authorization.policyContentHash) {
+    failures.push("policyContentHash differs from the authorization");
+  }
+
+  if (authorization.authorityGrantId !== undefined && correspondence.authorityGrantId !== authorization.authorityGrantId) {
+    failures.push("authorityGrantId differs from the authorization");
+  }
+
+  return failures.length === 0 ? { status: "passed" } : { status: "failed", failures };
+}
+
+// The authorization fields correspondence is checked against, from the record.
+function authorizationOf(record) {
+  const payload = record?.authorization?.payload;
+
+  if (payload === undefined || payload === null) {
+    return undefined;
+  }
+
+  const authorization = {
+    nonce: payload.nonce,
+    businessTransactionHash: payload.businessTransactionHash,
+  };
+
+  if (payload.policyContentHash !== undefined) {
+    authorization.policyContentHash = payload.policyContentHash;
+  }
+
+  if (payload.authorityGrant !== undefined && payload.authorityGrant !== null) {
+    authorization.authorityGrantId = payload.authorityGrant.grantId;
+  }
+
+  return authorization;
+}
+
+export function checkTrustRecordCorrespondence(record) {
+  const authorization = authorizationOf(record);
+  const executions = (Array.isArray(record?.executions) ? record.executions : []).map((execution) => {
+    if (authorization === undefined) {
+      // Nothing to compare with: not checked. It is not a mismatch, so it is not "failed".
+      return {
+        executionId: execution.executionId,
+        result: { status: "not_checked", reason: "no authorization is embedded in the trust record" },
+      };
+    }
+
+    if (execution.evidence === undefined || execution.evidence === null) {
+      return {
+        executionId: execution.executionId,
+        result: { status: "not_checked", reason: "execution has no evidence recorded" },
+      };
+    }
+
+    return {
+      executionId: execution.executionId,
+      result: checkExecutionCorrespondence(execution.evidence.correspondence, authorization),
+    };
+  });
+
+  if (executions.length === 0) {
+    return { status: "not_checked", executions };
+  }
+
+  if (executions.some((entry) => entry.result.status === "failed")) {
+    return { status: "failed", executions };
+  }
+
+  if (executions.some((entry) => entry.result.status === "not_checked")) {
+    return { status: "not_checked", executions };
+  }
+
+  return { status: "passed", executions };
+}