@blamejs/core 0.14.17 → 0.14.19

package/lib/external-db.js

@@ -44,6 +44,7 @@ var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
 var { ExternalDbError } = require("./framework-error");
 
 var log = boot("external-db");
@@ -61,7 +62,13 @@ function _emitMetric(name, value, labels) {
 // the leading keyword only so an attacker-controlled trailing fragment
 // can't smuggle a false classification. Skips leading whitespace plus
 // SQL line / block comments before reading the keyword.
-var _STATEMENT_CLASS_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|--[^\n]*\n\s*)*([A-Za-z]+)/;
+// Linear (non-backtracking) comment/whitespace skip: each iteration of
+// the outer group consumes exactly one whitespace char, one complete
+// block comment (matched with the star-not-slash form, never a lazy
+// `[\s\S]*?`), or one complete line comment — disjoint by first char,
+// so there is no ambiguous repetition for a crafted SQL string of
+// nested `/**/` or `*/--` runs to backtrack on (CWE-1333 ReDoS).
+var _STATEMENT_CLASS_RE = /^(?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/|--[^\n]*\n)*([A-Za-z]+)/;
 var _STATEMENT_CLASS_MAP = Object.freeze({
   SELECT: "SELECT", WITH: "SELECT", VALUES: "SELECT", TABLE: "SELECT",
   INSERT: "DML", UPDATE: "DML", DELETE: "DML", MERGE: "DML", UPSERT: "DML",
@@ -83,6 +90,61 @@ function _classifyStatement(sql) {
   return _STATEMENT_CLASS_MAP[m[1].toUpperCase()] || "OTHER";
 }
 
+// ---- OpenTelemetry database-client semantic conventions ----
+//
+// db.* span / metric attributes on the query / transaction / read emit
+// paths, so dashboards built on the OTel semconv correlate external-db
+// activity without a per-framework adapter. The DDL-audit side already
+// stamps these on db.ddl.executed; this mirrors the shape on the data
+// path. Reference: OpenTelemetry semantic conventions for database
+// client calls (db.system / db.operation / db.statement / db.name).
+//
+// db.system is the OTel-registered identifier for the DBMS — it is NOT
+// the framework's dialect string (Postgres is "postgresql" in the
+// registry, not "postgres"). Unknown dialects fall through to the
+// "other_sql" registry value.
+var _OTEL_DB_SYSTEM = Object.freeze({
+  postgres: "postgresql",
+  mysql:    "mysql",
+  sqlite:   "sqlite",
+  mongodb:  "mongodb",
+  other:    "other_sql",
+});
+
+// db.operation is the leading SQL keyword (SELECT / INSERT / BEGIN /
+// ...), uppercased — the OTel-conventional operation name, distinct
+// from the coarser forensic statement CLASS (_classifyStatement).
+// Reuses the comment-skipping leading-keyword regex; defensive reader,
+// returns null on anything unparseable so the attribute is simply
+// omitted rather than carrying a partial fragment.
+function _otelOperation(sql) {
+  if (typeof sql !== "string" || sql.length === 0) return null;
+  var m = _STATEMENT_CLASS_RE.exec(sql);
+  if (!m) return null;
+  return m[1].toUpperCase();
+}
+
+// db.system / db.operation / db.name carry no statement text and are
+// always emitted. db.statement is the SQL text — bound parameter values
+// are passed out-of-band to the driver (never folded in), but a caller
+// that inlines literals can still embed PII / secrets in the statement.
+// So db.statement is gated behind the SAME opts.includeSqlInAudit
+// opt-out that governs the raw `sql` audit field: the OTel attribute
+// must never re-expose statement text the operator opted out of. When
+// included it is truncated to the framework's 256-char log length.
+function _otelDbAttributes(b, sql, includeStatement) {
+  var attrs = {
+    "db.system":    _OTEL_DB_SYSTEM[b.dialect] || "other_sql",
+    "db.name":      b.name,
+  };
+  var op = _otelOperation(sql);
+  if (op !== null) attrs["db.operation"] = op;
+  if (includeStatement) {
+    attrs["db.statement"] = String(sql == null ? "" : sql).slice(0, 256);   // log-truncation length, not bytes
+  }
+  return attrs;
+}
+
 // Best-effort target-relation extractor for auth-failure forensics: the
 // table the denied role attempted to touch, so the audit row records
 // the OBJECT (SOC2 CC7.2 / NIST SP 800-53 AU-3 "what was accessed"),
@@ -321,6 +383,16 @@ class Pool {
  * `residencyTag` in the allowed-region list — refused with
  * `RESIDENCY_VIOLATION` when not.
  *
+ * Opt-in transport posture: set `requireTls: true` on a backend to
+ * refuse it at config time (`TLS_REQUIRED`) unless its declared
+ * transport is encrypted (`tls: true`, an `ssl` object, or
+ * `sslmode: "require" | "verify-ca" | "verify-full"`). `sslmode` values
+ * that permit a plaintext fallback (`prefer` / `allow` / `disable`) are
+ * refused. The gate is OFF by default — a backend that omits
+ * `requireTls` is used exactly as supplied, with no transport check.
+ * Mandated for cardholder data by PCI-DSS v4.0 Req 4 and for ePHI by
+ * HIPAA §164.312(e).
+ *
  * @opts
  *   backends:        { [name]: BackendConfig },   // required; one or more named backends
  *   defaultBackend?: string,                      // pool used when no opts.backend / classification / role match (defaults to first)
@@ -333,6 +405,8 @@ class Pool {
  *   //   ping(client):         async → void                             (optional; default `SELECT 1`)
  *   //   beginTx / commit / rollback(client):  async → void             (optional; default `BEGIN`/`COMMIT`/`ROLLBACK`)
  *   //   dialect:              "postgres" | "mysql" | "sqlite" | "mongodb" | "other"  (default "postgres")
+ *   //   requireTls:           boolean                                  (opt-in TLS posture gate; default off — see below)
+ *   //   tls / ssl / sslmode:  transport-TLS declaration consulted by requireTls (tls:true | ssl:<obj> | sslmode:"require"|"verify-ca"|"verify-full")
  *   //   applicationName:      string ≤ 63 bytes, no CR/LF/NUL          (Postgres pg_stat_activity tag; default null)
  *   //   pool:                 { min, max, idleTimeoutMs }              (defaults: 1 / 10 / C.TIME.minutes(1))
  *   //   classifications:      string[]                                 (defaults to ["*"])
@@ -387,6 +461,8 @@ function init(opts) {
         "backend '" + name + "': dialect must be one of " +
         "'postgres' | 'mysql' | 'sqlite' | 'mongodb' | 'other', got '" + dialect + "'", true);
     }
+    // requireTls posture gate (opt-in; default OFF → no behavior change).
+    _assertConnectionTls(name, cfg);
     // OWASP-3 — application_name normalization for Postgres backends.
     // Always set on every fresh connection (not just connectAs branch)
     // so pg_stat_activity / log_line_prefix / audit log surfaces show
@@ -506,6 +582,76 @@ function init(opts) {
   initialized = true;
 }
 
+// ---- requireTls posture gate (opt-in) ----
+//
+// PCI-DSS v4.0 Requirement 4 (protect cardholder data with strong
+// cryptography during transmission over open networks) and HIPAA
+// §164.312(e)(1) (transmission security — encrypt ePHI in transit)
+// both require that the connection between the app and an external
+// database is encrypted. The framework does not open the connection
+// itself — the operator supplies the driver via connect() — so the
+// posture is declared on the backend config and enforced at config
+// time.
+//
+// Default: OFF. A backend that does not set requireTls behaves exactly
+// as before — the operator-supplied connection is used as-is with no
+// gate. When requireTls is true, init() refuses the backend unless its
+// declared transport is TLS, surfacing the misconfiguration at boot
+// rather than letting plaintext credentials/PHI ride an open network.
+//
+// TLS posture is declared via any of (mirroring libpq SSLMODE / common
+// driver shapes):
+//   - tls: true                         — explicit boolean
+//   - ssl: <truthy>                      — node-postgres / mysql2 ssl object
+//   - sslmode: "require" | "verify-ca" | "verify-full"
+//
+// libpq SSLMODE semantics: only require / verify-ca / verify-full
+// GUARANTEE an encrypted channel. "prefer" and "allow" fall back to
+// plaintext when the server declines TLS, and "disable" never
+// encrypts — none of those satisfy a "must be encrypted" posture, so
+// they are refused under requireTls.
+var _TLS_GUARANTEED_SSLMODES = Object.freeze({
+  require:       true,
+  "verify-ca":   true,
+  "verify-full": true,
+});
+var _TLS_PLAINTEXT_SSLMODES = Object.freeze({
+  disable: true,
+  allow:   true,
+  prefer:  true,
+});
+
+function _declaresTls(cfg) {
+  if (cfg.tls === true) return true;
+  if (cfg.ssl !== undefined && cfg.ssl !== null && cfg.ssl !== false) return true;
+  if (typeof cfg.sslmode === "string") {
+    return _TLS_GUARANTEED_SSLMODES[cfg.sslmode.toLowerCase()] === true;
+  }
+  return false;
+}
+
+function _assertConnectionTls(name, cfg) {
+  // Opt-in: absent requireTls → no gate, no behavior change.
+  if (cfg.requireTls === undefined || cfg.requireTls === null) return;
+  validateOpts.optionalBoolean(cfg.requireTls,
+    "backend '" + name + "': requireTls", ExternalDbError, "INVALID_CONFIG");
+  if (cfg.requireTls !== true) return;
+  if (_declaresTls(cfg)) return;
+  var declared;
+  if (typeof cfg.sslmode === "string" && _TLS_PLAINTEXT_SSLMODES[cfg.sslmode.toLowerCase()]) {
+    declared = "sslmode '" + cfg.sslmode +
+      "' permits a plaintext fallback (only 'require' / 'verify-ca' / 'verify-full' guarantee encryption)";
+  } else if (cfg.tls === false || cfg.ssl === false) {
+    declared = "transport is declared non-TLS (tls/ssl is false)";
+  } else {
+    declared = "no TLS transport is declared (set tls: true, an ssl object, or sslmode: 'require' / 'verify-ca' / 'verify-full')";
+  }
+  throw _err("TLS_REQUIRED",
+    "backend '" + name + "': requireTls is set but " + declared +
+    ". PCI-DSS v4.0 Req 4 / HIPAA §164.312(e) require an encrypted channel " +
+    "for cardholder data / ePHI in transit.", true);
+}
+
 function _validateResidency() {
   var residency;
   try { residency = db().getDataResidency(); } catch (_e) { residency = null; }
@@ -634,7 +780,7 @@ async function query(sql, params, opts) {
     }, b.retryConfig);
 
     var durationMs = Date.now() - t0;
-    _emit("system.externaldb.query", "success", {
+    _emit("system.externaldb.query", "success", Object.assign({
       backend:        b.name,
       role:           role,
       durationMs:     durationMs,
@@ -645,7 +791,7 @@ async function query(sql, params, opts) {
       // metadata pass opts.includeSqlInAudit: true (then sealed via
       // field-crypto on the audit row).
       sql:            opts.includeSqlInAudit ? sql : null,
-    });
+    }, _otelDbAttributes(b, sql, opts.includeSqlInAudit)));
     _emitMetric("externaldb.query.success", 1,
       { backend: b.name, role: role || "(none)" });
     _emitMetric("externaldb.query.duration_ms", durationMs,
@@ -654,13 +800,13 @@ async function query(sql, params, opts) {
     return result;
   } catch (e) {
     var failureMs = Date.now() - t0;
-    _emit("system.externaldb.query", "failure", {
+    _emit("system.externaldb.query", "failure", Object.assign({
       backend:        b.name,
       role:           role,
       durationMs:     failureMs,
       classification: opts.classification || null,
       errorCode:      e.code || null,
-    }, (e && e.message) || String(e));
+    }, _otelDbAttributes(b, sql, opts.includeSqlInAudit)), (e && e.message) || String(e));
     _emitMetric("externaldb.query.failure", 1,
       { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
     _emitSlowQuery(b.name, role, failureMs, _classifyStatement(sql));
@@ -787,10 +933,15 @@ async function transaction(fn, opts) {
           await b.commit(client);
           committed = true;
           var durationMs = Date.now() - t0;
-          _emit("system.externaldb.transaction", "success", {
+          // OTel db.* semconv on the transaction span. The body runs N
+          // statements via tx.query; the span describes the unit of work,
+          // so db.operation reads "BEGIN" (the OTel-conventional marker
+          // for a transaction-scoped span) rather than any one inner
+          // statement.
+          _emit("system.externaldb.transaction", "success", Object.assign({
             backend: b.name, role: role, durationMs: durationMs,
             classification: opts.classification || null,
-          });
+          }, _otelDbAttributes(b, "BEGIN", opts.includeSqlInAudit)));
           _emitMetric("externaldb.transaction.success", 1,
             { backend: b.name, role: role || "(none)" });
           _emitMetric("externaldb.transaction.duration_ms", durationMs,
@@ -807,11 +958,11 @@ async function transaction(fn, opts) {
             continue;
           }
           var failureMs = Date.now() - t0;
-          _emit("system.externaldb.transaction", "failure", {
+          _emit("system.externaldb.transaction", "failure", Object.assign({
             backend: b.name, role: role, durationMs: failureMs,
             classification: opts.classification || null,
             errorCode: txErr.code || null,
-          }, (txErr && txErr.message) || String(txErr));
+          }, _otelDbAttributes(b, "BEGIN", opts.includeSqlInAudit)), (txErr && txErr.message) || String(txErr));
           _emitMetric("externaldb.transaction.failure", 1,
             { backend: b.name, role: role || "(none)", errorCode: txErr.code || "(none)" });
           if (txErr && txErr.code === "42501") {
@@ -1202,13 +1353,13 @@ async function _readQuery(sql, params, opts) {
       replica.pool.release(client);
       replica.consecutiveFailures = 0;
       var durationMs = Date.now() - t0;
-      _emit("system.externaldb.read", "success", {
+      _emit("system.externaldb.read", "success", Object.assign({
         backend:    b.name,
         role:       role,
         replicaIdx: replica.index,
         durationMs: durationMs,
         rowCount:   res && res.rowCount,
-      });
+      }, _otelDbAttributes(b, sql, opts.includeSqlInAudit)));
       _emitMetric("externaldb.read.success", 1,
         { backend: b.name, role: role || "(none)", replicaIdx: replica.index });
       _emitMetric("externaldb.read.duration_ms", durationMs,
@@ -1228,13 +1379,13 @@ async function _readQuery(sql, params, opts) {
       throw e;
     }
   } catch (e) {
-    _emit("system.externaldb.read", "failure", {
+    _emit("system.externaldb.read", "failure", Object.assign({
       backend:    b.name,
       role:       role,
       replicaIdx: replica.index,
       durationMs: Date.now() - t0,
       errorCode:  e.code || null,
-    }, (e && e.message) || String(e));
+    }, _otelDbAttributes(b, sql, opts.includeSqlInAudit)), (e && e.message) || String(e));
     _emitMetric("externaldb.read.failure", 1,
       { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
     if (e && e.code === "42501") {

package/lib/guard-email.js

@@ -6,8 +6,9 @@
  *
  * @intro
  *   RFC 822 / 5322 single-address validator + RFC 5322 message gate
- *   with header-injection defense, EAI / SMTPUTF8 support, label
- *   length caps, IP-literal denial, and sub-address handling.
+ *   with header-injection defense, domain-side IDN / Punycode
+ *   handling, mixed-script confusable detection, label length caps,
+ *   IP-literal denial, and sub-address handling.
  *
  *   Two entry shapes:
  *     - `validateAddress(addr, opts)` — single mailbox (RFC 5321
@@ -15,6 +16,20 @@
  *       domain 255 / address 320. Flags multi-`@`, IP literals,
  *       Punycode, mixed-script confusables, and codepoint-class
  *       threats (BIDI / control / null / zero-width).
+ *
+ *   Scope of Unicode handling: the DOMAIN side recognizes IDN /
+ *   Punycode (`xn--`) labels and mixed-script confusables, gated by
+ *   `allowedScripts` (RFC 5890 / RFC 5891). The LOCAL part is
+ *   ASCII atext only (RFC 5321 §4.1.2 / RFC 5322 §3.2.3) — a unicode
+ *   mailbox (RFC 6531 SMTPUTF8 / EAI) is NOT accepted and surfaces as
+ *   an `address-syntax` issue. This is deliberate: a unicode
+ *   local-part widens the homograph / confusable attack surface
+ *   beyond the domain (where registry IDN policy and Punycode
+ *   normalization apply) into the unregulated mailbox name, where no
+ *   equivalent normalization authority exists. RFC 6531 local-part
+ *   acceptance re-opens behind an explicit `allowUnicodeLocalPart`
+ *   opt-in when operator demand for genuine EAI mailboxes lands;
+ *   until then the conservative ASCII contract holds by default.
  *     - `validateMessage(rfc822, opts)` — full RFC 5322 message.
  *       Splits header section, unfolds folded headers, walks every
  *       single-line header for embedded CR/LF, drives address checks
@@ -32,7 +47,7 @@
  *   sanitization is safe.
  *
  * @card
- *   RFC 822 / 5322 single-address validator + RFC 5322 message gate with header-injection defense, EAI / SMTPUTF8 support, label length caps, IP-literal denial, and sub-address handling.
+ *   RFC 822 / 5322 single-address validator + RFC 5322 message gate with header-injection defense, domain-side IDN / Punycode and mixed-script confusable detection (ASCII-only local-part), label length caps, IP-literal denial, and sub-address handling.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -99,6 +114,15 @@ function _hasCrlfInHeaderValue(value) {
 // can produce a useful local-part-cap issue (instead of failing the
 // regex first and surfacing address-syntax). RFC 5321 cap is enforced
 // downstream via opts.maxLocalPartBytes.
+//
+// The local-part class is ASCII atext only — the printable-ASCII set
+// of RFC 5321 §4.1.2 / RFC 5322 §3.2.3. A unicode (non-ASCII)
+// local-part per RFC 6531 (SMTPUTF8 / EAI) is intentionally NOT
+// matched: it fails this regex and surfaces as an `address-syntax`
+// issue. Domain-side Unicode is handled separately (Punycode + mixed-
+// script detection, gated by allowedScripts). Keeping the local-part
+// ASCII avoids extending homograph / confusable exposure into the
+// mailbox name, which has no registry-level normalization authority.
 var _LOCAL = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+";
 var _LABEL = "[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?";
 var _DOMAIN = "(?:" + _LABEL + "(?:\\." + _LABEL + ")+)";
@@ -445,6 +469,15 @@ function _detectAddressIssues(input, opts) {
  * Cyrillic / Greek / Armenian / Cherokee), strict-ASCII regex shape,
  * and codepoint-class threats (BIDI / null / control / zero-width).
  *
+ * The local-part is validated as ASCII atext only (RFC 5321 §4.1.2 /
+ * RFC 5322 §3.2.3). A unicode local-part (RFC 6531 SMTPUTF8 / EAI)
+ * is rejected as an `address-syntax` issue — keeping the mailbox name
+ * ASCII bounds homograph / confusable exposure to the domain side,
+ * where Punycode normalization and `allowedScripts` gating apply.
+ * RFC 6531 local-part acceptance re-opens behind a future explicit
+ * `allowUnicodeLocalPart` opt-in on operator demand. Domain-side
+ * IDN / Punycode and mixed-script handling are already supported.
+ *
  * @opts
  *   profile:                 "strict" | "balanced" | "permissive",
  *   compliancePosture:       "hipaa" | "pci-dss" | "gdpr" | "soc2",