@blamejs/core 0.18.46 → 0.18.48

package/CHANGELOG.md

@@ -8,6 +8,46 @@ upgrading across more than a few patches at a time.
 
 ## v0.18.x
 
+- v0.18.48 (2026-08-22) — **A guard option you set and a guard option that exists were not the same set.** Every `*Policy` option across the guard family now names the values it takes, and refuses everything else where options are resolved rather than at the first request that trips the scan. Holding the options to their vocabularies surfaced four places where what a guard advertised and what it did had come apart: an option documented under a name nothing read, a value that disabled a critical check without appearing in any opts block, two policies whose settings the gate's floor overrode anyway, and one declared in all three profiles and read nowhere. **Fixed:** *A guard policy refuses a value outside its vocabulary* — The two hundred and sixty-two `*Policy` options across the guard family each declare the values they accept, checked where options are resolved — boot, not the first hostile input — and on every entry point, including the `gate()` and `validate()` of guards that bind their own resolver.
+
+The failure it ends is quiet, because policies are read leniently. `duplicateKeyPolicy: "rejct"` is not `allow`, so the check still runs; it is not `reject` either, so the finding drops from critical to a warning. The operator asked to refuse a duplicate key and silently got an audit line. Nothing was let through that a stricter reading would have caught, so this was never a hole — but a setting that means something other than what it says is worth a restart to learn about.
+
+`b.gateContract.policyVocabulary(names, values, overrides?)` builds these tables: most of a guard's policies answer the same question — refuse the construct, record it, or let it through — and one or two do not. Written out per option instead, a family of nine ends up with eight that accept `audit-only` and one that does not. Each guard also exports its `POLICY_VOCABULARY`, so a caller can ask what an option takes instead of reading the source. · *An option name the guard does not have is refused rather than ignored* — A `*Policy` key that no guard option matches was kept by the option merge, read by nothing, and left the profile default in force. `b.guardMime` had shipped that way: its opts block named `riskyTypesPolicy` while the code reads `riskyTypePolicy`, so an operator following the documentation and setting it to `reject` kept the balanced profile's `audit` and had risky content types reported rather than refused, with nothing to see but the documentation that was wrong to begin with.
+
+A guard's policy set is fully described by its profiles, postures and defaults, so a near-miss is decidable and now refused by name. The rest of the option surface stays open — callbacks, caches and host wiring are not enumerable in advance.
+
+The two statements a guard makes about an option — the vocabulary it enforces and the opts block an operator reads — are now compared to each other, which is what surfaced this one. · *`kidTraversalPolicy: "allow"` turned off JWT key-path traversal detection* — `b.guardJwt` documents the `kid` traversal check as unconditional, and the header field it inspects is the one that steers key lookup — a `kid` of `../../etc/passwd` reaching a file-backed resolver is the point of the check. The code consulted `kidTraversalPolicy` for an `allow` its opts block never offered, and that value skipped the check entirely.
+
+The check no longer reads a policy, and the option accepts `reject` alone. `algNonePolicy` is likewise fixed at `reject`: `alg=none` was already refused unconditionally and the option had never been read. · *Two guardFilename policies were settings the floor already overrode* — `traversalPolicy` and `nullBytePolicy` accepted `allow` and `audit`, and both were overridden by the refusal floor the gate applies to a leaf filename. An operator setting either believed they had turned a class of finding down; the refusal stood regardless, and the two disagreed in the audit record rather than in the verdict. Both now accept `reject` alone, so the floor is visible in what the guard will take rather than only in what it does.
+
+`adsPolicy` keeps `allow` for the one place that honours it — `verifyExtractionPath`, for an operator deliberately extracting stream-suffixed names — and no longer accepts an `audit` that did nothing. · *`svgzPolicy` was declared in every profile and read nowhere* — A gzip-compressed SVG is refused on its byte signature before any parse, and `b.guardSvg.sanitize` throws on one outright. `svgzPolicy` sat in all three profiles without being consulted, so an operator writing `svgzPolicy: "allow"` got a silent no-op and a reasonable belief that SVGZ now passed. The option takes `reject` alone, which is what the guard has always done. · *Three policies do not take `audit-only`, because their code reads the literal `audit`* — `audit-only` is the family's documented synonym for `audit`, and most policies treat them identically because the disposition mapper asks one predicate. Three conditions test for the literal spelling instead, and there the two words took different branches with nothing in the option's name to say which you had picked: `pkcePolicy: "audit-only"` refused every OAuth flow missing a PKCE challenge while `"audit"` served it with a finding; `pollutionPolicy: "audit-only"` removed `__proto__` from the parsed object while `"audit"` preserved it, a difference in the data rather than in a finding; and `pathSeparatorsPolicy: "audit-only"` failed a path-shaped name that `"audit"` accepted.
+
+`b.guardOauth.pkcePolicy`, `b.guardJson.pollutionPolicy` and `b.guardFilename.pathSeparatorsPolicy` now refuse `audit-only` rather than accepting it and meaning something else by it — as `b.guardArchive.nestedArchivePolicy`, `b.guardDomain.trailingDotPolicy` and `b.guardYaml.tagPolicy` already did, for the same reason. Write `audit` on those six.
+
+A detector holds the pairing: a policy compared against the literal `"audit"` may not also advertise the synonym, so the next one is a failing gate rather than two spellings that quietly disagree. · *Which guards refuse `strip` on a character policy, in full* — 0.18.47 made repair capability a declaration rather than something inferred from the presence of a `sanitize`, and named four guards the inference had been wrong about. Fourteen refuse `strip` on the shared character policies; the list is here because the boot error lands on a caller who had a working configuration, and four names is not the set.
+
+Refuse it: `b.guardAuth`, `b.guardCidr`, `b.guardCountry`, `b.guardDomain`, `b.guardGraphql`, `b.guardJsonpath`, `b.guardJwt`, `b.guardMime`, `b.guardOauth`, `b.guardRegex`, `b.guardShell`, `b.guardTemplate`, `b.guardTime`, `b.guardUuid`. Accept it: `b.guardEmail`, `b.guardFilename`, `b.guardHtml`, `b.guardJson`, `b.guardMarkdown`, `b.guardSvg`, `b.guardText`, `b.guardXml`, `b.guardYaml`.
+
+All fourteen refuse the character rather than removing it. Feed `b.guardUuid.sanitize` an identifier with a zero-width character in it and it throws `uuid.zero-width`, because a UUID with the character removed is a different identifier — and the same holds for a CIDR block, a country code, a domain, a JSONPath, a media type, a timestamp, a GraphQL document, an OAuth flow and an auth bundle. There is no repaired form to route a `strip` to.
+
+`b.guardAuth`, `b.guardOauth` and `b.guardGraphql` are the clearest case for making capability a declaration rather than an inference: each carries a `sanitizeTransform` that is the identity function, because an auth bundle and an OAuth flow are composed of values the framework must not rewrite — forging a JWT `alg` or editing a `state` parameter would disarm the token the guard exists to catch. Inferring "can repair" from the presence of a `sanitize` read all three as repairing.
+
+`b.guardCsv`, `b.guardImage` and `b.guardPdf` expose no shared character policy at all. guardCsv repairs characters through its own `bidiCharPolicy`, `controlCharPolicy` and `homoglyphPolicy`, and those still take `strip`. · *Twenty opts-block lines offered a repair the guard cannot perform* — `b.guardUuid`, `b.guardCountry`, `b.guardTime`, `b.guardMime`, `b.guardShell`, `b.guardRegex`, `b.guardJsonpath` and `b.guardTemplate` documented `strip` on their character policies. None of them repairs a character — a UUID with a zero-width character in it is not a UUID with the character removed, it is a different identifier — so the value was refused at construction while the documentation offered it. The lines now name what the guards accept.
+
+- v0.18.47 (2026-08-22) — **A misspelled character policy was accepted at boot and quietly meant something else.** `bidiPolicy: "rejct"` was accepted by every door the framework offers — the guard's own option resolver and the gate built from it — and then read leniently at runtime: the scan runs because the value is not `allow`, an issue is raised, and the disposition falls through to refuse. Nothing is let through, so it was never a hole; the operator simply asked for one disposition, got another, and was told nothing at the moment a boot error would have cost them a restart. Ninety-three settings across the guard family behaved that way. **Fixed:** *A character policy refuses a value outside its vocabulary* — The five character-threat policies every guard shares — `bidiPolicy`, `nullBytePolicy`, `controlPolicy`, `zeroWidthPolicy`, `tagsPolicy` — now accept only `allow`, `audit`, `audit-only`, `reject`, and `strip` where the guard can carry a repair out. Anything else is refused where options are resolved, which is boot, not the first request that trips the scan. Every entry point takes the check: the generated resolver, and the `gate()` and `validate()` of the guards that bind their own.
+
+The check is derived from each guard's own declared defaults rather than hand-listed per guard, for the same reason the size caps beside it are. Hand-listing is what produced the gap: `b.guardCountry` added this for its own three options after `{ reservedPolicy: "rejcet" }` served a reserved country code and reported success, and the other two hundred and fifty-nine policy options across the family never followed. A guard that declares its own vocabulary explicitly still wins, so that one is unchanged.
+
+Whether a guard can perform a repair is now DECLARED rather than inferred from whether it exports a `sanitize`. An identifier guard exports one that validates and throws — a UUID with a zero-width character in it is not a UUID, and there is nothing to repair — so inferring the capability let `b.guardRegex`, `b.guardJwt`, `b.guardShell` and `b.guardTemplate` accept `strip` at construction and then refuse at runtime, which is the same silent substitution. Guards that repair say so, and the claim is held from both ends: `b.gateContract.defineGuard` refuses a spec that declares repair without a `sanitize` — or a `sanitizeTransform` for one to be built from — and the family sweep separately checks that a guard claiming it actually removes the character, while one that does not claim it refuses the instruction.
+
+What this does not yet cover: the guard-specific policies — formula injection, homoglyphs, DOCTYPE, aliases, and the rest — still accept anything. Their vocabularies genuinely differ from one another, and the set a profile happens to select is not the set the code accepts, so inferring them would refuse values that work today. Each needs its own list, read from the guard rather than guessed. · *`audit-only` did not mean what `audit` means* — The two have been synonyms wherever a policy is turned into a disposition. The severity calculation recognised only the literal `audit`, so on the public validation path they disagreed: `zeroWidthPolicy: "audit"` returned a pass with a warning, while `audit-only` returned a failure with a high-severity issue. The same split affected the control-character and Unicode Tags policies.
+
+One predicate decides it now, in the module that owns the character scanning, and the disposition mapper asks the same one. Two spellings of a single setting is how they come to disagree; asking one question is how they stop. · *The DNSSEC algorithm table called RSASHA512 current* — RFC 9904 replaced RFC 8624 as the DNSSEC algorithm requirements, and it reads RSASHA512 as NOT RECOMMENDED for signing while still MUST for validation. `b.network.dns.classifyDnskeyAlgorithm(10)` reported it as `current`, so an operator asking which algorithm to sign a zone with got the opposite of what the current document says.
+
+It is not marked deprecated, and deliberately: validation remains mandatory, and a caller using that flag to decide whether to ACCEPT a zone must keep accepting it. One boolean cannot carry a requirement that differs between signing and validation, so the reason names both levels and the flag follows the side an operator can still choose.
+
+The citations moved with it — DSA, DSA-NSEC3-SHA1 and ECC-GOST to RFC 9904's Table 2, the DS digest vocabulary and GOST R 34.11-94 to Table 3, and RSAMD5 off RFC 6944, which had been obsoleted twice over, onto RFC 6725. Nothing asserted on algorithm 10 before, which is how a stale classification sat in a table everything else in the file kept current.
+
 - v0.18.46 (2026-08-22) — **A failing test reported the handle it leaked instead of the check that failed.** Thirty test files ran their assertions inside a `try` whose `finally` drained open handles. A throw from a `finally` replaces the error the body raised, so when a test failed and its skipped teardown left a socket behind, what surfaced was "a handle leaked" — the consequence — while the check that actually failed was discarded. That is the shape of failure that reads as an unexplained flake, and it was reachable in every suite that opens a server. **Fixed:** *A drain no longer replaces the failure it followed* — `try { ...tests... } finally { await drain() }` reads as correct. It is not. When the body throws, every teardown after the throw is skipped, so the drain finds the servers those teardowns would have closed and throws too — and a throw from a `finally` replaces the body's error. The run reports a leaked handle, which is true and useless: the check that failed is gone, and the leak looks like the bug.
 
 The drain now runs through one helper that keeps the body's error and appends the others to it, so a run that failed for a reason reports that reason, and a run that only leaked still reports the leak. Thirty files moved onto it.

package/lib/codepoint-class.js

@@ -207,6 +207,33 @@ function firstInRanges(text, ranges, from) {
 // The shape the detectors want: `{ index, char, codePoint }` for the first
 // codepoint of `text` in `ranges`, or null. `char` is the WHOLE codepoint,
 // which for an astral hit is a surrogate pair.
+/**
+ * @primitive  b.codepointClass.isAuditPolicy
+ * @signature  b.codepointClass.isAuditPolicy(policy)
+ * @since      0.18.47
+ * @status     stable
+ * @related    b.gateContract.policyDisposition, b.gateContract.charPolicyEnums
+ *
+ * Whether a policy value asks for an AUDIT — reporting the finding rather than
+ * refusing or repairing. `audit-only` is the framework's own synonym for
+ * `audit`, and this is the one place that decides so.
+ *
+ * It exists because the two spellings disagreed. The disposition mapper treated
+ * them as the same thing while the severity calculation recognised only the
+ * literal `audit`, so `zeroWidthPolicy: "audit-only"` produced a high-severity
+ * issue and a failed validation where `audit` produced a warning and a pass.
+ * Two spellings of one setting is how they come to disagree; asking one
+ * predicate is how they stop.
+ *
+ * @example
+ *   b.codepointClass.isAuditPolicy("audit");       // → true
+ *   b.codepointClass.isAuditPolicy("audit-only");  // → true
+ *   b.codepointClass.isAuditPolicy("reject");      // → false
+ */
+function isAuditPolicy(policy) {
+  return policy === "audit" || policy === "audit-only";
+}
+
 function _firstHit(text, ranges) {
   var i = firstInRanges(text, ranges);
   if (i === -1) return null;
@@ -817,7 +844,7 @@ function detectCharThreats(text, opts, codePrefix) {
         // reported, so the audit setting did nothing an operator could
         // observe except the thing they asked it not to do.
         severity: opts.controlPolicy === "reject" ? "high"
-                : opts.controlPolicy === "audit"  ? "warn" : "high",
+                : isAuditPolicy(opts.controlPolicy) ? "warn" : "high",
         ruleId: codePrefix + ".control",
         location: ctrlMatch.index,
         // DEL is a control character here but is not in the C0 block, so the
@@ -849,7 +876,7 @@ function detectCharThreats(text, opts, codePrefix) {
       issues.push({
         kind: "zero-width",
         severity: opts.zeroWidthPolicy === "reject" ? "critical"
-                : opts.zeroWidthPolicy === "audit"  ? "warn" : "high",
+                : isAuditPolicy(opts.zeroWidthPolicy) ? "warn" : "high",
         ruleId: codePrefix + ".zero-width",
         location: zwMatch.index,
         snippet: "zero-width / invisible-formatting char U+" +
@@ -877,7 +904,7 @@ function detectCharThreats(text, opts, codePrefix) {
       issues.push({
         kind: "unicode-tags",
         severity: tagsPolicy === "reject" ? "critical"
-                : tagsPolicy === "audit"  ? "warn" : "high",
+                : isAuditPolicy(tagsPolicy) ? "warn" : "high",
         ruleId: codePrefix + ".unicode-tags",
         location: tagMatch.index,
         snippet: "Unicode Tags block char U+" +
@@ -1724,6 +1751,7 @@ module.exports = {
   hex4:              hex4,
   charClass:         charClass,
   inRanges:          inRanges,
+  isAuditPolicy:     isAuditPolicy,
   firstInRanges:     firstInRanges,
   stripRanges:       stripRanges,
   replaceRanges:     replaceRanges,

package/lib/gate-contract.js

@@ -2143,13 +2143,166 @@ function buildContentGate(spec) {
  *   b.gateContract.policyDisposition("audit-only");  // → "audit"
  *   b.gateContract.policyDisposition("rejet");       // → "refuse" (fail closed)
  */
+// The character-threat policies every guard in the family shares, and the
+// vocabulary each accepts. A value outside it is a typo, and a typo is a
+// CONFIG-TIME error: read leniently at runtime it takes whichever branch is not
+// the strict one — the scan runs because the value is not "allow", an issue is
+// raised, and policyDisposition falls through to "refuse". That fails closed,
+// so it is not a hole, but the operator asked for one disposition and silently
+// got another. This turns it into a boot error instead.
+//
+// `strip` is an instruction to repair, so it is legal only where the guard has
+// a `sanitize` to repair with — the same rule the family's performable-actions
+// invariant asserts. An `entries` guard has none by design: a hostile archive
+// member cannot be made safe.
+var CHAR_POLICY_KEYS = Object.freeze([
+  "bidiPolicy", "nullBytePolicy", "controlPolicy", "zeroWidthPolicy", "tagsPolicy",
+]);
+var CHAR_POLICY_BASE = Object.freeze(["allow", "audit", "audit-only", "reject"]);
+
+// The vocabularies a guard's own policies keep reaching for. Named because
+// most of a guard's policies answer the same question — refuse this construct,
+// record it, or let it through — and because a hand-written array per option
+// is where a family of nine drops `audit-only` from one of them.
+var POLICY_VALUES = Object.freeze({
+  // Refuse the construct, record it, or let it through. `audit-only` is the
+  // family's documented synonym for `audit`.
+  rejectAuditAllow:      Object.freeze(["reject", "audit", "audit-only", "allow"]),
+  // The same, where the guard can also remove the construct and still produce
+  // a usable document. Only for a finding the sanitizer genuinely repairs:
+  // routing one to a repair that never happens serves the input as sanitized.
+  rejectStripAuditAllow: Object.freeze(["reject", "strip", "audit", "audit-only", "allow"]),
+});
+
+/**
+ * @primitive  b.gateContract.policyVocabulary
+ * @signature  b.gateContract.policyVocabulary(names, values, overrides?)
+ * @since      0.18.48
+ * @status     stable
+ * @related    b.gateContract.charPolicyEnums, b.gateContract.defineGuard
+ *
+ * An `enumOpts` table where `names` all take `values`, with `overrides` merged
+ * over the top for the options that differ. Most of a guard's policies share
+ * one vocabulary and one or two do not, and writing the shared one out per
+ * option is how a family of nine ends up with eight that accept `audit-only`
+ * and one that does not.
+ *
+ * @example
+ *   var POLICY_ENUM = gateContract.policyVocabulary(
+ *     ["doctypePolicy", "entityPolicy", "cdataPolicy"],
+ *     gateContract.POLICY_VALUES.rejectAuditAllow,
+ *     { xmlDsigPolicy: ["audit", "audit-only", "allow"] });
+ *   POLICY_ENUM.entityPolicy;   // → ["reject", "audit", "audit-only", "allow"]
+ *   POLICY_ENUM.xmlDsigPolicy;  // → ["audit", "audit-only", "allow"]
+ */
+function policyVocabulary(names, values, overrides) {
+  if (!Array.isArray(names) || !Array.isArray(values) || values.length === 0) {
+    throw GateContractError.factory("gate-contract/bad-opt",
+      "gateContract.policyVocabulary: names and values must both be arrays " +
+      "and values must be non-empty");
+  }
+  // Frozen a level down, and from a copy. A guard publishes this table as its
+  // `POLICY_VOCABULARY` while the resolver checks against the same arrays, so
+  // an introspection caller that pushed onto one would be editing the rule, not
+  // reading it: `POLICY_VOCABULARY.symlinkPolicy.push("bogus")` and the guard
+  // accepts "bogus". Copying also keeps the caller's own array theirs.
+  var out = {};
+  var shared = Object.freeze(values.slice());
+  names.forEach(function (name) {
+    out[name] = shared;
+  });
+  if (overrides && typeof overrides === "object") {
+    Object.keys(overrides).forEach(function (name) {
+      // A non-array override would be dropped by the resolver's own
+      // `Array.isArray` test and leave the option unconstrained — the option
+      // would read as declared while accepting anything, which is the state
+      // this whole mechanism exists to end. It is an author mistake, so it
+      // belongs where the author is looking.
+      if (!Array.isArray(overrides[name]) || overrides[name].length === 0) {
+        throw GateContractError.factory("gate-contract/bad-opt",
+          "gateContract.policyVocabulary: override for " + JSON.stringify(name) +
+          " must be a non-empty array of values");
+      }
+      out[name] = Object.freeze(overrides[name].slice());
+    });
+  }
+  return Object.freeze(out);
+}
+
+/**
+ * @primitive  b.gateContract.charPolicyEnums
+ * @signature  b.gateContract.charPolicyEnums(defaults, opts?)
+ * @since      0.18.47
+ * @status     stable
+ * @related    b.gateContract.resolveProfileAndPosture, b.gateContract.defineGuard
+ *
+ * The `enumOpts` entry for every character-threat policy present in `defaults`,
+ * so a guard binding its own resolver holds callers to the same vocabulary the
+ * generated one does. `opts.canRepair` adds `strip`, which is an instruction to
+ * repair and so legal only where the guard has a `sanitize` to perform it.
+ *
+ * Pass the result as `enumOpts` to `resolveProfileAndPosture`. A guard whose
+ * gate or validate binds its own resolver and omits this accepts a misspelled
+ * policy on that entry point while the generated path refuses it — the two
+ * doors disagreeing is how the check came to cover only one of them.
+ *
+ * @opts
+ *   canRepair:  boolean,   // default: false — adds `strip` to every entry
+ *
+ * @example
+ *   gateContract.resolveProfileAndPosture(opts, {
+ *     profiles:  PROFILES,
+ *     defaults:  DEFAULTS,
+ *     enumOpts:  gateContract.charPolicyEnums(DEFAULTS, { canRepair: true }),
+ *   });
+ */
+function charPolicyEnums(defaults, opts) {
+  var canRepair = !!(opts && opts.canRepair);
+  var out = null;
+  for (var i = 0; i < CHAR_POLICY_KEYS.length; i += 1) {
+    var key = CHAR_POLICY_KEYS[i];
+    // `tagsPolicy` is usually ABSENT from a guard's defaults because it
+    // INHERITS from zeroWidthPolicy (resolveTagsPolicy reads one when the other
+    // is unset). It is still a supported inline override, so a guard exposing
+    // the inherited behaviour must hold a typo in it to the same vocabulary —
+    // keying only on presence left `{ tagsPolicy: "strp" }` unchecked on every
+    // guard that inherits, and the Tags detector then read the typo as a
+    // high-severity refusal instead of the promised boot error.
+    var governs = defaults && (typeof defaults[key] === "string" ||
+      (key === "tagsPolicy" && typeof defaults.zeroWidthPolicy === "string"));
+    if (!governs) continue;
+    if (!out) out = {};
+    out[key] = canRepair ? CHAR_POLICY_BASE.concat(["strip"]) : CHAR_POLICY_BASE.slice();
+  }
+  return out;
+}
+
+function _withCharPolicyEnums(defaults, spec) {
+  var declared = spec.enumOpts && typeof spec.enumOpts === "object" ? spec.enumOpts : null;
+  // DECLARED, not inferred from the presence of a `sanitize`. An identifier
+  // guard exports one that validates and throws — there is nothing to repair,
+  // the value either is a UUID or is not — so inferring the capability let
+  // guardRegex, guardJwt, guardShell and guardTemplate accept `strip` at
+  // construction and refuse at runtime, which is the silent substitution this
+  // check exists to stop. A guard says whether it can repair a character, and
+  // the family sweep holds it to the claim.
+  var derived = charPolicyEnums(defaults, { canRepair: spec.charRepair === true });
+  if (!derived) return declared || null;
+  var out = declared ? Object.assign({}, declared) : {};
+  Object.keys(derived).forEach(function (key) {
+    if (declared && declared[key]) return;                // an explicit declaration wins
+    out[key] = derived[key];
+  });
+  return out;
+}
+
 var MITIGATION_POLICIES = Object.freeze({
   strip: true, "prefix-tab": true, "prefix-quote": true,
   "wrap-with-quotes-and-prefix": true, allowlist: true, redact: true, trim: true,
 });
 function policyDisposition(policy) {
   if (policy === "reject") return "refuse";
-  if (policy === "audit" || policy === "audit-only") return "audit";
+  if (codepointClass.isAuditPolicy(policy)) return "audit";
   if (MITIGATION_POLICIES[policy] === true) return "sanitize";
   return "refuse";
 }
@@ -2598,10 +2751,77 @@ function resolveProfileAndPosture(opts, cfg) {
       }
     });
   }
+  // The same failure with the NAME wrong instead of the value, which is
+  // quieter because there is no value to inspect: the merge keeps the key,
+  // nothing reads it, and the profile default stays in force. An operator who
+  // sets `riskyTypesPolicy: "reject"` on a guard whose option is
+  // `riskyTypePolicy` keeps the balanced profile's "audit" and gets no sign
+  // the setting was dropped.
+  //
+  // Only `*Policy` keys are decidable this way: a guard's policy set is fully
+  // described by its profiles, postures and defaults, so anything else with
+  // that suffix is a near-miss. The rest of the opts surface stays open by
+  // design — callbacks, caches and host wiring are not enumerable in advance.
+  _refuseUnknownPolicyKeys(opts, resolved, cfg, ErrorClass, prefix);
   return resolved;
 }
 
 
+// A published copy of an enumOpts table, frozen a level down so a caller
+// reading it cannot reorder the guard's own vocabulary underneath it.
+function _freezeVocabulary(enumOpts) {
+  var out = {};
+  if (enumOpts && typeof enumOpts === "object") {
+    Object.keys(enumOpts).forEach(function (k) {
+      out[k] = Array.isArray(enumOpts[k]) ? Object.freeze(enumOpts[k].slice()) : enumOpts[k];
+    });
+  }
+  return Object.freeze(out);
+}
+
+// Every `*Policy` name this guard answers to: whatever its defaults carry, plus
+// whatever any profile or posture overlay can introduce, plus the vocabularies
+// declared for it. The union matters — a policy that only a strict profile sets
+// is still a real option, and `tagsPolicy` is governed through the family's
+// derivation without appearing in any defaults block.
+function _knownPolicyKeys(cfg) {
+  var known = Object.create(null);
+  function absorb(o) {
+    if (!o || typeof o !== "object") return;
+    Object.keys(o).forEach(function (k) {
+      if (/Policy$/.test(k)) known[k] = true;
+    });
+  }
+  absorb(cfg.defaults);
+  absorb(cfg.enumOpts);
+  [cfg.profiles, cfg.compliancePostures].forEach(function (table) {
+    if (!table || typeof table !== "object") return;
+    Object.keys(table).forEach(function (name) { absorb(table[name]); });
+  });
+  return known;
+}
+
+// Refuses a caller-supplied `*Policy` the guard has no such option for. Reads
+// the caller's own opts rather than the merged result, so a guard's internal
+// wiring is never the thing that fails, and stays silent for a guard that has
+// no policies at all — there, the suffix carries no meaning to trade on.
+function _refuseUnknownPolicyKeys(opts, resolved, cfg, ErrorClass, prefix) {
+  if (!opts || typeof opts !== "object") return;
+  var supplied = Object.keys(opts).filter(function (k) {
+    return /Policy$/.test(k) && opts[k] !== undefined;
+  });
+  if (!supplied.length) return;
+  var known = _knownPolicyKeys(cfg);
+  var names = Object.keys(known);
+  if (!names.length) return;
+  for (var i = 0; i < supplied.length; i += 1) {
+    if (known[supplied[i]]) continue;
+    throw ErrorClass.factory(prefix + ".bad-opt",
+      prefix + ": no option named " + JSON.stringify(supplied[i]) +
+      " — this guard's policies are " + names.sort().join(", "));
+  }
+}
+
 // The own enumerable properties of `o` that were actually given a value. A key
 // present with the value `undefined` is treated as absent, so it cannot erase
 // a default it was never meant to touch.
@@ -3168,7 +3388,12 @@ function defineGuard(spec) {
       // validate() below.
       nonNegativeOpts:    _capKeys(defaults, spec.intOpts),
       // Options restricted to a fixed vocabulary, checked at the same funnel.
-      enumOpts:           spec.enumOpts || null,
+      // The character policies are derived rather than hand-listed, for the
+      // reason the caps above are: declared per guard, they were declared by
+      // one. guard-country wrote `enumOpts` for its own three opts after
+      // `{ reservedPolicy: "rejcet" }` served a reserved code and reported ok,
+      // and the other 259 policy opts across the family never followed.
+      enumOpts:           _withCharPolicyEnums(defaults, spec),
     });
   };
   if (typeof spec.detect === "function") {
@@ -3360,11 +3585,23 @@ function defineGuard(spec) {
   var out = {
     NAME:                spec.name,
     KIND:                spec.kind,
+    // Surfaced so a caller — and the family sweep — can ask whether `strip` is
+    // an instruction this guard can carry out, rather than inferring it from
+    // the presence of a `sanitize` that may only validate and throw.
+    CHAR_REPAIR:         spec.charRepair === true,
     // The options this guard DECLARES to be caps, where zero is refused. Every
     // other numeric option is derived from the defaults and held only to
     // "non-negative integer", because derivation cannot tell a cap from a
     // tolerance. Exposed so the family tests can tell the two apart.
     INT_OPTS:            Object.freeze(Array.isArray(spec.intOpts) ? spec.intOpts.slice() : []),
+    // The value each policy option accepts, after the family's character
+    // policies are folded in. Exposed for the same reason as INT_OPTS: the
+    // family sweep has to ask each guard what it takes rather than assume one
+    // vocabulary for all of them. Where a guard pins a policy to a single
+    // value — guardFilename's traversal, guardJwt's alg=none — the answer is a
+    // one-element list, and a sweep that assumed otherwise would report the
+    // pinning as a regression.
+    POLICY_VOCABULARY:   _freezeVocabulary(_withCharPolicyEnums(defaults, spec)),
     validate:            spec.validate,
     resolveOpts:         _resolveGuardOpts,
     buildProfile:        buildProfileFn,
@@ -3379,6 +3616,20 @@ function defineGuard(spec) {
     out.EXTENSIONS = Object.freeze((spec.extensions || []).slice());
   }
   if (spec.integrationFixtures) out.INTEGRATION_FIXTURES = spec.integrationFixtures;
+  // A declaration has to be backed by something. `charRepair: true` says the
+  // guard can carry out `strip`, which puts that value in its character-policy
+  // vocabulary — so a spec that declares it without a `sanitize` (or a
+  // `sanitizeTransform` for one to be built from) would accept the instruction
+  // at boot and refuse it at runtime, which is the substitution the declaration
+  // was introduced to stop. Checked HERE rather than earlier because
+  // sanitizeTransform generates the sanitize further up, and checking before
+  // that would refuse a spec that does supply a repair path.
+  if (spec.charRepair === true && typeof spec.sanitize !== "function") {
+    throw ErrorClass.factory(prefix + ".bad-spec",
+      prefix + ": charRepair is declared but the guard has no sanitize — " +
+      "`strip` on a character policy is an instruction to repair, so declare a " +
+      "sanitize or a sanitizeTransform, or drop charRepair.");
+  }
   if (typeof spec.sanitize === "function") out.sanitize = spec.sanitize;
   out.gate = gateFn;
   // Error class exported under its own constructor name (GuardCsvError etc.)
@@ -3713,6 +3964,9 @@ module.exports = {
   // defineGuard: the cap keys to declare, derived from its defaults so the
   // list cannot drift away from them.
   capKeysOf:                capKeysOf,
+  charPolicyEnums:          charPolicyEnums,
+  policyVocabulary:         policyVocabulary,
+  POLICY_VALUES:            POLICY_VALUES,
   identitySanitize:         identitySanitize,
   ctxValueFrom:             ctxValueFrom,
   runIssueValidator:  runIssueValidator,

package/lib/guard-archive.js

@@ -197,6 +197,20 @@ var INT_OPTS = ["maxEntries", "maxTotalBytes", "maxEntryBytes",
 // DERIVED from DEFAULTS rather than written out, because a hand-kept list is
 // what drifted away from the defaults it was meant to mirror and left limits
 // unchecked across the family.
+// Each policy's vocabulary, so a misspelling is a boot error rather than a
+// runtime surprise. Read leniently, a typo takes whichever branch is not the
+// strict one: `symlinkPolicy: "rejct"` is not "allow", so the check runs, and
+// it is not "reject" either, so the finding drops from critical to warn.
+//
+// `audit-only` is deliberately absent, unlike elsewhere in the family:
+// nestedArchivePolicy tests for "audit" exactly, so the synonym would fall
+// past both branches and record nothing at all.
+var POLICY_ENUM = gateContract.policyVocabulary([
+  "traversalPolicy", "absolutePathPolicy", "symlinkPolicy", "hardlinkPolicy",
+  "nestedArchivePolicy", "duplicateNamePolicy", "caseInsensitiveCollisionPolicy",
+  "encryptionPolicy", "sparseEntryPolicy",
+], ["reject", "audit", "allow"]);
+
 function _resolveOpts(opts) {
   return gateContract.resolveProfileAndPosture(opts, {
     profiles:           PROFILES,
@@ -206,6 +220,7 @@ function _resolveOpts(opts) {
     errCodePrefix:      "archive",
     intOpts:            INT_OPTS,
     nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
+    enumOpts:           POLICY_ENUM,
   });
 }
 
@@ -866,6 +881,9 @@ module.exports = {
   // ---- guard-* family registry exports (consumed by b.guardAll) ----
   NAME:                "archive",
   KIND:                "entries",                                                 // archive-entries guard (consumes ctx.entries)
+  // The value each policy accepts. Named here rather than derived, because
+  // this guard binds its own resolver instead of going through defineGuard.
+  POLICY_VOCABULARY:   POLICY_ENUM,
   INTEGRATION_FIXTURES: Object.freeze({
     kind:           "entries",
     contentType:    "application/zip",

package/lib/guard-auth.js

@@ -393,7 +393,35 @@ var INTEGRATION_FIXTURES = Object.freeze({
 // surface (validate / sanitize / bespoke gate) passed through verbatim.
 // The custom KIND ("auth-bundle") is accepted because the bespoke gate
 // reads its own ctx fields (ctx.authBundle / ctx.auth).
+// The policies this wrapper accepts on the wrapped guard's behalf, with the
+// wrapped guard's own vocabulary for each. Derived rather than restated: a
+// second copy of guardOauth's values here would be free to drift from the ones
+// the child actually enforces, and the operator would meet whichever of the
+// two happened to be wrong.
+//
+// Without this, forwarding `codeReusePolicy` through the wrapper failed at the
+// wrapper's own resolver, because the name belongs to the child and this
+// guard's profiles never mention it.
+//
+// The character policies are excluded even though they are forwarded: their
+// vocabulary is derived per guard from whether that guard can repair a
+// character, and this guard cannot. Taking the child's answer would hand this
+// one a `strip` it has no way to carry out the moment the two differ — the
+// substitution that accepting-then-refusing was introduced to stop.
+var CHILD_OWNED_POLICIES = Object.freeze([
+  "bidiPolicy", "controlPolicy", "nullBytePolicy", "zeroWidthPolicy", "tagsPolicy",
+]);
+var FORWARDED_POLICY_ENUM = Object.freeze(
+  OAUTH_FORWARDED_OPTS.reduce(function (acc, key) {
+    if (CHILD_OWNED_POLICIES.indexOf(key) !== -1) return acc;
+    var vocabulary = guardOauth.POLICY_VOCABULARY &&
+                     guardOauth.POLICY_VOCABULARY[key];
+    if (Array.isArray(vocabulary)) acc[key] = vocabulary;
+    return acc;
+  }, {}));
+
 var _guard = module.exports = gateContract.defineGuard({
+  enumOpts:    FORWARDED_POLICY_ENUM,
   name:        "auth",
   kind:        "auth-bundle",
   errorClass:  GuardAuthError,

package/lib/guard-cidr.js

@@ -494,10 +494,29 @@ var INTEGRATION_FIXTURES = gateContract.identifierFixtures("8.8.8.0/24", "10.0.0
 // standard serve -> audit-only -> refuse chain — reading ctx.identifier ||
 // ctx.cidr via ctxFields. No sanitize action: an allowlist gate never
 // rewrites the operator's stored network range.
+// Each policy's vocabulary, so a misspelling is a boot error rather than a
+// runtime surprise. Read leniently, a typo takes whichever branch is not the
+// strict one: `reservedRangesPolicy: "rejct"` is not "allow", so the check
+// runs, and it is not "reject" either, so the finding drops to a warning — the
+// operator asked to refuse a reserved range and silently got an audit.
+//
+// requireMaskPolicy carries its own spellings because the question is about the
+// mask rather than a threat disposition. `audit-only` rides with `audit` on the
+// three that take one, matching how the framework treats the two everywhere
+// else.
+var POLICY_ENUM = gateContract.policyVocabulary([
+  "networkAlignmentPolicy", "reservedRangesPolicy", "ipv4MappedIpv6Policy",
+], gateContract.POLICY_VALUES.rejectAuditAllow, {
+  // Names its own values because the finding is an absence — a bare address
+  // where a mask was expected — so "reject" alone would not say what of.
+  requireMaskPolicy: ["allow-bare-ip", "audit-bare-ip", "reject-bare-ip"],
+});
+
 module.exports = gateContract.defineGuard({
   name:        "cidr",
   kind:        "identifier",
   errorClass:  GuardCidrError,
+  enumOpts:    POLICY_ENUM,
   profiles:    PROFILES,
   base:        128,
   integrationFixtures: INTEGRATION_FIXTURES,

package/lib/guard-country.js

@@ -348,10 +348,10 @@ function _detectIssues(input, opts) {
  * @opts
  *   profile:            "strict"|"balanced"|"permissive",
  *   compliancePosture:  "hipaa"|"pci-dss"|"gdpr"|"soc2",
- *   bidiPolicy:         "reject"|"strip"|"audit"|"allow",
- *   controlPolicy:      "reject"|"strip"|"allow",
- *   nullBytePolicy:     "reject"|"strip"|"allow",
- *   zeroWidthPolicy:    "reject"|"strip"|"allow",
+ *   bidiPolicy:         "reject"|"audit"|"allow",
+ *   controlPolicy:      "reject"|"audit"|"allow",
+ *   nullBytePolicy:     "reject"|"audit"|"allow",
+ *   zeroWidthPolicy:    "reject"|"audit"|"allow",
  *   reservedPolicy:     "reject"|"audit"|"allow",
  *   userAssignedPolicy: "reject"|"audit"|"allow",
  *   formerlyUsedPolicy: "reject"|"audit"|"allow",

package/lib/guard-csv.js

@@ -639,7 +639,7 @@ function _stripIssues(text, opts) {
  * twice does not stack prefixes.
  *
  * @opts
- *   formulaInjectionPolicy: "prefix-tab"|"prefix-quote"|"wrap-with-quotes-and-prefix"|"reject"|"allowlist",
+ *   formulaInjectionPolicy: "prefix-tab"|"prefix-quote"|"wrap-with-quotes-and-prefix"|"reject"|"allowlist"|"audit-only"|"allow",
  *   formulasAllowlist:      string[],   // when policy === "allowlist"
  *   bidiCharPolicy:         "reject"|"strip"|"audit"|"allow",
  *   controlCharPolicy:      "reject"|"strip"|"allow",
@@ -1047,7 +1047,7 @@ function serialize(rows, opts) {
  *   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",
+ *   formulaInjectionPolicy: "prefix-tab"|"prefix-quote"|"wrap-with-quotes-and-prefix"|"reject"|"allowlist"|"audit-only"|"allow",
  *   dangerousFunctions:    string[],
  *   dialectPolicy:         "strict"|"permissive",
  *
@@ -1409,7 +1409,36 @@ var INTEGRATION_FIXTURES = Object.freeze({
 // extras (serialize / escapeCell / detect / schema / FORMULA_PREFIXES /
 // DANGEROUS_FUNCTIONS) passed through verbatim. The bespoke `gate` carries
 // CSV's sanitize-reparse-reserialize chain unchanged.
+// Each policy's vocabulary, so a misspelling is a boot error rather than a
+// runtime surprise. Read leniently, a typo takes whichever branch is not the
+// strict one: `formulaInjectionPolicy: "prefix-tabb"` is neither "allow" nor
+// "audit-only", so a mitigation is attempted, and it is not a spelling the
+// mitigation recognises — the operator asked for a tab prefix and got something
+// else without being told.
+//
+// The sets are the UNION of what the code compares, what the opts blocks
+// document and what the shipped profiles select, because no single source was
+// complete: the two opts blocks disagreed with each other, one listing
+// `allowlist` and the other `audit-only` / `allow`, while the code compares all
+// three. Both blocks now carry the full set.
+//
+// The last four are MODE settings rather than threat dispositions — a dialect,
+// a numeric rendering, whether whitespace is kept — so they share nothing with
+// the disposition vocabulary and are listed on their own terms.
+var POLICY_ENUM = Object.freeze({
+  formulaInjectionPolicy:   ["prefix-tab", "prefix-quote", "wrap-with-quotes-and-prefix",
+                             "reject", "allowlist", "audit-only", "allow"],
+  bidiCharPolicy:           ["reject", "strip", "audit", "allow"],
+  controlCharPolicy:        ["reject", "strip", "allow"],
+  homoglyphPolicy:          ["audit", "strip", "allow"],
+  trailingWhitespacePolicy: ["trim", "preserve", "reject"],
+  dialectPolicy:            ["strict", "permissive"],
+  numericPrecisionPolicy:   ["decimal-string-above-safe-int", "scientific", "reject-bigint"],
+  piiPolicy:                ["preserve", "redact"],
+});
+
 module.exports = gateContract.defineGuard({
+  enumOpts:    POLICY_ENUM,
   name:        "csv",
   kind:        "content",
   errorClass:  GuardCsvError,