@blamejs/core 0.15.12 → 0.15.14

package/lib/safe-ical.js

@@ -80,8 +80,11 @@
  */
 
 var C = require("./constants");
+var codepointClass = require("./codepoint-class");
+var structuredFields = require("./structured-fields");
 var { defineClass } = require("./framework-error");
 var gateContract = require("./gate-contract");
+var pick = require("./pick");
 
 var SafeIcalError = defineClass("SafeIcalError", { alwaysPermanent: true });
 
@@ -369,13 +372,11 @@ function _parseContentLine(line) {
 
   // Refuse NUL, C0 control bytes (other than TAB), and DEL in the
   // value. Header-injection / log-poisoning defense.
-  for (var k = 0; k < value.length; k++) {
-    var cc = value.charCodeAt(k);
-    if ((cc < 0x20 && cc !== 0x09) || cc === 0x7F) {                                                      // C0 + DEL refusal
-      throw new SafeIcalError("safe-ical/control-char-in-value",
-        "safeIcal.parse: control char 0x" + cc.toString(16) +
-        " in property value (header-injection defense)");
-    }
+  var ctrlAt = codepointClass.firstControlCharOffset(value);                                              // NUL / C0 (except TAB) / DEL refusal
+  if (ctrlAt !== -1) {
+    throw new SafeIcalError("safe-ical/control-char-in-value",
+      "safeIcal.parse: control char 0x" + value.charCodeAt(ctrlAt).toString(16) +
+      " in property value (header-injection defense)");
   }
 
   // Split params off the property name.
@@ -391,7 +392,7 @@ function _parseContentLine(line) {
     }
     var pname = seg.slice(0, eq).toUpperCase();
     var pvalue = seg.slice(eq + 1);
-    if (pname === "__proto__" || pname === "constructor" || pname === "prototype") continue;
+    if (pick.isPoisonedKey(pname)) continue;
     if (params[pname]) {
       params[pname].push(_stripDoubleQuotes(pvalue));
     } else {
@@ -412,26 +413,11 @@ function _findUnquotedColon(line) {
 }
 
 function _splitUnquoted(s, sep) {
-  var out = [];
-  var inQ = false;
-  var start = 0;
-  for (var i = 0; i < s.length; i++) {
-    var c = s.charAt(i);
-    if (c === '"') { inQ = !inQ; continue; }
-    if (c === sep && !inQ) {
-      out.push(s.slice(start, i));
-      start = i + 1;
-    }
-  }
-  out.push(s.slice(start));
-  return out;
+  return structuredFields.splitUnquoted(s, sep);
 }
 
 function _stripDoubleQuotes(s) {
-  if (s.length >= 2 && s.charAt(0) === '"' && s.charAt(s.length - 1) === '"') {
-    return s.slice(1, -1);
-  }
-  return s;
+  return structuredFields.stripDoubleQuotes(s);
 }
 
 // ---- Component parser (RFC 5545 §3.6) ----
@@ -458,7 +444,7 @@ function _parseComponent(lines, startIdx, ctx, depth) {
       "safeIcal.parse: expected BEGIN, got '" + begin.name + "'");
   }
   var compName = begin.value.toUpperCase();
-  if (!KNOWN_COMPONENTS[compName] && !ctx.extraComps[compName] &&
+  if (!Object.prototype.hasOwnProperty.call(KNOWN_COMPONENTS, compName) && !ctx.extraComps[compName] &&
       compName.indexOf("X-") !== 0) {
     throw new SafeIcalError("safe-ical/unknown-component",
       "safeIcal.parse: unknown component '" + compName +
@@ -489,7 +475,7 @@ function _parseComponent(lines, startIdx, ctx, depth) {
     }
     // Validate property name.
     var pn = ln.name;
-    if (!KNOWN_PROPERTIES[pn] && !ctx.extraProps[pn] && pn.indexOf("X-") !== 0) {
+    if (!Object.prototype.hasOwnProperty.call(KNOWN_PROPERTIES, pn) && !ctx.extraProps[pn] && pn.indexOf("X-") !== 0) {
       throw new SafeIcalError("safe-ical/unknown-property",
         "safeIcal.parse: unknown property '" + pn +
         "' (extend via opts.extraProperties or use X- prefix)");
@@ -504,7 +490,7 @@ function _parseComponent(lines, startIdx, ctx, depth) {
         "safeIcal.parse: property count in " + compName +
         " exceeds maxPropertiesPerComponent=" + ctx.caps.maxPropertiesPerComponent);
     }
-    if (pn === "__proto__" || pn === "constructor" || pn === "prototype") {
+    if (pick.isPoisonedKey(pn)) {
       i += 1;
       continue;
     }

package/lib/safe-icap.js

@@ -426,7 +426,7 @@ function _parseEncapsulated(value) {
     }
     var part = token.slice(0, eq);
     var offStr = token.slice(eq + 1);
-    if (!ENCAPSULATED_PARTS[part]) {
+    if (!Object.prototype.hasOwnProperty.call(ENCAPSULATED_PARTS, part)) {
       throw new SafeIcapError("safe-icap/bad-encapsulated",
         "safeIcap.parse: Encapsulated part '" + part + "' is not one of " +
         Object.keys(ENCAPSULATED_PARTS).join(", "));

package/lib/safe-json.js

@@ -37,6 +37,7 @@
 // ---- Error class ----
 
 var C = require("./constants");
+var pick = require("./pick");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var time = require("./time");
@@ -93,8 +94,6 @@ var DEFAULT_MAX_DEPTH = 100;
 var DEFAULT_MAX_KEYS = 10_000;
 var ABSOLUTE_MAX_KEYS = 1_000_000;
 
-var POISONED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
-
 // ---- parse ----
 
 /**
@@ -242,7 +241,7 @@ function parseOrDefault(input, fallback, opts) {
 }
 
 function _stripProtoKeys(key, value) {
-  if (POISONED_KEYS.has(key)) return undefined;
+  if (pick.isPoisonedKey(key)) return undefined;
   return value;
 }
 
@@ -256,7 +255,7 @@ function _walkAndCheck(value, depth, maxDepth, allowProto, maxKeys) {
     return;
   }
   if (!allowProto) {
-    POISONED_KEYS.forEach(function (k) {
+    pick.POISONED_KEYS.forEach(function (k) {
       if (Object.prototype.hasOwnProperty.call(value, k)) delete value[k];
     });
   }
@@ -338,7 +337,7 @@ function stringify(value, opts) {
   }
 
   function replacer(key, val) {
-    if (!allowProto && POISONED_KEYS.has(key)) return undefined;
+    if (!allowProto && pick.isPoisonedKey(key)) return undefined;
     return val;
   }
 
@@ -355,6 +354,49 @@ function stringify(value, opts) {
   }
 }
 
+/**
+ * @primitive b.safeJson.stringifyForScript
+ * @signature b.safeJson.stringifyForScript(value, opts?)
+ * @since     0.15.14
+ * @status    stable
+ * @related   b.safeJson.stringify
+ *
+ * Like `b.safeJson.stringify` but safe to embed verbatim inside an
+ * inline `<script>` element. Raw `JSON.stringify` does not escape `<`,
+ * `>`, or `&`, so a string value containing `</script>` (or `<!--`)
+ * closes the surrounding script element and injects markup; the
+ * Unicode line/paragraph separators U+2028 / U+2029 are also illegal
+ * unescaped in a script context on older parsers. This escapes all of
+ * them to their equivalent `\uXXXX` JSON escapes — the parsed value is
+ * byte-identical, but no substring can break out of a `<script>` block.
+ *
+ * @opts
+ *   indent:    number | string,   // forwarded to b.safeJson.stringify
+ *   allowProto:boolean,           // forwarded
+ *
+ * @example
+ *   var json = b.safeJson.stringifyForScript({ url: "/a</script>x" });
+ *   res.end('<script type="importmap">' + json + '</script>');
+ *   // → the "</script>" inside the value is emitted as "</script>"
+ */
+function stringifyForScript(value, opts) {
+  var json = stringify(value, opts);
+  // BS is a single backslash built at runtime so this source carries no
+  // escape literals (they round-trip badly through tooling). Escape < > &
+  // so the JSON cannot close / comment-open the surrounding inline
+  // <script>; escape U+2028 / U+2029 (illegal unescaped in a script on
+  // older parsers). The parsed value is unchanged.
+  var BS = String.fromCharCode(92);
+  json = json.replace(/[<>&]/g, function (c) {
+    if (c === "<") return BS + "u003c";
+    if (c === ">") return BS + "u003e";
+    return BS + "u0026";
+  });
+  json = json.split(String.fromCharCode(0x2028)).join(BS + "u2028");
+  json = json.split(String.fromCharCode(0x2029)).join(BS + "u2029");
+  return json;
+}
+
 // Walk the value, substituting any references that would create a cycle
 // with `replacement`. Uses an active-stack Set so SHARED non-circular
 // subtrees are preserved (only true cycles are replaced).
@@ -373,7 +415,7 @@ function _cleanCycles(value, replacement, allowProto) {
       out = {};
       for (var k in v) {
         if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
-        if (!allowProto && POISONED_KEYS.has(k)) continue;
+        if (!allowProto && pick.isPoisonedKey(k)) continue;
         out[k] = walk(v[k]);
       }
     }
@@ -432,7 +474,7 @@ function canonical(value) {
     if (typeof v === "string") return JSON.stringify(v);
     if (Array.isArray(v))      return "[" + v.map(ser).join(",") + "]";
     if (typeof v === "object") {
-      var keys = Object.keys(v).filter(function (k) { return !POISONED_KEYS.has(k); }).sort();
+      var keys = Object.keys(v).filter(function (k) { return !pick.isPoisonedKey(k); }).sort();
       var pairs = keys.map(function (k) { return JSON.stringify(k) + ":" + ser(v[k]); });
       return "{" + pairs.join(",") + "}";
     }
@@ -931,6 +973,7 @@ module.exports = {
   parse:          parse,
   parseOrDefault: parseOrDefault,
   stringify:      stringify,
+  stringifyForScript: stringifyForScript,
   canonical:      canonical,
   validate:       validate,
   registerFormat: registerFormat,
@@ -942,5 +985,5 @@ module.exports = {
   ABSOLUTE_MAX_BYTES: ABSOLUTE_MAX_BYTES,
   ABSOLUTE_MAX_DEPTH: ABSOLUTE_MAX_DEPTH,
   ABSOLUTE_MAX_KEYS:  ABSOLUTE_MAX_KEYS,
-  POISONED_KEYS:      Array.from(POISONED_KEYS),
+  POISONED_KEYS:      pick.POISONED_KEYS.slice(),
 };

package/lib/safe-jsonpath.js

@@ -38,6 +38,7 @@
 
 var codepointClass = require("./codepoint-class");
 var C = require("./constants");
+var safeBuffer = require("./safe-buffer");
 var { defineClass, FrameworkError } = require("./framework-error");
 
 // SafeJsonPathError — alwaysPermanent because every code path is a
@@ -86,7 +87,7 @@ function _hasControlOrNul(value) {
   // legitimate use in a JSON pointer / key / path expression.
   for (var i = 0; i < value.length; i++) {
     var c = value.charCodeAt(i);
-    if (c === 0 || (c < 32 && c !== 9) || c === 127) return true; // ASCII control-byte range
+    if (codepointClass.isForbiddenControlChar(c)) return true; // ASCII control-byte range
   }
   if (codepointClass.BIDI_RE.test(value)) return true; // allow:regex-no-length-cap — callers cap length via MAX_KEY_BYTES / MAX_EXPRESSION_BYTES
   if (codepointClass.ZERO_WIDTH_RE.test(value)) return true; // allow:regex-no-length-cap — callers cap length via MAX_KEY_BYTES / MAX_EXPRESSION_BYTES
@@ -108,9 +109,9 @@ function validateKey(key, opts) {
       "validateKey: key must be non-empty");
   }
   var maxBytes = opts.maxBytes || MAX_KEY_BYTES;
-  if (key.length > maxBytes) {
+  if (safeBuffer.byteLengthOf(key) > maxBytes) {
     throw _err("safe-jsonpath/key-too-long",
-      "validateKey: key exceeds " + maxBytes + " bytes (got " + key.length + ")");
+      "validateKey: key exceeds " + maxBytes + " bytes (got " + safeBuffer.byteLengthOf(key) + ")");
   }
   if (_hasControlOrNul(key)) {
     throw _err("safe-jsonpath/key-control-char",
@@ -167,9 +168,9 @@ function validateExpression(expr, opts) {
       "validateExpression: expr must be non-empty");
   }
   var maxBytes = opts.maxBytes || MAX_EXPRESSION_BYTES;
-  if (expr.length > maxBytes) {
+  if (safeBuffer.byteLengthOf(expr) > maxBytes) {
     throw _err("safe-jsonpath/expression-too-long",
-      "validateExpression: expr exceeds " + maxBytes + " bytes (got " + expr.length + ")");
+      "validateExpression: expr exceeds " + maxBytes + " bytes (got " + safeBuffer.byteLengthOf(expr) + ")");
   }
   if (_hasControlOrNul(expr)) {
     throw _err("safe-jsonpath/expression-control-char",

package/lib/safe-mime.js

@@ -45,7 +45,12 @@
  */
 
 var C = require("./constants");
+var safeBuffer = require("./safe-buffer");
+var numericBounds = require("./numeric-bounds");
+var codepointClass = require("./codepoint-class");
+var structuredFields = require("./structured-fields");
 var { defineClass } = require("./framework-error");
+var pick = require("./pick");
 
 var SafeMimeError = defineClass("SafeMimeError", { alwaysPermanent: true });
 
@@ -147,7 +152,7 @@ function parse(bytes, opts) {
   var encodings       = _normalizeStringSet(opts.transferEncodingAllowlist || DEFAULT_TRANSFER_ENCODINGS);
 
   var buf = _toBuffer(bytes);
-  if (buf.length > maxMessageBytes) {
+  if (safeBuffer.byteLengthOf(buf) > maxMessageBytes) {
     throw new SafeMimeError("safe-mime/oversize-message",
       "safeMime.parse: message size " + buf.length + " exceeds maxMessageBytes " + maxMessageBytes);
   }
@@ -398,7 +403,7 @@ function _parsePart(buf, ctx, depth) {
     };
   }
 
-  if (bodyBytes.length > ctx.maxBodyBytes) {
+  if (safeBuffer.byteLengthOf(bodyBytes) > ctx.maxBodyBytes) {
     throw new SafeMimeError("safe-mime/oversize-body",
       "safeMime.parse: body " + bodyBytes.length + " bytes exceeds maxBodyBytes=" + ctx.maxBodyBytes);
   }
@@ -413,7 +418,7 @@ function _parsePart(buf, ctx, depth) {
       "safeMime.parse: charset '" + charset + "' not in allowlist; refused");
   }
   var decodedBody = _decodeBody(bodyBytes, encoding);
-  if (decodedBody.length > ctx.maxBodyBytes) {
+  if (safeBuffer.byteLengthOf(decodedBody) > ctx.maxBodyBytes) {
     throw new SafeMimeError("safe-mime/oversize-body",
       "safeMime.parse: decoded body " + decodedBody.length +
       " bytes exceeds maxBodyBytes=" + ctx.maxBodyBytes);
@@ -458,13 +463,13 @@ function _parseHeaders(buf, ctx) {
   var headerMap = Object.create(null);
   for (var i = 0; i < lines.length; i += 1) {
     var line = lines[i];
-    var colon = line.indexOf(":");
-    if (colon < 0) {
+    var khv = structuredFields.parseKeyValuePiece(line, ":");
+    if (khv.value === null) {
       throw new SafeMimeError("safe-mime/malformed-headers",
         "safeMime.parse: header line missing colon: " + _previewBytes(line));
     }
-    var name  = line.slice(0, colon).toLowerCase().trim();
-    var value = line.slice(colon + 1).trim();
+    var name  = khv.key;
+    var value = khv.value.trim();
     // Refuse NUL, CR, LF, and other C0 control chars in header values.
     // Tab (0x09) is allowed (header folding). C1 control range
     // (0x80-0x9F) NOT refused — legitimate non-ASCII via EAI/RFC 2047
@@ -473,17 +478,15 @@ function _parseHeaders(buf, ctx) {
     // string prefix) rather than the UTF-16 code-unit index, so the
     // operator audit log lines up with the wire-level byte stream
     // they're inspecting.
-    for (var hci = 0; hci < value.length; hci += 1) {
-      var hcc = value.charCodeAt(hci);
-      if ((hcc < 0x20 && hcc !== 0x09) || hcc === 0x7F) {                                          // C0 control char + DEL refusal
-        var byteOffset = Buffer.byteLength(value.slice(0, hci), "utf8");
-        throw new SafeMimeError("safe-mime/control-char-in-header",
-          "safeMime.parse: header '" + name + "' contains control char 0x" +
-          hcc.toString(16) + " at byte offset " + byteOffset);                                            // toString radix 16 hex, not bytes
-      }
+    var hci = codepointClass.firstControlCharOffset(value);                                          // C0 control char (except TAB) + DEL refusal
+    if (hci !== -1) {
+      var byteOffset = Buffer.byteLength(value.slice(0, hci), "utf8");
+      throw new SafeMimeError("safe-mime/control-char-in-header",
+        "safeMime.parse: header '" + name + "' contains control char 0x" +
+        value.charCodeAt(hci).toString(16) + " at byte offset " + byteOffset);                            // toString radix 16 hex, not bytes
     }
     value = _decodeRfc2047Words(value);
-    if (name === "__proto__" || name === "constructor" || name === "prototype") continue;
+    if (pick.isPoisonedKey(name)) continue;
     if (!headerMap[name]) headerMap[name] = [];
     headerMap[name].push(value);
   }
@@ -525,19 +528,14 @@ function _parseContentType(value) {
   var parts = String(value).split(";");
   var type  = parts[0].toLowerCase().trim();
   var params = Object.create(null);
-  for (var i = 1; i < parts.length; i += 1) {
-    var p = parts[i].trim();
-    if (p.length === 0) continue;
-    var eq = p.indexOf("=");
-    if (eq < 0) continue;
-    var k = p.slice(0, eq).toLowerCase().trim();
-    var v = p.slice(eq + 1).trim();
+  var kvps = structuredFields.parseKeyValuePieces(parts, 1);
+  structuredFields.forEachKeyValue(kvps, function (k, v) {
     if (v.length >= 2 && v.charAt(0) === '"' && v.charAt(v.length - 1) === '"') {
       v = v.slice(1, -1).replace(/\\(.)/g, "$1");
     }
-    if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+    if (pick.isPoisonedKey(k)) return;
     params[k] = v;
-  }
+  });
   return { type: type, params: params };
 }
 
@@ -779,10 +777,8 @@ function _toBuffer(input) {
 
 function _intOpt(opts, key, fallback) {
   if (opts[key] === undefined || opts[key] === null) return fallback;
-  if (typeof opts[key] !== "number" || !isFinite(opts[key]) || opts[key] <= 0 || Math.floor(opts[key]) !== opts[key]) {
-    throw new SafeMimeError("safe-mime/bad-opt",
-      "safeMime.parse: opts." + key + " must be a positive finite integer (got " + opts[key] + ")");
-  }
+  numericBounds.requirePositiveFiniteInt(opts[key],
+    "safeMime.parse: opts." + key, SafeMimeError, "safe-mime/bad-opt");
   return opts[key];
 }
 

package/lib/safe-redirect.js

@@ -40,15 +40,12 @@
 
 var safeUrl = require("./safe-url");
 var validateOpts = require("./validate-opts");
+var codepointClass = require("./codepoint-class");
 
 var DEFAULT_FALLBACK = "/";
 
 function _hasControlChar(s) {
-  for (var i = 0; i < s.length; i += 1) {
-    var c = s.charCodeAt(i);
-    if (c < 0x20 || c === 0x7f) return true;                                     // ASCII control range thresholds
-  }
-  return false;
+  return codepointClass.firstControlCharOffset(s, { forbidTab: true }) !== -1;
 }
 
 function resolve(rawTarget, opts) {

package/lib/safe-schema.js

@@ -98,6 +98,8 @@
 
 var C = require("./constants");
 var safeJson = require("./safe-json");
+var pick = require("./pick");
+var ipUtils = require("./ip-utils");
 var { defineClass } = require("./framework-error");
 
 // Maximum URL length per RFC 7230 §3.1.1 guidance — also reused as the
@@ -154,7 +156,6 @@ var SafeSchemaError = defineClass("SafeSchemaError", { alwaysPermanent: true });
 // Object.prototype by submitting a JSON body with __proto__ /
 // constructor / prototype keys, even if the operator schema is
 // .passthrough().
-var POISONED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 // Pragmatic regexes — RFC-correct is impractical without exploding the
 // regex (especially email). Operators wanting deeper validation chain
@@ -169,7 +170,7 @@ var UUID_RE     = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0
 var DATE_RE     = /^\d{4}-\d{2}-\d{2}$/;
 // ISO-8601 datetime with timezone (Z or ±HH:MM); fractional seconds optional.
 var DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
-var IPV4_RE     = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+var IPV4_RE     = ipUtils.IPV4_RE;                                                  // canonical strict dotted-quad — single source in lib/ip-utils.js
 // CUID v1 / v2: 25-char base36, starts with 'c'. Common in TypeScript ecosystems.
 var CUID_RE     = /^c[a-z0-9]{24}$/;
 // ULID: Crockford-base32, 26 chars, time-sortable.
@@ -1012,7 +1013,7 @@ function object(shape) {
   // such a key) gets a refusal at construction time.
   var allOwnKeys = Object.getOwnPropertyNames(shape);
   for (var ai = 0; ai < allOwnKeys.length; ai++) {
-    if (POISONED_KEYS.has(allOwnKeys[ai])) {
+    if (pick.isPoisonedKey(allOwnKeys[ai])) {
       throw new SafeSchemaError("safe-schema/poisoned-shape-key",
         "object shape: key '" + allOwnKeys[ai] + "' is forbidden (prototype-pollution defense)");
     }
@@ -1054,7 +1055,7 @@ function _objectWithMode(shape, keys, mode) {
         // Prototype-pollution defense — refuse __proto__/constructor/
         // prototype regardless of mode. .passthrough() never propagates
         // these because they are always rejected as input.
-        if (POISONED_KEYS.has(ik)) {
+        if (pick.isPoisonedKey(ik)) {
           issues.push({
             path: path.concat([ik]),
             code: "object/poisoned-key",
@@ -1449,7 +1450,7 @@ function record(a, b) {
       for (var i = 0; i < keys.length; i++) {
         var k = keys[i];
         // Prototype-pollution defense — same shape as object() schema.
-        if (POISONED_KEYS.has(k)) {
+        if (pick.isPoisonedKey(k)) {
           issues.push({
             path: path.concat([k]),
             code: "record/poisoned-key",
@@ -1533,7 +1534,7 @@ function discriminatedUnion(discriminator, options) {
     throw new SafeSchemaError("safe-schema/bad-discriminator",
       "discriminatedUnion: discriminator must be a non-empty string key name");
   }
-  if (POISONED_KEYS.has(discriminator)) {
+  if (pick.isPoisonedKey(discriminator)) {
     throw new SafeSchemaError("safe-schema/poisoned-discriminator",
       "discriminatedUnion: discriminator key '" + discriminator + "' is forbidden");
   }

package/lib/safe-sieve.js

@@ -133,7 +133,7 @@ function _resolveProfile(opts) {
   if (!opts) return "strict";
   if (typeof opts.profile === "string") return opts.profile;
   if (typeof opts.compliancePosture === "string") {
-    return COMPLIANCE_POSTURES[opts.compliancePosture] || "strict";
+    return (Object.prototype.hasOwnProperty.call(COMPLIANCE_POSTURES, opts.compliancePosture) && COMPLIANCE_POSTURES[opts.compliancePosture]) || "strict";
   }
   return "strict";
 }

package/lib/safe-sql.js

@@ -429,6 +429,69 @@ function countPlaceholders(sql) {
   return count;
 }
 
+/**
+ * @primitive b.safeSql.toPositional
+ * @signature b.safeSql.toPositional(sql, dialect)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeSql.countPlaceholders, b.sql
+ *
+ * Rewrite bound `?` placeholders to Postgres `$N` positional form,
+ * skipping any `?` inside a string literal (`'...'` / `"..."` /
+ * `` `...` ``, doubled-quote escape aware) or a line / block comment. For
+ * any non-Postgres dialect the SQL is returned unchanged (`?` is already
+ * the wire form). This is the same quote- and comment-aware scan as
+ * `countPlaceholders`, extended to emit the rewritten string and to skip
+ * MySQL backtick-quoted identifiers; the query builder and the cluster
+ * store both compose it so the rewrite lives in one place.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.toPositional("a = ? AND b = ?", "postgres");
+ *   // → "a = $1 AND b = $2"
+ *
+ *   b.safeSql.toPositional("note = 'is ? literal' AND id = ?", "postgres");
+ *   // → "note = 'is ? literal' AND id = $1"
+ */
+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;
+}
+
 /**
  * @primitive b.safeSql.DEFAULT_IDENTIFIER_RE
  * @signature b.safeSql.DEFAULT_IDENTIFIER_RE
@@ -557,7 +620,69 @@ function assertSingleStatement(sql, opts) {
   return sql;
 }
 
+/**
+ * @primitive b.safeSql.assertNoRawStringLiteral
+ * @signature b.safeSql.assertNoRawStringLiteral(sql, where, makeError?)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeSql.assertSingleStatement, b.safeSql.countPlaceholders, b.sql
+ *
+ * The one quote/comment-aware scan that refuses a `'...'` STRING LITERAL in
+ * raw SQL — the injection backstop for the b.sql builder's raw fragments and
+ * the external-db raw-query path, which must bind every value with a `?`
+ * placeholder rather than splice a literal. Walks the SQL skipping `"..."`
+ * quoted identifiers (doubled-quote escapes handled), `-- line` comments, and
+ * slash-star block comments; on the first top-level `'` it throws the caller's
+ * error (`makeError(where)` returns the Error to throw). Both b.sql and the
+ * external-db raw gate route through this single scan so a fix to the scanner
+ * cannot drift between them.
+ *
+ * @example
+ *   b.safeSql.assertNoRawStringLiteral("WHERE id = ?", "where");   // ok (no literal)
+ *   try { b.safeSql.assertNoRawStringLiteral("WHERE name = 'x'", "where"); }
+ *   catch (e) { e.code; }                                          // → "sql/raw-literal"
+ */
+function assertNoRawStringLiteral(sql, where, makeError) {
+  var mkErr = typeof makeError === "function" ? makeError : function (w) {
+    return new SafeSqlError(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/raw-literal");
+  };
+  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 mkErr(where);
+    }
+    i += 1;
+  }
+}
+
 module.exports = {
+  assertNoRawStringLiteral: assertNoRawStringLiteral,
   validateIdentifier:  validateIdentifier,
   assertSingleStatement: assertSingleStatement,
   quoteIdentifier:     quoteIdentifier,
@@ -565,6 +690,7 @@ module.exports = {
   quoteList:           quoteList,
   assertOneOf:         assertOneOf,
   countPlaceholders:   countPlaceholders,
+  toPositional:        toPositional,
   SafeSqlError:        SafeSqlError,
   // Exposed so consumers can compose their own validators
   DEFAULT_IDENTIFIER_RE: DEFAULT_IDENTIFIER_RE,