@blamejs/core 0.9.46 → 0.10.1

package/lib/mail-spam-score.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * @module     b.mail.spamScore
+ * @nav        Mail
+ * @title      Mail Spam Score
+ * @order      557
+ *
+ * @intro
+ *   Operator-supplied spam scorer facade. The framework deliberately
+ *   does NOT vendor a spam-classifier engine — the bayes corpora,
+ *   URIBL caches, neural models, and per-recipient training are all
+ *   operator state. Instead, `b.mail.spamScore.create` wraps the
+ *   operator's chosen scorer (SpamAssassin via spamc, Rspamd HTTP
+ *   API, Cloudmark, Vade, in-house) in a uniform threshold-driven
+ *   verdict pipeline that the MX listener (v0.9.45) and submission
+ *   listener (v0.9.47) consume.
+ *
+ *   ## Operator-supplied scorer contract
+ *
+ *   ```
+ *   async function scorer({ rawBytes, headers, envelope }) {
+ *     // call out to SpamAssassin / Rspamd / commercial scorer
+ *     return { score: 7.3, reasons: ["BAYES_99", "URIBL_RED"] };
+ *   }
+ *   ```
+ *
+ *   - `score` MUST be a finite number (any range; the threshold is
+ *     operator-tuned). Negative scores mean "ham-shaped"; positive
+ *     scores mean "spam-shaped". Convention matches SpamAssassin.
+ *   - `reasons` MUST be an Array of short ASCII tags. The facade caps
+ *     each tag at 256 bytes and refuses control bytes; the cap protects
+ *     audit storage + outbound headers (`X-Spam-Status: ...`) from
+ *     hostile expansion via a compromised scorer.
+ *
+ *   ## Thresholds
+ *
+ *   - **strict** — 5.0 (matches SpamAssassin's default `required_score`).
+ *   - **balanced** — 7.5.
+ *   - **permissive** — 10.0.
+ *
+ *   Operators tune via `opts.threshold` per-instance. The verdict is
+ *   `"accept"` (score < threshold), `"score-tag"` (score === threshold —
+ *   add `X-Spam-Status` header but deliver), or `"refuse"`
+ *   (score > threshold — return SMTP 550).
+ *
+ *   ## Composition
+ *
+ *   - **`b.audit`** receives every `score` / `accept` / `score_tag` /
+ *     `refuse` decision. Audit failure is drop-silent (hot path).
+ *
+ *   ## Threat model
+ *
+ *   - **Hostile reason-tag** (compromised scorer injects CRLF into a
+ *     tag, smuggling extra `X-Spam-*` headers into the outbound
+ *     wrapper): defended by per-tag length cap + control-byte refusal.
+ *   - **NaN / Infinity score** (scorer bug): refused as
+ *     `mail-spam-score/bad-score`; the listener treats the message as
+ *     unscanned (operator's tempfail policy applies).
+ *   - **Slow scorer DoS**: the scorer function is operator code, so
+ *     timing belongs to the operator. The listener wraps the
+ *     `.score()` promise in its own per-connection deadline.
+ *
+ * @card
+ *   Threshold-driven spam-scorer facade. Operator wires SpamAssassin /
+ *   Rspamd / commercial scorer; the framework owns the verdict
+ *   pipeline + reason-tag hardening + audit emission. Three default
+ *   thresholds (strict 5.0 / balanced 7.5 / permissive 10.0).
+ */
+
+var { defineClass }   = require("./framework-error");
+var lazyRequire       = require("./lazy-require");
+var validateOpts      = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var MailSpamScoreError = defineClass("MailSpamScoreError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+// allow:raw-byte-literal — reason-tag length cap defends outbound
+// header / audit-store from hostile expansion via compromised scorer.
+var MAX_REASON_BYTES = 256;
+
+// allow:raw-byte-literal — reason-list count cap, defends audit volume.
+var MAX_REASONS = 32;
+
+var PROFILES = Object.freeze({
+  strict:     { threshold: 5.0,  maxReasons: MAX_REASONS, maxReasonBytes: MAX_REASON_BYTES },      // allow:raw-byte-literal — matches SpamAssassin default required_score
+  balanced:   { threshold: 7.5,  maxReasons: MAX_REASONS, maxReasonBytes: MAX_REASON_BYTES },
+  permissive: { threshold: 10.0, maxReasons: MAX_REASONS, maxReasonBytes: MAX_REASON_BYTES },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.mail.spamScore.create
+ * @signature b.mail.spamScore.create(opts)
+ * @since     0.9.81
+ * @status    stable
+ * @related   b.mail.scan.create
+ *
+ * Build a spam-score handle. Returns `{ score(message, opts),
+ * threshold, profile, MailSpamScoreError }` where `.score` resolves to
+ * `{ score, reasons, verdict }`. `verdict` is `"accept"` /
+ * `"score-tag"` / `"refuse"` based on threshold comparison.
+ *
+ * @opts
+ *   scorer:    async fn({ rawBytes, headers, envelope }) → { score, reasons } — required
+ *   threshold: number — overrides profile default
+ *   profile:   "strict" | "balanced" | "permissive"
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2"
+ *   audit:     b.audit instance
+ *
+ * @example
+ *   var spam = b.mail.spamScore.create({
+ *     scorer: async function (ctx) {
+ *       return await callSpamAssassin(ctx.rawBytes);
+ *     },
+ *   });
+ *   var v = await spam.score({ rawBytes: msg });
+ *   if (v.verdict === "refuse") refuseConnection(v.reasons.join(","));
+ */
+function create(opts) {
+  opts = validateOpts.requireObject(opts || {}, "mail.spamScore.create",
+    MailSpamScoreError, "mail-spam-score/bad-opts");
+  validateOpts(opts, [
+    "scorer", "threshold", "profile", "posture", "audit",
+  ], "mail.spamScore.create");
+  if (typeof opts.scorer !== "function") {
+    throw new MailSpamScoreError("mail-spam-score/bad-scorer",
+      "mail.spamScore.create.scorer must be a function; got " + (typeof opts.scorer));
+  }
+  var profile = opts.profile || (opts.posture && COMPLIANCE_POSTURES[opts.posture]) || DEFAULT_PROFILE;
+  if (!PROFILES[profile]) {
+    throw new MailSpamScoreError("mail-spam-score/bad-profile",
+      "mail.spamScore.create.profile: unknown '" + profile +
+      "' (valid: strict / balanced / permissive)");
+  }
+  var caps = PROFILES[profile];
+  var threshold;
+  if (opts.threshold !== undefined) {
+    if (typeof opts.threshold !== "number" || !isFinite(opts.threshold)) {
+      throw new MailSpamScoreError("mail-spam-score/bad-threshold",
+        "mail.spamScore.create.threshold must be a finite number; got " +
+        (typeof opts.threshold) + " " + String(opts.threshold));
+    }
+    threshold = opts.threshold;
+  } else {
+    threshold = caps.threshold;
+  }
+  var auditImpl = opts.audit || audit();
+
+  async function score(message) {
+    if (!message || typeof message !== "object") {
+      throw new MailSpamScoreError("mail-spam-score/bad-input",
+        "mail.spamScore.score: message must be an object with rawBytes/headers/envelope");
+    }
+    var rv;
+    try {
+      rv = await opts.scorer({
+        rawBytes: message.rawBytes,
+        headers:  message.headers || {},
+        envelope: message.envelope || {},
+      });
+    } catch (e) {
+      _emitAudit(auditImpl, "mail.spam_score.error", "failure", {
+        message: (e && e.message) || String(e),
+      });
+      throw new MailSpamScoreError("mail-spam-score/scorer-threw",
+        "mail.spamScore.score: scorer threw: " + ((e && e.message) || e));
+    }
+    if (!rv || typeof rv !== "object") {
+      throw new MailSpamScoreError("mail-spam-score/bad-result",
+        "mail.spamScore.score: scorer must return { score, reasons }; got " +
+        (typeof rv));
+    }
+    if (typeof rv.score !== "number" || !isFinite(rv.score)) {
+      throw new MailSpamScoreError("mail-spam-score/bad-score",
+        "mail.spamScore.score: scorer returned non-finite score=" + String(rv.score));
+    }
+    var reasons = _sanitizeReasons(rv.reasons, caps);
+
+    var verdict;
+    if (rv.score < threshold)       verdict = "accept";
+    else if (rv.score === threshold) verdict = "score-tag";
+    else                              verdict = "refuse";
+
+    _emitAudit(auditImpl, "mail.spam_score.score", "success", {
+      score: rv.score, threshold: threshold, verdict: verdict, reasons: reasons,
+    });
+    if (verdict === "accept") {
+      _emitAudit(auditImpl, "mail.spam_score.accept", "success", { score: rv.score });
+    } else if (verdict === "score-tag") {
+      _emitAudit(auditImpl, "mail.spam_score.score_tag", "success",
+        { score: rv.score, reasons: reasons });
+    } else {
+      _emitAudit(auditImpl, "mail.spam_score.refuse", "success",
+        { score: rv.score, reasons: reasons });
+    }
+    return { score: rv.score, reasons: reasons, verdict: verdict };
+  }
+
+  return {
+    score:                score,
+    threshold:            threshold,
+    profile:              profile,
+    MailSpamScoreError:   MailSpamScoreError,
+  };
+}
+
+/**
+ * @primitive b.mail.spamScore.compliancePosture
+ * @signature b.mail.spamScore.compliancePosture(posture)
+ * @since     0.9.81
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.mail.spamScore.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _sanitizeReasons(reasons, caps) {
+  if (reasons === undefined || reasons === null) return [];
+  if (!Array.isArray(reasons)) {
+    throw new MailSpamScoreError("mail-spam-score/bad-reasons",
+      "mail.spamScore.score: scorer returned non-array reasons (" + (typeof reasons) + ")");
+  }
+  if (reasons.length > caps.maxReasons) {
+    throw new MailSpamScoreError("mail-spam-score/too-many-reasons",
+      "mail.spamScore.score: scorer returned " + reasons.length +
+      " reasons; cap is " + caps.maxReasons);
+  }
+  var out = [];
+  for (var i = 0; i < reasons.length; i += 1) {
+    var r = reasons[i];
+    if (typeof r !== "string" || r.length === 0) {
+      throw new MailSpamScoreError("mail-spam-score/bad-reason",
+        "mail.spamScore.score: reasons[" + i + "] must be a non-empty string");
+    }
+    if (Buffer.byteLength(r, "utf8") > caps.maxReasonBytes) {
+      throw new MailSpamScoreError("mail-spam-score/oversize-reason",
+        "mail.spamScore.score: reasons[" + i + "] exceeds " + caps.maxReasonBytes + " bytes");
+    }
+    // Refuse control bytes (CR / LF / NUL / etc.) — a compromised
+    // scorer could try to smuggle CRLF into an outbound X-Spam-Status
+    // header.
+    for (var c = 0; c < r.length; c += 1) {
+      var cc = r.charCodeAt(c);
+      if (cc < 0x20 || cc === 0x7f) {                                                              // allow:raw-byte-literal — RFC 5234 CTL refusal range
+        throw new MailSpamScoreError("mail-spam-score/control-byte",
+          "mail.spamScore.score: reasons[" + i + "] contains control byte 0x" +
+          cc.toString(16));                                                                        // allow:raw-byte-literal — hex radix
+      }
+    }
+    out.push(r);
+  }
+  return out;
+}
+
+function _emitAudit(auditImpl, action, outcome, metadata) {
+  try {
+    if (auditImpl && typeof auditImpl.safeEmit === "function") {
+      auditImpl.safeEmit({ action: action, outcome: outcome, metadata: metadata });
+    }
+  } catch (_e) { /* drop-silent — audit failures don't break score path */ }
+}
+
+module.exports = {
+  create:                create,
+  compliancePosture:     compliancePosture,
+  PROFILES:              PROFILES,
+  COMPLIANCE_POSTURES:   COMPLIANCE_POSTURES,
+  MailSpamScoreError:    MailSpamScoreError,
+};

package/lib/mail.js

@@ -59,6 +59,7 @@ var C = require("./constants");
 var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var safeBuffer = require("./safe-buffer");
+var guardDomain = require("./guard-domain");
 var audit = lazyRequire(function () { return require("./audit"); });
 var httpClient = lazyRequire(function () { return require("./http-client"); });
 var guardEmail = lazyRequire(function () { return require("./guard-email"); });
@@ -770,6 +771,28 @@ function smtpTransport(opts) {
   var useImplicitTLS = port === 465 || opts.implicitTls === true;
   var rejectUnauthorized = opts.rejectUnauthorized !== false;
   var ehloName = opts.ehloName || "blamejs";
+  // GHSA-c7w3-x93f-qmm8 / GHSA-vvjj-xcjg-gr5g (nodemailer CRLF-injection
+  // class) — any string concatenated into an outbound SMTP wire command
+  // MUST be CRLF/NUL-free, otherwise an attacker who can shape ehloName /
+  // user / pass / host (via config injection or template indirection)
+  // gets to inject a fresh EHLO / MAIL FROM / RCPT TO line. Refuse at
+  // config-time so the operator's boot dies at the misconfiguration line
+  // rather than silently emitting a smuggled command at first send.
+  function _refuseCtlBytes(label, val) {
+    if (val === undefined || val === null) return;
+    if (typeof val !== "string") return;
+    if (/[\r\n\0]/.test(val)) {                                                                            // allow:regex-no-length-cap — CRLF/NUL is a 3-codepoint class
+      throw new MailError("mail/smtp-misconfigured",
+        "smtp transport: opts." + label + " contains CR/LF/NUL bytes " +
+        "(SMTP command-injection class — GHSA-c7w3-x93f-qmm8 / GHSA-vvjj-xcjg-gr5g)",
+        true);
+    }
+  }
+  _refuseCtlBytes("ehloName",   ehloName);
+  _refuseCtlBytes("user",       opts.user);
+  _refuseCtlBytes("pass",       opts.pass);
+  _refuseCtlBytes("host",       opts.host);
+  _refuseCtlBytes("servername", opts.servername);
   var timeoutMs = opts.timeoutMs || C.TIME.seconds(15);
   var tlsOpts = {
     rejectUnauthorized: rejectUnauthorized,
@@ -1557,6 +1580,7 @@ function create(opts) {
   validateOpts(opts, [
     "transport", "defaults", "audit",
     "commercial", "postalAddress", "footerSeparator", "footerHtml", "regulated",
+    "guardDomain", "profile",
   ], "mail");
   var transport = opts.transport || consoleTransport();
   if (typeof transport === "function") {
@@ -1569,6 +1593,68 @@ function create(opts) {
   var defaults = opts.defaults || {};
   var auditOn = opts.audit !== false;
 
+  // Default-on guardDomain hardening for every outbound recipient + the
+  // sender address. Refuses CVE-2017-5469-class IDN homograph spoofs in
+  // recipient or from domains, RFC 6761 special-use domain names
+  // (`.localhost`, `.test`, `.invalid`, `.example`) in production sends,
+  // RFC 1035 §2.3.4 label-length violations, and CVE-2021-22931-class
+  // bare-IP-as-domain (DNS-rebinding allowlist-bypass class). Operators
+  // sending to address literals (`<x@[1.2.3.4]>`) — rare; mostly mailing-
+  // list internals — pass `guardDomain: false` to opt out, or pass
+  // `guardDomain: { profile: "permissive" }` to relax the rules.
+  var guardDomainProfileName;
+  if (opts.guardDomain === false) {
+    guardDomainProfileName = null;
+  } else {
+    guardDomainProfileName = opts.guardDomain && typeof opts.guardDomain === "object"
+      ? (opts.guardDomain.profile || opts.profile || "strict")
+      : (opts.profile || "strict");
+  }
+  function _validateAddrDomain(addr, label) {
+    if (!guardDomainProfileName) return;
+    if (typeof addr !== "string") return;
+    // RFC 5322 §3.4 angle-bracket address (`name <local@dom>`) — extract
+    // the inner address via indexOf/lastIndexOf rather than a regex so
+    // we stay linear on input shape (CodeQL js/polynomial-redos class).
+    var ltIdx = addr.indexOf("<");
+    var gtIdx = addr.lastIndexOf(">");
+    var rawAddr = (ltIdx !== -1 && gtIdx > ltIdx)
+      ? addr.slice(ltIdx + 1, gtIdx)
+      : addr;
+    var atIdx = rawAddr.lastIndexOf("@");
+    if (atIdx === -1) return;
+    var domain = rawAddr.slice(atIdx + 1).trim();
+    // RFC 5321 §4.1.3 address-literal form `[1.2.3.4]` / `[IPv6:...]`
+    // — already a syntactic constraint via the brackets; b.guardDomain
+    // refuses bare IPs without brackets which is the security-relevant
+    // shape (CVE-2021-22931 DNS rebinding allowlist-bypass).
+    if (domain.length === 0 || domain[0] === "[") return;
+    // RFC 5891 ToASCII — convert any IDN labels to Punycode BEFORE
+    // guardDomain validation so EAI (RFC 6531) addresses like
+    // `<x@münchen.example>` pass under strict (which refuses raw
+    // Unicode labels per RFC 5891 §4.2 transport-safety rule). The
+    // SMTPUTF8 wire encoding is the transport's concern; the gate
+    // here runs on a transport-safe form.
+    var asciiDomain = toAscii(domain) || domain;
+    // Override punycodePolicy — `xn--…` labels are RFC 5891-encoded
+    // IDNs and the whole point of EAI (RFC 6531) is to deliver to
+    // them. The strict profile defaults to refusing Punycode (the
+    // generic "operator typed a homograph" defense); for mail.send
+    // we've already gone through RFC 5891 ToASCII, so the Punycode
+    // is structural, not a homograph attempt. All other strict
+    // defenses (mixed-script, BIDI, control, IP-literal, special-
+    // use, wildcard, DGA, raw-unicode pre-conversion) remain.
+    var verdict = guardDomain.validate(asciiDomain, {
+      profile:        guardDomainProfileName,
+      punycodePolicy: "allow",
+    });
+    if (!verdict.ok) {
+      throw new MailError("mail/recipient-domain-refused",
+        "mail.send: " + label + " domain '" + domain + "' refused by b.guardDomain (" +
+        (verdict.issues && verdict.issues[0] && verdict.issues[0].kind) + ")", true);
+    }
+  }
+
   // CAN-SPAM Act §7704(a)(5) — every commercial-content message MUST
   // include the sender's valid physical postal address. Validate the
   // address shape at create() so a typo / blank field surfaces at boot,
@@ -1698,6 +1784,19 @@ function create(opts) {
 
     _validateMessage(merged);
 
+    // Default-on guardDomain hardening on every recipient + the sender
+    // address (see closure setup above). Skipped when operator opts out
+    // via guardDomain:false.
+    if (guardDomainProfileName) {
+      _validateAddrDomain(merged.from, "from");
+      var _toArr  = _normalizeRecipientList(merged.to,  "to");
+      var _ccArr  = _normalizeRecipientList(merged.cc,  "cc");
+      var _bccArr = _normalizeRecipientList(merged.bcc, "bcc");
+      for (var _ti = 0; _ti < _toArr.length;  _ti += 1) _validateAddrDomain(_toArr[_ti],  "to");
+      for (var _ci = 0; _ci < _ccArr.length;  _ci += 1) _validateAddrDomain(_ccArr[_ci],  "cc");
+      for (var _bi = 0; _bi < _bccArr.length; _bi += 1) _validateAddrDomain(_bccArr[_bi], "bcc");
+    }
+
     var t0 = Date.now();
     try {
       var result = await transport.send(merged);

package/lib/metrics.js

@@ -142,12 +142,70 @@ function _normalizeLabelArg(callLabels, value, defaultValue) {
   };
 }
 
+// CRYPTO-18 — credential-shape detector. Operators routinely tap their
+// own observability with `{ token: req.headers.authorization }` or
+// `{ apiKey: req.headers["x-api-key"] }`, which then leak through the
+// /metrics scrape surface to any reader of the metrics endpoint. The
+// detector refuses (replaces with `[REDACTED-CREDENTIAL]`) any value
+// matching well-known credential shapes:
+//
+//   - "Bearer <token>" / "Basic <base64>" / "Negotiate <token>" — RFC
+//     6750 / 7617 / 4559 wire forms
+//   - "Token <opaque>" — common GitLab / Trello convention
+//   - "sk-" / "pk-" / "rk-" prefixes — Stripe, OpenAI, modern issuers
+//   - "ghp_" / "ghs_" / "github_pat_" — GitHub
+//   - JWT shape: header.payload.signature (each segment base64url with
+//     length >= 8)
+//   - High-entropy long strings (>= 40 chars, hex / base64-shape) are
+//     a heuristic fallback so unknown-issuer tokens still get caught
+var _CRED_PREFIX_RE = /^(?:Bearer|Basic|Negotiate|Token|Digest)\s+\S/i;
+var _CRED_ISSUER_RE = /^(?:sk-|pk-|rk-|ghp_|ghs_|gho_|github_pat_|xoxb-|xoxa-|xoxp-|xoxr-|xapp-)/;
+var _CRED_JWT_RE    = /^[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;                   // allow:raw-byte-literal — JWT segment min length
+var _CRED_ENTROPY_RE = /^[A-Za-z0-9_+/=-]{40,}$/;                                                    // allow:raw-byte-literal — high-entropy length floor
+
+// CRED_MAX_SCAN — upper bound on the byte slice the credential
+// detector inspects. Operator-supplied label values longer than this
+// are still REDACTED (a 4 KiB token that opens with a Bearer prefix is
+// still a credential), but the regex tests run on the prefix slice so
+// a 1 GB string can't ReDoS the scanner. Counter cardinality stays
+// stable: the same long string always maps to the same prefix slice.
+var CRED_MAX_SCAN = 256;                                                                             // allow:raw-byte-literal — prefix-scan length cap
+
+function _looksLikeCredential(str) {
+  if (typeof str !== "string") return false;
+  if (str.length < 8) return false;                                                                  // allow:raw-byte-literal — minimum credential length floor
+  // Clamp to the prefix slice so a hostile label value can't push the
+  // regex into superlinear time. All four credential shapes have
+  // signature in the first ~256 bytes; Stripe / GitHub / OpenAI tokens
+  // are <64 bytes, JWTs are typically <2 KiB but the header + first
+  // payload segment fit in the prefix.
+  var clamped = str.length > CRED_MAX_SCAN ? str.slice(0, CRED_MAX_SCAN) : str;
+  // CRED_MIN_LEN — credential shapes shorter than 8 chars don't carry
+  // enough entropy to be real tokens; hoisted to a named constant so
+  // every test() has its length floor visible at the call site
+  // (testFormatValidatorLengthCap convention).
+  var CRED_MIN_LEN = 8;                                                                              // allow:raw-byte-literal — minimum credential length floor
+  if (clamped.length >= CRED_MIN_LEN && _CRED_PREFIX_RE.test(clamped)) return true;
+  if (clamped.length >= CRED_MIN_LEN && _CRED_ISSUER_RE.test(clamped)) return true;
+  if (clamped.length >= CRED_MIN_LEN && _CRED_JWT_RE.test(clamped)) return true;
+  if (clamped.length >= CRED_MIN_LEN && _CRED_ENTROPY_RE.test(clamped)) return true;
+  return false;
+}
+
 function _validateLabelValue(value) {
   // Prometheus exposition: label values are quoted strings; backslash,
   // newline, double-quote get escaped at serialize time. Coerce here so
   // counters indexed by various input types still work.
   if (value === null || value === undefined) return "";
-  return String(value);
+  var coerced = String(value);
+  // CRYPTO-18 — credential-shape detector. Operators who tap their
+  // observability with raw header values leak bearer tokens / API
+  // keys through /metrics to every scrape reader. Refuse the value
+  // and surface a redaction marker so the metric still labels (so
+  // counter cardinality doesn't collapse to a single empty-string
+  // bucket) but the bytes themselves never reach the scrape stream.
+  if (_looksLikeCredential(coerced)) return "[REDACTED-CREDENTIAL]";
+  return coerced;
 }
 
 // Serialize a labels object to a canonical Map key. Routed through
@@ -725,6 +783,7 @@ function _resetForTest() {
  *   path:        string,    // absolute path to write the snapshot
  *   intervalMs:  number,    // milliseconds between flushes (>=100)
  *   fields:      Function,  // returns an object — written as JSON
+ *   fileMode:    number,    // POSIX mode (default 0o640 — owner rw, group r)
  *
  * @example
  *   var stop = b.metrics.snapshot.startWriter({
@@ -757,6 +816,17 @@ function snapshotStartWriter(opts) {
   var p          = opts.path;
   var fieldsFn   = opts.fields;
   var intervalMs = opts.intervalMs;
+  // CRYPTO-6 — file mode for the atomic write. Default 0o640
+  // (owner rw, group r, world none). Operators with a sidecar
+  // reader in a different group override to 0o644; multi-tenant
+  // hosts may even tighten to 0o600.
+  var fileMode = opts.fileMode !== undefined ? opts.fileMode : 0o640;                                // allow:raw-byte-literal — POSIX file mode octal
+  if (typeof fileMode !== "number" || !isFinite(fileMode) ||
+      fileMode < 0 || fileMode > 0o777 || Math.floor(fileMode) !== fileMode) {
+    throw new MetricsError("metrics-snapshot/bad-file-mode",
+      "metrics.snapshot.startWriter: opts.fileMode must be a POSIX file-mode integer in [0, 0o777], got " +
+      fileMode);
+  }
 
   var doFlush = function () {
     var snap;
@@ -775,7 +845,12 @@ function snapshotStartWriter(opts) {
       fields:    snap,
     };
     try {
-      atomicFile.writeSync(p, JSON.stringify(payload) + "\n", { fileMode: 0o644 });
+      // CRYPTO-6 — default 0o640 (owner rw, group r, world none) so
+      // operator-supplied snapshot fields aren't world-readable on a
+      // multi-tenant host. Operators with a sidecar reader running as
+      // a different group override via opts.fileMode at startWriter
+      // construction.
+      atomicFile.writeSync(p, JSON.stringify(payload) + "\n", { fileMode: fileMode });
     } catch (e) {
       log("snapshot.writeSync failed: " + (e && e.message ? e.message : String(e)));
     }
@@ -829,7 +904,9 @@ function snapshotRead(p) {
   // is well above the framework's expected snapshot size (~5-50 KiB)
   // and the safeJson absolute cap stays within reach.
   try {
-    parsed = safeJson.parse(raw, { maxBytes: 4 * 1024 * 1024 });   // allow:raw-byte-literal — 4 MiB snapshot-file ceiling
+    // CRYPTO-21 — route through C.BYTES.mib(4); the raw byte literal
+    // was a drift smell flagged by codebase-patterns.
+    parsed = safeJson.parse(raw, { maxBytes: C.BYTES.mib(4) });
   } catch (e) {
     throw new MetricsError("metrics-snapshot/bad-json",
       "metrics.snapshot.read: " + p + " contains invalid JSON: " + (e && e.message ? e.message : String(e)));
@@ -853,18 +930,43 @@ function snapshotRead(p) {
  * Format a snapshot object for human or machine consumption.
  *
  *   format: "text"       — operator-readable lines, one field per row (default)
- *   format: "prometheus" — Prometheus 0.0.4 text format, gauge metrics
- *                          named with a configurable prefix; only top-level
- *                          numeric fields under `snap.fields` are emitted
+ *   format: "prometheus" — Prometheus 0.0.4 text format
+ *
+ * ## Type detection (`prometheus` format only)
+ *
+ * Per Prometheus naming convention + OpenMetrics 1.0.0 §6.2, counter
+ * metric families MUST carry the `_total` suffix; every other numeric
+ * field renders as a gauge. The renderer auto-detects by suffix:
+ *
+ *   - field name ends in `_total` → `# TYPE <name> counter`
+ *   - everything else             → `# TYPE <name> gauge`
+ *
+ * Operators with metrics that don't fit the convention (e.g. a counter
+ * named `bytes_sent` without the `_total` suffix, or a gauge that
+ * happens to end in `_total`) opt the right type via `opts.fieldTypes`:
+ *
+ *   render(snap, { format: "prometheus", fieldTypes: {
+ *     bytes_sent: "counter",     // override default gauge
+ *     ratio_total: "gauge",       // override default counter
+ *   }});
+ *
+ * Pre-v0.9.47 every field rendered as gauge regardless of name, which
+ * broke `rate()` queries against counter-shaped series. Operators
+ * scraping a long-running deployment will see `rate(*_total[5m])`
+ * queries start returning the right answer once the new types reach
+ * the scrape target.
  *
  * @opts
- *   format:  "text" | "prometheus",   // default: "text"
- *   prefix:  string,                   // prometheus-only; default: "blamejs"
+ *   format:      "text" | "prometheus",   // default: "text"
+ *   prefix:      string,                   // prometheus-only; default: "blamejs"
+ *   fieldTypes:  Object,                   // prometheus-only; per-field type override
+ *                                          // map. Values: "counter" | "gauge".
  *
  * @example
  *   var snap = b.metrics.snapshot.read("/run/blamejs/metrics.json");
  *   process.stdout.write(b.metrics.snapshot.render(snap));
- *   // or for Prometheus scraping:
+ *   // or for Prometheus scraping (auto-detects http_requests_total
+ *   // as a counter via the _total suffix):
  *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
  *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
  */
@@ -899,6 +1001,11 @@ function snapshotRender(snap, opts) {
       throw new MetricsError("metrics-snapshot/bad-prefix",
         "metrics.snapshot.render: prometheus prefix must match [a-zA-Z_][a-zA-Z0-9_]*, got '" + prefix + "'");
     }
+    var fieldTypes = opts.fieldTypes || {};
+    if (typeof fieldTypes !== "object" || fieldTypes === null || Array.isArray(fieldTypes)) {
+      throw new MetricsError("metrics-snapshot/bad-field-types",
+        "metrics.snapshot.render: opts.fieldTypes must be an object mapping field-name → 'counter' | 'gauge'");
+    }
     var out = [];
     // allow:bare-canonicalize-walk — sort is for stable Prometheus
     // exposition output ordering, not canonicalize-for-hashing
@@ -909,7 +1016,20 @@ function snapshotRender(snap, opts) {
       if (typeof v2 !== "number" || !isFinite(v2)) continue;   // only numeric scalars
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k2)) continue;       // skip prom-incompatible names
       var metric = prefix + "_" + k2;
-      out.push("# TYPE " + metric + " gauge");
+      var declared = fieldTypes[k2];
+      var fieldType;
+      if (declared !== undefined) {
+        if (declared !== "counter" && declared !== "gauge") {
+          throw new MetricsError("metrics-snapshot/bad-field-type",
+            "metrics.snapshot.render: opts.fieldTypes." + k2 + " must be 'counter' or 'gauge', got '" + declared + "'");
+        }
+        fieldType = declared;
+      } else {
+        // Prometheus naming convention + OpenMetrics 1.0.0 §6.2:
+        // counter family names carry the _total suffix.
+        fieldType = /_total$/.test(k2) ? "counter" : "gauge";
+      }
+      out.push("# TYPE " + metric + " " + fieldType);
       out.push(metric + " " + v2);
     }
     return out.join("\n") + "\n";