@blamejs/core 0.4.1

package/lib/chain-writer.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Chain-writer primitive — race-safe append to a hash-chained log table.
+ *
+ * The framework's audit_log AND consent_log have the same shape:
+ *
+ *   1. Take the next monotonic counter
+ *   2. Compute prevHash from the previous row's rowHash
+ *   3. Seal the logical row via field-crypto (sealedFields → vault.seal,
+ *      derivedHashes computed)
+ *   4. Materialize null entries for every hashable column (so canonicalize
+ *      at write-time and verify-time agree on the key set)
+ *   5. Compute rowHash over the sealed content (excluding chain bookkeeping)
+ *   6. INSERT with prevHash / rowHash / nonce / fencingToken
+ *
+ * audit.js and consent.js previously each carried their own copy of
+ * the chain-write pattern. The duplication produced bugs at the same
+ * architectural points: a chain-fork race had to be fixed in audit
+ * via Mutex, and consent had the same race because the fix hadn't
+ * propagated. Per the framework's "if a task repeats more than once
+ * it should be a primitive" rule, the pattern lives here and every
+ * chain-writer consumer gets the same safety guarantees automatically.
+ *
+ * Each chain-writer instance owns:
+ *   - The table name (validated via sql-safe.assertOneOf at construction)
+ *   - The full column list (for INSERT)
+ *   - The hashable column list (for canonicalization)
+ *   - A Mutex serializing the chain (read-prev → compute-hash → insert)
+ *   - A Once initializing the in-process counter from MAX(monotonicCounter)
+ *
+ * Writes go through the cluster-storage dispatcher so the same chain
+ * definition works in single-node SQLite and cluster-mode external-db.
+ *
+ * Public API:
+ *
+ *   chainWriter.create({
+ *     table:           "audit_log" | "consent_log" | …,
+ *     columnsForInsert: [string],            order matters; INSERT uses this
+ *     hashableColumns:  [string],            for canonicalize null-fill
+ *     validateAction:   function (event)     optional; throws on invalid input
+ *   })
+ *
+ *   writer.append(logical)                   async; returns { rowHash, prevHash, …logical }
+ *   writer._resetForTest()                   re-initializes counter + mutex
+ *
+ * Operators usually don't construct chain-writers directly; audit and
+ * consent each construct one at module load.
+ */
+
+var { generateToken, generateBytes } = require("./crypto");
+var auditChain = require("./audit-chain");
+var cryptoField = require("./crypto-field");
+var cluster = require("./cluster");
+var clusterStorage = require("./cluster-storage");
+var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
+var C = require("./constants");
+var { FrameworkError } = require("./framework-error");
+
+// Allowlist of chain table names. Adding a new chain-backed table
+// (e.g. some future _blamejs_security_log) requires registering it here
+// so an operator can't accidentally point a chain-writer at a non-chain
+// table and corrupt the chain semantics.
+var ALLOWED_CHAIN_TABLES = new Set(["audit_log", "consent_log"]);
+
+var FRAMEWORK_SQL_TIMEOUT_MS = C.TIME.seconds(30);
+
+class ChainWriterError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "ChainWriterError";
+    this.code = code || "chain-writer/invalid";
+    this.isChainWriterError = true;
+  }
+}
+
+function create(opts) {
+  if (!opts || !opts.table || !Array.isArray(opts.columnsForInsert) ||
+      !Array.isArray(opts.hashableColumns)) {
+    throw new ChainWriterError(
+      "create requires { table, columnsForInsert, hashableColumns }",
+      "chain-writer/invalid-config"
+    );
+  }
+  // Validate table name shape AND require it's in the chain-table allowlist.
+  safeSql.validateIdentifier(opts.table);
+  safeSql.assertOneOf(opts.table, ALLOWED_CHAIN_TABLES);
+
+  // Validate every column name against the SQL identifier rules — we
+  // interpolate them into the INSERT SQL.
+  for (var i = 0; i < opts.columnsForInsert.length; i++) {
+    safeSql.validateIdentifier(opts.columnsForInsert[i]);
+  }
+  for (var j = 0; j < opts.hashableColumns.length; j++) {
+    safeSql.validateIdentifier(opts.hashableColumns[j]);
+  }
+
+  var table             = opts.table;
+  var columnsForInsert  = opts.columnsForInsert.slice();
+  var hashableColumns   = opts.hashableColumns.slice();
+  var validateInput     = opts.validateInput || null;
+
+  // Per-chain Mutex serializes the read-prev-tip + compute-hash + insert
+  // sequence. Without serialization, two concurrent awaiting append() calls
+  // would hash against the same prev-tip and produce sibling rows with the
+  // same prevHash — forking the chain.
+  var _chainMutex = new safeAsync.Mutex();
+
+  // Lazy counter primer — first append reads MAX(monotonicCounter) and
+  // increments from there. Once ensures concurrent first-callers share
+  // one in-flight init Promise.
+  var _nextCounter = 1;
+  var _counterInit = null;
+
+  function _ensureCounterInit() {
+    if (!_counterInit) {
+      _counterInit = new safeAsync.Once(async function () {
+        var row = await safeAsync.withTimeout(
+          safeAsync.asyncRetry(function () {
+            return clusterStorage.executeOne(
+              "SELECT MAX(monotonicCounter) AS m FROM " + safeSql.quoteIdentifier(table)
+            );
+          }),
+          FRAMEWORK_SQL_TIMEOUT_MS,
+          { name: table + ".readMaxCounter" }
+        );
+        _nextCounter = (row && row.m ? Number(row.m) : 0) + 1;
+      });
+    }
+    return _counterInit.invoke();
+  }
+
+  async function _readChainTipRow() {
+    return await safeAsync.withTimeout(
+      safeAsync.asyncRetry(function () {
+        return clusterStorage.executeOne(
+          "SELECT rowHash FROM " + safeSql.quoteIdentifier(table) +
+          " ORDER BY monotonicCounter DESC LIMIT 1"
+        );
+      }),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: table + ".readChainTip" }
+    );
+  }
+
+  async function _insertRow(values) {
+    // Build INSERT with quoted identifiers + ? placeholders. cluster-
+    // storage handles dialect-specific placeholder translation.
+    var quoted = columnsForInsert.map(function (c) { return safeSql.quoteIdentifier(c); }).join(", ");
+    var placeholders = columnsForInsert.map(function () { return "?"; }).join(", ");
+    return await safeAsync.withTimeout(
+      clusterStorage.execute(
+        "INSERT INTO " + safeSql.quoteIdentifier(table) +
+        " (" + quoted + ") VALUES (" + placeholders + ")",
+        values
+      ),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: table + ".insertRow" }
+    );
+  }
+
+  async function append(logical) {
+    if (validateInput) validateInput(logical);
+    cluster.requireLeader();
+    await _ensureCounterInit();
+
+    return await _chainMutex.runExclusive(async function () {
+      return await _appendInsideMutex(logical);
+    });
+  }
+
+  async function _appendInsideMutex(logical) {
+    var counter = _nextCounter++;
+    var nowMs   = Date.now();
+    var nonce   = generateBytes(16);
+
+    // Caller-supplied logical row: spread + add framework-managed fields.
+    var fullLogical = Object.assign({}, logical, {
+      _id:               (logical && logical._id) || generateToken(16),
+      recordedAt:        nowMs,
+      monotonicCounter:  counter,
+    });
+
+    // Seal sealed-fields, compute derived hashes
+    var sealed = cryptoField.sealRow(table, fullLogical);
+
+    // Materialize null entries for every hashable column the schema
+    // expects, so canonicalize sees the same key set at write-time and
+    // verify-time. JSON canonicalization distinguishes missing-key
+    // from key:null — must not.
+    for (var hci = 0; hci < hashableColumns.length; hci++) {
+      if (!(hashableColumns[hci] in sealed)) sealed[hashableColumns[hci]] = null;
+    }
+
+    // Compute rowHash over the sealed content fields
+    var tipRow = await _readChainTipRow();
+    var prevHash = tipRow ? tipRow.rowHash : auditChain.ZERO_HASH;
+    var rowHash = auditChain.computeRowHash(prevHash, sealed, nonce);
+
+    sealed.prevHash = prevHash;
+    sealed.rowHash  = rowHash;
+    sealed.nonce    = nonce;
+
+    var fencingToken = cluster.fencingToken();
+    var values = columnsForInsert.map(function (c) {
+      if (c === "fencingToken") return fencingToken;
+      return c in sealed ? sealed[c] : null;
+    });
+    await _insertRow(values);
+
+    return Object.assign({ rowHash: rowHash, prevHash: prevHash }, fullLogical);
+  }
+
+  function _resetForTest() {
+    _chainMutex = new safeAsync.Mutex();
+    _counterInit = null;
+    _nextCounter = 1;
+  }
+
+  return {
+    table:          table,
+    append:         append,
+    _resetForTest:  _resetForTest,
+    // Expose for diagnostic introspection
+    _getMutexForTest: function () { return _chainMutex; },
+  };
+}
+
+module.exports = {
+  create:               create,
+  ChainWriterError:     ChainWriterError,
+  ALLOWED_CHAIN_TABLES: ALLOWED_CHAIN_TABLES,
+  FRAMEWORK_SQL_TIMEOUT_MS: FRAMEWORK_SQL_TIMEOUT_MS,
+};

package/lib/cli-helpers.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * cli-helpers — shared shape for blamejs CLI subcommands AND for
+ * operators writing their own one-shot CLI scripts on top of the
+ * framework.
+ *
+ * Three patterns recur across every CLI command (`migrate`, `seed`,
+ * `audit`, `vault`, `backup`, `api-key`):
+ *
+ *   1. Bootstrap a headless `b.createApp` instance from `--data-dir`,
+ *      operate against vault + DB + audit chain, shut down cleanly.
+ *   2. Report success / error / usage with a consistent
+ *      `blamejs <verb> <sub>: <message>` prefix on stderr + canonical
+ *      exit codes (0 ok, 1 runtime failure, 2 arg error).
+ *   3. Resolve a passphrase from `--<flag>` or an env var, encode to
+ *      the Buffer the underlying crypto primitive needs.
+ *
+ *   var cli = b.cliHelpers;
+ *
+ *   var report = cli.makeReporter(ctx, "blamejs my-tool issue");
+ *   if (!args.flags["data-dir"]) return report.usage(MY_USAGE);
+ *
+ *   var pp = cli.resolvePassphrase(args, ctx, {
+ *     flag:   "passphrase",
+ *     envVar: "MY_TOOL_PASSPHRASE",
+ *   });
+ *   if (!pp) return report.error("--passphrase or MY_TOOL_PASSPHRASE is required", 2);
+ *
+ *   var booted;
+ *   try {
+ *     booted = await cli.bootApp({
+ *       dataDir:   args.flags["data-dir"],
+ *       vaultMode: "wrapped",
+ *       env:       ctx.env,
+ *     });
+ *     // do the op against booted.b.X / booted.app.db / etc.
+ *     return report.ok("done");
+ *   } catch (e) {
+ *     return report.error(e.message);
+ *   } finally {
+ *     if (booted) await booted.app.shutdown();
+ *   }
+ *
+ * The reporter writes through whichever stream `ctx.stdout` / `ctx.stderr`
+ * point at — `process.stdout` / `process.stderr` in production, captured
+ * stream stubs in tests — so the same handler is testable without
+ * spawning a child process.
+ */
+
+var validateOpts = require("./validate-opts");
+
+// ---- Streams + exit-code-shaped reporting --------------------------------
+
+function _writeLine(stream, line) {
+  if (!stream || typeof stream.write !== "function") return;
+  if (line == null) return;
+  stream.write(String(line) + "\n");
+}
+
+/**
+ * Make a reporter bound to a CLI context + a verb prefix. Every
+ * stderr message produced by .error / .usage gets the prefix.
+ *
+ *   var report = cliHelpers.makeReporter(ctx, "blamejs vault seal");
+ *   return report.ok("sealed: " + path);   // stdout, returns 0
+ *   return report.error("decrypt failed"); // stderr "blamejs vault seal: decrypt failed", returns 1
+ *   return report.error("missing arg", 2); // returns 2 (arg error vs runtime)
+ *   return report.usage(VAULT_USAGE);      // stderr USAGE, returns 2
+ *   return report.helpStdout(VAULT_USAGE); // stdout USAGE, returns 0 (for `help <verb>`)
+ */
+function makeReporter(ctx, prefix) {
+  if (!ctx || typeof ctx !== "object") {
+    throw new Error("cliHelpers.makeReporter: ctx is required");
+  }
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new Error("cliHelpers.makeReporter: prefix is required (non-empty string)");
+  }
+  var stdout = ctx.stdout || (typeof process !== "undefined" ? process.stdout : null);
+  var stderr = ctx.stderr || (typeof process !== "undefined" ? process.stderr : null);
+  return {
+    ok: function (message) {
+      if (message != null) _writeLine(stdout, message);
+      return 0;
+    },
+    error: function (message, exitCode) {
+      _writeLine(stderr, prefix + ": " + message);
+      return typeof exitCode === "number" ? exitCode : 1;
+    },
+    usage: function (usageText) {
+      _writeLine(stderr, usageText);
+      return 2;
+    },
+    helpStdout: function (usageText) {
+      _writeLine(stdout, usageText);
+      return 0;
+    },
+    // Direct access for handlers that have multi-line output.
+    write:    function (line) { _writeLine(stdout, line); },
+    writeErr: function (line) { _writeLine(stderr, line); },
+  };
+}
+
+// ---- Passphrase resolution -----------------------------------------------
+
+/**
+ * Resolve a passphrase from a flag or env var into a UTF-8 Buffer
+ * (the shape the underlying crypto primitives accept).
+ *
+ *   cli.resolvePassphrase(args, ctx, { flag: "passphrase", envVar: "BLAMEJS_VAULT_PASSPHRASE" })
+ *     → Buffer | null
+ *
+ * Returns `null` when neither source produced a non-empty string. The
+ * caller decides whether absence is a hard error (vault seal) or a
+ * soft default (operator chose plaintext-mode).
+ */
+function resolvePassphrase(args, ctx, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["flag", "envVar"], "cliHelpers.resolvePassphrase");
+  if (typeof opts.flag !== "string" || opts.flag.length === 0) {
+    throw new Error("cliHelpers.resolvePassphrase: opts.flag is required");
+  }
+  var raw = null;
+  if (args && args.flags && typeof args.flags[opts.flag] === "string" &&
+      args.flags[opts.flag].length > 0) {
+    raw = args.flags[opts.flag];
+  } else if (opts.envVar && ctx && ctx.env &&
+             typeof ctx.env[opts.envVar] === "string" &&
+             ctx.env[opts.envVar].length > 0) {
+    raw = ctx.env[opts.envVar];
+  }
+  if (raw == null) return null;
+  return Buffer.from(raw, "utf8");
+}
+
+// ---- Headless app bootstrap ----------------------------------------------
+
+/**
+ * Boot a serverless `b.createApp` instance from a data dir so a CLI
+ * script (the framework's own subcommands or operator-written tools)
+ * can operate against the same vault + DB + audit chain the live app
+ * uses, without standing up an HTTP listener.
+ *
+ *   var booted = await cli.bootApp({
+ *     dataDir:   "./data",
+ *     vaultMode: "wrapped",   // or "plaintext"; default "wrapped"
+ *     env:       process.env, // BLAMEJS_VAULT_PASSPHRASE read from here
+ *   });
+ *   // booted.b — the framework module
+ *   // booted.app — the headless app instance (call .shutdown() to clean up)
+ *
+ * Caller MUST call `await booted.app.shutdown()` in a `finally` so the
+ * SQLite file handles + cluster lease release. The default DB at-rest
+ * mode is `plain` because CLI runs are short-lived ops that never
+ * serve requests; the encrypted-at-rest mode needs a tmpfs handle that
+ * wouldn't survive the CLI exit anyway. Operators running against a
+ * production data dir whose DB is encrypted-at-rest set
+ * `dbAtRest: "encrypted"` and ensure `BLAMEJS_TMPDIR` is set.
+ */
+async function bootApp(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["dataDir", "vaultMode", "dbAtRest", "env"], "cliHelpers.bootApp");
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new Error("cliHelpers.bootApp: opts.dataDir is required");
+  }
+  var vaultMode = opts.vaultMode || "wrapped";
+  if (vaultMode !== "wrapped" && vaultMode !== "plaintext") {
+    throw new Error("cliHelpers.bootApp: opts.vaultMode must be 'wrapped' or 'plaintext'");
+  }
+  var env = opts.env || (typeof process !== "undefined" ? process.env : {});
+
+  var vaultPassphrase = null;
+  if (vaultMode === "wrapped") {
+    var raw = env && env.BLAMEJS_VAULT_PASSPHRASE;
+    if (typeof raw !== "string" || raw.length === 0) {
+      throw new Error("cliHelpers.bootApp: BLAMEJS_VAULT_PASSPHRASE is required " +
+        "for vault mode 'wrapped' (pass vaultMode: 'plaintext' for a dev data dir)");
+    }
+    vaultPassphrase = Buffer.from(raw, "utf8");
+  }
+
+  // Late require so this module stays loadable in contexts that aren't
+  // the framework root (tests, operator-side scripts importing only
+  // cli-helpers).
+  var b = require("../");
+  var app = await b.createApp({
+    dataDir: opts.dataDir,
+    routes:  function () {},
+    vault:   { mode: vaultMode, passphrase: vaultPassphrase },
+    db:      {
+      atRest:       opts.dbAtRest || "plain",
+      auditSigning: { mode: "plaintext" },
+    },
+  });
+  return { b: b, app: app };
+}
+
+module.exports = {
+  makeReporter:       makeReporter,
+  resolvePassphrase:  resolvePassphrase,
+  bootApp:            bootApp,
+};