@blamejs/core 0.9.24 → 0.9.38

package/lib/agent-trace.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * @module     b.agent.trace
+ * @nav        Agent
+ * @title      Agent Trace
+ * @order      85
+ *
+ * @intro
+ *   Distributed tracing through every agent boundary. Composes the
+ *   existing `b.tracing` (W3C trace context) so operators get a full
+ *   request waterfall across the agent stack without wiring spans
+ *   per-handler.
+ *
+ *   The substrate at v0.9.29 ships the integration surface:
+ *
+ *     - `startSpan(name, opts)` — wrap an agent method call in a span
+ *     - `injectIntoEnvelope(envelope, currentSpan)` — inject W3C
+ *       `traceparent` + `tracestate` into queue / event-bus / sub-
+ *       agent envelopes so the consumer can continue the trace
+ *     - `extractFromEnvelope(envelope)` — parse the envelope's
+ *       trace context (refused via `b.guardTraceContext` if
+ *       malformed)
+ *     - `recordResult(span, result, error?)` — close span with
+ *       success / error status
+ *     - `shouldSample(method)` — sampling decision (global +
+ *       per-method override)
+ *
+ *   Span shape (per method call):
+ *
+ *     name:        "<agent-kind>.<method>"    // e.g. "mail.agent.search"
+ *     attributes:
+ *       agent.method:        method name
+ *       agent.dispatch_mode: "local" | "queue" | "auto"
+ *       agent.tenant_id:     from v0.9.26 tenant scope (if present)
+ *       agent.posture:       JSON-array of v0.9.28 posture set
+ *       agent.shard:         from v0.9.21 shard routing
+ *       agent.result_status: "success" | "error" | "not_implemented"
+ *       agent.elapsed_ms:    integer
+ *
+ *   ```js
+ *   var trace = b.agent.trace.create({
+ *     tracing:    b.tracing.create({ instrumentationName: "mail-agent" }),
+ *     sampleRate: 1.0,
+ *     perMethod:  { fetch: 0.1, search: 0.5, send: 1.0 },
+ *   });
+ *
+ *   var span = trace.startSpan("mail.agent.fetch", { actor, method: "fetch" });
+ *   try {
+ *     var result = await agent.fetch(args);
+ *     trace.recordResult(span, result);
+ *   } catch (e) {
+ *     trace.recordResult(span, null, e);
+ *     throw e;
+ *   }
+ *   ```
+ *
+ * @card
+ *   Distributed tracing through every agent boundary. W3C trace
+ *   context injection at queue / event-bus / sub-agent envelopes;
+ *   per-method sampling; integrated with existing b.tracing.
+ */
+
+var lazyRequire        = require("./lazy-require");
+var { defineClass }    = require("./framework-error");
+var guardTraceContext  = require("./guard-trace-context");
+
+var audit              = lazyRequire(function () { return require("./audit"); });
+
+var AgentTraceError = defineClass("AgentTraceError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.agent.trace.create
+ * @signature b.agent.trace.create(opts)
+ * @since     0.9.29
+ * @status    stable
+ * @related   b.tracing.create, b.agent.orchestrator.create
+ *
+ * Create the trace facade. Composes operator-supplied `b.tracing`
+ * instance (or stub if absent — spans become no-ops).
+ *
+ * @opts
+ *   tracing:    b.tracing instance,       // required for live spans
+ *   audit:      b.audit namespace,         // optional
+ *   sampleRate: number in [0..1],          // default 1.0
+ *   perMethod:  { <method>: number },      // override per-method
+ *
+ * @example
+ *   var trace = b.agent.trace.create({ tracing: myTracing, sampleRate: 0.5 });
+ *   var span = trace.startSpan("mail.agent.fetch", { actor });
+ */
+function create(opts) {
+  opts = opts || {};
+  if (!opts.tracing || typeof opts.tracing !== "object") {
+    throw new AgentTraceError("agent-trace/bad-tracing",
+      "create: opts.tracing is required (b.tracing.create() result)");
+  }
+  var sampleRate = typeof opts.sampleRate === "number" ? opts.sampleRate : 1.0;
+  if (!isFinite(sampleRate) || sampleRate < 0 || sampleRate > 1) {
+    throw new AgentTraceError("agent-trace/bad-sample-rate",
+      "create: sampleRate must be in [0, 1]");
+  }
+  var perMethod = opts.perMethod || {};
+  var auditImpl = opts.audit || audit();
+
+  return {
+    startSpan:           function (name, sopts)             { return _startSpan(opts.tracing, name, sopts || {}); },
+    injectIntoEnvelope:  function (envelope, span)          { return _injectIntoEnvelope(opts.tracing, envelope, span); },
+    extractFromEnvelope: function (envelope)                { return _extractFromEnvelope(envelope); },
+    recordResult:        function (span, result, error)     { return _recordResult(span, result, error); },
+    shouldSample:        function (method)                  { return _shouldSample(sampleRate, perMethod, method); },
+    formatAttributes:    function (info)                    { return _formatAttributes(info); },
+    AgentTraceError:     AgentTraceError,
+    _ctx: { sampleRate: sampleRate, perMethod: perMethod, audit: auditImpl },
+  };
+}
+
+function _startSpan(tracing, name, sopts) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new AgentTraceError("agent-trace/bad-span-name",
+      "startSpan: name required");
+  }
+  // Compose b.tracing's manual-lifetime span — sets the span as active
+  // on the registry stack so tracing.contextHeaders() / currentSpan()
+  // see it, then exposes end() so the agent boundary controls
+  // lifetime across publish → consume.
+  if (typeof tracing.manualSpan === "function") {
+    return tracing.manualSpan(name, sopts);
+  }
+  // Operator passed a non-b.tracing object (operator-supplied OTel
+  // tracer directly) — try its native startSpan. Refuse if neither.
+  if (typeof tracing.startSpan === "function") {
+    return tracing.startSpan(name, sopts);
+  }
+  throw new AgentTraceError("agent-trace/bad-tracing",
+    "startSpan: opts.tracing must expose manualSpan() (b.tracing.create()) " +
+    "or startSpan() (raw OTel tracer); neither found");
+}
+
+function _injectIntoEnvelope(tracing, envelope, span) {
+  if (!envelope || typeof envelope !== "object") {
+    throw new AgentTraceError("agent-trace/bad-envelope",
+      "injectIntoEnvelope: envelope required");
+  }
+  // tracing.contextHeaders() returns { traceparent, tracestate? } when
+  // a span is active. We pass through whatever's current.
+  var headers = (typeof tracing.contextHeaders === "function") ? tracing.contextHeaders() : null;
+  if (!headers || typeof headers.traceparent !== "string") return envelope;
+  envelope._trace = {
+    traceparent: headers.traceparent,
+    tracestate:  headers.tracestate || "",
+  };
+  return envelope;
+}
+
+function _extractFromEnvelope(envelope) {
+  if (!envelope || typeof envelope !== "object" || !envelope._trace) return null;
+  // Validate via guardTraceContext — refuses malformed traceparent
+  // strings before the consumer side picks them up as a parent span.
+  try {
+    guardTraceContext.validate(envelope._trace);
+  } catch (e) {
+    throw new AgentTraceError("agent-trace/bad-envelope-trace",
+      "extractFromEnvelope: " + ((e && e.message) || String(e)));
+  }
+  return {
+    traceparent: envelope._trace.traceparent,
+    tracestate:  envelope._trace.tracestate || "",
+  };
+}
+
+function _recordResult(span, result, error) {
+  if (!span || typeof span !== "object") return;
+  if (error) {
+    if (typeof span.recordException === "function") {
+      try { span.recordException(error); } catch (_e) { /* best-effort */ }
+    }
+    if (typeof span.setStatus === "function") {
+      try { span.setStatus({ code: 2, message: error.message || String(error) }); }
+      catch (_e) { /* best-effort */ }
+    }
+  } else if (typeof span.setStatus === "function") {
+    try { span.setStatus({ code: 1 }); } catch (_e) { /* best-effort */ }
+  }
+  if (typeof span.end === "function") {
+    try { span.end(); } catch (_e) { /* best-effort */ }
+  }
+}
+
+function _shouldSample(globalRate, perMethod, method) {
+  if (typeof method === "string" && Object.prototype.hasOwnProperty.call(perMethod, method)) {
+    var r = perMethod[method];
+    if (typeof r === "number" && isFinite(r) && r >= 0 && r <= 1) {
+      return Math.random() < r;                                                                       // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
+    }
+  }
+  return Math.random() < globalRate;                                                                  // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
+}
+
+function _formatAttributes(info) {
+  if (!info || typeof info !== "object") return {};
+  var attrs = {};
+  if (info.method)       attrs["agent.method"]        = info.method;
+  if (info.dispatchMode) attrs["agent.dispatch_mode"] = info.dispatchMode;
+  if (info.tenantId)     attrs["agent.tenant_id"]     = info.tenantId;
+  if (Array.isArray(info.postureSet)) attrs["agent.posture"] = JSON.stringify(info.postureSet);
+  if (typeof info.shard === "number")  attrs["agent.shard"]       = info.shard;
+  if (info.resultStatus) attrs["agent.result_status"] = info.resultStatus;
+  if (typeof info.elapsedMs === "number") attrs["agent.elapsed_ms"] = info.elapsedMs;
+  return attrs;
+}
+
+module.exports = {
+  create:           create,
+  AgentTraceError:  AgentTraceError,
+  guards: {
+    context: guardTraceContext,
+  },
+};

package/lib/guard-all.js

@@ -83,6 +83,7 @@ var STANDALONE_GUARDS = [
   require("./guard-image"),
   require("./guard-pdf"),
   require("./guard-auth"),
+  require("./guard-smtp-command"),
 ];
 
 // Framework-wide profile + posture vocabulary that every guard MUST

package/lib/guard-dsn.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * @module     b.guardDsn
+ * @nav        Guards
+ * @title      Guard DSN
+ * @order      460
+ *
+ * @intro
+ *   RFC 3464 Delivery Status Notification parser. Reads the
+ *   `multipart/report; report-type=delivery-status` structure that
+ *   bounces, delayed-delivery notices, and successful-delivery
+ *   confirmations carry and surfaces the per-recipient action +
+ *   enhanced status code so operator-side delivery-failure routing
+ *   (`b.mail.bounce` retry curve, address-book invalidation, mailing-
+ *   list cleanup, transactional-mail dead-letter handling) reads a
+ *   stable shape regardless of MTA wording.
+ *
+ *   ## RFC 3464 structure
+ *
+ *   `multipart/report` per RFC 6522 §3:
+ *
+ *     1. `text/plain` (or text/html) — human-readable wording
+ *        ("Your message could not be delivered to alice@example.com");
+ *        the framework does NOT route on this prose.
+ *     2. **`message/delivery-status`** (RFC 3464 §2) — the
+ *        machine-readable DSN body the framework parses.
+ *     3. Optional `message/rfc822` (or `text/rfc822-headers`) —
+ *        the original message (or its headers) that bounced.
+ *
+ *   ## Required fields the parser extracts
+ *
+ *   **Per-message fields (RFC 3464 §2.2)**:
+ *     - `Reporting-MTA` — MTA that issued the DSN. Mandatory.
+ *     - `Original-Envelope-Id` (optional) — DSN-tied envelope id.
+ *     - `Arrival-Date` (optional) — when the original message
+ *       arrived at the reporting MTA.
+ *
+ *   **Per-recipient fields (RFC 3464 §2.3)** — repeated, one block
+ *   per recipient:
+ *     - `Final-Recipient` — recipient address as the reporting MTA
+ *       knows it. Mandatory.
+ *     - `Action` — `failed` / `delayed` / `delivered` / `relayed` /
+ *       `expanded`. Mandatory.
+ *     - `Status` — RFC 3463 enhanced status code, format
+ *       `D.D[D[D]].D[D[D]]` (e.g. `5.1.1` = bad address).
+ *     - `Original-Recipient` (optional).
+ *     - `Diagnostic-Code` (optional) — raw MTA error line.
+ *
+ *   ## RFC 3463 status-class semantics
+ *
+ *   The first digit classifies the verdict and drives the framework's
+ *   downstream routing:
+ *
+ *     - **`2.x.y`** — success (delivered / relayed / expanded). Used
+ *       by mailing-list `verp` tracking + delivery-receipt auditing.
+ *     - **`4.x.y`** — persistent transient failure. Operator's
+ *       `b.outbox` retry curve applies; address stays valid.
+ *     - **`5.x.y`** — permanent failure. Address-book invalidation
+ *       trigger; mailing-list cleanup; no further retries.
+ *
+ *   The framework surfaces `statusClass` (`success` / `temporary` /
+ *   `permanent`) so operator routing reads one shape regardless of
+ *   the exact subcode.
+ *
+ *   ## Defenses
+ *
+ *   - **Oversize DSN** — bounded body cap (default 256 KiB strict)
+ *     per the profile; legitimate DSNs are KB-scale, multi-MB DSNs
+ *     are pathological / DoS-shaped.
+ *   - **Recipient-count cap** — per-DSN recipient cap (default 256
+ *     strict). A DSN with thousands of recipients is forged or
+ *     misconfigured; operator opts permissive for mailing-list
+ *     blast-bounces.
+ *   - **Header-line cap** — each field-line capped at 998 bytes
+ *     per RFC 5322 §2.1.1.
+ *   - **CRLF + control-char refusal** — header injection defense
+ *     for fields that propagate to operator's audit log /
+ *     monitoring dashboard.
+ *
+ *   ## CVE / threat model
+ *
+ *   - **Bounce-flood / backscatter** — operator's MX should refuse
+ *     mail with envelope-from that doesn't pass SPF before
+ *     generating a DSN (the existing `b.mail.bounce` primitive does
+ *     this); this guard parses INBOUND DSNs and gates the parse
+ *     surface bounds, not the bounce-generation policy.
+ *   - **DSN header-injection class** (CVE-2026-32178 .NET
+ *     System.Net.Mail at outbound; the inbound parse path here)
+ *     — refuses CR/LF/NUL/C0 in header lines.
+ *   - **CSAF / iSchedule prose tampering** — operator inspecting
+ *     the prose part for the original recipient runs into the
+ *     ambiguous wording that DSNs vary across MTAs (Postfix vs
+ *     Exchange vs SES vs Gmail). The parser surfaces the
+ *     STRUCTURED fields so operator routing doesn't have to
+ *     regex MTA-specific prose.
+ *
+ * @card
+ *   RFC 3464 DSN parser. Walks message/delivery-status per-message + per-recipient blocks, surfaces Action / Status / Final-Recipient + the RFC 3463 status-class verdict (success / temporary / permanent). Bounded recipient count + body size + header-line length; CRLF / NUL / C0 refusal. Operator delivery-failure routing reads one shape regardless of MTA wording.
+ */
+
+var C                  = require("./constants");
+var { defineClass }    = require("./framework-error");
+
+var GuardDsnError = defineClass("GuardDsnError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: C.BYTES.kib(256), maxRecipients: 256, maxHeaderLine: 998 },                    // allow:raw-byte-literal — RFC 5322 §2.1.1 header line cap; RFC 3464 recipient count
+  balanced:   { maxBytes: C.BYTES.mib(1),   maxRecipients: 1024, maxHeaderLine: 998 },                   // allow:raw-byte-literal — RFC 5322 §2.1.1 line cap; mailing-list blast bounces
+  permissive: { maxBytes: C.BYTES.mib(4),   maxRecipients: 4096, maxHeaderLine: 998 },                   // allow:raw-byte-literal — RFC 5322 §2.1.1 line cap; large-blast bounce class
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var KNOWN_ACTIONS = Object.freeze({
+  failed:    true,
+  delayed:   true,
+  delivered: true,
+  relayed:   true,
+  expanded:  true,
+});
+
+// RFC 3463 §3.1: status code is digit . digit{1,3} . digit{1,3}.
+var STATUS_RE = /^([245])\.(\d{1,3})\.(\d{1,3})$/;                                                       // allow:regex-no-length-cap — anchored + per-component repeat cap
+
+/**
+ * @primitive b.guardDsn.parse
+ * @signature b.guardDsn.parse(deliveryStatusBody, opts?)
+ * @since     0.9.37
+ * @status    stable
+ * @related   b.safeMime.parse, b.guardEnvelope.check
+ *
+ * Parse a `message/delivery-status` body (the MIME part body, not
+ * the entire RFC 3464 multipart/report — extract that via
+ * `b.safeMime.parse` first). Returns `{ perMessage, perRecipients,
+ * worstStatusClass, action }`.
+ *
+ * Throws `GuardDsnError` on oversize body / recipient count /
+ * header-line length / malformed status code / required-field
+ * missing / control-char in field value.
+ *
+ * @opts
+ *   profile:  "strict" | "balanced" | "permissive",
+ *   posture:  "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   var mime = b.safeMime.parse(rawBouncedMessage);
+ *   var deliveryStatusPart = b.safeMime.findFirst(mime, function (p) {
+ *     return p.leaf && p.leaf.contentType === "message/delivery-status";
+ *   });
+ *   var dsn = b.guardDsn.parse(deliveryStatusPart.leaf.body);
+ *   if (dsn.worstStatusClass === "permanent") {
+ *     dsn.perRecipients.forEach(function (r) { invalidateAddress(r.finalRecipient); });
+ *   }
+ */
+function parse(deliveryStatusBody, opts) {
+  opts = opts || {};
+  var caps = _resolveProfile(opts);
+  var bytes;
+  if (Buffer.isBuffer(deliveryStatusBody)) {
+    bytes = deliveryStatusBody;
+  } else if (typeof deliveryStatusBody === "string") {
+    bytes = Buffer.from(deliveryStatusBody, "utf8");
+  } else {
+    throw new GuardDsnError("guard-dsn/bad-input",
+      "parse: deliveryStatusBody must be a Buffer or string");
+  }
+  if (bytes.length > caps.maxBytes) {
+    throw new GuardDsnError("guard-dsn/oversize-body",
+      "parse: body " + bytes.length + " bytes exceeds maxBytes=" + caps.maxBytes);
+  }
+
+  // RFC 3464 §2.1: the delivery-status body is per-message fields,
+  // a blank line, then per-recipient field groups separated by
+  // blank lines.
+  var text = bytes.toString("utf8");
+  var blocks = _splitBlocks(text);
+  if (blocks.length === 0) {
+    throw new GuardDsnError("guard-dsn/empty",
+      "parse: delivery-status body has no field blocks");
+  }
+  var perMessageFields = _parseFieldBlock(blocks[0], caps.maxHeaderLine);
+
+  // Reporting-MTA is mandatory per RFC 3464 §2.2.2.
+  if (!perMessageFields["reporting-mta"]) {
+    throw new GuardDsnError("guard-dsn/missing-reporting-mta",
+      "parse: required per-message field Reporting-MTA missing (RFC 3464 §2.2.2)");
+  }
+
+  var perRecipients = [];
+  for (var i = 1; i < blocks.length; i += 1) {
+    if (perRecipients.length >= caps.maxRecipients) {
+      throw new GuardDsnError("guard-dsn/too-many-recipients",
+        "parse: per-recipient count exceeds maxRecipients=" + caps.maxRecipients);
+    }
+    var fields = _parseFieldBlock(blocks[i], caps.maxHeaderLine);
+    if (Object.keys(fields).length === 0) continue;        // empty trailing block
+    if (!fields["final-recipient"]) {
+      throw new GuardDsnError("guard-dsn/missing-final-recipient",
+        "parse: per-recipient block missing Final-Recipient (RFC 3464 §2.3.2)");
+    }
+    if (!fields["action"]) {
+      throw new GuardDsnError("guard-dsn/missing-action",
+        "parse: per-recipient block missing Action (RFC 3464 §2.3.3)");
+    }
+    var action = fields["action"].toLowerCase();
+    if (!KNOWN_ACTIONS[action]) {
+      throw new GuardDsnError("guard-dsn/bad-action",
+        "parse: Action '" + action + "' not in RFC 3464 §2.3.3 vocabulary");
+    }
+    if (!fields["status"]) {
+      throw new GuardDsnError("guard-dsn/missing-status",
+        "parse: per-recipient block missing Status (RFC 3464 §2.3.4)");
+    }
+    var statusMatch = fields["status"].match(STATUS_RE);
+    if (!statusMatch) {
+      throw new GuardDsnError("guard-dsn/bad-status",
+        "parse: Status '" + fields["status"] + "' not RFC 3463 D.D.D form");
+    }
+    perRecipients.push({
+      finalRecipient:     _stripRecipientType(fields["final-recipient"]),
+      originalRecipient:  fields["original-recipient"] ? _stripRecipientType(fields["original-recipient"]) : null,
+      action:             action,
+      status:             fields["status"],
+      statusClass:        _statusClass(statusMatch[1]),
+      diagnosticCode:     fields["diagnostic-code"] || null,
+      remoteMta:          fields["remote-mta"] || null,
+      lastAttemptDate:    fields["last-attempt-date"] || null,
+    });
+  }
+
+  if (perRecipients.length === 0) {
+    throw new GuardDsnError("guard-dsn/no-recipients",
+      "parse: delivery-status has no per-recipient blocks (RFC 3464 §2.1 requires at least one)");
+  }
+
+  // Worst status class across recipients: permanent > temporary > success.
+  var worst = "success";
+  for (var r = 0; r < perRecipients.length; r += 1) {
+    if (perRecipients[r].statusClass === "permanent") { worst = "permanent"; break; }
+    if (perRecipients[r].statusClass === "temporary") worst = "temporary";
+  }
+
+  return {
+    perMessage: {
+      reportingMta:       perMessageFields["reporting-mta"],
+      originalEnvelopeId: perMessageFields["original-envelope-id"] || null,
+      arrivalDate:        perMessageFields["arrival-date"] || null,
+      receivedFromMta:    perMessageFields["received-from-mta"] || null,
+    },
+    perRecipients:    perRecipients,
+    worstStatusClass: worst,
+    action:           worst === "permanent" ? "invalidate" :
+                      worst === "temporary" ? "retry" :
+                      "deliver",
+  };
+}
+
+/**
+ * @primitive b.guardDsn.compliancePosture
+ * @signature b.guardDsn.compliancePosture(posture)
+ * @since     0.9.37
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.guardDsn.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _splitBlocks(text) {
+  // RFC 3464 §2.1: blank line separates per-message from
+  // per-recipient blocks; blank lines also separate consecutive
+  // per-recipient blocks.
+  // Normalize CRLF + bare-CR to LF for split.
+  var normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");                                    // allow:regex-no-length-cap — input length already capped
+  return normalized.split(/\n\s*\n/);                                                                    // allow:regex-no-length-cap — input length already capped
+}
+
+function _parseFieldBlock(block, maxHeaderLine) {
+  // RFC 5322 §2.2: header field = name ":" value; continuation
+  // lines start with whitespace.
+  var lines = block.split("\n");
+  var fields = Object.create(null);
+  var current = null;
+  for (var i = 0; i < lines.length; i += 1) {
+    var raw = lines[i];
+    if (raw.length > maxHeaderLine) {
+      throw new GuardDsnError("guard-dsn/oversize-header-line",
+        "parse: header line " + raw.length + " bytes exceeds maxHeaderLine=" + maxHeaderLine + " (RFC 5322 §2.1.1)");
+    }
+    if (raw.length === 0) continue;
+    _checkControlChars(raw);
+    if (/^[ \t]/.test(raw) && current) {                                                                 // allow:regex-no-length-cap — single-char check on capped line
+      // Continuation.
+      fields[current] += " " + raw.replace(/^[ \t]+/, "");                                               // allow:regex-no-length-cap — trim on capped line // allow:duplicate-regex — leading-WS-trim shape common to RFC 5322 header continuation parsers
+      continue;
+    }
+    var colon = raw.indexOf(":");
+    if (colon === -1) {
+      throw new GuardDsnError("guard-dsn/malformed-field",
+        "parse: line '" + raw + "' missing ':' field-name terminator");
+    }
+    var name = raw.slice(0, colon).trim().toLowerCase();
+    var value = raw.slice(colon + 1).trim();
+    if (name.length === 0) {
+      throw new GuardDsnError("guard-dsn/malformed-field",
+        "parse: empty field name on line '" + raw + "'");
+    }
+    fields[name] = value;
+    current = name;
+  }
+  return fields;
+}
+
+function _checkControlChars(line) {
+  // Refuse NUL, C0 controls (except TAB which is valid in
+  // continuation), DEL. Bare CR and LF can't appear because we
+  // already split on \n; this catches forms that survive the
+  // split (e.g. backslash + literal sequence).
+  for (var i = 0; i < line.length; i += 1) {
+    var c = line.charCodeAt(i);
+    if (c === 0x00 || c === 0x7f || (c < 0x20 && c !== 0x09)) {                                          // allow:raw-byte-literal — RFC 5322 control char + TAB allow
+      throw new GuardDsnError("guard-dsn/control-char",
+        "parse: control char 0x" + c.toString(16) + " in field line refused (header-injection defense)");
+    }
+  }
+}
+
+function _stripRecipientType(value) {
+  // RFC 3464 §2.3.2: "rfc822;alice@example.com" — type prefix
+  // before semicolon classifies the address. Strip for the common
+  // case of rfc822, surface the raw value otherwise.
+  var semi = value.indexOf(";");
+  if (semi === -1) return value;
+  var type = value.slice(0, semi).trim().toLowerCase();
+  if (type === "rfc822") return value.slice(semi + 1).trim();
+  return value;
+}
+
+function _statusClass(firstDigit) {
+  if (firstDigit === "2") return "success";
+  if (firstDigit === "4") return "temporary";
+  if (firstDigit === "5") return "permanent";
+  return "unknown";
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardDsnError("guard-dsn/bad-profile",
+      "guardDsn: unknown profile '" + p + "'");
+  }
+  return PROFILES[p];
+}
+
+module.exports = {
+  parse:                   parse,
+  compliancePosture:       compliancePosture,
+  PROFILES:                PROFILES,
+  COMPLIANCE_POSTURES:     COMPLIANCE_POSTURES,
+  KNOWN_ACTIONS:           KNOWN_ACTIONS,
+  GuardDsnError:           GuardDsnError,
+  NAME:                    "dsn",
+  KIND:                    "delivery-status",
+};