@blamejs/blamejs-shop 0.4.56 → 0.4.57

package/lib/vendor/blamejs/lib/session.js

@@ -48,6 +48,7 @@
  */
 var audit = require("./audit");
 var canonicalJson = require("./canonical-json");
+var validateOpts = require("./validate-opts");
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
@@ -149,6 +150,38 @@ function _sessionSqlTable() { return frameworkSchema.tableName(SESSION_TABLE); }
 // dispatch; this controls only the builder-side quoting + idiom selection.
 function _sessionSqlOpts() { return { dialect: clusterStorage.dialect() }; }
 
+// Per-subject valid-from boundary table. A monotonic epoch (ms) the issuer
+// bumps to invalidate every STATELESS self-validating token (sealed cookie
+// with no DB row, JWT) minted before the bump: log-out-everywhere, a
+// right-to-erasure cutoff, a forced re-auth after a credential change. Token
+// readers compare the token's iat against this boundary via check(). Same
+// dual-storage shape as _blamejs_sessions — registered in both db.js's
+// FRAMEWORK_SCHEMA (single-node SQLite) and framework-schema.js (cluster
+// external-db); clusterStorage.execute routes by cluster mode. The subject id
+// is hashed before it becomes the PRIMARY KEY, so the plaintext id never lands
+// in the table (the same sidHash / userIdHash discipline the sessions table
+// follows).
+var VALID_FROM_TABLE = "_blamejs_session_valid_from";   // allow:hand-rolled-sql — canonical logical table-name + reserved schema name
+var VALID_FROM_SUBJECT_NAMESPACE = "bj-session-valid-from-subject:";
+function _validFromSqlTable() { return frameworkSchema.tableName(VALID_FROM_TABLE); }
+function _hashSubjectId(subjectId) { return sha3Hash(VALID_FROM_SUBJECT_NAMESPACE + subjectId); }
+
+// Dialect-aware conflict-row references for the monotonic-max upsert in
+// bump(). Mirrors rate-limit.js's pattern: the proposed row is EXCLUDED
+// (Postgres/SQLite) / VALUES() (MySQL); the existing row is a self-reference.
+function _validFromConflictRefs(dialect, table) {
+  if (dialect === "mysql") {
+    return {
+      proposed: function (col) { return "VALUES(`" + col + "`)"; },
+      existing: function (col) { return "`" + table + "`.`" + col + "`"; },
+    };
+  }
+  return {
+    proposed: function (col) { return "EXCLUDED.\"" + col + "\""; },
+    existing: function (col) { return "\"" + table + "\".\"" + col + "\""; },
+  };
+}
+
 // Column order used for INSERT — kept as a constant so the placeholders
 // list and the values list stay in sync. Must match the session table's
 // schema in db.js (single-node) and framework-schema.js (cluster mode).
@@ -825,6 +858,10 @@ async function destroyAllForUser(userId) {
     .whereIn("userIdHash", userHashes)
     .toSql();
   var result = await _currentStore().execute(built.sql, built.params);
+  // Also raise the stateless valid-from boundary so a "logout everywhere"
+  // revokes the operator's stateless tokens (sealed cookies / JWTs checked via
+  // b.session.check) too, not only the store-backed rows just deleted.
+  await bump(userId);
   return result.rowCount || 0;
 }
 
@@ -1272,12 +1309,8 @@ function useStore(store) {
     _store = null;
     return;
   }
-  if (typeof store !== "object" ||
-      typeof store.execute    !== "function" ||
-      typeof store.executeOne !== "function") {
-    throw _err("INVALID_ARG",
-      "session.useStore: store must expose execute(sql,params) and executeOne(sql,params)", true);
-  }
+  validateOpts.requireMethods(store, ["execute", "executeOne"],
+    "session.useStore: store", SessionError, "INVALID_ARG", true);
   _store = store;
 }
 
@@ -1304,6 +1337,158 @@ function isAnonymous(userId) {
   return _isAnonymousUserId(userId);
 }
 
+/**
+ * @primitive b.session.bump
+ * @signature b.session.bump(subjectId, opts?)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.check, b.session.validFrom, b.session.destroyAllForUser
+ *
+ * Revoke every STATELESS self-validating token (sealed cookie carrying no DB
+ * row, JWT) for a subject by raising a durable per-subject valid-from boundary
+ * to now. Any token whose issued-at (`iat`) predates the boundary fails
+ * `b.session.check`. Unlike `destroyAllForUser` — which deletes server-side
+ * session rows — this revokes tokens the framework never stored a row for:
+ * log-out-everywhere, a right-to-erasure cutoff, a forced re-auth after a
+ * password / key change. `destroyAllForUser` calls this for you, so a single
+ * "logout everywhere" covers both store-backed and stateless tokens.
+ *
+ * The boundary is MONOTONIC: it only ever moves forward. A bump to an
+ * `epochMs` at or below the stored value is a no-op — a replayed or
+ * clock-skewed lower value can never widen a revoked window back open. Returns
+ * the boundary in effect after the call. Leader-only. The subject id is stored
+ * hashed; the plaintext id never lands in the table.
+ *
+ * @opts
+ *   epochMs:  number,   // boundary to set; default Date.now(). Tokens with iat < this are revoked.
+ *
+ * @example
+ *   // Force re-auth everywhere for a subject after a password change:
+ *   var boundary = await b.session.bump("user-42");
+ *   // Cut off at a specific instant (right-to-erasure effective time):
+ *   await b.session.bump("user-42", { epochMs: erasureEffectiveMs });
+ */
+async function bump(subjectId, opts) {
+  cluster.requireLeader();
+  if (typeof subjectId !== "string" || subjectId.length === 0) {
+    throw _err("INVALID_ARG", "session.bump requires a non-empty subjectId", true);
+  }
+  opts = opts || {};
+  var epochMs = opts.epochMs === undefined ? Date.now() : opts.epochMs;
+  if (typeof epochMs !== "number" || !isFinite(epochMs) || epochMs < 0) {
+    throw _err("INVALID_ARG",
+      "session.bump: epochMs must be a non-negative finite number, got " + JSON.stringify(epochMs), true);
+  }
+  var subjectHash = _hashSubjectId(subjectId);
+  var t = _validFromSqlTable();
+  var dialect = clusterStorage.dialect();
+  var refs = _validFromConflictRefs(dialect, t);
+
+  // Monotonic-max conflict action: keep the LATER of the proposed and the
+  // stored boundary, so a lower (replayed / clock-skewed) epoch can never move
+  // the boundary backwards and re-open a revoked window.
+  var validFromExpr = "CASE WHEN " + refs.proposed("validFromEpoch") + " > " +
+    refs.existing("validFromEpoch") + " THEN " + refs.proposed("validFromEpoch") +
+    " ELSE " + refs.existing("validFromEpoch") + " END";
+  var built = sql.upsert(t, _sessionSqlOpts())
+    .columns(["subjectHash", "validFromEpoch", "updatedAt"])
+    .values({ subjectHash: subjectHash, validFromEpoch: epochMs, updatedAt: Date.now() })
+    .onConflict(["subjectHash"])
+    .doUpdate({ validFromEpoch: validFromExpr, updatedAt: "?" }, [Date.now()])
+    .returning(["validFromEpoch"])
+    .toSql();
+  // The valid-from boundary is a FRAMEWORK table (FRAMEWORK_SCHEMA / cluster
+  // DDL), NOT session data — it must execute against clusterStorage (the
+  // framework db), never _currentStore(): a pluggable session-data store
+  // (b.session.useStore / localDbThin) does not provision this table, so
+  // routing the bump through it throws "no such table".
+  var row;
+  if (built.readbackSql) {
+    // MySQL: ON DUPLICATE KEY UPDATE has no RETURNING — run the upsert, then
+    // the readback SELECT b.sql emits (keyed on subjectHash).
+    await clusterStorage.execute(built.sql, built.params);
+    var readback = await clusterStorage.execute(built.readbackSql.sql, built.readbackSql.params);
+    row = readback.rows && readback.rows[0];
+  } else {
+    var result = await clusterStorage.execute(built.sql, built.params);
+    row = result.rows && result.rows[0];
+  }
+  var effective = row ? Number(row.validFromEpoch) : epochMs;
+
+  // Best-effort audit — matches the file's emit convention (safeEmit is
+  // already drop-silent internally).
+  try {
+    audit.safeEmit({
+      action:   "auth.session.valid_from_bump",
+      outcome:  "success",
+      metadata: { validFromEpoch: effective },
+    });
+  } catch (_ignored) { /* audit best-effort */ }
+
+  return effective;
+}
+
+/**
+ * @primitive b.session.validFrom
+ * @signature b.session.validFrom(subjectId)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.bump, b.session.check
+ *
+ * Read the current valid-from boundary (epoch ms) for a subject. Returns `0`
+ * when the subject has never been bumped — no token is revoked by boundary, so
+ * any non-negative token `iat` passes `b.session.check`. Runs anywhere (leader
+ * or follower) — it only reads. The subject id is hashed before lookup; the
+ * plaintext id never lands in the table.
+ *
+ * @example
+ *   var boundary = await b.session.validFrom("user-42");
+ *   // → 1735689600000  (last bump)   or   0  (never bumped)
+ */
+async function validFrom(subjectId) {
+  if (typeof subjectId !== "string" || subjectId.length === 0) return 0;
+  var built = sql.select(_validFromSqlTable(), _sessionSqlOpts())
+    .columns(["validFromEpoch"])
+    .where("subjectHash", _hashSubjectId(subjectId))
+    .toSql();
+  // Framework valid-from table — read from clusterStorage (the framework db),
+  // not _currentStore(), so a pluggable session-data store cannot divert it (it
+  // does not provision this table). See bump() for the full rationale.
+  var row = await clusterStorage.executeOne(built.sql, built.params);
+  return row ? Number(row.validFromEpoch) : 0;
+}
+
+/**
+ * @primitive b.session.check
+ * @signature b.session.check(subjectId, tokenIatMs)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.bump, b.session.validFrom
+ *
+ * Decide whether a stateless self-validating token is still valid against the
+ * subject's valid-from boundary. Returns `true` when the token's issued-at
+ * (`tokenIatMs`, epoch ms) is at or after the boundary; `false` when the token
+ * was issued before the last `bump` (revoked). A subject that was never bumped
+ * has boundary `0`, so any non-negative `iat` is valid. Runs anywhere.
+ *
+ * Fails CLOSED: a non-finite / negative / non-number `tokenIatMs` returns
+ * `false` (treat an unparseable token as revoked rather than admit it). Call
+ * this AFTER the token's own signature + expiry checks pass — it is the
+ * server-side revocation layer those stateless checks otherwise lack.
+ *
+ * @example
+ *   // jwt already signature- and exp-verified; iat is in seconds → ms:
+ *   var ok = await b.session.check(claims.sub, claims.iat * 1000);
+ *   if (!ok) { res.statusCode = 401; res.end("session revoked"); return; }
+ */
+async function check(subjectId, tokenIatMs) {
+  if (typeof tokenIatMs !== "number" || !isFinite(tokenIatMs) || tokenIatMs < 0) {
+    return false;
+  }
+  var boundary = await validFrom(subjectId);
+  return tokenIatMs >= boundary;
+}
+
 module.exports = {
   create:               create,
   verify:               verify,
@@ -1315,6 +1500,9 @@ module.exports = {
   updateData:           updateData,
   purgeExpired:         purgeExpired,
   count:                count,
+  bump:                 bump,
+  validFrom:            validFrom,
+  check:                check,
   useStore:             useStore,
   isAnonymous:          isAnonymous,
   stores:               require("./session-stores"),                                              // allow:inline-require — session-stores depends on local-db-thin which requires audit lazily; eager require is fine here

package/lib/vendor/blamejs/lib/sql.js

@@ -1107,39 +1107,11 @@ function _checkRawFragment(sql, params, opts, where) {
 // comments are skipped. Single linear pass, no backtracking regex. Same
 // shape as db-query.js's scanner.
 function _assertRawNoStringLiteral(sql, where) {
-  var i = 0;
-  var len = sql.length;
-  while (i < len) {
-    var ch = sql.charAt(i);
-    var next = i + 1 < len ? sql.charAt(i + 1) : "";
-    if (ch === '"') {
-      i += 1;
-      while (i < len) {
-        if (sql.charAt(i) === '"') {
-          if (sql.charAt(i + 1) === '"') { i += 2; continue; }
-          i += 1; break;
-        }
-        i += 1;
-      }
-      continue;
-    }
-    if (ch === "-" && next === "-") {
-      while (i < len && sql.charAt(i) !== "\n") i += 1;
-      continue;
-    }
-    if (ch === "/" && next === "*") {
-      i += 2;
-      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
-      i += 2;
-      continue;
-    }
-    if (ch === "'") {
-      throw _err(where + ": raw SQL must not contain a string literal ('...') - bind " +
-        "every value with a ? placeholder, or pass { allowLiterals: true } when the " +
-        "literal is static and operator-controlled", "sql-builder/raw-literal");
-    }
-    i += 1;
-  }
+  safeSql.assertNoRawStringLiteral(sql, where, function (w) {
+    return _err(w + ": raw SQL must not contain a string literal ('...') - bind " +
+      "every value with a ? placeholder, or pass { allowLiterals: true } when the " +
+      "literal is static and operator-controlled", "sql-builder/raw-literal");
+  });
 }
 
 // Refuse the two-char Postgres JSONB key-existence tokens (?| / ?&) in a raw
@@ -1188,51 +1160,10 @@ function _assertNoRawJsonbKeyOp(sql, where) {
 var _countPlaceholders = safeSql.countPlaceholders;
 
 // Translate the builder's `?` placeholders to a dialect's positional form
-// (Postgres `$1..$N`; SQLite / MySQL keep `?`). Quote / comment-aware single
-// pass - a `?` inside a string literal, a quoted identifier, or a comment is
-// NOT a placeholder and is left untouched. This is the toExternalSql terminal
-// for code that hands the SQL to an operator-supplied driver directly (no
-// clusterStorage in the path to do the rewrite). The translator lives here -
-// the builder owns its driver-final output rendering - rather than reaching
-// into clusterStorage (which transitively requires this module).
-function _toPositional(sql, dialect) {
-  if (dialect !== "postgres") return sql;
-  var out = "";
-  var n = 0;
-  var i = 0;
-  var len = sql.length;
-  while (i < len) {
-    var c = sql.charAt(i);
-    var nx = i + 1 < len ? sql.charAt(i + 1) : "";
-    if (c === "'" || c === '"' || c === "`") {
-      out += c;
-      i += 1;
-      while (i < len) {
-        var q = sql.charAt(i);
-        if (q === c) {
-          if (sql.charAt(i + 1) === c) { out += c + c; i += 2; continue; }
-          out += c; i += 1; break;
-        }
-        out += q; i += 1;
-      }
-      continue;
-    }
-    if (c === "-" && nx === "-") {
-      while (i < len && sql.charAt(i) !== "\n") { out += sql.charAt(i); i += 1; }
-      continue;
-    }
-    if (c === "/" && nx === "*") {
-      out += "/*"; i += 2;
-      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) { out += sql.charAt(i); i += 1; }
-      if (i < len) { out += "*/"; i += 2; }
-      continue;
-    }
-    if (c === "?") { n += 1; out += "$" + n; i += 1; continue; }
-    out += c;
-    i += 1;
-  }
-  return out;
-}
+// (Postgres `$1..$N`; SQLite / MySQL keep `?`); composed from safe-sql so the
+// quote / comment / backtick skip rules live in one place. The toExternalSql
+// terminal for code that hands the SQL to an operator-supplied driver directly.
+var _toPositional = safeSql.toPositional;
 
 /**
  * @primitive  b.sql.toExternalSql
@@ -1922,6 +1853,163 @@ class InsertBuilder extends Builder {
   }
 }
 
+// ---- INSERT ... SELECT ... WHERE (conditional / append-only) --------
+//
+// A conditional INSERT that materialises its row from a value-less SELECT
+// guarded by a WHERE - INSERT INTO t (cols) SELECT <cells> WHERE <guard>.
+// The append-only-ledger debit idiom: the new row is written ONLY when a
+// guard derived from the table itself holds (a store-credit / gift-card /
+// points / metered-quota balance that lives on the latest row, with no
+// mutable counter row to increment()). The SELECT has no FROM - it is a
+// single computed row that the WHERE either admits (one row inserted) or
+// rejects (zero rows), evaluated atomically inside the INSERT against the
+// table the guard's correlated subquery / EXISTS references, so two racing
+// debits cannot both pass the balance check.
+//
+// Standard-SQL across sqlite / Postgres / MySQL - the only dialect-divergent
+// clause is RETURNING (Postgres / SQLite; refused on MySQL by the shared
+// _renderReturning, which the MySQL caller replaces with an explicit read).
+// Every SELECT cell routes through the SAME _renderValueCell choke-point
+// INSERT VALUES uses (so a cell is a bound ?, a b.sql.cast(...) ?::type, or a
+// b.sql.fn(...) allowlisted server function - no param), and the guard is a
+// full Predicate (the whole where-family: whereExists / whereSub / whereOp /
+// whereRaw / whereGroup compose, which is how a balance fence is expressed).
+//
+// Safety default: an INSERT...SELECT with no WHERE is just an INSERT...VALUES
+// and shipping it un-guarded is almost always a bug, so the verb THROWS
+// without a where() unless allowNoWhere() opts in - the same discipline
+// update / delete apply.
+class InsertSelectWhereBuilder extends Builder {
+  constructor(tableNameOrRef, opts) {
+    super("insert-select-where", tableNameOrRef, opts);
+    this._columns = null;
+    this._values = null;          // single row, aligned to _columns
+    this._where = new Predicate(this, "AND");
+    this._returning = null;
+    this._allowNoWhere = false;
+  }
+
+  // Declare the target column list (validated + gated). values() infers it
+  // from a row object's keys when omitted, exactly like INSERT.
+  columns(cols) {
+    if (!Array.isArray(cols) || cols.length === 0) {
+      throw _err("columns() expects a non-empty array", "sql-builder/bad-columns");
+    }
+    var self = this;
+    cols.forEach(function (c) { self._assertColumnMember(c, "insertSelectWhere"); _validateColumn(c); });
+    this._columns = cols.slice();
+    return this;
+  }
+
+  // values(obj) - one row from a column->value map (sets _columns from the
+  // keys when not already declared). values(array) - one positional row
+  // aligned to a prior columns() call. A single row only: the SELECT
+  // materialises exactly one candidate row gated by the WHERE.
+  values(rowOrArray) {
+    if (Array.isArray(rowOrArray)) {
+      if (this._columns === null) {
+        throw _err("values(array) requires a prior columns([...]) call", "sql-builder/no-columns");
+      }
+      if (rowOrArray.length !== this._columns.length) {
+        throw _err("values(array): " + rowOrArray.length + " values but " +
+          this._columns.length + " columns", "sql-builder/value-count");
+      }
+      this._values = rowOrArray.slice();
+      return this;
+    }
+    if (rowOrArray && typeof rowOrArray === "object") {
+      var keys = Object.keys(rowOrArray);
+      if (keys.length === 0) throw _err("insertSelectWhere row object is empty", "sql-builder/empty-values");
+      if (this._columns === null) this.columns(keys);
+      var self = this;
+      this._values = this._columns.map(function (c) {
+        if (!Object.prototype.hasOwnProperty.call(rowOrArray, c)) {
+          throw _err("insertSelectWhere row is missing column '" + c + "'", "sql-builder/missing-column");
+        }
+        return rowOrArray[c];
+      });
+      keys.forEach(function (k) {
+        if (self._columns.indexOf(k) === -1) {
+          throw _err("insertSelectWhere row has column '" + k + "' not in the column set",
+            "sql-builder/extra-column");
+        }
+      });
+      return this;
+    }
+    throw _err("insertSelectWhere values() requires a row object or a value array aligned to columns()",
+      "sql-builder/bad-values");
+  }
+
+  // A deliberate un-guarded conditional insert opts in here - same shape as
+  // update / delete. Without it the verb refuses an empty WHERE.
+  allowNoWhere() { this._allowNoWhere = true; return this; }
+
+  where() { this._where.where.apply(this._where, arguments); return this; }
+  andWhere() { this._where.andWhere.apply(this._where, arguments); return this; }
+  orWhere() { this._where.orWhere.apply(this._where, arguments); return this; }
+  whereOp(col, op, value) { this._where.whereOp(col, op, value); return this; }
+  orWhereOp(col, op, value) { this._where.orWhereOp(col, op, value); return this; }
+  whereIn(col, values) { this._where.whereIn(col, values); return this; }
+  whereNotIn(col, values) { this._where.whereNotIn(col, values); return this; }
+  orWhereIn(col, values) { this._where.orWhereIn(col, values); return this; }
+  whereInArray(col, values) { this._where.whereInArray(col, values); return this; }
+  orWhereInArray(col, values) { this._where.orWhereInArray(col, values); return this; }
+  whereInJsonEach(col, jsonArrayString) { this._where.whereInJsonEach(col, jsonArrayString); return this; }
+  whereMatch(target, expr) { this._where.whereMatch(target, expr); return this; }
+  whereNull(col) { this._where.whereNull(col); return this; }
+  whereNotNull(col) { this._where.whereNotNull(col); return this; }
+  orWhereNull(col) { this._where.orWhereNull(col); return this; }
+  whereLike(col, term, mode) { this._where.whereLike(col, term, mode); return this; }
+  orWhereLike(col, term, mode) { this._where.orWhereLike(col, term, mode); return this; }
+  whereBetween(col, low, high) { this._where.whereBetween(col, low, high); return this; }
+  whereSub(col, op, sub) { this._where.whereSub(col, op, sub); return this; }
+  whereExists(sub) { this._where.whereExists(sub); return this; }
+  whereNotExists(sub) { this._where.whereNotExists(sub); return this; }
+  orWhereExists(sub) { this._where.orWhereExists(sub); return this; }
+  whereGroup(closure) { this._where.whereGroup(closure); return this; }
+  orWhereGroup(closure) { this._where.orWhereGroup(closure); return this; }
+  whereRaw(sql, params, opts) { this._where.whereRaw(sql, params, opts); return this; }
+  orWhereRaw(sql, params, opts) { this._where.orWhereRaw(sql, params, opts); return this; }
+
+  returning(cols) { this._returning = _normReturning(cols); return this; }
+
+  _render() {
+    if (this._columns === null || this._values === null) {
+      throw _err("insertSelectWhere requires columns + a values() row", "sql-builder/empty-values");
+    }
+    if (this._where.length === 0 && !this._allowNoWhere) {
+      throw _err("refusing unconditional insertSelectWhere - call where(...) first or " +
+        "allowNoWhere() (an un-guarded INSERT...SELECT is just INSERT...VALUES)",
+        "sql-builder/no-where");
+    }
+    var dialect = this._dialect;
+    var params = [];
+    var quotedCols = this._columns.map(function (c) { return _quoteId(c, dialect); }).join(", ");
+
+    // Each SELECT cell renders through the same choke-point INSERT VALUES
+    // uses: `?` (bound), `?::type` (cast), or an allowlisted server-function
+    // token (NOW() / CURRENT_TIMESTAMP - no param).
+    var cells = [];
+    for (var v = 0; v < this._values.length; v += 1) {
+      var rendered = _renderValueCell(this._values[v], dialect);
+      cells.push(rendered.sql);
+      for (var rp = 0; rp < rendered.params.length; rp += 1) params.push(rendered.params[rp]);
+    }
+
+    var sql = "INSERT INTO " + this._table.ref(dialect) + " (" + quotedCols + ") SELECT " +
+      cells.join(", ");
+
+    var w = this._where.build();
+    if (w.sql) {
+      sql += " WHERE " + w.sql;
+      for (var wi = 0; wi < w.params.length; wi += 1) params.push(w.params[wi]);
+    }
+
+    sql += _renderReturning(this._returning, dialect);
+    return _emit(sql, params);
+  }
+}
+
 // ---- UPDATE ---------------------------------------------------------
 
 class UpdateBuilder extends Builder {
@@ -3699,6 +3787,64 @@ function select(tableNameOrRef, opts) { return new SelectBuilder(tableNameOrRef,
  */
 function insert(tableNameOrRef, opts) { return new InsertBuilder(tableNameOrRef, opts); }
 
+/**
+ * @primitive  b.sql.insertSelectWhere
+ * @signature  b.sql.insertSelectWhere(table, opts?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.sql.insert, b.sql.upsert, b.sql.update
+ *
+ * Start a conditional `INSERT ... SELECT ... WHERE` builder - a row written
+ * ONLY when a guard derived from the table itself holds. Emits
+ * `INSERT INTO t (cols) SELECT <cells> WHERE <guard>`: the value-less SELECT
+ * is a single computed candidate row the WHERE either admits (one row
+ * inserted) or rejects (zero rows). It is the race-free append-only-ledger
+ * debit - a store-credit / gift-card / wallet / points / metered-quota /
+ * seat-counter balance that lives only on the latest row, with no mutable
+ * counter row to `increment()`. The guard's correlated subquery / `EXISTS`
+ * is evaluated atomically inside the INSERT, so two concurrent debits cannot
+ * both pass the same balance check.
+ *
+ * Supply the row via `columns([...])` + `values([...])` (positional),
+ * `values({ ... })` (one row object, inferring the column list from its
+ * keys), then the guard via the full `where` family (`whereExists` /
+ * `whereSub` / `whereOp` / `whereGroup` / `whereRaw` all compose - the
+ * balance fence is typically an `EXISTS` against the same table). Each SELECT
+ * cell routes through the same choke-point INSERT `values()` uses, so a cell
+ * may be a bound `?`, a `b.sql.cast(...)` (`?::type`), or a `b.sql.fn(...)`
+ * allowlisted server function (`NOW()`, no param). Standard SQL across sqlite
+ * / Postgres / MySQL; only `RETURNING` diverges (Postgres / SQLite - refused
+ * on MySQL, run an explicit read).
+ *
+ * Safety default: an INSERT...SELECT with no WHERE is just an
+ * INSERT...VALUES, so the verb THROWS without a `where()` unless
+ * `allowNoWhere()` opts in - the same discipline `update` / `delete` apply.
+ *
+ * @opts
+ *   dialect:         string,   // postgres | sqlite | mysql (default sqlite)
+ *   schema:          string,   // schema qualifier
+ *   prefix:          string,   // operator app-table namespace prefix
+ *   allowedColumns:  array,    // column-membership gate set
+ *
+ * @example
+ *   // Append a -25 debit ONLY if the wallet's balance row still covers it -
+ *   // a race-free conditional insert with no read-modify-write. The guard is
+ *   // an EXISTS over a same-dialect sub-builder (no raw statement verb).
+ *   var covered = b.sql.select("wallet", { dialect: "postgres" })
+ *     .selectRaw("1")
+ *     .whereRaw('"id" = ? AND "balance" >= ?', ["w-1", 25]);
+ *   b.sql.insertSelectWhere("wallet_ledger", { dialect: "postgres" })
+ *     .values({ wallet_id: "w-1", amount: -25, at: b.sql.fn("NOW") })
+ *     .whereExists(covered)
+ *     .returning(["id"])
+ *     .toSql();
+ *   // -> { sql: 'INSERT INTO wallet_ledger ("wallet_id", "amount", "at") ' +
+ *   //          'SELECT ?, ?, NOW() WHERE EXISTS (SELECT 1 FROM wallet ' +
+ *   //          'WHERE ("id" = ? AND "balance" >= ?)) RETURNING "id"',
+ *   //     params: ["w-1", -25, "w-1", 25] }
+ */
+function insertSelectWhere(tableNameOrRef, opts) { return new InsertSelectWhereBuilder(tableNameOrRef, opts); }
+
 /**
  * @primitive  b.sql.update
  * @signature  b.sql.update(table, opts?)
@@ -3806,6 +3952,7 @@ module.exports = {
   // Verbs
   select:        select,
   insert:        insert,
+  insertSelectWhere: insertSelectWhere,
   update:        update,
   delete:        del,
   upsert:        upsert,

package/lib/vendor/blamejs/lib/sse.js

@@ -76,6 +76,8 @@
 
 var C = require("./constants");
 var audit = require("./audit");
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
 var { SseError } = require("./framework-error");
 
 // Per W3C SSE — the wire format uses LF as terminator. A single LF
@@ -228,10 +230,8 @@ function _readLastEventId(req) {
 function create(req, res, opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || SseError;
-  if (!res || typeof res.write !== "function" || typeof res.end !== "function") {
-    throw errorClass.factory("sse/bad-res",
-      "sse.create: res must be a writable response stream");
-  }
+  validateOpts.requireMethods(res, ["write", "end"],
+    "sse.create: res (writable response stream)", errorClass, "sse/bad-res");
   var heartbeatMs = opts.heartbeatMs;
   if (heartbeatMs === undefined) heartbeatMs = C.TIME.seconds(15);
   if (typeof heartbeatMs !== "number" || !isFinite(heartbeatMs) ||
@@ -255,12 +255,8 @@ function create(req, res, opts) {
   // never affected. Config-time input → throw on a bad value.
   var maxBufferedBytes = opts.maxBufferedBytes;
   if (maxBufferedBytes === undefined) maxBufferedBytes = C.BYTES.mib(1);
-  if (typeof maxBufferedBytes !== "number" || !isFinite(maxBufferedBytes) ||
-      maxBufferedBytes <= 0 || Math.floor(maxBufferedBytes) !== maxBufferedBytes) {
-    throw errorClass.factory("sse/bad-opts",
-      "sse.create: maxBufferedBytes must be a positive integer byte count (got " +
-      JSON.stringify(maxBufferedBytes) + ")");
-  }
+  numericBounds.requirePositiveFiniteInt(maxBufferedBytes,
+    "sse.create: maxBufferedBytes", errorClass, "sse/bad-opts");
 
   var lastEventId = _readLastEventId(req);