@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-auth.js

@@ -1,30 +1,44 @@
 "use strict";
 /**
- * guard-auth — Composite auth-bundle safety primitive (b.guardAuth).
+ * @module b.guardAuth
+ * @nav    Guards
+ * @title  Guard Auth
  *
- * Composes guardJwt + guardOauth + the cookie/header middleware
- * validators into a single auth-flow check. KIND="auth-bundle" —
- * consumes `ctx.authBundle` shape:
- *   {
- *     jwtToken?:           string,           // routed to guardJwt
- *     oauthFlow?:          object,           // routed to guardOauth
- *     cookieHeader?:       string,           // routed to b.cookies.parseSafe
- *     requestHeaders?:     object,           // routed through threat-detection
- *   }
+ * @intro
+ *   Composite auth-bundle safety primitive (KIND="auth-bundle"). One
+ *   gate that sequences `b.guardJwt` (bearer token), `b.guardOauth`
+ *   (authorization-code / token-exchange flow shape), `b.cookies.parseSafe`
+ *   (Cookie header), and a light request-header threat scan
+ *   (Content-Length + Transfer-Encoding header smuggling per RFC 9112
+ *   §6.1) into a single check operators wire into the request
+ *   lifecycle. Consumes `ctx.authBundle`:
  *
- * Each sub-validator runs independently; aggregated issues are
- * returned with a `source` field tagging which sub-guard raised them.
- * Operators get one gate to drop into a request lifecycle that covers
- * the full canonical-auth threat surface.
+ *     {
+ *       jwtToken?:        string,    // routed to guardJwt
+ *       oauthFlow?:       object,    // routed to guardOauth
+ *       cookieHeader?:    string,    // routed to b.cookies.parseSafe
+ *       requestHeaders?:  object,    // routed through threat detection
+ *     }
  *
- *   var rv = b.guardAuth.validate({
- *     jwtToken:     bearerToken,
- *     oauthFlow:    req.query,
- *     cookieHeader: req.headers.cookie,
- *     requestHeaders: req.headers,
- *   }, { profile: "strict" });
+ *   Each sub-validator runs independently; aggregated issues carry a
+ *   `source` field (`"jwt"` / `"oauth"` / `"cookies"` / `"headers"` /
+ *   `"auth"`) tagging which sub-guard raised them so operators see
+ *   the full failure surface in one verdict.
+ *
+ *   Refusal posture: stale-token / alg=none JWT / unknown OAuth grant /
+ *   CL+TE header smuggling all surface as high-severity issues. Strict
+ *   profile requires at least one auth input via `requireAtLeastOne` —
+ *   a bundle with no jwtToken / oauthFlow / cookieHeader / requestHeaders
+ *   is refused so operators don't accidentally ship an unauthenticated
+ *   request through a gate they thought was active.
  *
- *   var g = b.guardAuth.gate({ profile: "strict" });
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance postures:
+ *   `hipaa` / `pci-dss` / `gdpr` / `soc2`. Operators select via
+ *   `{ profile: "strict" }` or `{ compliance: "hipaa" }`; postures
+ *   overlay on the profile baseline.
+ *
+ * @card
+ *   Composite auth-bundle safety primitive (KIND="auth-bundle").
  */
 
 var lazyRequire = require("./lazy-require");
@@ -183,6 +197,41 @@ function _detectIssues(bundle, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardAuth.validate
+ * @signature  b.guardAuth.validate(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardAuth.sanitize, b.guardAuth.gate, b.guardJwt.validate, b.guardOauth.validate
+ *
+ * Inspect an auth-bundle object and return `{ ok, issues, summary }`.
+ * Each issue carries `{ kind, severity, ruleId, source, snippet }`
+ * with severity in `"warn"|"high"|"critical"` and `source` tagging
+ * the sub-guard that raised it (`"jwt"` / `"oauth"` / `"cookies"` /
+ * `"headers"` / `"auth"`). Pure inspection — never mutates input or
+ * throws on hostile bundles.
+ *
+ * Strict profile sets `requireAtLeastOne: true` so an empty bundle
+ * (no jwtToken / oauthFlow / cookieHeader / requestHeaders) emits a
+ * `no-auth-input` issue — guards against an operator wiring a gate
+ * onto a request that ships no credentials at all.
+ *
+ * @opts
+ *   profile:           "strict"|"balanced"|"permissive",
+ *   compliance:        "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   childProfile:      "strict"|"balanced"|"permissive",   // forwarded to guardJwt / guardOauth
+ *   requireAtLeastOne: boolean,
+ *   allowedRedirectUris: string[],   // forwarded to guardOauth
+ *   maxBytes:          number,       // bundle JSON-byte cap
+ *
+ * @example
+ *   var rv = b.guardAuth.validate({
+ *     jwtToken: "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ4In0.",
+ *   }, { profile: "strict" });
+ *   rv.ok;                                             // → false
+ *   rv.issues.some(function (i) { return i.source === "jwt"; });   // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -191,6 +240,32 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardAuth.sanitize
+ * @signature  b.guardAuth.sanitize(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardAuth.validate, b.guardAuth.gate
+ *
+ * Strict pass-through validator. The auth-bundle is composed of values
+ * the framework cannot safely mutate (forging a JWT alg / rewriting an
+ * OAuth state parameter / dropping cookies would be silently dangerous
+ * — sanitize must never disarm an actual attack token), so this
+ * function refuses (throws `GuardAuthError`) on any critical or high
+ * issue and returns the input unchanged when clean.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *
+ * @example
+ *   var clean = b.guardAuth.sanitize({
+ *     jwtToken: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9." +
+ *               "eyJpc3MiOiJleGFtcGxlIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE3MDAwMDAwMDB9.sig",
+ *     cookieHeader: "sid=abc123",
+ *   }, { profile: "balanced" });
+ *   clean.cookieHeader;                                // → "sid=abc123"
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (!input || typeof input !== "object") {
@@ -207,6 +282,36 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardAuth.gate
+ * @signature  b.guardAuth.gate(opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardAuth.validate, b.guardAuth.sanitize, b.middleware.bearerAuth
+ *
+ * Build a `b.gateContract` gate that consumes `ctx.authBundle` (or
+ * `ctx.auth`) and dispatches to guardJwt / guardOauth / cookies /
+ * header-smuggling detection. Action chain on validation:
+ * `serve` (no bundle, or bundle clean) → `audit-only` (warn-only
+ * issues) → `refuse` (any critical or high issue from any
+ * sub-validator). No `sanitize` action — the auth bundle isn't
+ * repairable in transit.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *   childProfile: "strict"|"balanced"|"permissive",
+ *   allowedRedirectUris: string[],
+ *
+ * @example
+ *   var authGate = b.guardAuth.gate({ profile: "strict" });
+ *   var verdict = await authGate.check({ authBundle: {
+ *     jwtToken: "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ4In0.",
+ *   } });
+ *   verdict.action;                                    // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -230,14 +335,82 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardAuth.buildProfile
+ * @signature  b.guardAuth.buildProfile(opts)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardAuth.gate, b.guardAuth.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus inline
+ * overrides. `opts.extends` is a profile name (`"strict"` /
+ * `"balanced"` / `"permissive"`) 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
+ *
+ * @example
+ *   var custom = b.guardAuth.buildProfile({
+ *     extends: "balanced",
+ *     requireAtLeastOne: true,
+ *   });
+ *   custom.requireAtLeastOne;                          // → true
+ *   custom.bidiPolicy;                                 // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardAuth.compliancePosture
+ * @signature  b.guardAuth.compliancePosture(name)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardAuth.gate, b.guardAuth.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
+ * `GuardAuthError("auth.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardAuth.compliancePosture("hipaa");
+ *   posture.forensicSnippetBytes;                      // → 512
+ *   posture.bidiPolicy;                                // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "auth");
 }
 
 var _authRulePacks = gateContract.makeRulePackLoader(GuardAuthError, "auth");
+/**
+ * @primitive  b.guardAuth.loadRulePack
+ * @signature  b.guardAuth.loadRulePack(pack)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardAuth.gate
+ *
+ * Register an operator-supplied rule pack with the guard-auth
+ * 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 `GuardAuthError("auth.bad-opt")` when `pack` is
+ * missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardAuth.loadRulePack({
+ *     id: "tenant-bearer-prefix",
+ *     rules: [
+ *       { id: "tenant-prefix", severity: "high",
+ *         detect: function (b2) { return b2.jwtToken && b2.jwtToken.indexOf("tenant_") !== 0; },
+ *         reason: "JWT does not carry the required tenant_ prefix" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "tenant-bearer-prefix"
+ */
 var loadRulePack = _authRulePacks.load;
 
 module.exports = {

package/lib/guard-cidr.js

@@ -1,36 +1,46 @@
 "use strict";
 /**
- * guard-cidr — CIDR identifier-safety primitive (b.guardCidr).
+ * @module b.guardCidr
+ * @nav    Guards
+ * @title  Guard Cidr
  *
- * Validates user-supplied CIDR notation strings (IPv4 + IPv6) destined
- * for network-allowlists, ACLs, security-group rules, and tenant-
- * boundary configuration. KIND="identifier" — consumes ctx.identifier
- * (or ctx.cidr).
+ * @intro
+ *   CIDR identifier-safety primitive (KIND="identifier"). Validates
+ *   user-supplied CIDR notation strings (IPv4 + IPv6) destined for
+ *   network allowlists, ACLs, security-group rules, and tenant-
+ *   boundary configuration. Consumes `ctx.identifier` (or
+ *   `ctx.cidr`).
  *
- * Threat catalog:
- *   - Shape malformation — not "address/mask".
- *   - IPv4 octet out of range (> 255), wrong number of octets.
- *   - IPv6 zero-group inflation, multiple `::` (ambiguous).
- *   - Mask out of range (IPv4: 0-32; IPv6: 0-128); negative.
- *   - Network-address misalignment — `10.0.0.1/24` carries host bits
- *     set when /24 implies the pure network address `10.0.0.0/24`.
- *     Often a typo that produces unexpected match semantics.
- *   - Reserved IPv4 ranges (RFC 1918 private 10/8, 172.16/12,
- *     192.168/16; loopback 127/8; link-local 169.254/16; multicast
- *     224/4; reserved 240/4; documentation 192.0.2/24, 198.51.100/24,
- *     203.0.113/24; benchmarking 198.18/15; CGNAT 100.64/10).
- *   - Reserved IPv6 ranges — loopback `::1`, unspecified `::/128`,
- *     ULA `fc00::/7`, link-local `fe80::/10`, multicast `ff00::/8`,
- *     IPv4-mapped `::ffff:0:0/96`, documentation `2001:db8::/32`,
- *     teredo `2001::/32`, deprecated 6to4 `2002::/16`.
- *   - IPv4-mapped IPv6 confusion (CVE-2021-22931 IPv6 / IPv4 dual-
- *     stack class) — `::ffff:192.168.1.1` represents the IPv4 address
- *     in IPv6 namespace and trips dual-stack allowlist matchers.
- *   - BIDI / zero-width / control / null-byte universal refuse.
+ *   Shape and prefix-bound enforcement: every CIDR splits into
+ *   `address/mask`. IPv4 must be strict dotted-decimal (no leading
+ *   zeros — octal-form `0177.0.0.1` is refused at the parser; that
+ *   class is owned by `b.guardDomain`). IPv4 mask is `[0-32]`; IPv6
+ *   mask is `[0-128]`; out-of-range and non-numeric masks refuse.
+ *   IPv6 supports `::` zero-group compression with the standard
+ *   "at most one `::`" rule.
  *
- *   var rv = b.guardCidr.validate("10.0.0.0/8", { profile: "strict" });
- *   var safe = b.guardCidr.sanitize("10.0.0.1/24", { profile: "balanced" });
- *   var g = b.guardCidr.gate({ profile: "strict" });
+ *   Reserved-block awareness: IPv4 ranges per RFC 1918 (private 10/8,
+ *   172.16/12, 192.168/16), loopback 127/8, link-local 169.254/16,
+ *   multicast 224/4, reserved class-E 240/4, documentation 192.0.2/24,
+ *   198.51.100/24, 203.0.113/24, benchmarking 198.18/15, and CGNAT
+ *   100.64/10. IPv6 ranges: loopback `::1`, unspecified `::/128`,
+ *   ULA `fc00::/7`, link-local `fe80::/10`, multicast `ff00::/8`,
+ *   IPv4-mapped `::ffff:0:0/96`, documentation `2001:db8::/32`,
+ *   teredo `2001::/32`, deprecated 6to4 `2002::/16`. IPv4-mapped IPv6
+ *   trips dual-stack allowlist confusion (CVE-2021-22931 class) and
+ *   refuses under strict.
+ *
+ *   Network-address alignment: `10.0.0.1/24` has host bits set under
+ *   a /24 mask when the canonical network is `10.0.0.0/24`. Common
+ *   typo class — refused under strict, audited under balanced.
+ *   BIDI / control / null-byte / zero-width are universal-refuse at
+ *   every profile (codepoint-class catalog).
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   CIDR identifier-safety primitive (KIND="identifier").
  */
 
 var codepointClass = require("./codepoint-class");
@@ -418,6 +428,41 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardCidr.validate
+ * @signature  b.guardCidr.validate(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCidr.sanitize, b.guardCidr.gate
+ *
+ * Inspect a CIDR notation string and return `{ ok, issues, summary }`.
+ * Each issue carries `{ kind, severity, ruleId, snippet }` with
+ * severity in `"warn"|"high"|"critical"`. Detected: malformed address
+ * shape, octet-out-of-range, mask-out-of-range, network-address
+ * misalignment, reserved-range membership, IPv4-mapped-IPv6
+ * confusion, family mismatch, bare IP without `/mask`, BIDI / control
+ * / null-byte / zero-width codepoints. Pure inspection — never
+ * mutates input or throws.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   family:     "either"|"ipv4-only"|"ipv6-only",
+ *   networkAlignmentPolicy: "reject"|"audit"|"allow",
+ *   reservedRangesPolicy:   "reject"|"audit"|"allow",
+ *   ipv4MappedIpv6Policy:   "reject"|"audit"|"allow",
+ *   requireMaskPolicy:      "reject-bare-ip"|"audit-bare-ip"|"allow-bare-ip",
+ *   maxBytes:   number,    // CIDR string byte cap (default 64)
+ *
+ * @example
+ *   var rv = b.guardCidr.validate("10.0.0.0/8", { profile: "strict" });
+ *   rv.ok;                                             // → false
+ *   rv.issues.some(function (i) { return i.kind === "reserved-range"; });   // → true
+ *
+ *   var clean = b.guardCidr.validate("8.8.8.0/24", { profile: "strict" });
+ *   clean.ok;                                          // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -434,6 +479,31 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardCidr.sanitize
+ * @signature  b.guardCidr.sanitize(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardCidr.validate, b.guardCidr.gate
+ *
+ * Normalize a CIDR string when no critical/high issues fire. Throws
+ * `GuardCidrError` on any high/critical refusal (reserved-range,
+ * misalignment under strict, BIDI / null-byte / control bytes).
+ * Safe transforms applied otherwise: lowercase IPv6 hex groups,
+ * preserve mask form. IPv4 is returned unchanged (no canonical
+ * casing).
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *
+ * @example
+ *   var safe = b.guardCidr.sanitize("2001:DB8::/32", { profile: "permissive" });
+ *   safe;                                              // → "2001:db8::/32"
+ *
+ *   var v4 = b.guardCidr.sanitize("8.8.8.0/24", { profile: "strict" });
+ *   v4;                                                // → "8.8.8.0/24"
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -454,6 +524,32 @@ function sanitize(input, opts) {
   return mask === null ? addr.toLowerCase() : addr.toLowerCase() + "/" + mask;
 }
 
+/**
+ * @primitive  b.guardCidr.gate
+ * @signature  b.guardCidr.gate(opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCidr.validate, b.guardCidr.sanitize
+ *
+ * Build a `b.gateContract` gate that consumes `ctx.identifier` (or
+ * `ctx.cidr`) and dispatches `serve` (no input or clean) →
+ * `audit-only` (warn-only issues) → `refuse` (any critical or high
+ * issue). No `sanitize` action — CIDR sanitization is caller-driven
+ * via `b.guardCidr.sanitize`; an allowlist gate that silently rewrote
+ * the operator's network range would be its own bug class.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *   family:     "either"|"ipv4-only"|"ipv6-only",
+ *
+ * @example
+ *   var cidrGate = b.guardCidr.gate({ profile: "strict", family: "ipv4-only" });
+ *   var verdict = await cidrGate.check({ identifier: "10.0.0.0/8" });
+ *   verdict.action;                                    // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -477,14 +573,80 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardCidr.buildProfile
+ * @signature  b.guardCidr.buildProfile(opts)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardCidr.gate, b.guardCidr.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus inline
+ * overrides. `opts.extends` is a profile name (`"strict"` /
+ * `"balanced"` / `"permissive"`) or an array of names; later entries
+ * shadow earlier ones. Inline `opts` keys win last.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *
+ * @example
+ *   var custom = b.guardCidr.buildProfile({
+ *     extends: "balanced",
+ *     reservedRangesPolicy: "reject",
+ *   });
+ *   custom.reservedRangesPolicy;                       // → "reject"
+ *   custom.bidiPolicy;                                 // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardCidr.compliancePosture
+ * @signature  b.guardCidr.compliancePosture(name)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardCidr.gate, b.guardCidr.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
+ * `GuardCidrError("cidr.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardCidr.compliancePosture("hipaa");
+ *   posture.reservedRangesPolicy;                      // → "reject"
+ *   posture.forensicSnippetBytes;                      // → 128
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "cidr");
 }
 
 var _cidrRulePacks = gateContract.makeRulePackLoader(GuardCidrError, "cidr");
+/**
+ * @primitive  b.guardCidr.loadRulePack
+ * @signature  b.guardCidr.loadRulePack(pack)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardCidr.gate
+ *
+ * Register an operator-supplied rule pack with the guard-cidr
+ * 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 `GuardCidrError("cidr.bad-opt")` when `pack` is
+ * missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardCidr.loadRulePack({
+ *     id: "tenant-private-only",
+ *     rules: [
+ *       { id: "external-allowlisted", severity: "high",
+ *         detect: function (cidr) { return cidr.indexOf("10.") !== 0; },
+ *         reason: "tenant policy: only 10.0.0.0/8 ranges permitted" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "tenant-private-only"
+ */
 var loadRulePack = _cidrRulePacks.load;
 
 module.exports = {