@blamejs/blamejs-shop 0.4.91 → 0.4.92

package/lib/vendor/blamejs/lib/codepoint-class.js

@@ -1,9 +1,24 @@
 "use strict";
 /**
- * codepoint-class — shared codepoint-table threat catalog and regex
- * compiler for the guard-* family.
+ * @module b.codepointClass
+ * @nav    Validation
+ * @title  Codepoint Class
  *
- * Threat detectors that need to match Unicode bidi overrides, C0
+ * @intro
+ *   Shared codepoint-table threat catalog and regex compiler — the Unicode
+ *   bidi-override / C0-control / zero-width / null-byte / Unicode-Tags tables
+ *   (plus UTS #39 confusable-script detection) that the
+ *   <code>b.guard*</code> family composes internally, exposed on the public
+ *   surface so a consumer can build a custom free-text screen without
+ *   re-rolling the regexes (where the zero-width class is mistyped and the
+ *   astral Unicode-Tags "ASCII smuggling" block forgotten) or coupling to an
+ *   internal module path. For a ready-made unconstrained-free-text guard reach
+ *   for <code>b.guardText</code>; use this catalog when you need the raw
+ *   detectors, tables, or script classifier to compose your own. Detectors
+ *   emit attack characters programmatically from numeric codepoint tables
+ *   (never as source literals), so files that use them stay pure ASCII.
+ *
+ *   Threat detectors that need to match Unicode bidi overrides, C0
  * control characters, zero-width / invisible chars, etc. compose
  * regex character classes from numeric codepoint range tables here
  * instead of embedding the attack characters directly in their
@@ -48,20 +63,68 @@
  *     attackers use to hide payloads:
  *     SHY  U+00AD  ZWSP U+200B  ZWNJ U+200C  ZWJ  U+200D
  *     WJ   U+2060  BOM  U+FEFF
+ *
+ * @card
+ *   The Unicode threat-codepoint catalog (bidi / control / zero-width / Tags
+ *   tables + confusable-script detection) the guard family composes — exposed
+ *   so you can build a custom free-text screen without re-rolling the regexes.
  */
 
 var HEX_RADIX = 16;                                                 // base-16 radix, not byte size
 
+/**
+ * @primitive b.codepointClass.hex4
+ * @signature b.codepointClass.hex4(cp)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.charClass, b.codepointClass.fromCp
+ *
+ * Format a codepoint as a 4-digit `\uXXXX` regex escape (zero-padded, upper
+ * case) — the building block `charClass` uses to compile a range table into a
+ * character-class body without embedding the attack character as a literal.
+ *
+ * @example
+ *   b.codepointClass.hex4(0x202E);   // returns the escape "\\u202E"
+ */
 function hex4(cp) {
   var s = cp.toString(HEX_RADIX).toUpperCase();
   while (s.length < 4) s = "0" + s;
   return "\\u" + s;
 }
+/**
+ * @primitive b.codepointClass.charClass
+ * @signature b.codepointClass.charClass(rangeList)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.hex4, b.codepointClass.detectCharThreats
+ *
+ * Compile a codepoint range table — numbers and `[lo, hi]` pairs — into a regex
+ * character-class body (the inner text of `[...]`), so a detector can build its
+ * own class from a catalog table without typing the codepoints as literals.
+ *
+ * @example
+ *   var body = b.codepointClass.charClass([0x200E, [0x202A, 0x202E]]);
+ *   var re = new RegExp("[" + body + "]");
+ */
 function charClass(rangeList) {
   return rangeList.map(function (r) {
     return Array.isArray(r) ? hex4(r[0]) + "-" + hex4(r[1]) : hex4(r);
   }).join("");
 }
+/**
+ * @primitive b.codepointClass.fromCp
+ * @signature b.codepointClass.fromCp(cp)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.hex4
+ *
+ * `String.fromCharCode` shorthand — emit the actual character for a codepoint
+ * at runtime (e.g. to build a test fixture) instead of typing the attack
+ * character as a source literal.
+ *
+ * @example
+ *   var rlo = b.codepointClass.fromCp(0x202E);   // the U+202E override char
+ */
 function fromCp(cp) { return String.fromCharCode(cp); }
 
 var BIDI_RANGES       = [0x200E, 0x200F, 0x061C, [0x202A, 0x202E], [0x2066, 0x2069]];
@@ -120,9 +183,22 @@ var SCRIPT_RANGES = {
   hebrew:   [[0x0590, 0x05FF]],                                                   // Hebrew
 };
 
-// scriptFor(cp) — returns the script-name string for a codepoint, or
-// null when the codepoint is in a script not in the catalog (digits,
-// punctuation, symbols, etc. are not script-classifying).
+/**
+ * @primitive b.codepointClass.scriptFor
+ * @signature b.codepointClass.scriptFor(cp)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.detectMixedScripts
+ *
+ * Return the Unicode script name for a codepoint (`"latin"`, `"cyrillic"`,
+ * `"greek"`, `"han"`, ...), or `null` when the codepoint is script-neutral
+ * (digits, punctuation, symbols). The classifier `detectMixedScripts` uses to
+ * spot homograph / confusable mixing (UTS&nbsp;#39).
+ *
+ * @example
+ *   b.codepointClass.scriptFor("a".charCodeAt(0));   // returns "latin"
+ *   b.codepointClass.scriptFor(0x0430);              // returns "cyrillic" (the confusable a)
+ */
 function scriptFor(cp) {
   var keys = Object.keys(SCRIPT_RANGES);
   for (var i = 0; i < keys.length; i += 1) {
@@ -134,17 +210,26 @@ function scriptFor(cp) {
   return null;
 }
 
-// detectMixedScripts(label, allowedScripts?) — returns null when the
-// label is single-script (or every script appears in the optional
-// allowedScripts allowlist), or an array of the detected script names
-// when the label mixes scripts (homograph attack shape — Cyrillic 'а'
-// inside an otherwise-Latin label, etc.). The result is the FULL set
-// of scripts seen; callers decide refuse / audit / strip.
-//
-// allowedScripts: an array of script names the caller treats as
-// acceptable; when supplied, a label whose every script is on the list
-// returns null even if multiple scripts appear (legitimate mixed-
-// script content like an English word inside a Japanese label).
+/**
+ * @primitive b.codepointClass.detectMixedScripts
+ * @signature b.codepointClass.detectMixedScripts(label, allowedScripts)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.scriptFor, b.guardText
+ *
+ * UTS&nbsp;#39 confusable detection: return `null` when `label` is single-script
+ * (or every script it uses is in the optional `allowedScripts` allowlist), or
+ * the full array of script names when it mixes scripts — the homograph attack
+ * shape (a Cyrillic confusable letter inside an otherwise-Latin label). Callers
+ * decide refuse / audit / strip. Pass `allowedScripts` to permit legitimate
+ * mixing (an ASCII word inside a non-Latin label).
+ *
+ * @example
+ *   b.codepointClass.detectMixedScripts("paypal");   // null (single-script)
+ *   var spoof = "pa" + b.codepointClass.fromCp(0x0443) + "pal";  // Cyrillic u (U+0443)
+ *   b.codepointClass.detectMixedScripts(spoof);                       // ["latin", "cyrillic"]
+ *   b.codepointClass.detectMixedScripts(spoof, ["latin", "cyrillic"]); // null (allowlisted)
+ */
 function detectMixedScripts(label, allowedScripts) {
   if (typeof label !== "string" || label.length === 0) return null;
   var seen = {};
@@ -162,16 +247,32 @@ function detectMixedScripts(label, allowedScripts) {
   return null;
 }
 
-// detectCharThreats — returns an array of issue objects for character-
-// class threats (bidi / null / C0-control) per the opts policy. Emits
-// at most one issue per class. Used by guard-* primitives' detection
-// pass instead of repeating the per-class match-and-push block.
-//
-// Issue shape mirrors guard-* convention:
-//   { kind, severity, ruleId, location, snippet }
-//
-//   issues.push.apply(issues,
-//     codepointClass.detectCharThreats(text, opts, "html"));
+/**
+ * @primitive b.codepointClass.detectCharThreats
+ * @signature b.codepointClass.detectCharThreats(text, opts, codePrefix, zeroWidthSeverity)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.assertNoCharThreats, b.codepointClass.applyCharStripPolicies, b.guardText
+ *
+ * Scan `text` for the character-class threats — bidi override, null byte, C0
+ * control, and (opt-in) zero-width — and return an array of issue objects
+ * `{ kind, severity, ruleId, location, snippet }`, at most one per class. Each
+ * class is gated by an opts policy that isn't `"allow"`; `ruleId` is prefixed
+ * with `codePrefix`. The non-throwing detection pass the `b.guard*` family
+ * shares instead of re-rolling the per-class match-and-push. `zeroWidthSeverity`
+ * opts the zero-width scan in and stamps its severity.
+ *
+ * @opts
+ *   bidiPolicy:      string,   // non-"allow" -> flag bidi overrides
+ *   nullBytePolicy:  string,   // non-"allow" -> flag null bytes
+ *   controlPolicy:   string,   // non-"allow" -> flag C0 controls
+ *   zeroWidthPolicy: string,   // non-"allow" (+ zeroWidthSeverity) -> flag zero-width
+ *
+ * @example
+ *   var issues = b.codepointClass.detectCharThreats(
+ *     userText, { bidiPolicy: "reject", nullBytePolicy: "reject" }, "comment");
+ *   if (issues.length) refuse(issues[0].ruleId);
+ */
 function detectCharThreats(text, opts, codePrefix, zeroWidthSeverity) {
   var issues = [];
   if (typeof text !== "string") return issues;
@@ -233,11 +334,29 @@ function detectCharThreats(text, opts, codePrefix, zeroWidthSeverity) {
   return issues;
 }
 
-// assertNoCharThreats — throws an instance of errorFactory(code, msg)
-// when the text contains a class that's set to "reject" in opts.
-// Opt-name vocabulary: bidiPolicy / nullBytePolicy / controlPolicy
-// (the standard guard-* family naming; older guard-csv uses different
-// names and keeps its inline checks).
+/**
+ * @primitive b.codepointClass.assertNoCharThreats
+ * @signature b.codepointClass.assertNoCharThreats(text, opts, errorFactory, codePrefix)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.detectCharThreats, b.guardText
+ *
+ * Throw — via `errorFactory(code, message)` — when `text` contains a character
+ * class whose opts policy is `"reject"` (bidi / null byte / C0 control). The
+ * throwing counterpart of `detectCharThreats`; `errorFactory` lets the caller
+ * raise its own typed error and `codePrefix` namespaces the rule code. The
+ * caller bounds the input length before calling (the regexes are unbounded).
+ *
+ * @opts
+ *   bidiPolicy:     string,   // "reject" -> throw on a bidi override
+ *   nullBytePolicy: string,   // "reject" -> throw on a null byte
+ *   controlPolicy:  string,   // "reject" -> throw on a C0 control
+ *
+ * @example
+ *   b.codepointClass.assertNoCharThreats(value,
+ *     { bidiPolicy: "reject", nullBytePolicy: "reject" },
+ *     function (code, msg) { return new TypeError(code + ": " + msg); }, "note");
+ */
 function assertNoCharThreats(text, opts, errorFactory, codePrefix) {
   if (typeof text !== "string") return;
   if (opts && opts.bidiPolicy === "reject" && BIDI_RE.test(text)) {           // allow:regex-no-length-cap — caller bounds length before invoking
@@ -254,15 +373,30 @@ function assertNoCharThreats(text, opts, errorFactory, codePrefix) {
   }
 }
 
-// applyCharStripPolicies — given a text and a policy object, apply
-// strip-mode replacements for each character-class threat. Reads:
-//   opts.bidiPolicy === "strip"      -> strip BIDI overrides
-//   opts.controlPolicy === "strip"   -> strip C0 controls
-//   opts.nullBytePolicy === "strip"  -> strip null bytes
-//   opts.zeroWidthPolicy === "strip" -> strip zero-widths
-//   opts.tagsPolicy === "strip"      -> strip Unicode Tags (U+E0000..)
-// Returns the cleaned string. Used by every guard's sanitize path so
-// each one doesn't reinvent the same sequence of replace() calls.
+/**
+ * @primitive b.codepointClass.applyCharStripPolicies
+ * @signature b.codepointClass.applyCharStripPolicies(text, opts)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.detectCharThreats, b.guardText
+ *
+ * Strip each character-class threat whose opts policy is `"strip"` and return
+ * the cleaned string — the sanitize counterpart of `detectCharThreats`, shared
+ * by every guard's sanitize path so none re-rolls the same sequence of
+ * `replace()` calls. Removes bidi overrides, C0 controls, null bytes,
+ * zero-width chars, and the Unicode-Tags block ("ASCII smuggling") per policy.
+ *
+ * @opts
+ *   bidiPolicy:      string,   // "strip" -> remove bidi overrides
+ *   controlPolicy:   string,   // "strip" -> remove C0 controls
+ *   nullBytePolicy:  string,   // "strip" -> remove null bytes
+ *   zeroWidthPolicy: string,   // "strip" -> remove zero-width / invisible chars
+ *   tagsPolicy:      string,   // "strip" -> remove the Unicode Tags block
+ *
+ * @example
+ *   var clean = b.codepointClass.applyCharStripPolicies(userText,
+ *     { bidiPolicy: "strip", zeroWidthPolicy: "strip", tagsPolicy: "strip" });
+ */
 function applyCharStripPolicies(text, opts) {
   if (typeof text !== "string") return text;
   var out = text;
@@ -278,11 +412,21 @@ function applyCharStripPolicies(text, opts) {
 // (. * + ? ^ $ { } ( ) | [ ] \).
 var REGEXP_META_RE = /[.*+?^${}()|[\]\\]/g;
 
-// escapeRegExp — escape every RegExp metacharacter in a string so an
-// operator- or input-supplied token matches literally when spliced into a
-// `new RegExp(...)`. Three lib sites previously rolled the identical body;
-// centralized here so a token destined for dynamic compilation cannot
-// inject a pattern.
+/**
+ * @primitive b.codepointClass.escapeRegExp
+ * @signature b.codepointClass.escapeRegExp(s)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.charClass
+ *
+ * Escape every ECMAScript RegExp metacharacter in a string so an operator- or
+ * input-supplied token matches literally when spliced into a `new RegExp(...)`
+ * — a token destined for dynamic compilation cannot inject a pattern.
+ *
+ * @example
+ *   var re = new RegExp(b.codepointClass.escapeRegExp("a.b*c"));
+ *   re.test("a.b*c");   // true — the . and * are literal
+ */
 function escapeRegExp(s) {
   return String(s).replace(REGEXP_META_RE, "\\$&");
 }
@@ -293,19 +437,43 @@ function escapeRegExp(s) {
 // lives once.
 var HEX_PAIR_RE = /^[0-9A-Fa-f]{2}$/;
 
-// isAsciiAlnum — codepoint is an ASCII letter or digit (A-Z / a-z / 0-9).
-// The ASCII-alphanumeric range test recurs across every byte-class parser
-// (URL unreserved, XML name chars, header tokens); centralized so the three
-// range literals live once rather than as a re-rolled `cc>=0x41&&...` chain.
+/**
+ * @primitive b.codepointClass.isAsciiAlnum
+ * @signature b.codepointClass.isAsciiAlnum(cc)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.isUnreserved
+ *
+ * Test whether a char code is an ASCII letter or digit (`A-Z` / `a-z` / `0-9`)
+ * — the alphanumeric range check that recurs across every byte-class parser
+ * (URL unreserved, XML name chars, header tokens), centralized so the range
+ * literals live once.
+ *
+ * @example
+ *   b.codepointClass.isAsciiAlnum("Z".charCodeAt(0));   // true
+ *   b.codepointClass.isAsciiAlnum("-".charCodeAt(0));   // false
+ */
 function isAsciiAlnum(cc) {
   return (cc >= 0x41 && cc <= 0x5a) ||   // A-Z
          (cc >= 0x61 && cc <= 0x7a) ||   // a-z
          (cc >= 0x30 && cc <= 0x39);     // 0-9
 }
 
-// isUnreserved — codepoint is in the RFC 3986 §2.3 unreserved set:
-// ALPHA / DIGIT / "-" / "." / "_" / "~". A percent-escape of an unreserved
-// character is over-encoding the URI spec says SHOULD be decoded (§6.2.2.3).
+/**
+ * @primitive b.codepointClass.isUnreserved
+ * @signature b.codepointClass.isUnreserved(cc)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.isAsciiAlnum
+ *
+ * Test whether a char code is in the RFC&nbsp;3986 §2.3 unreserved set —
+ * `ALPHA` / `DIGIT` / `-` / `.` / `_` / `~`. A percent-escape of an unreserved
+ * character is over-encoding the URI spec says SHOULD be decoded (§6.2.2.3).
+ *
+ * @example
+ *   b.codepointClass.isUnreserved("~".charCodeAt(0));   // true
+ *   b.codepointClass.isUnreserved("/".charCodeAt(0));   // false
+ */
 function isUnreserved(cc) {
   return isAsciiAlnum(cc) ||
          cc === 0x2d ||   // -
@@ -314,24 +482,29 @@ function isUnreserved(cc) {
          cc === 0x7e;     // ~
 }
 
-// isForbiddenControlChar — the header-injection / RFC 5322 control-byte
-// predicate every "refuse control bytes in a header / line / value" loop
-// shares across the mail guards (dsn / imap / list-id / list-unsubscribe /
-// mail-compose / mail-sieve / managesieve) and the safe-* text parsers
-// (ical / mime / vcard / toml). TRUE for DEL (0x7f) and any C0 control
-// (< 0x20) other than TAB (0x09); LF (0x0a) and CR (0x0d) are refused by
-// default but can be permitted per call (a line reader that has already
-// split on CRLF, or a grammar that allows folding). Distinct from the
-// C0_CTRL_RANGES regex above, which is the stripping/scanning table that
-// always exempts LF/CR and never matches DEL.
-//
-// opts.forbidTab — TAB (0x09) is normally permitted (it is folding
-// whitespace in RFC 5322 header values). The stricter identifier / key /
-// name / single-line-value contexts (idempotency keys, step-up challenge
-// values, mailbox / folder / message-id names, assembly ids, DNSBL-free
-// single-line values) forbid EVERY C0 control plus DEL — there is no
-// folding to honour — so they pass `{ forbidTab: true }`, making the
-// predicate exactly `code < 0x20 || code === 0x7f`.
+/**
+ * @primitive b.codepointClass.isForbiddenControlChar
+ * @signature b.codepointClass.isForbiddenControlChar(code, opts)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.firstControlCharOffset
+ *
+ * The header-injection / RFC&nbsp;5322 control-byte predicate every "refuse
+ * control bytes in a header / line / value" loop shares. Returns `true` for DEL
+ * (`0x7f`) and any C0 control (`< 0x20`) other than TAB (`0x09`); LF and CR are
+ * refused by default but can be permitted per call (a reader that already split
+ * on CRLF, or a folding grammar). Distinct from the `C0_CTRL_RE` scanning table
+ * which always exempts LF/CR and never matches DEL.
+ *
+ * @opts
+ *   forbidTab: boolean,   // also forbid TAB -> predicate is `code < 0x20 || code === 0x7f`
+ *   allowLf:   boolean,   // permit LF (0x0a)
+ *   allowCr:   boolean,   // permit CR (0x0d)
+ *
+ * @example
+ *   b.codepointClass.isForbiddenControlChar(0x00);                 // true (NUL)
+ *   b.codepointClass.isForbiddenControlChar(0x09, { forbidTab: true }); // true (TAB forbidden)
+ */
 function isForbiddenControlChar(code, opts) {
   if (code === 0x7f) return true;          // DEL
   if (code >= 0x20) return false;
@@ -343,12 +516,28 @@ function isForbiddenControlChar(code, opts) {
   return true;
 }
 
-// firstControlCharOffset — index of the first isForbiddenControlChar in `s`
-// (under the same opts), or -1 when none. Callers wrap it as a boolean
-// (`offset !== -1`), throw with the offending code (`s.charCodeAt(offset)`),
-// or derive a byte offset from the index — replacing the open-coded
-// `for (i) { c = charCodeAt(i); if (c === 0 || c === 0x7f || (c < 0x20 &&
-// c !== 0x09)) … }` scan each parser previously rolled by hand.
+/**
+ * @primitive b.codepointClass.firstControlCharOffset
+ * @signature b.codepointClass.firstControlCharOffset(s, opts)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.isForbiddenControlChar
+ *
+ * Return the index of the first forbidden control char in `s` (under the same
+ * `opts` as `isForbiddenControlChar`), or `-1` when none. Callers wrap it as a
+ * boolean (`!== -1`), throw with the offending code (`s.charCodeAt(offset)`),
+ * or derive a byte offset — replacing the open-coded control-byte scan each
+ * parser previously rolled by hand.
+ *
+ * @opts
+ *   forbidTab: boolean,   // also treat TAB as forbidden
+ *   allowLf:   boolean,   // permit LF (0x0a)
+ *   allowCr:   boolean,   // permit CR (0x0d)
+ *
+ * @example
+ *   b.codepointClass.firstControlCharOffset("ok\x00bad");   // 2 (the NUL)
+ *   b.codepointClass.firstControlCharOffset("clean");          // -1
+ */
 function firstControlCharOffset(s, opts) {
   for (var i = 0; i < s.length; i += 1) {
     if (isForbiddenControlChar(s.charCodeAt(i), opts)) return i;
@@ -364,6 +553,24 @@ function firstControlCharOffset(s, opts) {
 // / guard-markdown cannot drift on this (the bug class that shipped one buggy
 // + one correct copy).
 var NUMERIC_ENTITY_RE_G = /&#(?:x([0-9a-f]+)|(\d+));?/gi;
+/**
+ * @primitive b.codepointClass.decodeNumericEntities
+ * @signature b.codepointClass.decodeNumericEntities(s)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.codepointClass.detectCharThreats
+ *
+ * Decode HTML numeric character references (hex `&#x..;` and decimal `&#..;`)
+ * just enough to expose a scheme hidden behind entity-encoding. The trailing
+ * semicolon is OPTIONAL — a browser decodes `&#106avascript:` (no semicolon)
+ * the same as `&#106;avascript:`, so a semicolon-required decoder lets the
+ * no-semicolon form slip a scheme past an allowlist. Shared so the markup
+ * guards cannot drift on this.
+ *
+ * @example
+ *   b.codepointClass.decodeNumericEntities("&#106;avascript:");   // "javascript:"
+ *   b.codepointClass.decodeNumericEntities("&#106avascript:");    // "javascript:" (no semicolon)
+ */
 function decodeNumericEntities(s) {
   return String(s == null ? "" : s).replace(NUMERIC_ENTITY_RE_G, function (m, hex, dec) {
     var cp = hex !== undefined ? parseInt(hex, 16) : parseInt(dec, 10);

package/lib/vendor/blamejs/lib/framework-error.js

@@ -73,9 +73,19 @@ function defineClass(name, opts) {
   var alwaysPermanent = !!opts.alwaysPermanent;
   var withStatusCode  = !!opts.withStatusCode;
   var withCause       = !!opts.withCause;
+  // permanentClassifier(code, statusCode) => bool — DERIVES this.permanent from
+  // the error's own code (+ optional status) at EVERY construction, so a class
+  // whose terminal/transient nature depends on the code (a network client whose
+  // 4xx is terminal but 5xx is transient) classifies identically no matter which
+  // call site or helper builds it. The classifier's default governs a forgotten
+  // code, so it can fail closed. Constructor shape: (code, message, statusCode).
+  var permanentClassifier = typeof opts.permanentClassifier === "function" ? opts.permanentClassifier : null;
   if (alwaysPermanent && (withStatusCode || withCause)) {
     throw new Error("defineClass: alwaysPermanent is mutually exclusive with withStatusCode / withCause");
   }
+  if (permanentClassifier && (alwaysPermanent || withStatusCode || withCause)) {
+    throw new Error("defineClass: permanentClassifier is mutually exclusive with alwaysPermanent / withStatusCode / withCause");
+  }
   var flagKey = "is" + name;
 
   // Generated class — uses an anonymous class expression so we can set
@@ -88,6 +98,10 @@ function defineClass(name, opts) {
       this[flagKey] = true;
       if (alwaysPermanent) {
         this.permanent = true;
+      } else if (permanentClassifier) {
+        // (code, message, statusCode) — permanent derived from the code (+ status).
+        this.statusCode = arg3;
+        this.permanent = !!permanentClassifier(code, arg3);
       } else if (withCause) {
         this.cause = arg3;
       } else {

package/lib/vendor/blamejs/lib/fsm.js

@@ -71,7 +71,19 @@
  *     other concurrent calls await before they start.
  *   * Every transition emits `fsm.<machineName>.transition` via
  *     `audit.safeEmit` (drop-silent — operator audit-sink failures
- *     don't crash the caller).
+ *     don't crash the caller). The state commits before the
+ *     destination's `onEnter` runs, so a throwing `onEnter` still
+ *     records the transition (with outcome `failure` + the error)
+ *     rather than silently losing the audit entry.
+ *   * `instance.target(event)` resolves a transition's destination
+ *     state side-effect-free — same edge + guard check as `can()` but
+ *     returns the to-state (or `null` when the edge is illegal /
+ *     guard-refused). Use it to compose an external compare-and-swap
+ *     (the cross-instance claim on autocommit-only substrates) without
+ *     calling `transition()` before the claim is known to land.
+ *   * `transition(event, { audit: false })` suppresses the built-in
+ *     emit so that composition can emit its own enriched record once
+ *     the external claim resolves.
  *
  *   ## Serialization
  *
@@ -309,6 +321,12 @@ function _buildInstance(def, initialState, initialHistory, initialContext) {
   };
   instance.allowed   = function () { return _allowed(instance); };
   instance.can       = function (name) { return _can(instance, name); };
+  // Side-effect-free destination resolver — mirrors can() but returns the
+  // to-state (or null). Lets a consumer composing an EXTERNAL compare-and-swap
+  // (e.g. b.sql.guardedUpdate on an autocommit-only substrate) build the
+  // `SET status = <to>` claim without calling transition(), which would mutate
+  // state and emit an audit before the cross-instance claim is known to land.
+  instance.target    = function (name) { return _resolveTarget(instance, name); };
   instance.transition = function (name, opts) { return _enqueueTransition(instance, name, opts || {}); };
   instance.toJSON    = function () { return _toJSON(instance); };
   return instance;
@@ -332,22 +350,35 @@ function _allowed(instance) {
   return out;
 }
 
-function _can(instance, name) {
-  if (typeof name !== "string") return false;
+// Resolve the destination state for `name` from the current state,
+// side-effect-free: matches the (from, on) edge and runs the PURE guard
+// (guards are contractually side-effect-free). Returns the to-state string
+// when the transition is allowed, or null when the edge is illegal from the
+// current state or the guard refuses / throws. The single source of truth
+// for both can() (boolean) and target() (destination) so they can never
+// disagree about whether an edge is takeable.
+function _resolveTarget(instance, name) {
+  if (typeof name !== "string") return null;
   var defs = instance._def._byName[name];
-  if (!defs) return false;
+  if (!defs) return null;
   for (var i = 0; i < defs.length; i++) {
     var t = defs[i];
     if (t.from !== instance.state) continue;
     if (t.guard) {
       var verdict;
       try { verdict = t.guard(instance.context); }
-      catch (_e) { return false; }
-      if (verdict !== true) return false;
+      catch (_e) { return null; }
+      if (verdict !== true) return null;
     }
-    return true;
+    return t.to;
   }
-  return false;
+  return null;
+}
+
+// A to-state is always a non-empty identifier (validated at define-time), so
+// "resolved !== null" is an exact "is this edge takeable" test.
+function _can(instance, name) {
+  return _resolveTarget(instance, name) !== null;
 }
 
 function _enqueueTransition(instance, name, opts) {
@@ -428,25 +459,50 @@ async function _runTransition(instance, name, opts) {
   if (opts.actor != null)    historyEntry.actor    = opts.actor;
   if (opts.metadata != null) historyEntry.metadata = opts.metadata;
   instance.history.push(historyEntry);
+  // onEnter on the destination state. The state is ALREADY committed and the
+  // history entry pushed, so the transition is durable no matter what onEnter
+  // does. A throw from onEnter must still surface to the caller (operators
+  // wrap it to roll back), but it must NOT skip the audit emit below: the
+  // state moved, and "every transition lands in the audit chain" is the
+  // primitive's contract. Capture the onEnter error, always emit, then
+  // re-throw — otherwise a throwing onEnter leaves a committed state change
+  // with no audit record (a compliance hole for HIPAA/SOX/PCI state trails).
+  var enterErr = null;
   if (toBody && typeof toBody.onEnter === "function") {
-    var enterResult = toBody.onEnter(instance.context);
-    if (enterResult && typeof enterResult.then === "function") {
-      await enterResult;
+    try {
+      var enterResult = toBody.onEnter(instance.context);
+      if (enterResult && typeof enterResult.then === "function") {
+        await enterResult;
+      }
+    } catch (e) {
+      enterErr = e;
     }
   }
-  // Audit emission is drop-silent — operator audit-sink failures
-  // never crash the caller. The .safeEmit wrapper is itself
-  // drop-silent; the additional try/catch protects against the
-  // lazy-loaded audit module throwing at first-access time.
-  try {
-    audit().namespaced("fsm")(instance._def.name + ".transition", "success", {
-      from:       fromState,
-      to:         toState,
-      transition: name,
-      machine:    instance._def.name,
-      callerMeta: opts.metadata || null,
-    }, { actor: opts.actor ? { id: opts.actor } : { id: "<system>" } });
-  } catch (_e) { /* drop-silent — audit best-effort */ }
+  // Audit emission is drop-silent — operator audit-sink failures never crash
+  // the caller. The .safeEmit wrapper is itself drop-silent; the additional
+  // try/catch protects against the lazy-loaded audit module throwing at
+  // first-access time. Suppressed when the caller passes { audit: false } so a
+  // composition driving an external compare-and-swap can emit its OWN enriched
+  // record (with the claim's rowCount / external txn id) once the claim is
+  // known to have landed — see instance.target(). When onEnter threw, the
+  // record still fires but stamps outcome "failure" + the error so an auditor
+  // sees the transition committed with a failed entry hook.
+  if (opts.audit !== false) {
+    try {
+      var auditMeta = {
+        from:       fromState,
+        to:         toState,
+        transition: name,
+        machine:    instance._def.name,
+        callerMeta: opts.metadata || null,
+      };
+      if (enterErr) auditMeta.onEnterError = enterErr.message || String(enterErr);
+      audit().namespaced("fsm")(instance._def.name + ".transition",
+        enterErr ? "failure" : "success", auditMeta,
+        { actor: opts.actor ? { id: opts.actor } : { id: "<system>" } });
+    } catch (_e) { /* drop-silent — audit best-effort */ }
+  }
+  if (enterErr) throw enterErr;
   return { from: fromState, to: toState, on: name };
 }