@blamejs/core 0.8.43 → 0.8.49

package/lib/backup/manifest.js

@@ -69,10 +69,16 @@
  */
 
 var C = require("../constants");
+var lazyRequire = require("../lazy-require");
 var safeBuffer = require("../safe-buffer");
 var safeJson = require("../safe-json");
 var { FrameworkError } = require("../framework-error");
 
+// audit-sign is loaded lazily — manifest.js is consumed by both the
+// backup writer (which has audit-sign initialized) and read-only
+// inspectors (CLI / verifier) where audit-sign may not be wired.
+var auditSign = lazyRequire(function () { return require("../audit-sign"); });
+
 class BackupManifestError extends FrameworkError {
   constructor(code, message) {
     super(message, code);
@@ -189,6 +195,31 @@ function validate(manifest) {
       (manifest.metadata === null || typeof manifest.metadata !== "object" || Array.isArray(manifest.metadata))) {
     errors.push("metadata: must be a plain object when present");
   }
+  // Optional signature block. When present, every sub-field is
+  // required — partial signatures are a smell (operators saw an
+  // unsigned bundle and tried to hand-edit a signature in).
+  if (manifest.signature !== undefined) {
+    if (manifest.signature === null || typeof manifest.signature !== "object" ||
+        Array.isArray(manifest.signature)) {
+      errors.push("signature: must be a plain object when present");
+    } else {
+      if (typeof manifest.signature.algorithm !== "string" || manifest.signature.algorithm.length === 0) {
+        errors.push("signature.algorithm: required non-empty string");
+      }
+      if (typeof manifest.signature.publicKey !== "string" || manifest.signature.publicKey.length === 0) {
+        errors.push("signature.publicKey: required non-empty string");
+      }
+      if (typeof manifest.signature.fingerprint !== "string" || manifest.signature.fingerprint.length === 0) {
+        errors.push("signature.fingerprint: required non-empty string");
+      }
+      if (!_isBase64(manifest.signature.value)) {
+        errors.push("signature.value: required base64 string");
+      }
+      if (!_isIso8601(manifest.signature.signedAt)) {
+        errors.push("signature.signedAt: required ISO-8601 timestamp string");
+      }
+    }
+  }
   return { ok: errors.length === 0, errors: errors };
 }
 
@@ -216,12 +247,7 @@ function create(opts) {
   return manifest;
 }
 
-function serialize(manifest) {
-  var v = validate(manifest);
-  if (!v.ok) {
-    throw new BackupManifestError("backup-manifest/invalid",
-      "serialize: " + v.errors.join("; "));
-  }
+function _canonical(manifest, includeSignature) {
   // Stable key ordering so the same manifest object always serializes
   // to the same bytes (operators can hash the manifest as part of
   // bundle-integrity logging without surprises across runs).
@@ -245,7 +271,139 @@ function serialize(manifest) {
     }),
   };
   if (manifest.metadata) canonical.metadata = manifest.metadata;
-  return JSON.stringify(canonical, null, 2) + "\n";
+  // Signature block lives alongside the rest of the manifest fields
+  // and is itself stable-ordered. Sign-time canonicalization (the
+  // bytes the audit-sign keypair signs) excludes the signature field
+  // so the signature can be appended without altering the signed
+  // payload.
+  if (includeSignature && manifest.signature) {
+    canonical.signature = {
+      algorithm:   manifest.signature.algorithm,
+      publicKey:   manifest.signature.publicKey,
+      fingerprint: manifest.signature.fingerprint,
+      value:       manifest.signature.value,
+      signedAt:    manifest.signature.signedAt,
+    };
+  }
+  return canonical;
+}
+
+// The canonical payload the audit-sign keypair signs over — the
+// manifest serialized without its `signature` field. Exposed so
+// verifiers can recompute the exact bytes that produced the signature.
+function signingPayload(manifest) {
+  return JSON.stringify(_canonical(manifest, false), null, 2) + "\n";
+}
+
+function serialize(manifest) {
+  var v = validate(manifest);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "serialize: " + v.errors.join("; "));
+  }
+  return JSON.stringify(_canonical(manifest, true), null, 2) + "\n";
+}
+
+// Sign the manifest in-place via the audit-sign keypair (ML-DSA-87
+// 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("; "));
+  }
+  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");
+  }
+  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)));
+  }
+  manifest.signature = {
+    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) {
+  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" };
+  }
+  var sig = manifest.signature;
+  if (typeof sig.algorithm !== "string" || sig.algorithm.length === 0) {
+    return { ok: false, reason: "signature.algorithm is required" };
+  }
+  if (typeof sig.publicKey !== "string" || sig.publicKey.length === 0) {
+    return { ok: false, reason: "signature.publicKey is required" };
+  }
+  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,
+    };
+  }
+  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.
+  var ok;
+  try {
+    var signer = auditSign();
+    if (signer && typeof signer.verify === "function") {
+      ok = signer.verify(payload, sigBuf, sig.publicKey);
+    } else {
+      ok = require("node:crypto").verify(null,
+        Buffer.from(payload, "utf8"), sig.publicKey, sigBuf);
+    }
+  } catch (e) {
+    return {
+      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,
+    };
+  }
+  return { ok: true, fingerprint: sig.fingerprint };
 }
 
 function parse(jsonStr) {
@@ -275,6 +433,9 @@ module.exports = {
   validate:             validate,
   serialize:            serialize,
   parse:                parse,
+  sign:                 sign,
+  signingPayload:       signingPayload,
+  verifySignature:      verifySignature,
   FORMAT_VERSION:       FORMAT_VERSION,
   FRAMEWORK_NAME:       FRAMEWORK_NAME,
   VALID_KINDS:          VALID_KINDS,