@parmana/verifier 1.6.2 → 1.6.3

package/README.md

@@ -25,7 +25,16 @@ node bin/parmana-verify.mjs test/vectors/record-whole-record-v3.json test/vector
 ```
 
 ```json
-{"valid":true,"coverage":"full","errors":[],"checks":{"trustRecordHash":true,"signature":true,"hybridSignatures":true}}
+{
+  "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:
@@ -36,6 +45,15 @@ node bin/parmana-verify.mjs test/vectors/record-tampered-amount.json test/vector
 
 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)).
 
+On Windows PowerShell, run the same two commands with Windows paths. Use Node 24 or later:
+
+```powershell
+node bin\parmana-verify.mjs test\vectors\record-whole-record-v3.json test\vectors\trust-whole-record.json
+node bin\parmana-verify.mjs test\vectors\record-tampered-amount.json test\vectors\trust.json
+```
+
+The first prints the valid result above and exits with `0`. The second prints `"valid":false` and exits with `1`.
+
 ## Installation and usage
 
 The package is published on npm as [`@parmana/verifier`](https://www.npmjs.com/package/@parmana/verifier). Install it, or run it without installing:
@@ -104,6 +122,15 @@ A key is used only if all of these hold:
 
 A compromised key is rejected whatever the timestamp, so signatures it made stay void.
 
+### Records with no hybrid envelope
+
+A record with no `signatures` array is a legacy-only record. The verifier refuses it by default. It is accepted only when:
+
+- the trust file sets `hybridRequiredFrom` and the record was created before that instant; or
+- the trust file sets `"allowLegacyOnly": true` and does not set `hybridRequiredFrom`.
+
+Otherwise the result is invalid, and the error says which setting would accept it. A record created at or after `hybridRequiredFrom` always needs a valid hybrid envelope, whatever `allowLegacyOnly` says. See [docs/FORMAT.md](docs/FORMAT.md#trust-set-trustjson).
+
 ## Examples
 
 Run every example with:
@@ -141,7 +168,7 @@ The suite covers the legacy signature and hash, hybrid signatures, schema versio
 - 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.
+- 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.
 - It does not verify the policy the record cites, the authorization decision logic, or the state of any connector or external system.
@@ -166,9 +193,12 @@ Every report is listed once, here. Start with the question you have.
 
 **Releases**
 
+- **Published versions:** `@parmana/verifier` 1.6.2 on npm and `parmana-verifier` 1.6.2 on PyPI, from release `verifier-v1.6.2`.
 - **Changelog:** [CHANGELOG.md](CHANGELOG.md) lists each change to the record formats and the command-line interface.
+- **Release process:** [RELEASING.md](RELEASING.md) describes how a release is built, checked and published.
 
 ---
+
 ## Read the Parmana blog
 
 The [Parmana blog](https://blog.parmanasystems.com) explains how the verifier fits into the wider product, in plain terms. Read the post for your role:
@@ -183,16 +213,20 @@ New posts are published regularly, so check the blog for updates.
 
 This is version 1.6.2, released with the SDK packages. Each change to the record formats or the command-line interface is listed in [CHANGELOG.md](CHANGELOG.md).
 
+On 2026-10-29, on Node 24.22.1 and Windows PowerShell, the two quick-start commands above returned the output shown, with exit codes `0` and `1`. The release process builds the packages, records their hashes, and attaches build provenance. See [RELEASING.md](RELEASING.md) for the steps.
+
+What this version does not do is listed under [Limitations](#limitations).
+
 ## 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`        |
-| `reports/`   | Pointer to the reports index in this README (see Reports and evidence)   |
+| 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`      |
+| `reports/`  | Pointer to the reports index in this README (see Reports and evidence) |
 
 ## Security
 

package/bin/parmana-verify.mjs

@@ -46,7 +46,7 @@ try {
   process.exit(2);
 }
 
-const result = verifyExecutionTrustRecord(proof, policy.keys, { hybridRequiredFrom: policy.hybridRequiredFrom ?? undefined });
+const result = verifyExecutionTrustRecord(proof, policy.keys, { hybridRequiredFrom: policy.hybridRequiredFrom ?? undefined, allowLegacyOnly: policy.allowLegacyOnly });
 
 console.log(JSON.stringify(result));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmana/verifier",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Offline verifier for Parmana Execution Trust Records.",
   "license": "Apache-2.0",
   "type": "module",

package/src/trust.mjs

@@ -47,6 +47,14 @@ export function parseTrustPolicy(document) {
     hybridRequiredFrom = document.hybridRequiredFrom;
   }
 
+  // Off by default: a record with no hybrid envelope is refused unless the
+  // trust file explicitly allows legacy-only records.
+  if (document.allowLegacyOnly !== undefined && typeof document.allowLegacyOnly !== "boolean") {
+    throw new Error('allowLegacyOnly must be true or false');
+  }
+
+  const allowLegacyOnly = document.allowLegacyOnly === true;
+
   const trustKeys = new Map();
 
   for (const [index, entry] of document.keys.entries()) {
@@ -100,5 +108,5 @@ export function parseTrustPolicy(document) {
     });
   }
 
-  return { keys: trustKeys, hybridRequiredFrom };
+  return { keys: trustKeys, hybridRequiredFrom, allowLegacyOnly };
 }

package/src/verify.mjs

@@ -116,16 +116,30 @@ export function verifyExecutionTrustRecord(record, trustKeys, options = {}) {
     checks.hybridSignatures = false;
   }
 
-  const cutoverOk = !isAtOrAfterCutover(record.createdAt, options.hybridRequiredFrom) || checks.hybridSignatures === true;
-
-  if (!cutoverOk) {
+  // A record with no hybrid envelope is accepted only when the caller allows
+  // it: explicitly (allowLegacyOnly), or because it predates a cutover the
+  // caller supplied. Otherwise it is refused, so a stripped envelope never
+  // passes by default.
+  const cutoverGiven = options.hybridRequiredFrom !== undefined && options.hybridRequiredFrom !== null;
+  const predatesCutover = cutoverGiven && !isAtOrAfterCutover(record.createdAt, options.hybridRequiredFrom);
+  // With a cutover, the cutover alone decides; allowLegacyOnly applies only when none is given.
+  const legacyOnlyAllowed = cutoverGiven ? predatesCutover : options.allowLegacyOnly === true;
+
+  // A record created at or after the cutover needs a valid envelope, whether it
+  // is missing or present but invalid.
+  const atOrAfterCutover = cutoverGiven && !predatesCutover;
+  if (atOrAfterCutover && checks.hybridSignatures !== true) {
     errors.push(`record created at or after hybridRequiredFrom (${options.hybridRequiredFrom}) has no valid hybrid envelope.`);
+  } else if (checks.hybridSignatures === undefined && !legacyOnlyAllowed) {
+    errors.push("record has no hybrid envelope: set hybridRequiredFrom or allowLegacyOnly to accept a legacy-only record.");
   }
 
+  const envelopeOk = checks.hybridSignatures === undefined ? legacyOnlyAllowed : checks.hybridSignatures;
+
   const coverage = schemaVersion === WHOLE_RECORD_SCHEMA_VERSION && checks.hybridSignatures === true ? "full" : "legacy";
 
   return {
-    valid: hashValid && signatureValid && (checks.hybridSignatures ?? true) && cutoverOk,
+    valid: hashValid && signatureValid && envelopeOk,
     coverage,
     errors,
     checks,