@blamejs/core 0.7.18 → 0.7.20

package/lib/backup/bundle.js

@@ -1,217 +1,217 @@
-"use strict";
-/**
- * backup-bundle — produce an encrypted backup bundle on disk.
- *
- * Given a dataDir + file include list + passphrase, walks each file,
- * encrypts its bytes via backup-crypto, computes a sha3-512 checksum
- * of the plaintext, and emits a bundle directory:
- *
- *   <outDir>/manifest.json     — backup-manifest schema
- *   <outDir>/files/<path>.enc  — per-file encrypted blob
- *
- * Where <path> mirrors the file's relativePath under dataDir (subdirs
- * preserved). The manifest is the only authoritative description of
- * the bundle's contents — a restorer reads it first, then streams
- * each blob into staging.
- *
- *   await b.backupBundle.create({
- *     dataDir:      "./data",
- *     outDir:       "./backups/2026-04-27.bundle",  // must NOT exist
- *     passphrase:   Buffer.from("operator passphrase"),
- *     vaultKeyJson: "<vault.key contents>",           // string; encrypted into manifest
- *     files: [
- *       { relativePath: "db.enc",         kind: "raw",          required: true },
- *       { relativePath: "db.key.enc",     kind: "raw",          required: true },
- *       { relativePath: "vault.key",      kind: "raw",          required: false },
- *       { relativePath: "ca.key.sealed",  kind: "vault-sealed", required: false },
- *     ],
- *     metadata:     { reason: "scheduled-daily" },
- *     progressCallback: function (event) { ... },
- *   });
- *   // → { manifest, manifestPath, outDir, bundleSize, fileCount, durationMs }
- *
- * vaultKeyJson is encrypted with the operator passphrase + a fresh
- * salt and stored in the manifest's vaultKeyEnc. With only the
- * passphrase, a restorer on a different machine can recover the
- * framework's vault keypair and unseal the bundle's vault-sealed
- * files post-restore. Without the passphrase, the bundle is opaque.
- *
- * Per-file salts: each file gets its own fresh salt. Argon2id is
- * memory-hard but per-file fresh-salt means an attacker who recovers
- * one file's key from the passphrase has no leverage on other files
- * — the salt rotation forces the full Argon2 computation per file.
- *
- * The bundler does NOT compress files. Operators with large datasets
- * who want compression run their backup pipeline through their own
- * compressor (gzip, zstd) downstream of the framework primitive.
- */
-
-var fs = require("fs");
-var path = require("path");
-var atomicFile = require("../atomic-file");
-var backupCrypto = require("./crypto");
-var backupManifest = require("./manifest");
-var validateOpts = require("../validate-opts");
-var { defineClass } = require("../framework-error");
-
-var BackupBundleError = defineClass("BackupBundleError", { alwaysPermanent: true });
-
-function _emit(cb, ev) {
-  if (typeof cb === "function") {
-    try { cb(ev); } catch (_e) { /* progress-callback errors are non-fatal */ }
-  }
-}
-
-// Map relativePath → encryptedPath inside the bundle. Mirrors the
-// directory structure under files/ and appends .enc so every blob
-// has a clear stride and isn't confused with the source file.
-function _encryptedPathFor(relativePath) {
-  // POSIX-normalize separators in the bundle so manifests written on
-  // Windows and Linux look the same on disk.
-  var posix = relativePath.split(path.sep).join("/");
-  return "files/" + posix + ".enc";
-}
-
-async function create(opts) {
-  var t0 = Date.now();
-  opts = opts || {};
-  if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
-    throw new BackupBundleError("backup-bundle/no-datadir",
-      "create: opts.dataDir is required and must exist");
-  }
-  validateOpts.requireNonEmptyString(opts.outDir, "create: opts.outDir", BackupBundleError, "backup-bundle/no-outdir");
-  if (fs.existsSync(opts.outDir)) {
-    throw new BackupBundleError("backup-bundle/outdir-exists",
-      "create: outDir already exists: " + opts.outDir +
-      " (refusing to overwrite — pick a fresh path)");
-  }
-  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
-    throw new BackupBundleError("backup-bundle/no-passphrase",
-      "create: opts.passphrase is required (Buffer or string)");
-  }
-  if (typeof opts.vaultKeyJson !== "string" || opts.vaultKeyJson.length === 0) {
-    throw new BackupBundleError("backup-bundle/no-vault-key-json",
-      "create: opts.vaultKeyJson is required (the in-memory vault keypair JSON; " +
-      "use vault.getKeysJson() or read vault.key from disk)");
-  }
-  if (!Array.isArray(opts.files) || opts.files.length === 0) {
-    throw new BackupBundleError("backup-bundle/no-files",
-      "create: opts.files must be a non-empty array of include entries");
-  }
-  var passphrase = opts.passphrase;
-  var dataDir = opts.dataDir;
-  var outDir = opts.outDir;
-  var progress = opts.progressCallback;
-
-  atomicFile.ensureDir(outDir);
-  atomicFile.ensureDir(path.join(outDir, "files"));
-
-  // 1. Encrypt the vault key JSON
-  _emit(progress, { phase: "wrap_vault_key" });
-  var wrappedVk = await backupCrypto.encryptWithFreshSalt(opts.vaultKeyJson, passphrase);
-
-  // 2. Walk each include entry, encrypt the bytes, emit a blob
-  var fileEntries = [];
-  var totalBytes = 0;
-
-  for (var i = 0; i < opts.files.length; i++) {
-    var entry = opts.files[i];
-    if (!entry || typeof entry.relativePath !== "string" || entry.relativePath.length === 0) {
-      throw new BackupBundleError("backup-bundle/bad-include",
-        "create: files[" + i + "] requires { relativePath: string }");
-    }
-    if (entry.relativePath.indexOf("..") !== -1 || /^[/\\]/.test(entry.relativePath)) {
-      throw new BackupBundleError("backup-bundle/bad-include",
-        "create: files[" + i + "].relativePath must be a relative path (got '" + entry.relativePath + "')");
-    }
-    var srcPath = path.join(dataDir, entry.relativePath);
-    if (!fs.existsSync(srcPath)) {
-      if (entry.required) {
-        throw new BackupBundleError("backup-bundle/missing-required",
-          "create: required file missing: " + entry.relativePath);
-      }
-      _emit(progress, { phase: "skip_missing", relativePath: entry.relativePath });
-      continue;
-    }
-    var stat = fs.statSync(srcPath);
-    if (!stat.isFile()) {
-      // Directories aren't supported in this slice — the bundler
-      // operates on a flat list of files. Operator wanting a recursive
-      // sweep walks the dir themselves and passes the resulting list.
-      throw new BackupBundleError("backup-bundle/not-a-file",
-        "create: '" + entry.relativePath + "' is not a regular file");
-    }
-
-    _emit(progress, { phase: "read", relativePath: entry.relativePath, size: stat.size });
-    var plain = fs.readFileSync(srcPath);
-    var checksum = backupCrypto.checksum(plain);
-    var encResult = await backupCrypto.encryptWithFreshSalt(plain, passphrase);
-    var encPath = _encryptedPathFor(entry.relativePath);
-    var destFull = path.join(outDir, encPath);
-    atomicFile.ensureDir(path.dirname(destFull));
-    atomicFile.writeSync(destFull, encResult.encrypted, { fileMode: 0o600 });
-
-    var kind = entry.kind || "raw";
-    if (!backupManifest.VALID_KINDS[kind]) {
-      throw new BackupBundleError("backup-bundle/bad-kind",
-        "create: files[" + i + "].kind must be one of raw, vault-sealed, plaintext (got '" + kind + "')");
-    }
-
-    fileEntries.push({
-      relativePath:  entry.relativePath,
-      encryptedPath: encPath,
-      size:          plain.length,
-      encryptedSize: encResult.encrypted.length,
-      checksum:      checksum,
-      salt:          encResult.salt,
-      kind:          kind,
-    });
-    totalBytes += encResult.encrypted.length;
-    _emit(progress, {
-      phase: "encrypted",
-      relativePath: entry.relativePath,
-      encryptedSize: encResult.encrypted.length,
-    });
-  }
-
-  if (fileEntries.length === 0) {
-    // Nothing to write; refuse to emit an empty manifest. Operators
-    // who genuinely want an "empty backup" need to revisit their
-    // include list.
-    throw new BackupBundleError("backup-bundle/empty",
-      "create: no files included in bundle (every entry was missing or skipped)");
-  }
-
-  // 3. Build the manifest and write it last (so a half-written bundle
-  // can be detected by absence of manifest.json — an integrity tell)
-  _emit(progress, { phase: "write_manifest" });
-  var manifest = backupManifest.create({
-    vaultKeySalt: wrappedVk.salt,
-    vaultKeyEnc:  wrappedVk.encrypted.toString("base64"),
-    files:        fileEntries,
-    metadata:     opts.metadata || undefined,
-  });
-  var manifestPath = path.join(outDir, "manifest.json");
-  atomicFile.writeSync(manifestPath, backupManifest.serialize(manifest), { fileMode: 0o600 });
-
-  var durationMs = Date.now() - t0;
-  _emit(progress, {
-    phase: "done",
-    fileCount: fileEntries.length,
-    bundleSize: totalBytes,
-    durationMs: durationMs,
-  });
-  return {
-    manifest:     manifest,
-    manifestPath: manifestPath,
-    outDir:       outDir,
-    bundleSize:   totalBytes,
-    fileCount:    fileEntries.length,
-    durationMs:   durationMs,
-  };
-}
-
-module.exports = {
-  create:             create,
-  BackupBundleError:  BackupBundleError,
-};
+"use strict";
+/**
+ * backup-bundle — produce an encrypted backup bundle on disk.
+ *
+ * Given a dataDir + file include list + passphrase, walks each file,
+ * encrypts its bytes via backup-crypto, computes a sha3-512 checksum
+ * of the plaintext, and emits a bundle directory:
+ *
+ *   <outDir>/manifest.json     — backup-manifest schema
+ *   <outDir>/files/<path>.enc  — per-file encrypted blob
+ *
+ * Where <path> mirrors the file's relativePath under dataDir (subdirs
+ * preserved). The manifest is the only authoritative description of
+ * the bundle's contents — a restorer reads it first, then streams
+ * each blob into staging.
+ *
+ *   await b.backupBundle.create({
+ *     dataDir:      "./data",
+ *     outDir:       "./backups/2026-04-27.bundle",  // must NOT exist
+ *     passphrase:   Buffer.from("operator passphrase"),
+ *     vaultKeyJson: "<vault.key contents>",           // string; encrypted into manifest
+ *     files: [
+ *       { relativePath: "db.enc",         kind: "raw",          required: true },
+ *       { relativePath: "db.key.enc",     kind: "raw",          required: true },
+ *       { relativePath: "vault.key",      kind: "raw",          required: false },
+ *       { relativePath: "ca.key.sealed",  kind: "vault-sealed", required: false },
+ *     ],
+ *     metadata:     { reason: "scheduled-daily" },
+ *     progressCallback: function (event) { ... },
+ *   });
+ *   // → { manifest, manifestPath, outDir, bundleSize, fileCount, durationMs }
+ *
+ * vaultKeyJson is encrypted with the operator passphrase + a fresh
+ * salt and stored in the manifest's vaultKeyEnc. With only the
+ * passphrase, a restorer on a different machine can recover the
+ * framework's vault keypair and unseal the bundle's vault-sealed
+ * files post-restore. Without the passphrase, the bundle is opaque.
+ *
+ * Per-file salts: each file gets its own fresh salt. Argon2id is
+ * memory-hard but per-file fresh-salt means an attacker who recovers
+ * one file's key from the passphrase has no leverage on other files
+ * — the salt rotation forces the full Argon2 computation per file.
+ *
+ * The bundler does NOT compress files. Operators with large datasets
+ * who want compression run their backup pipeline through their own
+ * compressor (gzip, zstd) downstream of the framework primitive.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var backupCrypto = require("./crypto");
+var backupManifest = require("./manifest");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var BackupBundleError = defineClass("BackupBundleError", { alwaysPermanent: true });
+
+function _emit(cb, ev) {
+  if (typeof cb === "function") {
+    try { cb(ev); } catch (_e) { /* progress-callback errors are non-fatal */ }
+  }
+}
+
+// Map relativePath → encryptedPath inside the bundle. Mirrors the
+// directory structure under files/ and appends .enc so every blob
+// has a clear stride and isn't confused with the source file.
+function _encryptedPathFor(relativePath) {
+  // POSIX-normalize separators in the bundle so manifests written on
+  // Windows and Linux look the same on disk.
+  var posix = relativePath.split(path.sep).join("/");
+  return "files/" + posix + ".enc";
+}
+
+async function create(opts) {
+  var t0 = Date.now();
+  opts = opts || {};
+  if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
+    throw new BackupBundleError("backup-bundle/no-datadir",
+      "create: opts.dataDir is required and must exist");
+  }
+  validateOpts.requireNonEmptyString(opts.outDir, "create: opts.outDir", BackupBundleError, "backup-bundle/no-outdir");
+  if (fs.existsSync(opts.outDir)) {
+    throw new BackupBundleError("backup-bundle/outdir-exists",
+      "create: outDir already exists: " + opts.outDir +
+      " (refusing to overwrite — pick a fresh path)");
+  }
+  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
+    throw new BackupBundleError("backup-bundle/no-passphrase",
+      "create: opts.passphrase is required (Buffer or string)");
+  }
+  if (typeof opts.vaultKeyJson !== "string" || opts.vaultKeyJson.length === 0) {
+    throw new BackupBundleError("backup-bundle/no-vault-key-json",
+      "create: opts.vaultKeyJson is required (the in-memory vault keypair JSON; " +
+      "use vault.getKeysJson() or read vault.key from disk)");
+  }
+  if (!Array.isArray(opts.files) || opts.files.length === 0) {
+    throw new BackupBundleError("backup-bundle/no-files",
+      "create: opts.files must be a non-empty array of include entries");
+  }
+  var passphrase = opts.passphrase;
+  var dataDir = opts.dataDir;
+  var outDir = opts.outDir;
+  var progress = opts.progressCallback;
+
+  atomicFile.ensureDir(outDir);
+  atomicFile.ensureDir(path.join(outDir, "files"));
+
+  // 1. Encrypt the vault key JSON
+  _emit(progress, { phase: "wrap_vault_key" });
+  var wrappedVk = await backupCrypto.encryptWithFreshSalt(opts.vaultKeyJson, passphrase);
+
+  // 2. Walk each include entry, encrypt the bytes, emit a blob
+  var fileEntries = [];
+  var totalBytes = 0;
+
+  for (var i = 0; i < opts.files.length; i++) {
+    var entry = opts.files[i];
+    if (!entry || typeof entry.relativePath !== "string" || entry.relativePath.length === 0) {
+      throw new BackupBundleError("backup-bundle/bad-include",
+        "create: files[" + i + "] requires { relativePath: string }");
+    }
+    if (entry.relativePath.indexOf("..") !== -1 || /^[/\\]/.test(entry.relativePath)) {
+      throw new BackupBundleError("backup-bundle/bad-include",
+        "create: files[" + i + "].relativePath must be a relative path (got '" + entry.relativePath + "')");
+    }
+    var srcPath = path.join(dataDir, entry.relativePath);
+    if (!fs.existsSync(srcPath)) {
+      if (entry.required) {
+        throw new BackupBundleError("backup-bundle/missing-required",
+          "create: required file missing: " + entry.relativePath);
+      }
+      _emit(progress, { phase: "skip_missing", relativePath: entry.relativePath });
+      continue;
+    }
+    var stat = fs.statSync(srcPath);
+    if (!stat.isFile()) {
+      // Directories aren't supported in this slice — the bundler
+      // operates on a flat list of files. Operator wanting a recursive
+      // sweep walks the dir themselves and passes the resulting list.
+      throw new BackupBundleError("backup-bundle/not-a-file",
+        "create: '" + entry.relativePath + "' is not a regular file");
+    }
+
+    _emit(progress, { phase: "read", relativePath: entry.relativePath, size: stat.size });
+    var plain = fs.readFileSync(srcPath);
+    var checksum = backupCrypto.checksum(plain);
+    var encResult = await backupCrypto.encryptWithFreshSalt(plain, passphrase);
+    var encPath = _encryptedPathFor(entry.relativePath);
+    var destFull = path.join(outDir, encPath);
+    atomicFile.ensureDir(path.dirname(destFull));
+    atomicFile.writeSync(destFull, encResult.encrypted, { fileMode: 0o600 });
+
+    var kind = entry.kind || "raw";
+    if (!backupManifest.VALID_KINDS[kind]) {
+      throw new BackupBundleError("backup-bundle/bad-kind",
+        "create: files[" + i + "].kind must be one of raw, vault-sealed, plaintext (got '" + kind + "')");
+    }
+
+    fileEntries.push({
+      relativePath:  entry.relativePath,
+      encryptedPath: encPath,
+      size:          plain.length,
+      encryptedSize: encResult.encrypted.length,
+      checksum:      checksum,
+      salt:          encResult.salt,
+      kind:          kind,
+    });
+    totalBytes += encResult.encrypted.length;
+    _emit(progress, {
+      phase: "encrypted",
+      relativePath: entry.relativePath,
+      encryptedSize: encResult.encrypted.length,
+    });
+  }
+
+  if (fileEntries.length === 0) {
+    // Nothing to write; refuse to emit an empty manifest. Operators
+    // who genuinely want an "empty backup" need to revisit their
+    // include list.
+    throw new BackupBundleError("backup-bundle/empty",
+      "create: no files included in bundle (every entry was missing or skipped)");
+  }
+
+  // 3. Build the manifest and write it last (so a half-written bundle
+  // can be detected by absence of manifest.json — an integrity tell)
+  _emit(progress, { phase: "write_manifest" });
+  var manifest = backupManifest.create({
+    vaultKeySalt: wrappedVk.salt,
+    vaultKeyEnc:  wrappedVk.encrypted.toString("base64"),
+    files:        fileEntries,
+    metadata:     opts.metadata || undefined,
+  });
+  var manifestPath = path.join(outDir, "manifest.json");
+  atomicFile.writeSync(manifestPath, backupManifest.serialize(manifest), { fileMode: 0o600 });
+
+  var durationMs = Date.now() - t0;
+  _emit(progress, {
+    phase: "done",
+    fileCount: fileEntries.length,
+    bundleSize: totalBytes,
+    durationMs: durationMs,
+  });
+  return {
+    manifest:     manifest,
+    manifestPath: manifestPath,
+    outDir:       outDir,
+    bundleSize:   totalBytes,
+    fileCount:    fileEntries.length,
+    durationMs:   durationMs,
+  };
+}
+
+module.exports = {
+  create:             create,
+  BackupBundleError:  BackupBundleError,
+};