@parmana/verifier 1.6.3 → 2.0.0

package/src/verify.mjs

@@ -1,326 +1,343 @@
-// 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;
-  }
-
-  // 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 && envelopeOk,
-    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);
-}
+// 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";
+import { parseTimestamp } from "./timestamp.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: {} };
+  }
+
+  // Schema version 2 signs only seven top-level fields. A record with no
+  // schemaVersion is treated as version 2. Both are refused unless the caller
+  // opts in with allowLegacyV2, so a partially covered record is never
+  // accepted by default.
+  const declaredVersion = record.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
+  if (declaredVersion === 2 && options.allowLegacyV2 !== true) {
+    return {
+      valid: false,
+      coverage: "legacy",
+      errors: [
+        "schemaVersion 2 (or no schemaVersion) covers only seven top-level fields and is refused by default: set allowLegacyV2 to accept it, or re-issue the record as schemaVersion 3.",
+      ],
+      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;
+  }
+
+  // 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 && envelopeOk,
+    coverage,
+    errors,
+    checks,
+  };
+}
+
+function isAtOrAfterCutover(createdAt, hybridRequiredFrom) {
+  if (hybridRequiredFrom === undefined) {
+    return false;
+  }
+
+  const created = parseTimestamp(createdAt);
+
+  return !Number.isNaN(created) && created >= parseTimestamp(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 = parseTimestamp(createdAt);
+
+  if (Number.isNaN(at)) {
+    return false;
+  }
+
+  if (at < parseTimestamp(trusted.validFrom)) {
+    return false;
+  }
+
+  return trusted.validUntil === null || at < parseTimestamp(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);
+}