@parmana/verifier 1.6.2 → 2.0.0

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "@parmana/verifier",
-  "version": "1.6.2",
-  "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"
-  ]
-}
+{
+  "name": "@parmana/verifier",
+  "version": "2.0.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 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"
+  ]
+}

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/timestamp.mjs

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

package/src/trust.mjs

@@ -1,104 +1,121 @@
-// 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 };
-}
+// 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";
+import { parseTimestamp } from "./timestamp.mjs";
+
+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(parseTimestamp(document.hybridRequiredFrom))) {
+      throw new Error('hybridRequiredFrom must be an ISO-8601 UTC timestamp ending in "Z"');
+    }
+
+    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;
+
+  // Off by default: a schema version 2 record (or one with no schemaVersion)
+  // is refused unless the trust file explicitly allows it.
+  if (document.allowLegacyV2 !== undefined && typeof document.allowLegacyV2 !== "boolean") {
+    throw new Error('allowLegacyV2 must be true or false');
+  }
+
+  const allowLegacyV2 = document.allowLegacyV2 === true;
+
+  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(parseTimestamp(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(parseTimestamp(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, allowLegacyOnly, allowLegacyV2 };
+}