@parmana/verifier 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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
+
+       http://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/NOTICE

@@ -0,0 +1 @@
+Copyright 2026 Parmana Systems Private Limited

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
-
-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.
+# Parmana Verifier
+
+[![CI](https://github.com/pavancharak/parmana-verifier/actions/workflows/ci.yml/badge.svg)](https://github.com/pavancharak/parmana-verifier/actions/workflows/ci.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](package.json)
+
+Check whether an AI agent's action was approved and recorded as signed, using only a file and the keys you trust. No network access, no account, no dependencies.
+
+Parmana signs an **Execution Trust Record** for every action an agent takes through it. The record says what was authorized, what ran, and what the outcome was, and it is signed with keys. This verifier checks that a record has not been changed and that it was signed by keys you chose to trust. It does not ask Parmana's servers anything, so you do not have to trust them to check a record.
+
+The records come from [Parmana](https://github.com/pavancharak/parmana-core), which signs them. The verifier works without the rest of Parmana: it needs only a record and a trust file.
+
+## Who it is for
+
+- **Auditors and reviewers** who need to confirm a record without relying on the system that produced it.
+- **Operators** who want to check records in their own environment, with keys they pinned themselves.
+- **Developers** who want a small, dependency-free reference implementation of the record checks.
+
+## Quick start
+
+Requires Node.js 24 or later. Ed25519 works on any Node 24 build; post-quantum ML-DSA-65 signatures need OpenSSL 3.5 or later. From a clone of this repository:
+
+```sh
+node bin/parmana-verify.mjs test/vectors/record-whole-record-v3.json test/vectors/trust-whole-record.json
+```
+
+```json
+{"valid":true,"coverage":"full","errors":[],"checks":{"trustRecordHash":true,"signature":true,"hybridSignatures":true}}
+```
+
+The exit code is `0`. A record that has been changed is rejected:
+
+```sh
+node bin/parmana-verify.mjs test/vectors/record-tampered-amount.json test/vectors/trust.json
+```
+
+The exit code is `1`, and the output lists the failed checks. The test vectors are labelled test material; see [test/vectors/README.md](test/vectors/README.md). For real records, pin the keys you trust (see [Pinning a key](#pinning-a-key)).
+
+## Installation and usage
+
+The package is not published to npm. Run it from a clone of this repository.
+
+```sh
+node bin/parmana-verify.mjs <proof.json> <trust.json>
+node bin/parmana-verify.mjs key-fingerprint <public-key.pem>
+```
+
+- `proof.json` is the Execution Trust Record.
+- `trust.json` is the trust set. It lists each key you accept:
+
+  ```json
+  {
+    "keys": [
+      {
+        "keyId": "default",
+        "algorithm": "ed25519",
+        "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
+        "fingerprint": "sha256:<64 hex digits>",
+        "validFrom": "2026-01-01T00:00:00.000Z",
+        "validUntil": null,
+        "compromised": false
+      }
+    ]
+  }
+  ```
+
+- `key-fingerprint` prints the `sha256:` value to pin for a PEM key. To pin a key safely, follow the steps in [Pinning a key](#pinning-a-key).
+
+The verify command prints one line of JSON and exits with `0` (valid), `1` (invalid, with reasons), or `2` (usage, missing file, or invalid JSON). The full input and output rules are in [docs/FORMAT.md](docs/FORMAT.md).
+
+On Windows PowerShell, use the same commands with Windows paths, for example `node bin\parmana-verify.mjs proof.json trust.json`.
+
+## 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.
+
+1. Get the operator's public key PEM and the `sha256:` fingerprint they published. Get the fingerprint from a source other than the one that gave you the key, such as a signed message or a call to a known number.
+2. Run `node bin/parmana-verify.mjs key-fingerprint public-key.pem` on the PEM you received.
+3. Compare the two fingerprints character by character. If they differ, do not use the key.
+4. Only then add the key to your trust file with that fingerprint.
+
+## Trust rules
+
+A key is used only if all of these hold:
+
+- its PEM hashes to the pinned fingerprint (SHA-256 of the SPKI DER encoding);
+- the algorithm named by the signature matches the algorithm in the trust file;
+- it is not marked `compromised`;
+- the record's `createdAt` is at or after `validFrom` and before `validUntil` (if set).
+
+A compromised key is rejected whatever the timestamp, so signatures it made stay void.
+
+## Examples
+
+Run every example with:
+
+```sh
+npm run examples
+```
+
+The examples are in `examples/`, and each one prints what it checks:
+
+- `01-verify-a-proof.mjs`: verify a record and explain each check.
+- `02-tamper-detection.mjs`: change a signed field, then show that recomputing the hash does not help an attacker.
+- `03-pinned-keys-and-windows.mjs`: how pinned fingerprints, validity windows and compromised keys decide what is accepted.
+- `04-hybrid-envelope.mjs`: the Ed25519 and ML-DSA-65 entries of a hybrid record (needs Node 24).
+- `05-build-and-verify-a-record.mjs`: build, hash, sign, pin and verify a record from scratch, with a runtime test key.
+- `06-command-line.mjs`: the command-line exit codes, and fingerprinting a key for pinning.
+- `07-whole-record-coverage.mjs`: what coverage `full` and `legacy` mean, and that a changed covered field is refused.
+- `08-hybrid-cutover.mjs`: the `hybridRequiredFrom` cutover, and what it adds to a record created after it.
+- `09-unsupported-schema-version.mjs`: a schema version other than 2 or 3 is refused, not guessed at.
+
+Each example exits `0` when it behaves as described, so the set runs in CI.
+
+## Testing
+
+```sh
+npm test
+```
+
+Run the tests on Node 24. On Node 22 or any runtime without ML-DSA-65, the hybrid tests are skipped. Test keys are generated at run time, labelled "TEST KEY - NOT FOR PRODUCTION", and never written to disk.
+
+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/`.
+
+## 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.
+- 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.
+- 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.
+- It does not verify the policy the record cites, the authorization decision logic, or the state of any connector or external system.
+- It does not confirm that the action described by the record was executed.
+- The records in `test/vectors/` were produced by the Parmana signing code and are test material only. They show that the checks agree with that code; they are not an independent specification.
+
+## Status
+
+This is version 0.3.0. The record formats and the command-line interface may still change before 1.0; each change is listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Repository layout
+
+| Path         | Contents                                                                 |
+| ------------ | ------------------------------------------------------------------------ |
+| `bin/`       | The `parmana-verify` command-line entry point                            |
+| `src/`       | The checks: canonical JSON, hashing, signatures, trust rules             |
+| `test/`      | The test suite, and `test/vectors/`, the labelled test records           |
+| `examples/`  | Nine runnable examples, run by `npm run examples`                        |
+| `docs/`      | `FORMAT.md` (the input and output rules) and `SECURITY-REVIEW.md`        |
+
+## Security
+
+Do not open a public issue for a security problem. Report it through GitHub's private vulnerability reporting: open the **Security** tab and choose **Report a vulnerability**. See [SECURITY.md](SECURITY.md). The scope for an external review is in [docs/SECURITY-REVIEW.md](docs/SECURITY-REVIEW.md).
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before you open a pull request. Run `npm test` on Node 24 first. Every commit must carry a `Signed-off-by` line (`git commit -s`), certifying the [Developer Certificate of Origin](https://developercertificate.org). Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/bin/parmana-verify.mjs

@@ -0,0 +1,53 @@
+#!/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 });
+
+console.log(JSON.stringify(result));
+
+process.exit(result.valid ? 0 : 1);

package/package.json

@@ -1,6 +1,40 @@
-{
-  "name": "@parmana/verifier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@parmana/verifier",
+  "version": "0.3.0",
+  "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",
+    "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

@@ -0,0 +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;
+}

package/src/trust.mjs

@@ -0,0 +1,104 @@
+// Trust set: the keys a verifier accepts, each pinned by fingerprint.
+//
+// A key is used only when all of these hold:
+//   - its PEM hashes to the pinned fingerprint (SHA-256 of the SPKI DER);
+//   - its algorithm matches the algorithm the signature names;
+//   - it is not marked compromised;
+//   - the record's createdAt falls within [validFrom, validUntil).
+//
+// The trust set is supplied by the caller. The verifier never fetches keys.
+
+import { createHash, createPublicKey } from "node:crypto";
+
+export const ALGORITHM_NAMES = ["ed25519", "dilithium3"];
+
+export function keyFingerprint(publicKeyPem) {
+  return fingerprintOfKey(createPublicKey(publicKeyPem));
+}
+
+export function fingerprintOfKey(publicKey) {
+  const der = publicKey.export({ type: "spki", format: "der" });
+  return `sha256:${createHash("sha256").update(der).digest("hex")}`;
+}
+
+// Parses a trust-set document into a Map keyId -> entry. Throws an Error with
+// a readable message when the document is malformed.
+export function parseTrustSet(document) {
+  return parseTrustPolicy(document).keys;
+}
+
+// Parses a trust-set document into { keys, hybridRequiredFrom }. keys is the
+// Map that parseTrustSet returns. hybridRequiredFrom is the optional cutover:
+// a record created at or after it must carry a valid hybrid envelope. It is
+// null when the document does not set one. It must be an ISO-8601 UTC
+// timestamp ending in "Z", so that it means the same time everywhere.
+export function parseTrustPolicy(document) {
+  if (document === null || typeof document !== "object" || !Array.isArray(document.keys)) {
+    throw new Error('trust set must be an object with a "keys" array');
+  }
+
+  let hybridRequiredFrom = null;
+
+  if (document.hybridRequiredFrom !== undefined && document.hybridRequiredFrom !== null) {
+    if (typeof document.hybridRequiredFrom !== "string" || !/Z$/.test(document.hybridRequiredFrom) || Number.isNaN(Date.parse(document.hybridRequiredFrom))) {
+      throw new Error('hybridRequiredFrom must be an ISO-8601 UTC timestamp ending in "Z"');
+    }
+
+    hybridRequiredFrom = document.hybridRequiredFrom;
+  }
+
+  const trustKeys = new Map();
+
+  for (const [index, entry] of document.keys.entries()) {
+    const at = `keys[${index}]`;
+
+    if (entry === null || typeof entry !== "object") {
+      throw new Error(`${at} must be an object`);
+    }
+
+    if (typeof entry.keyId !== "string" || entry.keyId === "") {
+      throw new Error(`${at}.keyId must be a non-empty string`);
+    }
+
+    if (trustKeys.has(entry.keyId)) {
+      throw new Error(`duplicate keyId "${entry.keyId}"`);
+    }
+
+    if (!ALGORITHM_NAMES.includes(entry.algorithm)) {
+      throw new Error(`${at}.algorithm must be one of ${ALGORITHM_NAMES.join(", ")}`);
+    }
+
+    if (typeof entry.publicKeyPem !== "string") {
+      throw new Error(`${at}.publicKeyPem must be a PEM string`);
+    }
+
+    if (typeof entry.fingerprint !== "string" || !/^sha256:[0-9a-f]{64}$/.test(entry.fingerprint)) {
+      throw new Error(`${at}.fingerprint must be "sha256:" followed by 64 lowercase hex digits`);
+    }
+
+    if (typeof entry.validFrom !== "string" || Number.isNaN(Date.parse(entry.validFrom))) {
+      throw new Error(`${at}.validFrom must be an ISO timestamp`);
+    }
+
+    if (entry.validUntil !== undefined && entry.validUntil !== null &&
+        (typeof entry.validUntil !== "string" || Number.isNaN(Date.parse(entry.validUntil)))) {
+      throw new Error(`${at}.validUntil must be an ISO timestamp or null`);
+    }
+
+    if (entry.compromised !== undefined && typeof entry.compromised !== "boolean") {
+      throw new Error(`${at}.compromised must be true or false`);
+    }
+
+    trustKeys.set(entry.keyId, {
+      keyId: entry.keyId,
+      algorithm: entry.algorithm,
+      publicKeyPem: entry.publicKeyPem,
+      fingerprint: entry.fingerprint,
+      validFrom: entry.validFrom,
+      validUntil: entry.validUntil ?? null,
+      compromised: entry.compromised ?? false,
+    });
+  }
+
+  return { keys: trustKeys, hybridRequiredFrom };
+}

package/src/verify.mjs

@@ -0,0 +1,312 @@
+// Offline verification of an Execution Trust Record.
+//
+// Checks run on the record alone:
+//   1. trustRecordHash equals the SHA-256 (hex) of the canonical record fields.
+//   2. signature is a valid signature over those canonical bytes, made by a
+//      trusted key named by signature.keyId (see trust.mjs for the trust rules).
+//   3. If signatures is present, it is a hybrid envelope: at least two entries,
+//      no repeated algorithm, and every entry verifies over the message for
+//      its schemaVersion (default 2). Any failure makes the record invalid.
+//      A record with schemaVersion 3 must carry a hybrid envelope.
+//   4. If a cutover is given (options.hybridRequiredFrom, from the trust
+//      file), a record created at or after it must pass check 3.
+//
+// Schema versions:
+//   2  the message is the canonical fields plus schemaVersion.
+//   3  the message is every top-level field except signature, signatures,
+//      schemaVersion, verifications and receipts, plus schemaVersion.
+//      Fields outside the version 2 message, such as updatedAt, are covered.
+//
+// The result's coverage is "full" when a version 3 envelope verifies, and
+// "legacy" otherwise. Records with other schemaVersion values are invalid.
+//
+// Supported algorithms:
+//   ed25519     Ed25519 keys. Messages over 4096 bytes may be signed as a
+//               commitment: the prefix below followed by the SHA-512 digest of
+//               the canonical bytes. A raw signature over a large message is
+//               also accepted. A commitment over a small message is rejected.
+//   dilithium3  ML-DSA-65 keys (Node 24+ with OpenSSL 3.5+). Raw signatures
+//               only.
+//
+// The verifier reads no environment variables, no private keys, and makes no
+// network calls.
+
+import {
+  createHash,
+  createPublicKey,
+  generateKeyPairSync,
+  verify as verifySignature,
+} from "node:crypto";
+import { canonicalBytes } from "./canonical.mjs";
+import { fingerprintOfKey } from "./trust.mjs";
+
+const ALGORITHMS = {
+  ed25519: { keyType: "ed25519", commitment: true },
+  dilithium3: { keyType: "ml-dsa-65", commitment: false },
+};
+
+const RAW_MESSAGE_LIMIT_BYTES = 4096;
+const COMMITMENT_PREFIX = Buffer.from("PARMANA-ED25519-LARGE-MESSAGE-V1\0", "utf8");
+const DEFAULT_SCHEMA_VERSION = 2;
+const WHOLE_RECORD_SCHEMA_VERSION = 3;
+const SUPPORTED_SCHEMA_VERSIONS = [2, 3];
+
+// Top-level fields that a version 3 message does not cover. verifications and
+// receipts are attached after signing; receipts carry their own signature.
+const WHOLE_RECORD_EXCLUDED_FIELDS = ["signature", "signatures", "schemaVersion", "verifications", "receipts"];
+
+// The fields covered by trustRecordHash and the legacy signature.
+export function canonicalTrustRecord(record) {
+  return {
+    trustRecordId: record.trustRecordId,
+    businessTransactionId: record.businessTransactionId,
+    transaction: record.transaction,
+    authorization: record.authorization,
+    overrides: record.overrides,
+    executions: record.executions,
+    createdAt: record.createdAt,
+  };
+}
+
+// The message a hybrid envelope of the given schema version signs.
+export function hybridMessage(record, schemaVersion) {
+  if (schemaVersion === WHOLE_RECORD_SCHEMA_VERSION) {
+    const covered = Object.entries(record).filter(([key]) => !WHOLE_RECORD_EXCLUDED_FIELDS.includes(key));
+
+    return canonicalBytes({ ...Object.fromEntries(covered), schemaVersion });
+  }
+
+  return canonicalBytes({ ...canonicalTrustRecord(record), schemaVersion });
+}
+
+// trustKeys is a Map from keyId to a trust entry, as returned by parseTrustSet.
+// options.hybridRequiredFrom is an ISO-8601 UTC timestamp from the trust file
+// (see parseTrustPolicy); records created at or after it need a hybrid envelope.
+export function verifyExecutionTrustRecord(record, trustKeys, options = {}) {
+  const errors = [];
+
+  if (!isObject(record)) {
+    return { valid: false, coverage: "legacy", errors: ["record must be a JSON object"], checks: {} };
+  }
+
+  const legacyMessage = canonicalBytes(canonicalTrustRecord(record));
+  const expectedHash = createHash("sha256").update(legacyMessage).digest("hex");
+  const hashValid = expectedHash === record.trustRecordHash;
+
+  if (!hashValid) {
+    errors.push(`trustRecordHash mismatch: expected ${expectedHash}.`);
+  }
+
+  const context = { trustKeys, createdAt: record.createdAt };
+
+  const signatureValid = verifyLegacySignature(record.signature, legacyMessage, context, errors);
+
+  const checks = { trustRecordHash: hashValid, signature: signatureValid };
+
+  const schemaVersion = record.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
+  const hasEnvelope = record.signatures !== undefined && record.signatures !== null;
+
+  if (!SUPPORTED_SCHEMA_VERSIONS.includes(schemaVersion)) {
+    errors.push(`unsupported schemaVersion ${String(schemaVersion)}: expected 2 or 3.`);
+    checks.hybridSignatures = false;
+  } else if (hasEnvelope) {
+    checks.hybridSignatures = verifyHybridSignatures(record.signatures, hybridMessage(record, schemaVersion), context, errors);
+  } else if (schemaVersion === WHOLE_RECORD_SCHEMA_VERSION) {
+    errors.push("schemaVersion 3 record has no signatures array: a whole-record signature is required.");
+    checks.hybridSignatures = false;
+  }
+
+  const cutoverOk = !isAtOrAfterCutover(record.createdAt, options.hybridRequiredFrom) || checks.hybridSignatures === true;
+
+  if (!cutoverOk) {
+    errors.push(`record created at or after hybridRequiredFrom (${options.hybridRequiredFrom}) has no valid hybrid envelope.`);
+  }
+
+  const coverage = schemaVersion === WHOLE_RECORD_SCHEMA_VERSION && checks.hybridSignatures === true ? "full" : "legacy";
+
+  return {
+    valid: hashValid && signatureValid && (checks.hybridSignatures ?? true) && cutoverOk,
+    coverage,
+    errors,
+    checks,
+  };
+}
+
+function isAtOrAfterCutover(createdAt, hybridRequiredFrom) {
+  if (hybridRequiredFrom === undefined) {
+    return false;
+  }
+
+  const created = Date.parse(createdAt);
+
+  return !Number.isNaN(created) && created >= Date.parse(hybridRequiredFrom);
+}
+
+function verifyLegacySignature(signature, message, context, errors) {
+  if (!isSignatureEntry(signature)) {
+    errors.push("signature is missing or malformed.");
+    return false;
+  }
+
+  return verifyEntry(signature, message, context, errors);
+}
+
+function verifyHybridSignatures(entries, message, context, errors) {
+  if (!Array.isArray(entries) || !entries.every(isSignatureEntry)) {
+    errors.push("malformed signatures: expected an array of entries with string algorithm, keyId and signature.");
+    return false;
+  }
+
+  if (entries.length < 2) {
+    errors.push(`signatures array has ${entries.length} entr${entries.length === 1 ? "y" : "ies"}, need at least 2 for a hybrid record.`);
+    return false;
+  }
+
+  const seen = new Set();
+  let allValid = true;
+
+  for (const entry of entries) {
+    if (seen.has(entry.algorithm)) {
+      errors.push(`duplicate algorithm in signatures array: ${entry.algorithm}.`);
+      allValid = false;
+      continue;
+    }
+
+    seen.add(entry.algorithm);
+    allValid = verifyEntry(entry, message, context, errors) && allValid;
+  }
+
+  return allValid;
+}
+
+// Accepts { algorithm, keyId, signature } entries. The legacy `signature` field
+// uses `value` for the same three parts, so that is accepted too.
+function verifyEntry(entry, message, context, errors) {
+  const signatureText = entry.signature ?? entry.value;
+  const algorithm = ALGORITHMS[entry.algorithm];
+
+  if (!algorithm) {
+    errors.push(`unsupported algorithm: ${entry.algorithm}.`);
+    return false;
+  }
+
+  const trusted = context.trustKeys.get(entry.keyId);
+
+  if (!trusted) {
+    errors.push(`no trusted key for keyId "${entry.keyId}".`);
+    return false;
+  }
+
+  if (trusted.algorithm !== entry.algorithm) {
+    errors.push(`keyId "${entry.keyId}" is trusted for ${trusted.algorithm}, not ${entry.algorithm}.`);
+    return false;
+  }
+
+  if (trusted.compromised) {
+    errors.push(`keyId "${entry.keyId}" is marked compromised; its signatures are not accepted.`);
+    return false;
+  }
+
+  if (!withinValidityWindow(trusted, context.createdAt)) {
+    errors.push(`createdAt ${context.createdAt} is outside the validity window of keyId "${entry.keyId}".`);
+    return false;
+  }
+
+  if (entry.algorithm === "dilithium3" && !mlDsaSupported()) {
+    errors.push("algorithm dilithium3 needs Node 24 or later with OpenSSL 3.5 or later.");
+    return false;
+  }
+
+  let publicKey;
+
+  try {
+    publicKey = createPublicKey(trusted.publicKeyPem);
+  } catch {
+    errors.push(`public key for keyId "${entry.keyId}" is not a valid PEM key.`);
+    return false;
+  }
+
+  if (fingerprintOfKey(publicKey) !== trusted.fingerprint) {
+    errors.push(`public key for keyId "${entry.keyId}" does not match its pinned fingerprint.`);
+    return false;
+  }
+
+  if (publicKey.asymmetricKeyType !== algorithm.keyType) {
+    errors.push(`public key for keyId "${entry.keyId}" has type ${publicKey.asymmetricKeyType}, expected ${algorithm.keyType}.`);
+    return false;
+  }
+
+  const sigBytes = Buffer.from(signatureText, "base64");
+
+  const rawValid = safeVerify(message, sigBytes, publicKey);
+
+  const commitmentValid =
+    !rawValid &&
+    algorithm.commitment &&
+    message.length > RAW_MESSAGE_LIMIT_BYTES &&
+    safeVerify(commitment(message), sigBytes, publicKey);
+
+  if (!rawValid && !commitmentValid) {
+    errors.push(`signature verification failed for keyId "${entry.keyId}" (${entry.algorithm}).`);
+    return false;
+  }
+
+  return true;
+}
+
+function withinValidityWindow(trusted, createdAt) {
+  const at = Date.parse(createdAt);
+
+  if (Number.isNaN(at)) {
+    return false;
+  }
+
+  if (at < Date.parse(trusted.validFrom)) {
+    return false;
+  }
+
+  return trusted.validUntil === null || at < Date.parse(trusted.validUntil);
+}
+
+function commitment(message) {
+  return Buffer.concat([
+    COMMITMENT_PREFIX,
+    createHash("sha512").update(message).digest(),
+  ]);
+}
+
+function safeVerify(message, sigBytes, publicKey) {
+  try {
+    return verifySignature(null, Buffer.from(message), publicKey, sigBytes);
+  } catch {
+    return false;
+  }
+}
+
+let mlDsa;
+
+function mlDsaSupported() {
+  if (mlDsa === undefined) {
+    try {
+      generateKeyPairSync("ml-dsa-65");
+      mlDsa = true;
+    } catch {
+      mlDsa = false;
+    }
+  }
+
+  return mlDsa;
+}
+
+function isSignatureEntry(value) {
+  return (
+    isObject(value) &&
+    typeof value.algorithm === "string" &&
+    typeof value.keyId === "string" &&
+    (typeof value.signature === "string" || typeof value.value === "string")
+  );
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}