@blamejs/blamejs-shop 0.0.44

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

@@ -0,0 +1,265 @@
+"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 nodeFs = require("node:fs");
+var nodePath = require("node:path");
+var atomicFile = require("../atomic-file");
+var bCrypto = 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(nodePath.sep).join("/");
+  return "files/" + posix + ".enc";
+}
+
+async function create(opts) {
+  var t0 = Date.now();
+  opts = opts || {};
+  if (typeof opts.dataDir !== "string" || !nodeFs.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 (nodeFs.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(nodePath.join(outDir, "files"));
+
+  // 1. Encrypt the vault key JSON
+  _emit(progress, { phase: "wrap_vault_key" });
+  var wrappedVk = await bCrypto.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 = nodePath.join(dataDir, entry.relativePath);
+    if (!nodeFs.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 = nodeFs.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 });
+    // CodeQL js/file-system-race defense — open + fstat + readSync binds
+    // every byte we encrypt to the inode statSync just measured. The
+    // earlier required-vs-skip branch above (existsSync → continue when
+    // not entry.required) is honored before we reach this point; the
+    // dest path is then computed from entry.relativePath, not srcPath.
+    var plain;
+    var srcFd = nodeFs.openSync(srcPath, "r");
+    try {
+      var srcStat = nodeFs.fstatSync(srcFd);
+      plain = Buffer.alloc(srcStat.size);
+      var read = 0;
+      while (read < srcStat.size) {
+        var n = nodeFs.readSync(srcFd, plain, read, srcStat.size - read, null);
+        if (n === 0) break;
+        read += n;
+      }
+      if (read !== srcStat.size) {
+        throw new BackupBundleError("backup-bundle/short-read",
+          "create: short read on '" + entry.relativePath + "': " + read + " of " + srcStat.size + " bytes");
+      }
+    } finally {
+      try { nodeFs.closeSync(srcFd); } catch (_c) { /* close best-effort */ }
+    }
+    var checksum = bCrypto.checksum(plain);
+    var encResult = await bCrypto.encryptWithFreshSalt(plain, passphrase);
+    var encPath = _encryptedPathFor(entry.relativePath);
+    var destFull = nodePath.join(outDir, encPath);
+    atomicFile.ensureDir(nodePath.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,
+  });
+  // Sign the manifest with the audit-sign keypair so a tampered
+  // manifest fails verification on restore. The signer is best-
+  // effort: callers running outside an audit-sign-initialized process
+  // (CLI tooling, ad-hoc bundlers) can pass `opts.sign: false` to
+  // emit an unsigned bundle. Default ON to match the rest of the
+  // framework's signed-by-default posture.
+  var shouldSign = opts.sign !== false;
+  if (shouldSign) {
+    try { backupManifest.sign(manifest); }
+    catch (e) {
+      var msg = (e && e.message) || String(e);
+      // auditSign.init() not awaited yet — emit unsigned bundle. Callers
+      // running outside the framework's boot sequence (CLI tooling,
+      // ad-hoc bundlers, primitive smoke tests) can finish without a
+      // signed manifest; restore-side `requireSignature: true` opt
+      // refuses any unsigned manifest.
+      if (msg.indexOf("auditSign.init() must be awaited") !== -1) {
+        _emit(progress, { phase: "manifest-unsigned", reason: "audit-sign-not-initialized" });
+      } else if (opts.signOptional === true) {
+        _emit(progress, { phase: "manifest-unsigned", reason: msg });
+      } else {
+        throw new BackupBundleError("backup-bundle/sign-failed",
+          "create: manifest sign failed: " + msg);
+      }
+    }
+  }
+  var manifestPath = nodePath.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,
+};

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

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * backup-crypto — passphrase-based symmetric crypto for backup files.
+ *
+ * The primitive layer used by lib/backup.js and the backup/restore
+ * workers. Argon2id key derivation + XChaCha20-Poly1305 AEAD. Salt is
+ * managed alongside the ciphertext so backups carry their KDF input
+ * with them — restoring a backup needs the bundle's salt + the
+ * operator passphrase, nothing else.
+ *
+ *   var bc = b.backupCrypto;
+ *
+ *   bc.ARGON2_OPTS                      // baseline KDF parameters
+ *
+ *   await bc.deriveKey(passphrase, saltHex)
+ *     → Buffer(32)                      // raw key bytes for AEAD
+ *
+ *   await bc.encryptWithPassphrase(plain, passphrase, saltHex)
+ *     → Buffer (24-byte nonce + ciphertext+tag)
+ *   await bc.decryptWithPassphrase(buf, passphrase, saltHex)
+ *     → Buffer (plaintext)
+ *
+ *   await bc.encryptWithFreshSalt(plain, passphrase)
+ *     → { encrypted: Buffer, salt: hexString }
+ *
+ *   bc.checksum(buf)                    // sha3-512 hex; bundle integrity
+ *
+ * Argon2id parameters match lib/vault-wrap defaults — backup integrity
+ * tracks the framework's at-rest discipline. Operators with stricter
+ * requirements (longer passphrases, higher memoryCost) bypass these
+ * defaults by passing a full Argon2 opts object to deriveKey.
+ *
+ * Algorithm choices are deliberate and locked:
+ *   - KDF:  Argon2id (RFC 9106) — memory-hard, the only KDF the
+ *           framework uses for password-derived keys
+ *   - AEAD: XChaCha20-Poly1305 — 24-byte random nonce per message
+ *           means we never need to track per-passphrase nonce counters
+ *
+ * Operators with non-standard cipher needs build their own primitive;
+ * this one's whole point is "do the framework's PQC-aligned crypto
+ * correctly without per-call decisions".
+ */
+
+var nodeCrypto = require("node:crypto");
+var C = require("../constants");
+var safeBuffer = require("../safe-buffer");
+var { xchacha20poly1305 } = require("../vendor/noble-ciphers.cjs");
+var argon2 = require("../argon2-builtin");
+var { FrameworkError } = require("../framework-error");
+
+class BackupCryptoError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "BackupCryptoError";
+    this.permanent = true;
+    this.isBackupCryptoError = true;
+  }
+}
+
+// Baseline Argon2id parameters. Identical to vault-wrap's defaults so
+// operators see one set of numbers across the framework's password-
+// derivation surfaces. Tuned for: ~64 MiB memory, 3 passes, 4 lanes,
+// 32-byte raw output (matches XChaCha20-Poly1305 key length).
+var ARGON2_OPTS = Object.freeze({
+  type:        2,                       // 2 = argon2id
+  memoryCost:  C.BYTES.kib(64),         // 64 MiB expressed in argon2's KiB units
+  timeCost:    3,
+  parallelism: 4,
+  hashLength:  C.BYTES.bytes(32),       // matches XChaCha20-Poly1305 key length
+  raw:         true,
+});
+
+var SALT_BYTES  = C.BYTES.bytes(32);    // 256 bits — comfortable margin for global uniqueness
+var NONCE_BYTES = C.BYTES.bytes(24);    // XChaCha20 nonce length
+
+function checksum(buf) {
+  if (!Buffer.isBuffer(buf) && typeof buf !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "checksum: argument must be a Buffer or string");
+  }
+  return nodeCrypto.createHash("sha3-512").update(buf).digest("hex");
+}
+
+function _validateSaltHex(saltHex) {
+  if (!safeBuffer.isHex(saltHex) || saltHex.length % 2 !== 0) {
+    throw new BackupCryptoError("backup-crypto/bad-salt",
+      "saltHex must be a non-empty hex string with even length");
+  }
+}
+
+function _validatePassphrase(p) {
+  if (!Buffer.isBuffer(p) && typeof p !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-passphrase",
+      "passphrase must be a Buffer or string");
+  }
+  if (Buffer.isBuffer(p) ? p.length === 0 : p.length === 0) {
+    throw new BackupCryptoError("backup-crypto/bad-passphrase",
+      "passphrase must be non-empty");
+  }
+}
+
+async function deriveKey(passphrase, saltHex, opts) {
+  _validatePassphrase(passphrase);
+  _validateSaltHex(saltHex);
+  var argonOpts = Object.assign({}, ARGON2_OPTS, opts || {}, {
+    salt: Buffer.from(saltHex, "hex"),
+  });
+  var hash = await argon2.hash(passphrase, argonOpts);
+  // Argon2 raw mode returns a Buffer of hashLength bytes. Defensive
+  // length check — better to fail loudly than ship a short key into
+  // XChaCha20 and trip a later cryptic error.
+  if (!Buffer.isBuffer(hash) || hash.length !== ARGON2_OPTS.hashLength) {
+    throw new BackupCryptoError("backup-crypto/derive-failed",
+      "argon2 hash returned unexpected output (expected " + ARGON2_OPTS.hashLength +
+      "-byte Buffer, got " + (hash && hash.length) + ")");
+  }
+  return hash;
+}
+
+async function encryptWithPassphrase(plaintext, passphrase, saltHex) {
+  if (!Buffer.isBuffer(plaintext) && typeof plaintext !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-plaintext",
+      "encryptWithPassphrase: plaintext must be a Buffer or string");
+  }
+  var plainBuf = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, "utf8");
+  var key = await deriveKey(passphrase, saltHex);
+  var nonce = nodeCrypto.randomBytes(NONCE_BYTES);
+  var ct = xchacha20poly1305(new Uint8Array(key), nonce).encrypt(new Uint8Array(plainBuf));
+  return Buffer.concat([nonce, Buffer.from(ct)]);
+}
+
+async function decryptWithPassphrase(encrypted, passphrase, saltHex) {
+  if (!Buffer.isBuffer(encrypted)) {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "decryptWithPassphrase: encrypted must be a Buffer");
+  }
+  if (encrypted.length <= NONCE_BYTES) {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "decryptWithPassphrase: encrypted buffer is too short to contain nonce + tag");
+  }
+  var key = await deriveKey(passphrase, saltHex);
+  var nonce = encrypted.subarray(0, NONCE_BYTES);
+  var ct    = encrypted.subarray(NONCE_BYTES);
+  var plain;
+  try {
+    plain = xchacha20poly1305(new Uint8Array(key), new Uint8Array(nonce))
+      .decrypt(new Uint8Array(ct));
+  } catch (e) {
+    throw new BackupCryptoError("backup-crypto/decrypt-failed",
+      "XChaCha20-Poly1305 decryption failed (wrong passphrase or tampered ciphertext): " +
+      ((e && e.message) || String(e)));
+  }
+  return Buffer.from(plain);
+}
+
+// Convenience for the common "encrypt this with a fresh salt" pattern.
+// Returns the salt as hex so callers can store it alongside the
+// ciphertext in the bundle manifest.
+async function encryptWithFreshSalt(plaintext, passphrase) {
+  var salt = nodeCrypto.randomBytes(SALT_BYTES);
+  var saltHex = salt.toString("hex");
+  var encrypted = await encryptWithPassphrase(plaintext, passphrase, saltHex);
+  return { encrypted: encrypted, salt: saltHex };
+}
+
+module.exports = {
+  deriveKey:             deriveKey,
+  encryptWithPassphrase: encryptWithPassphrase,
+  decryptWithPassphrase: decryptWithPassphrase,
+  encryptWithFreshSalt:  encryptWithFreshSalt,
+  checksum:              checksum,
+  ARGON2_OPTS:           ARGON2_OPTS,
+  SALT_BYTES:            SALT_BYTES,
+  NONCE_BYTES:           NONCE_BYTES,
+  BackupCryptoError:     BackupCryptoError,
+};