@blamejs/blamejs-shop 0.4.91 → 0.4.93

package/lib/vendor/blamejs/lib/backup/manifest.js

@@ -314,47 +314,39 @@ function serialize(manifest) {
 // or SLH-DSA-SHAKE-256f — whichever audit-sign was initialized with).
 // The signature covers the manifest's canonical bytes WITHOUT the
 // signature field; appending it does not change the signed payload.
-function sign(manifest) {
-  var v = validate(manifest);
-  if (!v.ok) {
-    throw new BackupManifestError("backup-manifest/invalid",
-      "sign: " + v.errors.join("; "));
-  }
+// Sign caller-supplied canonical bytes with the audit-sign keypair, returning a
+// detached signature block. Shared by sign() (v1 manifest schema) and
+// signBytes() (schema-agnostic). `payload` is a Buffer (signed verbatim) or a
+// string (signed as UTF-8) — auditSign.sign normalizes both identically.
+function _signPayload(payload, who) {
   var signer = auditSign();
   if (!signer || typeof signer.sign !== "function") {
     throw new BackupManifestError("backup-manifest/no-signer",
-      "sign: audit-sign module is not available; call b.auditSign.init() first");
+      who + ": audit-sign module is not available; call b.auditSign.init() first");
   }
-  var payload = signingPayload(manifest);
   var signatureBytes;
   try { signatureBytes = signer.sign(payload); }
   catch (e) {
     throw new BackupManifestError("backup-manifest/sign-failed",
-      "sign: audit-sign.sign threw: " + ((e && e.message) || String(e)));
+      who + ": audit-sign.sign threw: " + ((e && e.message) || String(e)));
   }
-  manifest.signature = {
+  return {
     algorithm:   signer.getAlgorithm(),
     publicKey:   signer.getPublicKey(),
     fingerprint: signer.getPublicKeyFingerprint(),
     value:       signatureBytes.toString("base64"),
     signedAt:    new Date().toISOString(),
   };
-  return manifest;
 }
 
-// Verify a previously-signed manifest. Returns { ok, reason?,
-// fingerprint? }. Caller policy decides whether a missing or
-// fingerprint-mismatched signature is fatal — verifyManifestSignature
-// in lib/backup/index.js wraps this with operator-facing semantics.
-function verifySignature(manifest, opts) {
+// Verify `payload` against a detached signature block (the shape _signPayload
+// returns). Shared by verifySignature() and verifyBytes(). Returns
+// { ok, reason?, fingerprint? }; enforces opts.expectedFingerprint pinning.
+function _verifyPayloadAgainstBlock(payload, sig, opts) {
   opts = opts || {};
-  if (!manifest || typeof manifest !== "object") {
-    return { ok: false, reason: "manifest must be an object" };
-  }
-  if (!manifest.signature || typeof manifest.signature !== "object") {
-    return { ok: false, reason: "manifest has no signature block" };
+  if (!sig || typeof sig !== "object") {
+    return { ok: false, reason: "signature block must be an object" };
   }
-  var sig = manifest.signature;
   if (typeof sig.algorithm !== "string" || sig.algorithm.length === 0) {
     return { ok: false, reason: "signature.algorithm is required" };
   }
@@ -364,28 +356,50 @@ function verifySignature(manifest, opts) {
   if (typeof sig.value !== "string" || sig.value.length === 0) {
     return { ok: false, reason: "signature.value is required" };
   }
-  // Caller may pin the expected fingerprint — operators tracking key
-  // rotation pass the active audit-sign fingerprint and refuse any
-  // bundle signed under a different historical key.
-  if (typeof opts.expectedFingerprint === "string" &&
-      opts.expectedFingerprint.length > 0 &&
-      sig.fingerprint !== opts.expectedFingerprint) {
-    return {
-      ok: false,
-      reason: "signature.fingerprint=" + sig.fingerprint +
-              " does not match expectedFingerprint=" + opts.expectedFingerprint,
-      fingerprint: sig.fingerprint,
-    };
+  // The fingerprint of the key the signature is ACTUALLY verified under —
+  // recomputed from sig.publicKey, never the block's self-asserted
+  // sig.fingerprint (which an attacker controls). Used for the pin check below
+  // and returned on success so the caller sees the real key, not a claim.
+  var derivedFingerprint = null;
+  try {
+    var signerForFp = auditSign();
+    if (signerForFp && typeof signerForFp.fingerprintOf === "function") {
+      derivedFingerprint = signerForFp.fingerprintOf(sig.publicKey);
+    }
+  } catch (fpErr) {
+    return { ok: false, reason: "could not derive fingerprint from publicKey: " +
+      ((fpErr && fpErr.message) || String(fpErr)) };
+  }
+  // Caller may pin the expected fingerprint — operators tracking key rotation
+  // pass the active audit-sign fingerprint and refuse any payload signed under
+  // a different historical key. CRITICAL: the pin is checked against the
+  // fingerprint RECOMPUTED from the block's own publicKey, NOT the block's
+  // self-asserted `fingerprint` field. An attacker can sign arbitrary bytes
+  // with their own key and set `fingerprint` to the trusted value; binding the
+  // pin to fingerprintOf(publicKey) — the key the signature is actually
+  // verified under — closes that substitution (the signature can only verify
+  // under publicKey, and publicKey must hash to the trusted fingerprint).
+  if (typeof opts.expectedFingerprint === "string" && opts.expectedFingerprint.length > 0) {
+    if (derivedFingerprint === null) {
+      return { ok: false, reason: "fingerprint pinning requires audit-sign.fingerprintOf (unavailable)" };
+    }
+    if (derivedFingerprint !== opts.expectedFingerprint) {
+      return {
+        ok: false,
+        reason: "publicKey fingerprint=" + derivedFingerprint +
+                " does not match expectedFingerprint=" + opts.expectedFingerprint,
+        fingerprint: derivedFingerprint,
+      };
+    }
   }
-  var payload = signingPayload(manifest);
   var sigBuf;
   try { sigBuf = Buffer.from(sig.value, "base64"); }
   catch (_e) {
     return { ok: false, reason: "signature.value is not valid base64" };
   }
-  // Use audit-sign.verify when available (handles algorithm dispatch
-  // identically to the signer); fall back to nodeCrypto.verify for
-  // verifier processes that don't init audit-sign.
+  // Use audit-sign.verify when available (handles algorithm dispatch identically
+  // to the signer); fall back to nodeCrypto.verify for verifier processes that
+  // don't init audit-sign.
   var ok;
   try {
     var signer = auditSign();
@@ -393,23 +407,154 @@ function verifySignature(manifest, opts) {
       ok = signer.verify(payload, sigBuf, sig.publicKey);
     } else {
       ok = require("node:crypto").verify(null,
-        Buffer.from(payload, "utf8"), sig.publicKey, sigBuf);
+        Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8"), sig.publicKey, sigBuf);
     }
   } catch (e) {
     return {
-      ok:           false,
-      reason:       "verify threw: " + ((e && e.message) || String(e)),
-      fingerprint:  sig.fingerprint,
+      ok:          false,
+      reason:      "verify threw: " + ((e && e.message) || String(e)),
+      fingerprint: sig.fingerprint,
     };
   }
   if (!ok) {
     return {
       ok:          false,
       reason:      "signature did not verify under provided publicKey",
-      fingerprint: sig.fingerprint,
+      fingerprint: derivedFingerprint || sig.fingerprint,
     };
   }
-  return { ok: true, fingerprint: sig.fingerprint };
+  // Return the fingerprint of the key the signature actually verified under
+  // (recomputed), not the block's self-asserted value.
+  return { ok: true, fingerprint: derivedFingerprint || sig.fingerprint };
+}
+
+/**
+ * @primitive b.backupManifest.sign
+ * @signature b.backupManifest.sign(manifest)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.backupManifest.verifySignature, b.backupManifest.signBytes, b.auditSign.sign
+ *
+ * Sign a v1 backup manifest in place with the audit-sign keypair, attaching a
+ * detached `signature` block over the manifest's canonical bytes (the
+ * serialization WITHOUT the signature field, so appending it doesn't change
+ * the signed payload). Validates the manifest against the v1 schema first;
+ * throws `backup-manifest/invalid` on a malformed manifest and
+ * `backup-manifest/no-signer` when `b.auditSign.init()` hasn't run. For a
+ * schema-agnostic alternative see `signBytes`.
+ *
+ * @example
+ *   b.backupManifest.sign(manifest);
+ *   manifest.signature.fingerprint;   // the signing key's fingerprint
+ */
+function sign(manifest) {
+  var v = validate(manifest);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "sign: " + v.errors.join("; "));
+  }
+  manifest.signature = _signPayload(signingPayload(manifest), "sign");
+  return manifest;
+}
+
+/**
+ * @primitive b.backupManifest.signBytes
+ * @signature b.backupManifest.signBytes(canonicalBytes)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.backupManifest.verifyBytes, b.backupManifest.sign, b.auditSign.sign
+ *
+ * Sign caller-supplied canonical bytes with the framework's audit-sign keypair,
+ * returning a detached signature block — the schema-agnostic counterpart of
+ * `sign()`. Where `sign()` is bound to the v1 manifest schema (it `validate()`s
+ * the whole `{ version, framework, files[] }` shape before signing), this signs
+ * any bytes a consumer canonicalizes itself, so a bespoke backup-header /
+ * manifest format reuses the same post-quantum signing keypair + fingerprint
+ * pinning without adopting the framework schema.
+ *
+ * `canonicalBytes` is a Buffer (signed verbatim) or a string (signed as UTF-8).
+ * Returns `{ algorithm, publicKey, fingerprint, value, signedAt }`. Requires
+ * `b.auditSign.init()` (throws `backup-manifest/no-signer` otherwise).
+ *
+ * @example
+ *   var sig = b.backupManifest.signBytes(myCanonicalHeaderBuffer);
+ *   // store sig alongside the header; later:
+ *   var v = b.backupManifest.verifyBytes(myCanonicalHeaderBuffer, sig,
+ *     { expectedFingerprint: b.auditSign.getPublicKeyFingerprint() });
+ *   // v.ok === true
+ */
+function signBytes(canonicalBytes) {
+  if (typeof canonicalBytes !== "string" && !Buffer.isBuffer(canonicalBytes)) {
+    throw new BackupManifestError("backup-manifest/bad-input",
+      "signBytes: canonicalBytes must be a string or Buffer");
+  }
+  return _signPayload(canonicalBytes, "signBytes");
+}
+
+// Verify a previously-signed manifest. Returns { ok, reason?,
+// fingerprint? }. Caller policy decides whether a missing or
+// fingerprint-mismatched signature is fatal — verifyManifestSignature
+// in lib/backup/index.js wraps this with operator-facing semantics.
+/**
+ * @primitive b.backupManifest.verifySignature
+ * @signature b.backupManifest.verifySignature(manifest, opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.backupManifest.sign, b.backupManifest.verifyBytes
+ *
+ * Verify a signed v1 backup manifest's detached `signature` block over its
+ * canonical bytes. Returns `{ ok, reason?, fingerprint? }` — never throws — so
+ * a caller decides whether a missing / mismatched signature is fatal. Pass
+ * `opts.expectedFingerprint` to pin the active audit-sign key and refuse a
+ * manifest signed under a different (rotated) key. For a schema-agnostic
+ * alternative see `verifyBytes`.
+ *
+ * @opts
+ *   expectedFingerprint: string,   // refuse a manifest whose fingerprint differs
+ *
+ * @example
+ *   var v = b.backupManifest.verifySignature(manifest,
+ *     { expectedFingerprint: b.auditSign.getPublicKeyFingerprint() });
+ *   if (!v.ok) throw new Error("untrusted backup: " + v.reason);
+ */
+function verifySignature(manifest, opts) {
+  if (!manifest || typeof manifest !== "object") {
+    return { ok: false, reason: "manifest must be an object" };
+  }
+  if (!manifest.signature || typeof manifest.signature !== "object") {
+    return { ok: false, reason: "manifest has no signature block" };
+  }
+  return _verifyPayloadAgainstBlock(signingPayload(manifest), manifest.signature, opts);
+}
+
+/**
+ * @primitive b.backupManifest.verifyBytes
+ * @signature b.backupManifest.verifyBytes(canonicalBytes, signatureBlock, opts?)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.backupManifest.signBytes, b.backupManifest.verifySignature
+ *
+ * Verify caller-supplied canonical bytes against a detached signature block
+ * produced by `signBytes()` — the schema-agnostic counterpart of
+ * `verifySignature()`. Returns `{ ok, reason?, fingerprint? }`. Pass
+ * `opts.expectedFingerprint` to pin the active audit-sign key and refuse a
+ * block signed under a different (rotated / historical) key. Falls back to
+ * `node:crypto.verify` when audit-sign isn't initialized, so a downstream
+ * verifier process can check a signature without holding the signing key.
+ *
+ * @opts
+ *   expectedFingerprint: string,   // refuse a block whose fingerprint differs
+ *
+ * @example
+ *   var v = b.backupManifest.verifyBytes(headerBytes, sigBlock,
+ *     { expectedFingerprint: trustedFingerprint });
+ *   if (!v.ok) throw new Error("untrusted header: " + v.reason);
+ */
+function verifyBytes(canonicalBytes, signatureBlock, opts) {
+  if (typeof canonicalBytes !== "string" && !Buffer.isBuffer(canonicalBytes)) {
+    return { ok: false, reason: "verifyBytes: canonicalBytes must be a string or Buffer" };
+  }
+  return _verifyPayloadAgainstBlock(canonicalBytes, signatureBlock, opts);
 }
 
 function parse(jsonStr) {
@@ -440,8 +585,10 @@ module.exports = {
   serialize:            serialize,
   parse:                parse,
   sign:                 sign,
+  signBytes:            signBytes,
   signingPayload:       signingPayload,
   verifySignature:      verifySignature,
+  verifyBytes:          verifyBytes,
   FORMAT_VERSION:       FORMAT_VERSION,
   FRAMEWORK_NAME:       FRAMEWORK_NAME,
   VALID_KINDS:          VALID_KINDS,