@parmana/verifier 2.0.1 → 2.0.3

package/bin/parmana-verify.mjs

@@ -1,53 +1,55 @@
-#!/usr/bin/env node
-// Usage:
-//   parmana-verify <proof.json> <trust.json>
-//   parmana-verify key-fingerprint <public-key.pem>
-//
-// verify exits 0 = valid, 1 = invalid, 2 = usage or read error.
-// key-fingerprint prints the "sha256:..." value to pin in a trust file.
-
-import { readFileSync } from "node:fs";
-import { verifyExecutionTrustRecord } from "../src/verify.mjs";
-import { keyFingerprint, parseTrustPolicy } from "../src/trust.mjs";
-
-const args = process.argv.slice(2);
-const USAGE = "usage: parmana-verify <proof.json> <trust.json>\n       parmana-verify key-fingerprint <public-key.pem>";
-
-if (args[0] === "key-fingerprint") {
-  if (args.length !== 2) {
-    console.error(USAGE);
-    process.exit(2);
-  }
-
-  try {
-    console.log(keyFingerprint(readFileSync(args[1], "utf8")));
-    process.exit(0);
-  } catch (error) {
-    console.error(`key error: ${error.message}`);
-    process.exit(2);
-  }
-}
-
-const [proofPath, trustPath] = args;
-
-if (!proofPath || !trustPath || args.length !== 2) {
-  console.error(USAGE);
-  process.exit(2);
-}
-
-let proof;
-let policy;
-
-try {
-  proof = JSON.parse(readFileSync(proofPath, "utf8"));
-  policy = parseTrustPolicy(JSON.parse(readFileSync(trustPath, "utf8")));
-} catch (error) {
-  console.error(`read error: ${error.message}`);
-  process.exit(2);
-}
-
-const result = verifyExecutionTrustRecord(proof, policy.keys, { hybridRequiredFrom: policy.hybridRequiredFrom ?? undefined, allowLegacyOnly: policy.allowLegacyOnly, allowLegacyV2: policy.allowLegacyV2 });
-
-console.log(JSON.stringify(result));
-
-process.exit(result.valid ? 0 : 1);
+#!/usr/bin/env node
+// Usage:
+//   parmana-verify <proof.json> <trust.json>
+//   parmana-verify key-fingerprint <public-key.pem>
+//
+// verify exits 0 = valid, 1 = invalid, 2 = usage or read error.
+// key-fingerprint prints the "sha256:..." value to pin in a trust file.
+
+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>";
+
+if (args[0] === "key-fingerprint") {
+  if (args.length !== 2) {
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  try {
+    console.log(keyFingerprint(readFileSync(args[1], "utf8")));
+    process.exit(0);
+  } catch (error) {
+    console.error(`key error: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+const [proofPath, trustPath] = args;
+
+if (!proofPath || !trustPath || args.length !== 2) {
+  console.error(USAGE);
+  process.exit(2);
+}
+
+let proof;
+let policy;
+
+try {
+  proof = JSON.parse(readFileSync(proofPath, "utf8"));
+  policy = parseTrustPolicy(JSON.parse(readFileSync(trustPath, "utf8")));
+} catch (error) {
+  console.error(`read error: ${error.message}`);
+  process.exit(2);
+}
+
+const result = verifyExecutionTrustRecord(proof, policy.keys, { hybridRequiredFrom: policy.hybridRequiredFrom ?? undefined, allowLegacyOnly: policy.allowLegacyOnly, allowLegacyV2: policy.allowLegacyV2 });
+
+// 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,40 +1,40 @@
-{
-  "name": "@parmana/verifier",
-  "version": "2.0.1",
-  "description": "Offline verifier for Parmana Execution Trust Records.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "bin": {
-    "parmana-verify": "bin/parmana-verify.mjs"
-  },
-  "files": [
-    "bin",
-    "src",
-    "LICENSE",
-    "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",
-    "examples": "node examples/run-all.mjs"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pavancharak/parmana-verifier.git"
-  },
-  "homepage": "https://github.com/pavancharak/parmana-verifier#readme",
-  "bugs": {
-    "url": "https://github.com/pavancharak/parmana-verifier/issues"
-  },
-  "keywords": [
-    "parmana",
-    "verifier",
-    "execution-trust-record",
-    "ed25519",
-    "ml-dsa",
-    "post-quantum",
-    "offline"
-  ]
-}
+{
+  "name": "@parmana/verifier",
+  "version": "2.0.3",
+  "description": "Offline verifier for Parmana Execution Trust Records.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "parmana-verify": "bin/parmana-verify.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "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/correspondence.test.mjs test/parmana-core-records.test.mjs test/quickstart.test.mjs",
+    "examples": "node examples/run-all.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pavancharak/parmana-verifier.git"
+  },
+  "homepage": "https://github.com/pavancharak/parmana-verifier#readme",
+  "bugs": {
+    "url": "https://github.com/pavancharak/parmana-verifier/issues"
+  },
+  "keywords": [
+    "parmana",
+    "verifier",
+    "execution-trust-record",
+    "ed25519",
+    "ml-dsa",
+    "post-quantum",
+    "offline"
+  ]
+}

package/src/canonical.mjs

@@ -1,35 +1,35 @@
-// Canonical serialization for Parmana artifacts.
-//
-// Object keys are sorted in code-unit order, arrays keep their order, and the
-// result is UTF-8 encoded JSON. Every hash and signature is computed over
-// these bytes, so the verifier must produce exactly the same bytes as the
-// signer.
-
-export function canonicalBytes(value) {
-  return new TextEncoder().encode(JSON.stringify(normalize(value)));
-}
-
-function normalize(value) {
-  if (value === null || typeof value !== "object") {
-    return value;
-  }
-
-  if (Array.isArray(value)) {
-    return value.map(normalize);
-  }
-
-  const normalized = {};
-
-  for (const key of Object.keys(value).sort()) {
-    // defineProperty, not assignment: a key named "__proto__" must stay an
-    // own property so its content is covered by the hash and signature.
-    Object.defineProperty(normalized, key, {
-      value: normalize(value[key]),
-      enumerable: true,
-      writable: true,
-      configurable: true,
-    });
-  }
-
-  return normalized;
-}
+// Canonical serialization for Parmana artifacts.
+//
+// Object keys are sorted in code-unit order, arrays keep their order, and the
+// result is UTF-8 encoded JSON. Every hash and signature is computed over
+// these bytes, so the verifier must produce exactly the same bytes as the
+// signer.
+
+export function canonicalBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(normalize(value)));
+}
+
+function normalize(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(normalize);
+  }
+
+  const normalized = {};
+
+  for (const key of Object.keys(value).sort()) {
+    // defineProperty, not assignment: a key named "__proto__" must stay an
+    // own property so its content is covered by the hash and signature.
+    Object.defineProperty(normalized, key, {
+      value: normalize(value[key]),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  return normalized;
+}

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 };
+}

package/src/timestamp.mjs

@@ -1,65 +1,65 @@
-// Strict ISO-8601 timestamp parsing, matching python/parmana_verifier/timestamps.py.
-//
-// Accepts a date, or a date and time with an explicit offset ("Z" or "+hh:mm").
-// A timestamp without an offset is rejected rather than read in the local time
-// zone, so a result never depends on the machine's clock setting. Returns NaN
-// for anything else, so callers can keep their existing Number.isNaN checks.
-
-const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?(Z|[+-]\d{2}:\d{2})$/;
-const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
-
-export function parseTimestamp(value) {
-  if (typeof value !== "string") return NaN;
-
-  const dateOnly = DATE_ONLY.exec(value);
-  if (dateOnly) {
-    return utcOrNaN(Number(dateOnly[1]), Number(dateOnly[2]), Number(dateOnly[3]), 0, 0, 0, 0);
-  }
-
-  const match = DATE_TIME.exec(value);
-  if (!match) return NaN;
-
-  const [, year, month, day, hour, minute, second, fraction, offset] = match;
-  const millis = Number(((fraction ?? "") + "000").slice(0, 3));
-  const utc = utcOrNaN(
-    Number(year),
-    Number(month),
-    Number(day),
-    Number(hour),
-    Number(minute),
-    Number(second ?? 0),
-    millis,
-  );
-  if (Number.isNaN(utc)) return NaN;
-
-  const offsetMs = offset === "Z" ? 0 : offsetToMillis(offset);
-  if (offsetMs === undefined) return NaN;
-
-  return utc - offsetMs;
-}
-
-function utcOrNaN(year, month, day, hour, minute, second, millis) {
-  if (month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59) return NaN;
-
-  const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millis));
-
-  // Date.UTC rolls an impossible day (for example 31 February) into the next
-  // month. Reject it by checking the fields round-trip unchanged.
-  if (
-    date.getUTCFullYear() !== year ||
-    date.getUTCMonth() !== month - 1 ||
-    date.getUTCDate() !== day
-  ) {
-    return NaN;
-  }
-
-  return date.getTime();
-}
-
-function offsetToMillis(text) {
-  const sign = text[0] === "+" ? 1 : -1;
-  const hours = Number(text.slice(1, 3));
-  const minutes = Number(text.slice(4, 6));
-  if (hours > 23 || minutes > 59) return undefined;
-  return sign * (hours * 60 + minutes) * 60_000;
-}
+// Strict ISO-8601 timestamp parsing, matching python/parmana_verifier/timestamps.py.
+//
+// Accepts a date, or a date and time with an explicit offset ("Z" or "+hh:mm").
+// A timestamp without an offset is rejected rather than read in the local time
+// zone, so a result never depends on the machine's clock setting. Returns NaN
+// for anything else, so callers can keep their existing Number.isNaN checks.
+
+const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?(Z|[+-]\d{2}:\d{2})$/;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+export function parseTimestamp(value) {
+  if (typeof value !== "string") return NaN;
+
+  const dateOnly = DATE_ONLY.exec(value);
+  if (dateOnly) {
+    return utcOrNaN(Number(dateOnly[1]), Number(dateOnly[2]), Number(dateOnly[3]), 0, 0, 0, 0);
+  }
+
+  const match = DATE_TIME.exec(value);
+  if (!match) return NaN;
+
+  const [, year, month, day, hour, minute, second, fraction, offset] = match;
+  const millis = Number(((fraction ?? "") + "000").slice(0, 3));
+  const utc = utcOrNaN(
+    Number(year),
+    Number(month),
+    Number(day),
+    Number(hour),
+    Number(minute),
+    Number(second ?? 0),
+    millis,
+  );
+  if (Number.isNaN(utc)) return NaN;
+
+  const offsetMs = offset === "Z" ? 0 : offsetToMillis(offset);
+  if (offsetMs === undefined) return NaN;
+
+  return utc - offsetMs;
+}
+
+function utcOrNaN(year, month, day, hour, minute, second, millis) {
+  if (month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59) return NaN;
+
+  const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millis));
+
+  // Date.UTC rolls an impossible day (for example 31 February) into the next
+  // month. Reject it by checking the fields round-trip unchanged.
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return NaN;
+  }
+
+  return date.getTime();
+}
+
+function offsetToMillis(text) {
+  const sign = text[0] === "+" ? 1 : -1;
+  const hours = Number(text.slice(1, 3));
+  const minutes = Number(text.slice(4, 6));
+  if (hours > 23 || minutes > 59) return undefined;
+  return sign * (hours * 60 + minutes) * 60_000;
+}