@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/safe-smtp.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * @module     b.safeSmtp
+ * @nav        Parsers
+ * @title      Safe SMTP
+ * @order      215
+ *
+ * @intro
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes.
+ *   Operators consuming the framework's MX listener (`b.mail.server.mx`),
+ *   submission listener (slice that follows), or building their own
+ *   SMTP-shaped tooling (proxies, log analyzers, test fixtures) reach
+ *   for these primitives rather than reinventing the dot-terminator
+ *   scan + dot-stuffing reversal.
+ *
+ *   Separates the "what shape is the wire data" parsing concern from
+ *   the "is this wire data hostile" guard concern (which lives in
+ *   `b.guardSmtpCommand`). A safe-* parser primitive returns a
+ *   bounded shape or `-1`; a guard-* primitive returns a boolean
+ *   threat verdict or throws a typed error.
+ *
+ *   Wire-protocol references:
+ *     - RFC 5321 §2.3.8 — line termination MUST be CRLF
+ *     - RFC 5321 §4.5.2 — dot-stuffing on the SMTP body
+ *     - RFC 5321 §4.1.1.4 — DATA command terminates with `<CRLF>.<CRLF>`
+ *     - CVE-2023-51764 / -51765 / -51766 / 2024-32178 — SMTP
+ *       smuggling (parsers that accept bare-LF dot-terminators).
+ *       The guard primitive `b.guardSmtpCommand.detectBodySmuggling`
+ *       owns smuggling detection; the safe-* terminator scanner
+ *       here is strict CRLF-only by construction.
+ *
+ * @card
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes —
+ *   findDotTerminator + dotUnstuff. Strict CRLF-only by construction
+ *   (bare-LF terminators are not honored — the smuggling-detection
+ *   guard lives in b.guardSmtpCommand.detectBodySmuggling).
+ */
+
+var { defineClass } = require("./framework-error");
+
+var SafeSmtpError = defineClass("SafeSmtpError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.safeSmtp.findDotTerminator
+ * @signature b.safeSmtp.findDotTerminator(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.dotUnstuff, b.guardSmtpCommand.detectBodySmuggling
+ *
+ * Scan `buf` for the canonical RFC 5321 §4.1.1.4 DATA-body terminator
+ * `<CRLF>.<CRLF>` (5 bytes: 0x0d 0x0a 0x2e 0x0d 0x0a). Returns the
+ * byte index where the body ends (exclusive — the index of the
+ * trailing CRLF the terminator starts on), or `-1` if the terminator
+ * is not yet present.
+ *
+ * Strict CRLF-only by construction — bare-LF alternate terminators
+ * are NOT honored. Operators worried about smuggling shape route the
+ * SAME body through `b.guardSmtpCommand.detectBodySmuggling` before
+ * trusting the terminator index returned here.
+ *
+ * @example
+ *   var body = Buffer.from("Hello world.\r\n.\r\n");
+ *   b.safeSmtp.findDotTerminator(body);
+ *   // → 13  (index of \r in \r\n.\r\n)
+ *
+ *   b.safeSmtp.findDotTerminator(Buffer.from("incomplete body"));
+ *   // → -1
+ */
+function findDotTerminator(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "findDotTerminator: input must be a Buffer");
+  }
+  for (var i = 0; i <= buf.length - 5; i += 1) {                                                     // allow:raw-byte-literal — 5-byte CRLF.CRLF terminator length
+    if (buf[i] === 0x0d && buf[i + 1] === 0x0a &&
+        buf[i + 2] === 0x2e &&
+        buf[i + 3] === 0x0d && buf[i + 4] === 0x0a) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * @primitive b.safeSmtp.dotUnstuff
+ * @signature b.safeSmtp.dotUnstuff(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.findDotTerminator
+ *
+ * Reverse RFC 5321 §4.5.2 dot-stuffing on a DATA-body buffer. SMTP
+ * senders that need to transmit a body line beginning with `.` MUST
+ * prepend an extra `.` (so the line on the wire begins with `..`);
+ * the receiver strips the leading `.` from any body line that
+ * begins with one before storing the message. Returns a fresh
+ * Buffer with the dots reversed; the input is never mutated. Result
+ * length is always `<= input length`.
+ *
+ * @example
+ *   var wire = Buffer.from("hello\r\n..secret\r\nworld\r\n");
+ *   b.safeSmtp.dotUnstuff(wire).toString("utf8");
+ *   // → "hello\r\n.secret\r\nworld\r\n"
+ */
+function dotUnstuff(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "dotUnstuff: input must be a Buffer");
+  }
+  var out = Buffer.alloc(buf.length);
+  var oi = 0;
+  for (var i = 0; i < buf.length; i += 1) {
+    out[oi++] = buf[i];
+    // After \r\n, if the next byte is `.` followed by another non-CR
+    // byte (i.e., not the terminator itself), strip the stuffing dot.
+    if (i >= 1 && buf[i - 1] === 0x0d && buf[i] === 0x0a &&
+        i + 1 < buf.length && buf[i + 1] === 0x2e &&
+        i + 2 < buf.length && buf[i + 2] !== 0x0d) {
+      i += 1;
+    }
+  }
+  return out.subarray(0, oi);
+}
+
+/**
+ * @primitive b.safeSmtp.dotStuff
+ * @signature b.safeSmtp.dotStuff(buf)
+ * @since     0.9.57
+ * @status    stable
+ * @related   b.safeSmtp.dotUnstuff, b.safeSmtp.findDotTerminator
+ *
+ * Apply RFC 5321 §4.5.2 / RFC 1939 §3 dot-stuffing to a DATA / RETR
+ * body buffer. Lines that start with `.` get an extra `.` prepended
+ * so the receiver's parser doesn't mistake them for the terminator.
+ *
+ * Strict CRLF-aware: a line boundary is any of:
+ *   - start of buffer
+ *   - byte sequence \r\n (canonical CRLF)
+ *
+ * Bare LF inside a line is NOT treated as a line boundary, so a body
+ * containing `\n` (CVE-2023-51764 smuggling shape) doesn't gain
+ * spurious dot-stuffing that would confuse a downstream parser. The
+ * upstream caller is expected to either canonicalize or refuse bare-LF
+ * via `b.guardSmtpCommand.detectBodySmuggling`.
+ *
+ * Output guarantees a trailing `\r\n` so the caller can append the
+ * `.\r\n` terminator without worrying about whether the body already
+ * ended with one.
+ *
+ * @example
+ *   var body = Buffer.from(".secret\r\n.\r\nmore\r\n");
+ *   b.safeSmtp.dotStuff(body).toString("utf8");
+ *   // → "..secret\r\n..\r\nmore\r\n"
+ */
+function dotStuff(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "dotStuff: input must be a Buffer");
+  }
+  if (buf.length === 0) return buf;
+  // Worst case: every byte is a line-start dot — 2x length. Pre-allocate
+  // upper bound; subarray to actual length at return.
+  var out = Buffer.alloc(buf.length * 2);
+  var oi = 0;
+  // First byte: if `.`, prepend `.` (line-start).
+  if (buf[0] === 0x2e /* . */) out[oi++] = 0x2e;
+  out[oi++] = buf[0];
+  for (var i = 1; i < buf.length; i += 1) {
+    out[oi++] = buf[i];
+    // Inspect the byte AFTER a canonical \r\n line boundary. If it's
+    // `.`, prepend the stuffing dot. Match strictly on the CRLF
+    // sequence; bare LF is not a line boundary here.
+    if (i >= 1 && buf[i - 1] === 0x0d && buf[i] === 0x0a &&
+        i + 1 < buf.length && buf[i + 1] === 0x2e) {
+      out[oi++] = 0x2e;
+    }
+  }
+  return out.subarray(0, oi);
+}
+
+module.exports = {
+  findDotTerminator: findDotTerminator,
+  dotUnstuff:        dotUnstuff,
+  dotStuff:          dotStuff,
+  SafeSmtpError:     SafeSmtpError,
+};

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

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * @module b.safeSql
+ * @nav    Validation
+ * @title  Safe Sql
+ *
+ * @intro
+ *   SQL identifier validation + dialect-aware quoting + allowlist
+ *   gating. Defends against IDENTIFIER injection — the residual attack
+ *   surface left over when a TABLE name or COLUMN name flows from
+ *   operator-supplied config into a SQL string. Values bind through
+ *   parameterized queries everywhere in the framework, but parameters
+ *   can't carry identifiers; that interpolation is what this module
+ *   guards.
+ *
+ *   Default identifier shape: `^[A-Za-z_][A-Za-z0-9_]*$`, length 1–63
+ *   (Postgres NAMEDATALEN — the strictest of the supported dialects).
+ *   Reserved words (SELECT / DROP / PRAGMA / ATTACH / …) and the
+ *   SQLite-internal `sqlite_` prefix are refused unless the caller
+ *   explicitly opts in. Quoting follows dialect convention: SQLite +
+ *   Postgres double-quote, MySQL backtick. Multi-segment names
+ *   (`schema.table`) validate + quote each segment independently so
+ *   the dotted form `"schema"."table"` resolves correctly instead of
+ *   collapsing into one literal identifier with a dot in it.
+ *
+ *   Recommended pattern is the closed allowlist:
+ *
+ *     var ALLOWED = new Set(["audit_log", "consent_log"]);
+ *     b.safeSql.assertOneOf(name, ALLOWED);
+ *     var sql = "INSERT INTO " + b.safeSql.quoteIdentifier(name) + " ...";
+ *
+ *   The allowlist is the strongest guarantee. Operators with genuinely
+ *   dynamic identifier needs use `validateIdentifier` alone, accepting
+ *   that any string passing the regex is allowed.
+ *
+ *   Validation policy: every primitive throws `SafeSqlError` on bad
+ *   input — these run at SQL-composition time, well before the query
+ *   reaches the database. The throw IS the security signal.
+ *
+ * @card
+ *   SQL identifier validation + dialect-aware quoting + allowlist gating.
+ */
+
+// Reserved-word block list — the most dangerous to accept as a bare
+// identifier. Not exhaustive; the allowlist pattern below is preferred.
+var BANNED_IDENTIFIERS = new Set([
+  "select", "insert", "update", "delete", "drop", "create", "alter",
+  "truncate", "grant", "revoke", "union", "exec", "execute",
+  "where", "from", "join", "into", "values", "table", "database",
+  "schema", "index", "view", "trigger", "procedure", "function",
+  "begin", "commit", "rollback", "savepoint",
+  // SQLite-specific commands that escape the parameterized-query
+  // model. attach/detach mount external databases; pragma changes
+  // PRAGMAs (foreign_keys / cell_size_check / trusted_schema /
+  // journal_mode etc.) which can disable security-relevant
+  // protections; analyze / vacuum drop or rewrite indexes.
+  "pragma", "attach", "detach", "analyze", "vacuum", "reindex",
+]);
+
+// Default identifier shape — Postgres NAMEDATALEN (63 chars) is the
+// strictest of the dialects we support, so use it as the bound.
+var DEFAULT_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+
+var { FrameworkError } = require("./framework-error");
+
+/**
+ * @primitive b.safeSql.SafeSqlError
+ * @signature b.safeSql.SafeSqlError
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteIdentifier, b.safeSql.assertOneOf
+ *
+ * Error class thrown by every `b.safeSql` primitive on bad input.
+ * Extends `FrameworkError`. Carries a stable `.code` —
+ * `sql/bad-type` / `sql/empty` / `sql/too-long` / `sql/null-byte` /
+ * `sql/bad-shape` / `sql/reserved-word` / `sql/internal-prefix` /
+ * `sql/not-allowed` / `sql/bad-allowlist`. Operators catch these at
+ * SQL-composition boundaries; the throw fires before the query
+ * reaches the database driver.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   try {
+ *     b.safeSql.validateIdentifier("drop");
+ *   } catch (e) {
+ *     e instanceof b.safeSql.SafeSqlError;   // → true
+ *     e.code;                                // → "sql/reserved-word"
+ *   }
+ */
+class SafeSqlError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "SafeSqlError";
+    this.code = code || "sql/invalid";
+    this.isSafeSqlError = true;
+  }
+}
+
+/**
+ * @primitive b.safeSql.validateIdentifier
+ * @signature b.safeSql.validateIdentifier(name, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.assertOneOf, b.safeSql.SafeSqlError
+ *
+ * Throw-on-bad-shape validator for SQL table / column / index names.
+ * Enforces the default identifier regex (`[A-Za-z_][A-Za-z0-9_]*`),
+ * a 63-character cap (Postgres NAMEDATALEN — strictest supported
+ * dialect), no embedded null byte, no SQL reserved word, no
+ * SQLite-internal `sqlite_` prefix. Returns `name` on success so the
+ * call composes inside a SQL fragment without an extra temporary.
+ *
+ * @opts
+ *   pattern:              RegExp,  // override the default shape regex
+ *   allowReserved:        boolean, // default false; permit reserved words like "select"/"drop"
+ *   allowSqliteInternal:  boolean, // default false; permit "sqlite_..." identifiers
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.validateIdentifier("audit_log");
+ *   // → "audit_log"
+ *
+ *   try { b.safeSql.validateIdentifier("drop"); }
+ *   catch (e) { e.code; }
+ *   // → "sql/reserved-word"
+ *
+ *   try { b.safeSql.validateIdentifier("evil; DROP"); }
+ *   catch (e) { e.code; }
+ *   // → "sql/bad-shape"
+ *
+ *   // Operator opts in to a custom shape (still ASCII-only, still capped).
+ *   b.safeSql.validateIdentifier("col-1", { pattern: /^[A-Za-z][A-Za-z0-9_-]*$/ });
+ *   // → "col-1"
+ */
+function validateIdentifier(name, opts) {
+  opts = opts || {};
+  if (typeof name !== "string") {
+    throw new SafeSqlError("identifier must be a string (got " + typeof name + ")",
+      "sql/bad-type");
+  }
+  if (name.length === 0) {
+    throw new SafeSqlError("identifier must not be empty", "sql/empty");
+  }
+  if (name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' exceeds maxLength " + MAX_IDENTIFIER_LENGTH,
+      "sql/too-long"
+    );
+  }
+  if (name.indexOf("\0") >= 0) {
+    throw new SafeSqlError("identifier contains null byte", "sql/null-byte");
+  }
+  var pattern = opts.pattern || DEFAULT_IDENTIFIER_RE;
+  if (!pattern.test(name)) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' does not match required pattern " + pattern,
+      "sql/bad-shape"
+    );
+  }
+  if (!opts.allowReserved && BANNED_IDENTIFIERS.has(name.toLowerCase())) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' is a SQL reserved word",
+      "sql/reserved-word"
+    );
+  }
+  if (!opts.allowSqliteInternal && /^sqlite_/i.test(name)) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' uses the SQLite-internal 'sqlite_' prefix",
+      "sql/internal-prefix"
+    );
+  }
+  return name;
+}
+
+/**
+ * @primitive b.safeSql.quoteIdentifier
+ * @signature b.safeSql.quoteIdentifier(name, dialect?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteQualified
+ *
+ * Validate `name` then wrap it in dialect-appropriate quotes —
+ * double-quote for SQLite + Postgres (per SQL standard), backtick for
+ * MySQL. Default dialect is `"sqlite"`. Throws `SafeSqlError` if the
+ * identifier fails `validateIdentifier`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.quoteIdentifier("users");
+ *   // → '"users"'
+ *
+ *   b.safeSql.quoteIdentifier("Order", "postgres");
+ *   // → '"Order"'
+ *
+ *   b.safeSql.quoteIdentifier("users", "mysql");
+ *   // → "`users`"
+ */
+function quoteIdentifier(name, dialect) {
+  validateIdentifier(name);
+  dialect = (dialect || "sqlite").toLowerCase();
+  if (dialect === "mysql") return "`" + name + "`";
+  // sqlite + postgres both use double-quote per SQL standard
+  return '"' + name + '"';
+}
+
+/**
+ * @primitive b.safeSql.quoteQualified
+ * @signature b.safeSql.quoteQualified(parts, dialect?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.validateIdentifier
+ *
+ * Quote a multi-part qualified name like `schema.table` or
+ * `database.schema.table`. Each segment is validated and quoted
+ * independently so the resulting SQL is `"schema"."table"` (three
+ * lookups against the catalog) instead of `"schema.table"` (one
+ * literal identifier with a dot in its name — a different and
+ * usually-nonexistent object). Accepts an array of parts OR a
+ * dot-separated string.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.quoteQualified(["public", "users"]);
+ *   // → '"public"."users"'
+ *
+ *   b.safeSql.quoteQualified("public.users");
+ *   // → '"public"."users"'
+ *
+ *   b.safeSql.quoteQualified("dbA.public.users");
+ *   // → '"dbA"."public"."users"'
+ *
+ *   b.safeSql.quoteQualified(["app", "orders"], "mysql");
+ *   // → "`app`.`orders`"
+ */
+function quoteQualified(parts, dialect) {
+  var arr;
+  if (typeof parts === "string") {
+    if (parts.length === 0) {
+      throw new SafeSqlError("qualified name must not be empty", "sql/empty");
+    }
+    arr = parts.split(".");
+  } else if (Array.isArray(parts)) {
+    arr = parts.slice();
+  } else {
+    throw new SafeSqlError(
+      "qualified name must be a string or array, got " + typeof parts,
+      "sql/bad-type"
+    );
+  }
+  if (arr.length === 0) {
+    throw new SafeSqlError("qualified name must have at least one segment", "sql/empty");
+  }
+  var quoted = [];
+  for (var i = 0; i < arr.length; i++) {
+    quoted.push(quoteIdentifier(arr[i], dialect));
+  }
+  return quoted.join(".");
+}
+
+/**
+ * @primitive b.safeSql.assertOneOf
+ * @signature b.safeSql.assertOneOf(name, allowlist)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteIdentifier
+ *
+ * Closed-allowlist gate — the strongest guarantee against identifier
+ * injection. `allowlist` is a `Set` or `Array` of permitted names;
+ * anything outside throws `SafeSqlError` with `.code = "sql/not-allowed"`.
+ * Returns `name` on success so the call composes inline with
+ * `quoteIdentifier`. Use this whenever the operator-supplied identifier
+ * is drawn from a known finite set (which is most cases — table names
+ * are config, not user input).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var ALLOWED = new Set(["audit_log", "consent_log", "session"]);
+ *
+ *   b.safeSql.assertOneOf("audit_log", ALLOWED);
+ *   // → "audit_log"
+ *
+ *   try { b.safeSql.assertOneOf("users", ALLOWED); }
+ *   catch (e) { e.code; }
+ *   // → "sql/not-allowed"
+ *
+ *   // Array form works too.
+ *   b.safeSql.assertOneOf("audit_log", ["audit_log", "consent_log"]);
+ *   // → "audit_log"
+ */
+function assertOneOf(name, allowlist) {
+  if (typeof name !== "string") {
+    throw new SafeSqlError("name must be a string", "sql/bad-type");
+  }
+  // Accept either Set or array
+  var ok = false;
+  if (allowlist && typeof allowlist.has === "function") {
+    ok = allowlist.has(name);
+  } else if (Array.isArray(allowlist)) {
+    ok = allowlist.indexOf(name) !== -1;
+  } else {
+    throw new SafeSqlError("allowlist must be a Set or array", "sql/bad-allowlist");
+  }
+  if (!ok) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' not in allowlist",
+      "sql/not-allowed"
+    );
+  }
+  return name;
+}
+
+/**
+ * @primitive b.safeSql.DEFAULT_IDENTIFIER_RE
+ * @signature b.safeSql.DEFAULT_IDENTIFIER_RE
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.MAX_IDENTIFIER_LENGTH
+ *
+ * The default identifier shape regex — `/^[A-Za-z_][A-Za-z0-9_]*$/`.
+ * Exposed so operator code that needs a slightly-wider or
+ * slightly-narrower shape can compose against it instead of
+ * re-deriving the pattern. ASCII-only by design — Unicode
+ * identifiers are dialect-specific and surface in mismatched-encoding
+ * footguns we don't want to default into.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.DEFAULT_IDENTIFIER_RE.test("audit_log");
+ *   // → true
+ *
+ *   b.safeSql.DEFAULT_IDENTIFIER_RE.test("1starts_with_digit");
+ *   // → false
+ */
+
+/**
+ * @primitive b.safeSql.MAX_IDENTIFIER_LENGTH
+ * @signature b.safeSql.MAX_IDENTIFIER_LENGTH
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.DEFAULT_IDENTIFIER_RE
+ *
+ * Hard cap on identifier length — 63 characters. Matches Postgres'
+ * NAMEDATALEN default; SQLite and MySQL accept longer names but
+ * defaulting to the strictest dialect keeps cross-dialect SQL
+ * portable.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.MAX_IDENTIFIER_LENGTH;
+ *   // → 63
+ */
+
+module.exports = {
+  validateIdentifier:  validateIdentifier,
+  quoteIdentifier:     quoteIdentifier,
+  quoteQualified:      quoteQualified,
+  assertOneOf:         assertOneOf,
+  SafeSqlError:        SafeSqlError,
+  // Exposed so consumers can compose their own validators
+  DEFAULT_IDENTIFIER_RE: DEFAULT_IDENTIFIER_RE,
+  MAX_IDENTIFIER_LENGTH: MAX_IDENTIFIER_LENGTH,
+};