@blamejs/core 0.4.1

package/lib/backup/manifest.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * backup-manifest — schema + validation for backup bundle manifests.
+ *
+ * Every backup bundle the framework produces carries a manifest.json
+ * at its root. The manifest is the single source of truth for: which
+ * files are in the bundle, their plaintext size + checksum, the per-
+ * file salt used by backup-crypto, and the wrapped vault key needed
+ * to interpret vault-sealed file contents post-restore.
+ *
+ * The encrypted file BYTES are stored separately under the bundle's
+ * files/ directory (one file per entry) — the manifest references
+ * them by relativePath. This keeps the manifest small enough to
+ * inspect / log without carrying gigabytes of base64 inline, and lets
+ * a restorer stream-decrypt files one at a time without loading the
+ * whole bundle into memory.
+ *
+ * Manifest format (v1):
+ *
+ *   {
+ *     version:           1,
+ *     createdAt:         "<ISO 8601 string>",
+ *     framework:         "blamejs",
+ *     frameworkVersion:  "0.1.84",
+ *     vaultKeySalt:      "<hex>",         // salt used to wrap vault.key
+ *     vaultKeyEnc:       "<base64>",      // wrapped vault.key bytes
+ *     files: [
+ *       {
+ *         relativePath:    "db.enc",         // operator-facing path under dataDir
+ *         encryptedPath:   "files/db.enc.bin", // path within the bundle
+ *         size:            12345,           // plaintext size in bytes
+ *         checksum:        "<sha3-512 hex>",  // checksum of the PLAINTEXT
+ *         encryptedSize:   12369,           // size of the encrypted blob (bytes)
+ *         salt:            "<hex>",         // per-file Argon2 salt
+ *         kind:            "raw"            // "raw" | "vault-sealed" | "plaintext"
+ *       },
+ *       ...
+ *     ],
+ *     metadata: { ... operator-supplied free-form ... }
+ *   }
+ *
+ * The `kind` field hints at how the post-restore framework should
+ * interpret the file:
+ *   - raw            on-disk binary that the framework reads as-is
+ *                    (db.enc, db.key.enc, etc.)
+ *   - vault-sealed   the file's contents are vault-prefix wrapped
+ *                    (legacy-style sealed PEMs); restore writes them
+ *                    back as-is and the framework unseals at use
+ *   - plaintext      operator content not under vault discipline
+ *                    (config snapshots, README, etc.)
+ *
+ * The kind is informational — the bundler does NOT re-seal or unseal
+ * based on it; backup-crypto encrypts every file's bytes the same
+ * way regardless of kind. Operators / dashboards can use kind for
+ * post-restore validation.
+ *
+ *   var bm = b.backupManifest;
+ *
+ *   var manifest = bm.create({
+ *     vaultKeySalt: "...",
+ *     vaultKeyEnc:  "<base64>",
+ *     files: [...],
+ *     metadata: { reason: "scheduled-daily" },
+ *   });
+ *   var json = bm.serialize(manifest);    // canonical JSON for storage
+ *
+ *   var loaded = bm.parse(json);          // validates on parse, throws on error
+ *   var v = bm.validate(loaded);          // → { ok, errors } without throwing
+ */
+
+var C = require("../constants");
+var { FrameworkError } = require("../framework-error");
+
+class BackupManifestError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "BackupManifestError";
+    this.permanent = true;
+    this.isBackupManifestError = true;
+  }
+}
+
+var FORMAT_VERSION = 1;
+var FRAMEWORK_NAME = "blamejs";
+var VALID_KINDS = { "raw": 1, "vault-sealed": 1, "plaintext": 1 };
+var HEX_RE = /^[0-9a-fA-F]+$/;
+var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+function _isHex(s, evenLength) {
+  if (typeof s !== "string" || s.length === 0) return false;
+  if (!HEX_RE.test(s)) return false;
+  if (evenLength && s.length % 2 !== 0) return false;
+  return true;
+}
+function _isBase64(s) {
+  return typeof s === "string" && s.length > 0 && BASE64_RE.test(s);
+}
+function _isIso8601(s) {
+  if (typeof s !== "string" || s.length === 0) return false;
+  var d = new Date(s);
+  return !isNaN(d.getTime()) && d.toISOString() === s;
+}
+
+function _validateFileEntry(f, idx, errors) {
+  if (!f || typeof f !== "object") {
+    errors.push("files[" + idx + "]: must be an object");
+    return;
+  }
+  if (typeof f.relativePath !== "string" || f.relativePath.length === 0) {
+    errors.push("files[" + idx + "].relativePath: required non-empty string");
+  } else if (f.relativePath.indexOf("..") !== -1 || /^[/\\]/.test(f.relativePath)) {
+    // No traversal — when restored, relativePath joins under dataDir
+    errors.push("files[" + idx + "].relativePath: must be a relative path without '..' or leading separator");
+  }
+  if (typeof f.encryptedPath !== "string" || f.encryptedPath.length === 0) {
+    errors.push("files[" + idx + "].encryptedPath: required non-empty string");
+  } else if (f.encryptedPath.indexOf("..") !== -1 || /^[/\\]/.test(f.encryptedPath)) {
+    errors.push("files[" + idx + "].encryptedPath: must be a relative path without '..' or leading separator");
+  }
+  if (typeof f.size !== "number" || !Number.isInteger(f.size) || f.size < 0) {
+    errors.push("files[" + idx + "].size: required non-negative integer");
+  }
+  if (typeof f.encryptedSize !== "number" || !Number.isInteger(f.encryptedSize) || f.encryptedSize < 0) {
+    errors.push("files[" + idx + "].encryptedSize: required non-negative integer");
+  }
+  if (!_isHex(f.checksum, true) || f.checksum.length !== 128) {
+    errors.push("files[" + idx + "].checksum: required 128-char hex string (sha3-512)");
+  }
+  if (!_isHex(f.salt, true)) {
+    errors.push("files[" + idx + "].salt: required hex string");
+  }
+  if (typeof f.kind !== "string" || !VALID_KINDS[f.kind]) {
+    errors.push("files[" + idx + "].kind: must be one of raw, vault-sealed, plaintext");
+  }
+}
+
+function validate(manifest) {
+  var errors = [];
+  if (!manifest || typeof manifest !== "object") {
+    return { ok: false, errors: ["manifest must be an object"] };
+  }
+  if (manifest.version !== FORMAT_VERSION) {
+    errors.push("version: required " + FORMAT_VERSION + ", got " + manifest.version);
+  }
+  if (manifest.framework !== FRAMEWORK_NAME) {
+    errors.push("framework: required '" + FRAMEWORK_NAME + "', got " + JSON.stringify(manifest.framework));
+  }
+  if (typeof manifest.frameworkVersion !== "string" || manifest.frameworkVersion.length === 0) {
+    errors.push("frameworkVersion: required non-empty string");
+  }
+  if (!_isIso8601(manifest.createdAt)) {
+    errors.push("createdAt: required ISO-8601 timestamp string");
+  }
+  if (!_isHex(manifest.vaultKeySalt, true)) {
+    errors.push("vaultKeySalt: required hex string");
+  }
+  if (!_isBase64(manifest.vaultKeyEnc)) {
+    errors.push("vaultKeyEnc: required base64 string");
+  }
+  if (!Array.isArray(manifest.files)) {
+    errors.push("files: required array");
+  } else {
+    // Detect duplicate relativePath / encryptedPath — would corrupt restore
+    var seenRel = Object.create(null);
+    var seenEnc = Object.create(null);
+    for (var i = 0; i < manifest.files.length; i++) {
+      _validateFileEntry(manifest.files[i], i, errors);
+      var f = manifest.files[i];
+      if (f && typeof f.relativePath === "string") {
+        if (seenRel[f.relativePath]) {
+          errors.push("files[" + i + "].relativePath: duplicate '" + f.relativePath + "'");
+        }
+        seenRel[f.relativePath] = true;
+      }
+      if (f && typeof f.encryptedPath === "string") {
+        if (seenEnc[f.encryptedPath]) {
+          errors.push("files[" + i + "].encryptedPath: duplicate '" + f.encryptedPath + "'");
+        }
+        seenEnc[f.encryptedPath] = true;
+      }
+    }
+  }
+  if (manifest.metadata !== undefined &&
+      (manifest.metadata === null || typeof manifest.metadata !== "object" || Array.isArray(manifest.metadata))) {
+    errors.push("metadata: must be a plain object when present");
+  }
+  return { ok: errors.length === 0, errors: errors };
+}
+
+function create(opts) {
+  opts = opts || {};
+  var manifest = {
+    version:          FORMAT_VERSION,
+    framework:        FRAMEWORK_NAME,
+    frameworkVersion: typeof opts.frameworkVersion === "string" && opts.frameworkVersion.length > 0
+      ? opts.frameworkVersion
+      : (C.version || "0.0.0"),
+    createdAt:        opts.createdAt || new Date().toISOString(),
+    vaultKeySalt:     opts.vaultKeySalt,
+    vaultKeyEnc:      opts.vaultKeyEnc,
+    files:            Array.isArray(opts.files) ? opts.files.slice() : [],
+  };
+  if (opts.metadata && typeof opts.metadata === "object" && !Array.isArray(opts.metadata)) {
+    manifest.metadata = Object.assign({}, opts.metadata);
+  }
+  var v = validate(manifest);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "create: " + v.errors.join("; "));
+  }
+  return manifest;
+}
+
+function serialize(manifest) {
+  var v = validate(manifest);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "serialize: " + v.errors.join("; "));
+  }
+  // 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).
+  var canonical = {
+    version:          manifest.version,
+    framework:        manifest.framework,
+    frameworkVersion: manifest.frameworkVersion,
+    createdAt:        manifest.createdAt,
+    vaultKeySalt:     manifest.vaultKeySalt,
+    vaultKeyEnc:      manifest.vaultKeyEnc,
+    files:            manifest.files.map(function (f) {
+      return {
+        relativePath:  f.relativePath,
+        encryptedPath: f.encryptedPath,
+        size:          f.size,
+        encryptedSize: f.encryptedSize,
+        checksum:      f.checksum,
+        salt:          f.salt,
+        kind:          f.kind,
+      };
+    }),
+  };
+  if (manifest.metadata) canonical.metadata = manifest.metadata;
+  return JSON.stringify(canonical, null, 2) + "\n";
+}
+
+function parse(jsonStr) {
+  if (typeof jsonStr !== "string" && !Buffer.isBuffer(jsonStr)) {
+    throw new BackupManifestError("backup-manifest/bad-input",
+      "parse: argument must be a string or Buffer");
+  }
+  var s = Buffer.isBuffer(jsonStr) ? jsonStr.toString("utf8") : jsonStr;
+  var obj;
+  try { obj = JSON.parse(s); }
+  catch (e) {
+    throw new BackupManifestError("backup-manifest/bad-json",
+      "parse: not valid JSON: " + ((e && e.message) || String(e)));
+  }
+  var v = validate(obj);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "parse: " + v.errors.join("; "));
+  }
+  return obj;
+}
+
+module.exports = {
+  create:               create,
+  validate:             validate,
+  serialize:            serialize,
+  parse:                parse,
+  FORMAT_VERSION:       FORMAT_VERSION,
+  FRAMEWORK_NAME:       FRAMEWORK_NAME,
+  VALID_KINDS:          VALID_KINDS,
+  BackupManifestError:  BackupManifestError,
+};

package/lib/bundler.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * bundler — content-hashed asset pipeline + manifest.
+ *
+ * What this primitive does today:
+ *   - Reads each named entry from disk
+ *   - Computes a content hash (SHA3-512, first 16 hex chars)
+ *   - Writes the entry to outdir/<name>.<hash>.<ext> for cache-busting
+ *   - Emits manifest.json mapping logical name → hashed filename
+ *   - Optionally watches entries and rebuilds on change
+ *
+ * What it does NOT do today (deliberately deferred):
+ *   - Module-graph resolution (esbuild-style multi-file bundling)
+ *   - Tree shaking, dead-code elimination, AST transforms
+ *   - Source maps
+ *   - Minification (a regex-based pass mishandles comments inside
+ *     string and regex literals; AST-based minification waits for the
+ *     esbuild-wasm vendoring slice)
+ *
+ * Operators with multi-file ESM source either pre-concat manually and
+ * point bundler at the result, or use an external tool today; the
+ * bundler primitive's interface stays stable when full bundling lands.
+ *
+ *   var bundler = b.bundler.create({
+ *     entries:   { app: "./public/js/app.js", styles: "./public/css/app.css" },
+ *     outdir:    "./public/dist",
+ *     manifest:  "manifest.json",   // false to skip; default "manifest.json"
+ *     hashLen:   16,                // hex chars in filename hash (default 16)
+ *     hash:      true,              // include hash in filename; false → name.ext
+ *     cwd:       process.cwd(),
+ *   });
+ *
+ *   var result = await bundler.build();
+ *   //  { outputs: [{ name, entry, path, hash, bytes, ext }], manifestPath, durationMs }
+ *
+ *   bundler.watch(function (rebuild) { ... });    // rebuild on entry change
+ *   await bundler.close();                        // stop watchers
+ *
+ * Manifest format (manifest.json under outdir):
+ *   { "app": "app.4a8c2f1d9e3b7062.js", "styles": "styles.b29f1e7c.css" }
+ *
+ * Integrates with lib/static.js: serve `outdir` as a static directory;
+ * lib/static.js's hashed-path detection sets long-cache headers on
+ * files that look hashed, and integrity() reads the manifest to
+ * generate Subresource Integrity attributes.
+ */
+
+var path = require("path");
+var fs = require("fs");
+var crypto = require("./crypto");
+var atomicFile = require("./atomic-file");
+var { defineClass } = require("./framework-error");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+
+var BundlerError = defineClass("BundlerError", { alwaysPermanent: true });
+
+function _hashContent(buf, hexLen) {
+  // SHA3-512 → take the first hexLen hex chars. Same family as the
+  // framework's other content fingerprints (no SHA-256 for new code).
+  return crypto.sha3Hash(buf).slice(0, hexLen);
+}
+
+function _hashedName(baseName, hash, ext) {
+  return baseName + "." + hash + ext;
+}
+
+// outDir mode is 0o755 (world-readable) because the bundler emits
+// assets a public HTTP server reads. Other framework dirs default to
+// 0o700 via atomicFile.ensureDir.
+function _ensureOutDir(p) {
+  try { atomicFile.ensureDir(p, 0o755); }
+  catch (e) {
+    if (e && e.code !== "EEXIST") {
+      throw new BundlerError("bundler/mkdir-failed",
+        "could not create outdir '" + p + "': " + ((e && e.message) || String(e)));
+    }
+  }
+}
+
+function _validateEntries(entries) {
+  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+    throw new BundlerError("bundler/no-entries",
+      "bundler.create requires opts.entries (a { name: path } map)");
+  }
+  var names = Object.keys(entries);
+  if (names.length === 0) {
+    throw new BundlerError("bundler/no-entries",
+      "bundler.create: opts.entries map must have at least one entry");
+  }
+  // Reject names with path separators or '..' so operator-supplied
+  // logical names can't escape the outdir on write.
+  for (var i = 0; i < names.length; i++) {
+    var n = names[i];
+    if (typeof n !== "string" || n.length === 0 ||
+        /[\\/]/.test(n) || n === ".." || n === ".") {
+      throw new BundlerError("bundler/bad-entry-name",
+        "entry name '" + n + "' must be a non-empty string without path separators");
+    }
+    var p = entries[n];
+    if (typeof p !== "string" || p.length === 0) {
+      throw new BundlerError("bundler/bad-entry-path",
+        "entry '" + n + "' must map to a non-empty source path");
+    }
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "entries", "outdir", "cwd",
+    "manifest", "hash", "hashLen", "graceMs", "log",
+    "_watch", "_setTimeout", "_clearTimeout",
+  ], "b.bundler");
+  _validateEntries(opts.entries);
+  if (typeof opts.outdir !== "string" || opts.outdir.length === 0) {
+    throw new BundlerError("bundler/no-outdir",
+      "bundler.create requires opts.outdir");
+  }
+
+  var entries     = Object.assign({}, opts.entries);
+  var cwd         = opts.cwd || process.cwd();
+  var outdir      = path.isAbsolute(opts.outdir) ? opts.outdir : path.resolve(cwd, opts.outdir);
+  var manifestName = (opts.manifest === false || opts.manifest === null)
+    ? null
+    : (typeof opts.manifest === "string" && opts.manifest.length > 0
+        ? opts.manifest
+        : "manifest.json");
+  var hashOn   = opts.hash !== false;
+  var hashLen  = typeof opts.hashLen === "number" && opts.hashLen >= 4 && opts.hashLen <= 64
+    ? Math.floor(opts.hashLen) : 16;
+  var log      = opts.log || null;
+
+  // Test seam: tests pass a fake watcher so we don't actually fs.watch
+  var watchFn = opts._watch || function (dirOrFile, wopts, listener) {
+    return fs.watch(dirOrFile, wopts, listener);
+  };
+  var setTimeoutFn  = opts._setTimeout  || setTimeout;
+  var clearTimeoutFn = opts._clearTimeout || clearTimeout;
+  var graceMs = typeof opts.graceMs === "number" && opts.graceMs >= 0 ? opts.graceMs : 100;
+
+  var watchers      = [];
+  var debounceTimer = null;
+  var watching      = false;
+
+  function _resolveEntry(p) {
+    return path.isAbsolute(p) ? p : path.resolve(cwd, p);
+  }
+
+  function _logVia(level, message, fields) {
+    if (log && typeof log[level] === "function") {
+      try { log[level](message, fields); } catch (_e) { /* logger best-effort */ }
+      return;
+    }
+    var line = "[blamejs:bundler] " + message + (fields ? " " + JSON.stringify(fields) : "");
+    if (level === "error" || level === "warn" || level === "fatal") console.error(line);
+    else console.log(line);
+  }
+
+  async function build() {
+    var t0 = Date.now();
+    _ensureOutDir(outdir);
+
+    var outputs = [];
+    var manifest = {};
+    var names = Object.keys(entries);
+
+    for (var i = 0; i < names.length; i++) {
+      var name = names[i];
+      var entryPath = _resolveEntry(entries[name]);
+      var ext = path.extname(entryPath);
+      var content;
+      try { content = fs.readFileSync(entryPath); }
+      catch (e) {
+        throw new BundlerError("bundler/read-failed",
+          "could not read entry '" + name + "' at " + entryPath +
+          ": " + ((e && e.message) || String(e)));
+      }
+      var hash = hashOn ? _hashContent(content, hashLen) : null;
+      var outName = hashOn ? _hashedName(name, hash, ext) : (name + ext);
+      var outPath = path.join(outdir, outName);
+      // atomic-file write so a concurrent reader (the http server
+      // serving outdir) never sees a partial file
+      atomicFile.writeSync(outPath, content, { mode: 0o644 });
+      outputs.push({
+        name:  name,
+        entry: entryPath,
+        path:  outPath,
+        hash:  hash,
+        bytes: content.length,
+        ext:   ext,
+      });
+      manifest[name] = outName;
+    }
+
+    var manifestPath = null;
+    if (manifestName) {
+      manifestPath = path.join(outdir, manifestName);
+      atomicFile.writeSync(
+        manifestPath,
+        safeJson.stringify(manifest, null, 2) + "\n",
+        { mode: 0o644 }
+      );
+    }
+
+    var result = {
+      outputs:      outputs,
+      manifestPath: manifestPath,
+      manifest:     manifest,
+      durationMs:   Date.now() - t0,
+    };
+    _logVia("info", "build complete",
+      { entries: outputs.length, durationMs: result.durationMs });
+    return result;
+  }
+
+  function _scheduleRebuild(reason, callback) {
+    if (debounceTimer) {
+      try { clearTimeoutFn(debounceTimer); } catch (_e) {}
+    }
+    debounceTimer = setTimeoutFn(function () {
+      debounceTimer = null;
+      _logVia("info", "rebuilding", { reason: reason });
+      build().then(
+        function (r) { if (callback) try { callback(null, r); } catch (_e) {} },
+        function (e) {
+          _logVia("error", "rebuild failed", { error: (e && e.message) || String(e) });
+          if (callback) try { callback(e, null); } catch (_e) {}
+        }
+      );
+    }, graceMs);
+    if (debounceTimer && typeof debounceTimer.unref === "function") debounceTimer.unref();
+  }
+
+  function watch(callback) {
+    if (watching) return;
+    watching = true;
+    var names = Object.keys(entries);
+    for (var i = 0; i < names.length; i++) {
+      (function (name) {
+        var entryPath = _resolveEntry(entries[name]);
+        // Watch the entry's directory (single-file watches are flaky
+        // across editors that write-then-rename). Filter events to the
+        // entry's basename only.
+        var dir = path.dirname(entryPath);
+        var base = path.basename(entryPath);
+        var w;
+        try {
+          w = watchFn(dir, { persistent: false }, function (eventType, filename) {
+            if (filename && String(filename) === base) {
+              _scheduleRebuild(name, callback);
+            }
+          });
+        } catch (e) {
+          _logVia("warn", "could not watch " + dir,
+            { error: (e && e.message) || String(e) });
+          return;
+        }
+        if (w && typeof w.on === "function") {
+          w.on("error", function (err) {
+            _logVia("warn", "watcher error",
+              { dir: dir, error: (err && err.message) || String(err) });
+          });
+        }
+        watchers.push(w);
+      })(names[i]);
+    }
+  }
+
+  async function close() {
+    watching = false;
+    if (debounceTimer) {
+      try { clearTimeoutFn(debounceTimer); } catch (_e) {}
+      debounceTimer = null;
+    }
+    for (var i = 0; i < watchers.length; i++) {
+      try { if (watchers[i] && typeof watchers[i].close === "function") watchers[i].close(); }
+      catch (_e) { /* close best-effort */ }
+    }
+    watchers = [];
+  }
+
+  return {
+    build:    build,
+    watch:    watch,
+    close:    close,
+    entries:  entries,
+    outdir:   outdir,
+  };
+}
+
+module.exports = {
+  create:        create,
+  BundlerError:  BundlerError,
+};