@blamejs/core 0.8.43 → 0.8.49

package/lib/guard-csv.js

@@ -1,56 +1,57 @@
 "use strict";
 /**
- * guard-csv — CSV content-safety primitive (b.guardCsv).
- *
- * Wraps lib/csv.js (RFC 4180 parse + stringify) with the broader threat
- * catalog operators face when emitting CSVs from user-supplied data,
- * plus the b.gateContract composition contract for use as a gate inside
- * b.staticServe / b.fileUpload / b.mail / b.objectStore.
- *
- *   var out = b.guardCsv.serialize(rows, { profile: "strict" });
- *   var rv  = b.guardCsv.validate(input, { profile: "strict" });
- *   var s   = b.guardCsv.sanitize(input, { profile: "balanced" });
- *   var g   = b.guardCsv.gate({ profile: "strict" });
- *   b.staticServe.create({ contentSafety: { ".csv": g } });
- *
- * Threat-detection regex literals are composed PROGRAMMATICALLY from
- * numeric codepoint ranges (BIDI_RANGES / C0_CTRL_RANGES / etc.) so the
- * source file never embeds the attack characters themselves — only their
- * codepoint numbers. This mirrors the way an attacker would compose the
- * payload (programmatic codepoint emission, not literal typing) and
- * keeps the source ASCII-clean (zero irregular-whitespace lint findings,
- * no eslint-disable comments, machine-greppable as data tables).
- *
- * Threat catalog covered:
- *
- *   - Formula injection (5 modes: prefix-tab / prefix-quote /
- *     wrap-with-quotes-and-prefix / reject / allowlist) with all 8
- *     ASCII triggers (= + - @ TAB CR LF |) plus full-width variants
- *     (U+FF1D / U+FF0B / U+FF0D / U+FF20) per OWASP locale catalog.
- *   - Dangerous-function denylist — WEBSERVICE / HYPERLINK / IMAGE /
- *     IMPORT* / RTD / DDE / CALL / GOOGLEFINANCE / GOOGLETRANSLATE.
- *   - Unicode bidi override (CVE-2021-42574 Trojan Source).
- *   - Homoglyph detection (Cyrillic / Greek / fullwidth Latin) when
- *     mixed with ASCII letters in the same cell.
- *   - C0 control chars (minus tab / lf / cr — those are dialect chars
- *     the parser handles separately).
- *   - Null byte detection (single canonical handling — strip / reject).
- *   - BOM injection mid-stream (any BOM past byte 0).
- *   - Zero-width chars (ZWSP / ZWNJ / ZWJ / WJ / SHY).
- *   - Dialect ambiguity (mixed line endings) — strict refuses.
- *   - CSV-bomb caps: per-cell, total, sanitize amplification ratio.
- *   - Numeric precision loss (above Number.MAX_SAFE_INTEGER → decimal
- *     string per policy).
- *   - Trailing whitespace exfiltration policy (trim / preserve / reject).
- *   - PII redaction via composes b.redact when piiPolicy === "redact".
- *   - Schema-bound serializer with type / regex / range / nullable
- *     validation.
- *   - Profiles: strict (OWASP-aligned, prefix-tab default per OWASP) /
- *     balanced / permissive / email-attachment.
- *   - Compliance postures: hipaa / pci-dss / gdpr / soc2.
- *   - Operator extensibility: profile composition, custom rules, hooks
- *     (beforeCheck / afterCheck / onIssue / onSanitize / onRefuse /
- *     onAudit), threat-intel feeds, sandbox isolation, snapshot tests.
+ * @module b.guardCsv
+ * @nav    Guards
+ * @title  Guard Csv
+ *
+ * @intro
+ *   CSV content-safety guard — defends against the broader threat
+ *   catalog operators face when emitting or accepting CSVs sourced from
+ *   user input. `b.csv.parse` / `b.csv.stringify` handle RFC 4180
+ *   shape; this module layers the security catalog on top.
+ *
+ *   CSV-injection / formula-trigger defense: spreadsheet evaluators
+ *   (Excel / LibreOffice / Google Sheets) treat any cell beginning with
+ *   `=`, `+`, `-`, `@`, TAB, CR, LF, or `|` as a formula — including
+ *   exfiltration vectors like `=WEBSERVICE(...)`, `=HYPERLINK(...)`,
+ *   `=IMPORTXML(...)`. Full-width variants (U+FF1D `＝`, U+FF0B `＋`,
+ *   U+FF0D `－`, U+FF20 `＠`) are caught alongside the ASCII triggers
+ *   per the OWASP locale catalog. Five mitigation modes apply:
+ *   `prefix-tab` (OWASP-recommended, prepends TAB so the evaluator
+ *   treats the cell as text), `prefix-quote` (legacy `'` prefix),
+ *   `wrap-with-quotes-and-prefix` (email-attachment posture),
+ *   `reject` (throw), `allowlist` (only documented safe functions
+ *   like SUM / AVERAGE pass through unprefixed).
+ *
+ *   Unicode bidi/zero-width strip: CVE-2021-42574 Trojan Source bidi
+ *   overrides (U+202A-202E, U+2066-2069) are rejected or stripped
+ *   per profile; zero-width characters (ZWSP / ZWNJ / ZWJ / WJ / SHY)
+ *   always strip. Leading bidi/zero-width prefixes are stripped before
+ *   the formula scan so a cell beginning with U+200B`=SUM(...)` cannot
+ *   slip past the start-anchor check.
+ *
+ *   CSV-bomb caps: per-cell (`maxCellBytes`, default 64 KiB), total
+ *   (`maxTotalBytes`, default 1 GiB), row count (`maxRows`, default
+ *   ~1 M), column count (`maxColumns`, default 1024), and a sanitize
+ *   amplification ratio (`sanitizeAmplificationCap`, default 1.5x)
+ *   that refuses pathological re-quote expansions.
+ *
+ *   Doubled-quote escape is delegated to `b.csv.stringify` — every
+ *   cell value containing the delimiter, the quote char, CR, or LF
+ *   is wrapped in quotes with embedded quotes doubled per RFC 4180.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive` /
+ *   `email-attachment`. Compliance postures: `hipaa` / `pci-dss` /
+ *   `gdpr` / `soc2`. Operators select via `{ profile: "strict" }` or
+ *   `{ compliance: "hipaa" }`; postures overlay on top of the
+ *   profile baseline.
+ *
+ *   Threat-detection regex literals are composed programmatically
+ *   from numeric codepoint ranges so the source file stays pure
+ *   ASCII — never embeds the attack characters themselves.
+ *
+ * @card
+ *   CSV content-safety guard — defends against the broader threat catalog operators face when emitting or accepting CSVs sourced from user input.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -449,6 +450,54 @@ function _resolveOpts(opts) {
 
 // ---- Cell-level escape with full threat application ----
 
+/**
+ * @primitive  b.guardCsv.escapeCell
+ * @signature  b.guardCsv.escapeCell(value, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.serialize, b.guardCsv.gate, b.csv.stringify
+ *
+ * Apply the full guard-csv threat catalog to a single cell value:
+ * formula-prefix mitigation, null-byte / C0-control / bidi handling,
+ * trailing-whitespace policy, numeric-precision policy, and BigInt
+ * disposition. Returns the safe string form. Throws `GuardCsvError`
+ * when a `reject` policy fires (formula-trigger under
+ * `formulaInjectionPolicy: "reject"`, control char under
+ * `controlCharPolicy: "reject"`, etc.) or when the cell exceeds
+ * `maxCellBytes`.
+ *
+ * Used internally by `b.guardCsv.serialize` per cell; exposed
+ * directly for operators that emit CSV through their own writer
+ * (streaming exports, third-party libraries) and only need the
+ * per-cell defense.
+ *
+ * @opts
+ *   formulaInjectionPolicy: "prefix-tab"|"prefix-quote"|"wrap-with-quotes-and-prefix"|"reject"|"allowlist",
+ *   formulasAllowlist:      string[],   // when policy === "allowlist"
+ *   bidiCharPolicy:         "reject"|"strip"|"audit"|"allow",
+ *   controlCharPolicy:      "reject"|"strip"|"allow",
+ *   nullByteHandling:       "reject"|"strip"|"allow",
+ *   trailingWhitespacePolicy: "trim"|"preserve"|"reject",
+ *   numericPrecisionPolicy: "decimal-string-above-safe-int"|"scientific"|"reject-bigint",
+ *   maxCellBytes:           number,     // default 65536 (64 KiB)
+ *
+ * @example
+ *   var safe = b.guardCsv.escapeCell("=cmd|x", { formulaInjectionPolicy: "prefix-tab" });
+ *   safe;                                              // → "\t=cmd|x"
+ *
+ *   // Reject mode throws GuardCsvError instead of disarming.
+ *   try {
+ *     b.guardCsv.escapeCell("+1234567", { formulaInjectionPolicy: "reject" });
+ *   } catch (e) {
+ *     e.code;                                          // → "csv.formula-injection"
+ *   }
+ *
+ *   // Numeric precision: above MAX_SAFE_INTEGER, write as decimal string.
+ *   var huge = b.guardCsv.escapeCell(9007199254740993, {
+ *     numericPrecisionPolicy: "decimal-string-above-safe-int",
+ *   });
+ *   huge;                                              // → "9007199254740993"
+ */
 function escapeCell(value, opts) {
   opts = Object.assign({}, DEFAULTS, opts || {});
   var str = value == null ? "" : String(value);
@@ -516,6 +565,41 @@ function escapeCell(value, opts) {
 
 // ---- Schema-bound serializer ----
 
+/**
+ * @primitive  b.guardCsv.schema
+ * @signature  b.guardCsv.schema(spec)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.serialize, b.guardCsv.validate
+ *
+ * Build a schema-bound serializer/validator pair. Each row's column
+ * values are checked against the column's `type` (`"string"` /
+ * `"number"` / `"boolean"`), optional `regex`, optional `min` / `max`
+ * (for numbers), and `nullable` flag before the row reaches
+ * `serialize`. Type / range / regex / null violations throw
+ * `GuardCsvError` with codes `csv.schema-type` / `csv.schema-range`
+ * / `csv.schema-regex` / `csv.schema-null` and the offending row
+ * index — operators get the failing-row coordinates without parsing
+ * the error string.
+ *
+ * Returns `{ serialize, validate, columns }`. The returned
+ * `serialize` accepts the same opts as `b.guardCsv.serialize` and
+ * applies the column ordering automatically.
+ *
+ * @example
+ *   var bound = b.guardCsv.schema({
+ *     columns: [
+ *       { name: "email", type: "string", regex: /^[^@]+@[^@]+$/ },
+ *       { name: "age",   type: "number", min: 0, max: 150, nullable: true },
+ *     ],
+ *   });
+ *
+ *   var out = bound.serialize([
+ *     { email: "alice@example.com", age: 30 },
+ *     { email: "bob@example.com",   age: null },
+ *   ], { profile: "strict" });
+ *   out.indexOf("alice@example.com") !== -1;           // → true
+ */
 function schema(spec) {
   validateOpts.requireObject(spec, "guardCsv.schema", GuardCsvError);
   if (!Array.isArray(spec.columns)) {
@@ -588,6 +672,52 @@ function schema(spec) {
 
 // ---- Module-level entry points ----
 
+/**
+ * @primitive  b.guardCsv.serialize
+ * @signature  b.guardCsv.serialize(rows, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCsv.escapeCell, b.guardCsv.gate, b.csv.stringify
+ *
+ * Emit RFC 4180 CSV from `rows` (array of objects or array of
+ * arrays) with the full guard-csv threat catalog applied per cell
+ * — formula-prefix mitigation, bidi/null/control handling,
+ * trailing-whitespace policy, numeric-precision policy. Doubled-
+ * quote escape is delegated to `b.csv.stringify`. Caps enforced:
+ * `maxRows`, `maxCellBytes`, `maxColumns`, `maxTotalBytes` (each
+ * a positive finite integer; passing `Infinity` throws).
+ *
+ * When `piiPolicy: "redact"` is set and an `opts.redact` instance
+ * is passed (typically `b.redact.create(...)`), every emitted
+ * string cell is run through `redact.string(...)` before
+ * stringification. The HIPAA / PCI-DSS / GDPR postures default
+ * `piiPolicy` to `"redact"`.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive"|"email-attachment",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   headers:    string[]|false,    // explicit column order; false suppresses header row
+ *   delimiter:  string,            // default ","
+ *   lineEnding: string,            // default "\r\n"
+ *   bomPrefix:  boolean,           // prepend U+FEFF (Excel-friendly)
+ *   maxRows:    number,            // default 1048576
+ *   maxCellBytes:  number,         // default 65536
+ *   maxColumns: number,            // default 1024
+ *   maxTotalBytes: number,         // default 1073741824 (1 GiB)
+ *   piiPolicy:  "preserve"|"redact",
+ *   redact:     b.redact instance, // required when piiPolicy === "redact"
+ *
+ * @example
+ *   var out = b.guardCsv.serialize([
+ *     { name: "alice", note: "=WEBSERVICE(\"http://x\")" },
+ *     { name: "bob",   note: "ok" },
+ *   ], { profile: "strict" });
+ *
+ *   // Formula trigger disarmed with a leading TAB per OWASP guidance:
+ *   out.indexOf("\t=WEBSERVICE") !== -1;               // → true
+ *   out.indexOf("\r\n") !== -1;                        // → true
+ */
 function serialize(rows, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -663,11 +793,89 @@ function serialize(rows, opts) {
   return out;
 }
 
+/**
+ * @primitive  b.guardCsv.validate
+ * @signature  b.guardCsv.validate(input, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCsv.sanitize, b.guardCsv.gate
+ *
+ * Inspect `input` (string or Buffer of CSV text) and return
+ * `{ ok, issues, summary }`. Each issue carries `{ kind, severity,
+ * ruleId, location, snippet }` with severity in
+ * `"warn"|"high"|"critical"`. Detected: BOM mid-stream, Unicode
+ * bidi override (CVE-2021-42574), C0 control char, null byte,
+ * homoglyph, zero-width char, formula-prefix cell (bidi/zero-width
+ * leading prefix is stripped before the scan), dangerous-function
+ * denylist hit, mixed line endings (when `dialectPolicy: "strict"`).
+ * Pure inspection — never mutates input or throws.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive"|"email-attachment",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiCharPolicy:        "reject"|"strip"|"audit"|"allow",
+ *   controlCharPolicy:     "reject"|"strip"|"allow",
+ *   nullByteHandling:      "reject"|"strip"|"allow",
+ *   homoglyphPolicy:       "audit"|"strip"|"allow",
+ *   formulaInjectionPolicy: "prefix-tab"|"prefix-quote"|"wrap-with-quotes-and-prefix"|"reject"|"audit-only"|"allow",
+ *   dangerousFunctions:    string[],
+ *   dialectPolicy:         "strict"|"permissive",
+ *
+ * @example
+ *   var rv = b.guardCsv.validate("name,formula\r\nalice,=WEBSERVICE(\"x\")\r\n", {
+ *     profile: "strict",
+ *   });
+ *   rv.ok;                                             // → false
+ *   rv.issues.some(function (i) { return i.kind === "dangerous-function"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   return gateContract.runIssueValidator(input, opts, _detectIssues);
 }
 
+/**
+ * @primitive  b.guardCsv.sanitize
+ * @signature  b.guardCsv.sanitize(input, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.validate, b.guardCsv.gate
+ *
+ * Best-effort cleanup of `input` (string or Buffer): strips leading
+ * BOM (when `bomPrefix: false`), bidi override chars (when
+ * `bidiCharPolicy: "strip"`), C0 control chars (when
+ * `controlCharPolicy: "strip"`), null bytes (when
+ * `nullByteHandling: "strip"`), zero-width chars (always), and
+ * trailing whitespace per `trailingWhitespacePolicy`. Refuses
+ * pathological expansion: when the sanitized output exceeds
+ * `sanitizeAmplificationCap` (default 1.5x) the function throws
+ * `GuardCsvError("csv.sanitize-amplified")` — sanitize is a
+ * shrinking operation by contract, never a growing one.
+ *
+ * Note: sanitize does NOT prepend formula-trigger mitigations to
+ * cells (that's `b.guardCsv.serialize` / `b.guardCsv.escapeCell`'s
+ * job, applied during emission). Use the `gate` action chain for
+ * accept-side defense — it sanitizes, re-parses, and re-serializes
+ * with the formula mitigation baked in.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive"|"email-attachment",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiCharPolicy:    "reject"|"strip"|"audit"|"allow",
+ *   controlCharPolicy: "reject"|"strip"|"allow",
+ *   nullByteHandling:  "reject"|"strip"|"allow",
+ *   homoglyphPolicy:   "audit"|"strip"|"allow",
+ *   trailingWhitespacePolicy: "trim"|"preserve"|"reject",
+ *   sanitizeAmplificationCap: number,   // default 1.5
+ *
+ * @example
+ *   // Build hostile input programmatically so the source stays ASCII.
+ *   var ZWSP = String.fromCharCode(0x200B);
+ *   var clean = b.guardCsv.sanitize("name,note\r\nalice,hi" + ZWSP + "\r\n", {
+ *     profile: "balanced",
+ *   });
+ *   clean.indexOf(ZWSP) === -1;                        // → true
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   var text = typeof input === "string"
@@ -686,6 +894,29 @@ function sanitize(input, opts) {
   return sanitized;
 }
 
+/**
+ * @primitive  b.guardCsv.detect
+ * @signature  b.guardCsv.detect(input)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.validate, b.csv.parse
+ *
+ * Sniff dialect heuristics from `input` (string or Buffer): most-
+ * frequent delimiter on the first line (`","`, `";"`, `"\t"`,
+ * `"|"`), dominant line-ending, header presence (first line starts
+ * with an ASCII letter), encoding hint (`"utf-8"` vs `"utf-8-sig"`
+ * when a leading BOM is present), and a single-pass `dialect`
+ * verdict (`"consistent"` vs `"mixed"` line endings). Returns a
+ * confidence score in `[0, 1]`. Pure inspection.
+ *
+ * @example
+ *   var d = b.guardCsv.detect("name,age\r\nalice,30\r\nbob,40\r\n");
+ *   d.delimiter;                                       // → ","
+ *   d.lineEnding;                                      // → "\r\n"
+ *   d.hasHeader;                                       // → true
+ *   d.encoding;                                        // → "utf-8"
+ *   d.dialect;                                         // → "consistent"
+ */
 function detect(input) {
   var text = typeof input === "string"
     ? input
@@ -724,6 +955,51 @@ function detect(input) {
 
 // ---- Gate factory (b.gateContract shape) ----
 
+/**
+ * @primitive  b.guardCsv.gate
+ * @signature  b.guardCsv.gate(opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCsv.validate, b.guardCsv.sanitize, b.staticServe.create, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate suitable for plugging into
+ * `b.staticServe({ contentSafety: { ".csv": gate } })`,
+ * `b.fileUpload({ contentSafety: { "text/csv": gate } })`,
+ * `b.mail`, or `b.objectStore`. Action chain on validation:
+ * `serve` (no issues) → `audit-only` (warn-only issues) →
+ * `sanitize` (critical/high but no `reject` policy active —
+ * sanitize, re-parse, re-serialize so formula mitigation lands)
+ * → `refuse` (critical/high under any `reject` policy, or when
+ * sanitize fails / amplifies past cap).
+ *
+ * Operator extensibility: pass `operatorRules: [{ id, severity,
+ * detect: fn(ctx)→boolean, reason }]` to inject custom detectors
+ * alongside the built-in catalog. Rules run best-effort — a
+ * throwing detector is silently skipped (the framework cannot
+ * crash a request because an operator rule mishandled bytes).
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive"|"email-attachment",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *   operatorRules: [{ id: string, severity: "warn"|"high"|"critical",
+ *                    detect: function, reason: string }],
+ *
+ * @example
+ *   var csvGate = b.guardCsv.gate({ profile: "strict" });
+ *
+ *   // Wire into staticServe so every served .csv runs through the gate.
+ *   var serve = b.staticServe.create({
+ *     root: "/var/data",
+ *     contentSafety: { ".csv": csvGate },
+ *   });
+ *
+ *   // Direct invocation for an upload pipeline:
+ *   var hostile = Buffer.from("name,formula\r\nalice,=cmd|x\r\n", "utf8");
+ *   var verdict = await csvGate.check({ bytes: hostile });
+ *   verdict.action;                                    // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -784,13 +1060,83 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardCsv.buildProfile
+ * @signature  b.guardCsv.buildProfile(opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.gate, b.guardCsv.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus
+ * inline overrides. `opts.extends` is a profile name (`"strict"`
+ * / `"balanced"` / `"permissive"` / `"email-attachment"`) or an
+ * array of names; later entries shadow earlier ones. Inline
+ * `opts` keys win last. Used to keep operator-defined profiles
+ * traceable to a baseline rather than re-typing every key.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guard-csv key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardCsv.buildProfile({
+ *     extends: "strict",
+ *     trailingWhitespacePolicy: "preserve",
+ *     bomPrefix: true,
+ *   });
+ *   custom.formulaInjectionPolicy;                     // → "prefix-tab"
+ *   custom.bomPrefix;                                  // → true
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardCsv.compliancePosture
+ * @signature  b.guardCsv.compliancePosture(name)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCsv.gate, b.guardCsv.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (`"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of
+ * the posture object — the caller may mutate freely. Throws
+ * `GuardCsvError("csv.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardCsv.compliancePosture("hipaa");
+ *   posture.piiPolicy;                                 // → "redact"
+ *   posture.bidiCharPolicy;                            // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "csv");
 }
 
 var _csvRulePacks = gateContract.makeRulePackLoader(GuardCsvError, "csv");
+/**
+ * @primitive  b.guardCsv.loadRulePack
+ * @signature  b.guardCsv.loadRulePack(pack)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardCsv.gate
+ *
+ * Register an operator-supplied rule pack with the guard-csv
+ * registry. The pack is identified by `pack.id` (non-empty
+ * string) and stored for later inspection / dispatch by gates
+ * that opt in via `opts.rulePackId`. Returns the pack object
+ * unchanged on success; throws `GuardCsvError("csv.bad-opt")`
+ * when `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardCsv.loadRulePack({
+ *     id: "pii-extra",
+ *     rules: [
+ *       { id: "ssn-cell", severity: "critical",
+ *         detect: function (cell) { return /^\d{3}-\d{2}-\d{4}$/.test(cell); },
+ *         reason: "US SSN-shaped value in CSV cell" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "pii-extra"
+ */
 var loadRulePack = _csvRulePacks.load;
 
 module.exports = {