@blamejs/core 0.15.11 → 0.15.13

package/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/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);
 

package/lib/static.js

@@ -489,84 +489,147 @@ function _httpDate(date) {
 }
 
 function _validateCreateOpts(opts) {
-  validateOpts.requireObject(opts, "staticServe.create", StaticServeError);
-  validateOpts.requireNonEmptyString(opts.root, "staticServe.create: root", StaticServeError, "BAD_OPT");
+  // Declarative per-field validation. shape() runs requireObject(opts)
+  // itself (same "opts must be an object" / BAD_OPT contract the inline
+  // requireObject produced), then dispatches each field. A field whose
+  // check is one of the rule tokens maps to the token directly; a field
+  // with a bespoke message (mountPath / hashedPathPattern), a
+  // duck-typed-handle shape (permissions / cache / fileType / retention /
+  // revokeStore — each carrying its own operator-facing description), a
+  // numeric bound, or an audit/observability shape uses the
+  // validator-function hatch so the exact thrown code + message + label
+  // are preserved. Cross-field business logic (root existence,
+  // allowedFileTypes↔fileType wiring, the contentSafety map, the
+  // mountType enum, the quota↔cache requirement) stays below shape.
+  validateOpts.shape(opts, {
+    root: "required-string",
+    mountPath: function (value, _label, errorClass, code) {
+      // empty string is operator-permissible: "no mount, root is request URL"
+      if (typeof value === "string" && value.length === 0) return;
+      if (value !== undefined && value !== null && typeof value !== "string") {
+        throw errorClass.factory(code, "staticServe.create: mountPath must be a string");
+      }
+    },
+    hashedPathPattern: function (value, _label, errorClass, code) {
+      if (value !== undefined && value !== null && !(value instanceof RegExp)) {
+        throw errorClass.factory(code, "staticServe.create: hashedPathPattern must be a RegExp");
+      }
+    },
+    // indexFile === null is the operator's "disable" sentinel; the helper
+    // returns null/undefined unchanged so we keep that semantic.
+    indexFile: "optional-string",
+    defaultMaxAge: function (value, label, errorClass, code) {
+      numericBounds.requireNonNegativeFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    contentTypes: "optional-plain-object",
+    // contentSafety — extension-keyed gate map. undefined → the framework
+    // wires b.guardAll.byExtension({ profile: "strict" }) so every shipped
+    // guard is ON by default; null is the explicit opt-out (audited at
+    // create() time); a plain { ext: gate } object validates each value is a
+    // gate (a .check fn). The label / code / message match the prior inline
+    // check exactly so a test asserting them still holds.
+    contentSafety: function (value, _label, errorClass, code) {
+      if (value === undefined || value === null) return;
+      validateOpts.optionalPlainObject(value,
+        "staticServe.create: contentSafety", errorClass, code,
+        "must be a plain { ext: gate } object, null to opt out, or " +
+        "undefined for the default-on b.guardAll wiring");
+      var safetyKeys = Object.keys(value);
+      for (var sk = 0; sk < safetyKeys.length; sk++) {
+        var ext = safetyKeys[sk];
+        var g = value[ext];
+        if (!g || typeof g.check !== "function") {
+          throw errorClass.factory(code,
+            "staticServe.create: contentSafety[" + JSON.stringify(ext) +
+            "] must be a gate (b.guardCsv.gate / b.guardHtml.gate / etc.)");
+        }
+      }
+    },
+    permissions: function (value, label, errorClass, code) {
+      validateOpts.optionalObjectWithMethod(value, "check", label, errorClass, code,
+        "must be a b.permissions instance (check fn)");
+    },
+    cache: function (value, label, errorClass, code) {
+      validateOpts.optionalObjectWithMethod(value, "get", label, errorClass, code,
+        "must be a b.cache instance (used for cluster-shared bandwidth + concurrency tracking)");
+    },
+    fileType: function (value, label, errorClass, code) {
+      validateOpts.optionalObjectWithMethod(value, "detect", label, errorClass, code,
+        "must be a b.fileType instance (magic-byte MIME detection)");
+    },
+    retention: function (value, label, errorClass, code) {
+      validateOpts.optionalObjectWithMethod(value, "isServable", label, errorClass, code,
+        "must expose isServable(absPath, ctx) → boolean (compliance retention check)");
+    },
+    revokeStore: function (value, label, errorClass, code) {
+      validateOpts.optionalObjectWithMethod(value, "isRevoked", label, errorClass, code,
+        "must expose isRevoked(key) and revoke(key) for force-revoke support");
+    },
+    allowedFileTypes: "optional-string-array",
+    audit: function (value, _label, errorClass, _code) {
+      validateOpts.auditShape(value, "staticServe.create", errorClass);
+    },
+    observability: function (value, _label, errorClass, _code) {
+      validateOpts.observabilityShape(value, "staticServe.create", errorClass);
+    },
+    onServe: "optional-function",
+    onError: "optional-function",
+    acceptRanges: "optional-boolean",
+    auditSuccess: "optional-boolean",
+    auditFailures: "optional-boolean",
+    safeAttachmentForRiskyMimes: "optional-boolean",
+    forceAttachmentForNonText: "optional-boolean",
+    safeRenderSvg: "optional-boolean",
+    safeRenderPdf: "optional-boolean",
+    maxBytesPerActorPerWindowMs: function (value, label, errorClass, code) {
+      numericBounds.requireNonNegativeFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    maxBytesAllActorsPerWindowMs: function (value, label, errorClass, code) {
+      numericBounds.requireNonNegativeFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    bandwidthWindowMs: function (value, label, errorClass, code) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    maxConcurrentDownloadsPerActor: function (value, label, errorClass, code) {
+      numericBounds.requireNonNegativeFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    maxIdleMs: function (value, label, errorClass, code) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value, label, errorClass, code);
+    },
+    // maxRangeBytes — per-range byte cap (slowloris-range defense). A
+    // positive finite integer caps Range requests; Infinity is the
+    // documented opt-out, so the numericBounds finite-int helpers (which
+    // reject Infinity) can't be used directly here.
+    maxRangeBytes: function (value, label, errorClass, code) {
+      if (value === undefined || value === null || value === Infinity) return;
+      numericBounds.requirePositiveFiniteInt(value, label, errorClass, code);
+    },
+  }, "staticServe.create", StaticServeError, "BAD_OPT", {
+    // contentSafetyDisabledReason (audit-row string) and mountType (curated
+    // | user-content enum) carry dedicated cross-field validation below
+    // shape — the audit reason read and the enum throw whose exact message a
+    // test asserts. Listing them here keeps that bespoke logic the single
+    // validator rather than re-checking the same key inside shape.
+    allow: ["contentSafetyDisabledReason", "mountType"],
+  });
+
   if (!nodeFs.existsSync(opts.root)) {
     throw _err("BAD_OPT", "staticServe.create: root does not exist: " + opts.root);
   }
-  if (typeof opts.mountPath === "string" && opts.mountPath.length === 0) {
-    // empty string is operator-permissible: "no mount, root is request URL"
-  } else if (opts.mountPath !== undefined && opts.mountPath !== null &&
-             typeof opts.mountPath !== "string") {
-    throw _err("BAD_OPT", "staticServe.create: mountPath must be a string");
-  }
-  if (opts.hashedPathPattern !== undefined && opts.hashedPathPattern !== null &&
-      !(opts.hashedPathPattern instanceof RegExp)) {
-    throw _err("BAD_OPT", "staticServe.create: hashedPathPattern must be a RegExp");
-  }
-  // indexFile === null is the operator's "disable" sentinel; the helper
-  // returns null/undefined unchanged so we keep that semantic.
-  validateOpts.optionalNonEmptyString(opts.indexFile,
-    "staticServe.create: indexFile", StaticServeError, "BAD_OPT");
-  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.defaultMaxAge,
-    "staticServe.create: defaultMaxAge", StaticServeError, "BAD_OPT");
-  validateOpts.optionalPlainObject(opts.contentTypes,
-    "staticServe.create: contentTypes", StaticServeError, "BAD_OPT");
-  validateOpts.optionalObjectWithMethod(opts.permissions, "check",
-    "staticServe.create: permissions", StaticServeError, "BAD_OPT",
-    "must be a b.permissions instance (check fn)");
-  validateOpts.optionalObjectWithMethod(opts.cache, "get",
-    "staticServe.create: cache", StaticServeError, "BAD_OPT",
-    "must be a b.cache instance (used for cluster-shared bandwidth + concurrency tracking)");
-  validateOpts.optionalObjectWithMethod(opts.fileType, "detect",
-    "staticServe.create: fileType", StaticServeError, "BAD_OPT",
-    "must be a b.fileType instance (magic-byte MIME detection)");
-  validateOpts.optionalObjectWithMethod(opts.retention, "isServable",
-    "staticServe.create: retention", StaticServeError, "BAD_OPT",
-    "must expose isServable(absPath, ctx) → boolean (compliance retention check)");
-  validateOpts.optionalObjectWithMethod(opts.revokeStore, "isRevoked",
-    "staticServe.create: revokeStore", StaticServeError, "BAD_OPT",
-    "must expose isRevoked(key) and revoke(key) for force-revoke support");
-  validateOpts.optionalNonEmptyStringArray(opts.allowedFileTypes,
-    "staticServe.create: allowedFileTypes", StaticServeError, "BAD_OPT");
   if (Array.isArray(opts.allowedFileTypes) && opts.allowedFileTypes.length > 0 &&
       (!opts.fileType || typeof opts.fileType.detect !== "function")) {
     throw _err("BAD_OPT",
       "staticServe.create: allowedFileTypes is set but fileType primitive is not wired " +
       "(pass fileType: b.fileType so the framework can sniff magic bytes before serving)");
   }
-  validateOpts.auditShape(opts.audit, "staticServe.create", StaticServeError);
-  validateOpts.observabilityShape(opts.observability, "staticServe.create", StaticServeError);
-  validateOpts.optionalFunction(opts.onServe, "staticServe.create: onServe", StaticServeError);
-  validateOpts.optionalFunction(opts.onError, "staticServe.create: onError", StaticServeError);
-  // contentSafety — extension-keyed gate map. Default behaviour: when
-  // undefined, the framework wires b.guardAll.byExtension({ profile:
-  // "strict" }) automatically so every shipped guard is ON by default.
-  // Explicit opt-out: contentSafety: null (audited at create() time so
-  // a security review can reconstruct which deploys disabled the
-  // default-on protection).
+  // contentSafety — extension-keyed gate map; validated in the shape above
+  // (plain { ext: gate } object / null opt-out / undefined default-on).
+  // When undefined, the framework wires b.guardAll.byExtension({ profile:
+  // "strict" }) automatically so every shipped guard is ON by default;
+  // contentSafety: null is the explicit opt-out, audited at create() time so
+  // a security review can reconstruct which deploys disabled the default-on
+  // protection.
   // Example: contentSafety: { ".csv": b.guardCsv.gate({ profile: "strict" }) }
-  if (opts.contentSafety !== undefined && opts.contentSafety !== null) {
-    validateOpts.optionalPlainObject(opts.contentSafety,
-      "staticServe.create: contentSafety", StaticServeError, "BAD_OPT",
-      "must be a plain { ext: gate } object, null to opt out, or " +
-      "undefined for the default-on b.guardAll wiring");
-    var safetyKeys = Object.keys(opts.contentSafety);
-    for (var sk = 0; sk < safetyKeys.length; sk++) {
-      var ext = safetyKeys[sk];
-      var g = opts.contentSafety[ext];
-      if (!g || typeof g.check !== "function") {
-        throw _err("BAD_OPT",
-          "staticServe.create: contentSafety[" + JSON.stringify(ext) +
-          "] must be a gate (b.guardCsv.gate / b.guardHtml.gate / etc.)");
-      }
-    }
-  }
-  validateOpts.optionalBoolean(opts.acceptRanges, "staticServe.create: acceptRanges", StaticServeError);
-  validateOpts.optionalBoolean(opts.auditSuccess, "staticServe.create: auditSuccess", StaticServeError);
-  validateOpts.optionalBoolean(opts.auditFailures, "staticServe.create: auditFailures", StaticServeError);
-  validateOpts.optionalBoolean(opts.safeAttachmentForRiskyMimes,
-    "staticServe.create: safeAttachmentForRiskyMimes", StaticServeError);
   // mountType — config-time enum. A typo ("usercontent", "uploads")
   // would silently fall back to the curated default and serve untrusted
   // HTML inline, so THROW at boot rather than mis-type the mount.
@@ -576,22 +639,6 @@ function _validateCreateOpts(opts) {
       "staticServe.create: mountType must be 'curated' (default) or " +
       "'user-content'; got " + JSON.stringify(opts.mountType));
   }
-  validateOpts.optionalBoolean(opts.forceAttachmentForNonText,
-    "staticServe.create: forceAttachmentForNonText", StaticServeError);
-  validateOpts.optionalBoolean(opts.safeRenderSvg,
-    "staticServe.create: safeRenderSvg", StaticServeError);
-  validateOpts.optionalBoolean(opts.safeRenderPdf,
-    "staticServe.create: safeRenderPdf", StaticServeError);
-  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesPerActorPerWindowMs,
-    "staticServe.create: maxBytesPerActorPerWindowMs", StaticServeError, "BAD_OPT");
-  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesAllActorsPerWindowMs,
-    "staticServe.create: maxBytesAllActorsPerWindowMs", StaticServeError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.bandwidthWindowMs,
-    "staticServe.create: bandwidthWindowMs", StaticServeError, "BAD_OPT");
-  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxConcurrentDownloadsPerActor,
-    "staticServe.create: maxConcurrentDownloadsPerActor", StaticServeError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxIdleMs,
-    "staticServe.create: maxIdleMs", StaticServeError, "BAD_OPT");
   // Quotas require a cache for cluster-shared coordination.
   if ((opts.maxBytesPerActorPerWindowMs > 0 ||
        opts.maxBytesAllActorsPerWindowMs > 0 ||
@@ -701,20 +748,11 @@ async function integrity(absPath) {
 
 function create(opts) {
   opts = opts || {};
-  // The v0.6.x test surface called `validateOpts(opts, [...allowed], label)`
-  // for the unknown-key check. Preserve that gate in addition to the
-  // throw-at-config-time validation so tests catch typos.
-  validateOpts(opts, [
-    "root", "mountPath", "hashedPathPattern",
-    "indexFile", "defaultMaxAge", "contentTypes",
-    "permissions", "cache", "fileType", "retention", "revokeStore",
-    "allowedFileTypes", "audit", "observability", "onServe", "onError",
-    "acceptRanges", "auditSuccess", "auditFailures",
-    "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
-    "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
-    "contentSafety", "contentSafetyDisabledReason",
-    "mountType", "forceAttachmentForNonText", "safeRenderSvg", "safeRenderPdf",
-  ], "staticServe.create");
+  // The exhaustive shape() in _validateCreateOpts is the authoritative
+  // unknown-key gate: any opt not declared in its schema (nor listed in
+  // its options.allow pass-through) is rejected as an unknown opt, so the
+  // typo-catching the v0.6.x `validateOpts(opts, [...allowed])` call gave
+  // is now subsumed by the per-field validation below.
   _validateCreateOpts(opts);
   var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
   var root            = nodePath.resolve(opts.root);