@blamejs/blamejs-shop 0.4.56 → 0.4.57

package/lib/vendor/blamejs/test/layer-0-primitives/session-valid-from.test.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * b.session.bump / validFrom / check — per-subject valid-from boundary for
+ * STATELESS self-validating tokens (sealed cookies with no DB row, JWTs) that
+ * destroy()/destroyAllForUser() can't revoke by deleting a row (#331).
+ *
+ * Drives the real consumer path through the public b.session surface against a
+ * real test DB (setupTestDb provisions the framework _blamejs_session_valid_from
+ * table). RED on the current tree: b.session.bump is undefined.
+ */
+
+var helpers = require("../helpers");
+var b     = helpers.b;
+var check = helpers.check;
+var setupTestDb = helpers.setupTestDb;
+var teardownTestDb = helpers.teardownTestDb;
+var fs   = require("fs");
+var os   = require("os");
+var path = require("path");
+
+async function run() {
+  var tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-svf-"));
+  try {
+    await setupTestDb(tmpDir);
+    var s = b.session;
+
+    check("bump / validFrom / check are exported on b.session",
+      typeof s.bump === "function" && typeof s.validFrom === "function" && typeof s.check === "function");
+
+    // A never-bumped subject has boundary 0 — every non-negative iat is valid.
+    check("validFrom is 0 for a never-bumped subject", (await s.validFrom("user-1")) === 0);
+    var t0 = Date.now() - 10000;
+    check("a token issued before any bump is valid", (await s.check("user-1", t0)) === true);
+
+    // bump raises the boundary to now; tokens issued before it are revoked.
+    var boundary = await s.bump("user-1");
+    check("bump returns the effective boundary (>= the pre-bump iat)",
+      typeof boundary === "number" && boundary >= t0);
+    check("validFrom now reflects the bump", (await s.validFrom("user-1")) === boundary);
+    check("a token issued BEFORE the bump is now revoked", (await s.check("user-1", t0)) === false);
+    check("a token issued AFTER the bump is still valid", (await s.check("user-1", boundary + 1000)) === true);
+
+    // Monotonic: a lower (replayed / clock-skewed) epoch can't move it back.
+    var lower = await s.bump("user-1", { epochMs: boundary - 5000 });
+    check("a bump to a LOWER epoch is a monotonic no-op", lower === boundary);
+    var higher = await s.bump("user-1", { epochMs: boundary + 5000 });
+    check("a bump to a HIGHER epoch advances the boundary", higher === boundary + 5000);
+
+    // check fails CLOSED on a malformed iat (treat an unparseable token as revoked).
+    check("check fails closed on NaN iat", (await s.check("user-1", NaN)) === false);
+    check("check fails closed on a negative iat", (await s.check("user-1", -1)) === false);
+    check("check fails closed on a non-number iat", (await s.check("user-1", "123")) === false);
+
+    // bump validates its inputs (config-time throw tier).
+    var threwSubject = false;
+    try { await s.bump(""); } catch (e) { threwSubject = /INVALID_ARG/.test(e.code || ""); }
+    check("bump rejects an empty subjectId", threwSubject);
+    var threwEpoch = false;
+    try { await s.bump("user-1", { epochMs: -1 }); } catch (e) { threwEpoch = /INVALID_ARG/.test(e.code || ""); }
+    check("bump rejects a negative epochMs", threwEpoch);
+
+    // #17 integration: a "logout everywhere" via destroyAllForUser also raises
+    // the stateless boundary, so the operator's stateless tokens are revoked
+    // too — not only the store-backed rows.
+    check("a fresh subject starts un-bumped", (await s.validFrom("user-2")) === 0);
+    await s.destroyAllForUser("user-2");
+    check("destroyAllForUser raises the stateless valid-from boundary", (await s.validFrom("user-2")) > 0);
+  } finally {
+    try { await teardownTestDb(tmpDir); } catch (_e) { /* best-effort */ }
+  }
+}
+
+module.exports = { run: run };

package/lib/vendor/blamejs/test/layer-0-primitives/sql.test.js

@@ -31,6 +31,7 @@ async function run() {
   check("b.sql.update",      typeof b.sql.update === "function");
   check("b.sql.delete",      typeof b.sql.delete === "function");
   check("b.sql.upsert",      typeof b.sql.upsert === "function");
+  check("b.sql.insertSelectWhere", typeof b.sql.insertSelectWhere === "function");
   check("b.sql.table",       typeof b.sql.table === "function");
   check("b.sql.createTable", typeof b.sql.createTable === "function");
   check("b.sql.createIndex", typeof b.sql.createIndex === "function");
@@ -590,6 +591,105 @@ async function run() {
   check("upsert readback renders a cast conflict key (CAST) binding the inner value, not the wrapper",
         rbCast.readbackSql && rbCast.readbackSql.sql.indexOf("CAST(") !== -1 &&
           rbCast.readbackSql.params.length === 1 && rbCast.readbackSql.params[0] === "42");
+
+  // ==== insertSelectWhere (conditional INSERT...SELECT...WHERE, #335) ====
+  // The append-only-ledger debit: a row written ONLY when a guard derived
+  // from the table itself holds, with no mutable counter row to increment().
+  // Standard SQL across all three dialects; the SELECT is value-less and the
+  // WHERE admits one row or zero.
+
+  // Object-form values infer the column list; the guard is an EXISTS over a
+  // same-dialect sub-builder (the balance fence). The cells route through the
+  // value-cell choke-point (fn(NOW) emits a token, no param).
+  var ledgerBalance = sql.select("wallet_ledger", { dialect: "postgres" }).selectRaw("1")
+    .whereRaw('"wallet_id" = ?', ["w-1"]);
+  var debit = sql.insertSelectWhere("wallet_ledger", { dialect: "postgres" })
+    .values({ wallet_id: "w-1", amount: -25, at: sql.fn("NOW") })
+    .whereExists(ledgerBalance)
+    .returning(["id"]).toSql();
+  check("insertSelectWhere emits INSERT...SELECT cells...WHERE EXISTS...RETURNING",
+        debit.sql === 'INSERT INTO wallet_ledger ("wallet_id", "amount", "at") ' +
+          'SELECT ?, ?, NOW() WHERE EXISTS (SELECT 1 FROM wallet_ledger WHERE ("wallet_id" = ?)) ' +
+          'RETURNING "id"');
+  check("insertSelectWhere binds value cells then the guard params in order, fn emits no param",
+        debit.params.length === 3 && debit.params[0] === "w-1" &&
+          debit.params[1] === -25 && debit.params[2] === "w-1");
+
+  // Positional values() aligned to a prior columns() call, sqlite dialect,
+  // a scalar guard (whereOp). No RETURNING -> none emitted.
+  var lit = sql.insertSelectWhere("seats", { dialect: "sqlite" })
+    .columns(["event_id", "seat_no"]).values(["e-9", 12])
+    .whereOp("event_id", "=", "e-9").toSql();
+  check("insertSelectWhere positional values + sqlite quoting + scalar guard",
+        lit.sql === 'INSERT INTO seats ("event_id", "seat_no") SELECT ?, ? WHERE "event_id" = ?' &&
+          lit.params.length === 3 && lit.params[2] === "e-9");
+
+  // cast cell binds value + casts the placeholder (Postgres ?::jsonb).
+  var castSel = sql.insertSelectWhere("docs", { dialect: "postgres" })
+    .values({ id: 1, meta: sql.cast('{"a":1}', "jsonb") })
+    .whereOp("id", "=", 1).toSql();
+  check("insertSelectWhere renders a cast SELECT cell (?::jsonb) binding the inner value",
+        /SELECT \?, \?::jsonb WHERE "id" = \?/.test(castSel.sql) &&
+          castSel.params.length === 3 && castSel.params[1] === '{"a":1}');
+
+  // MySQL: standard form, backtick quoting; RETURNING refused (run an explicit read).
+  var my = sql.insertSelectWhere("ledger", { dialect: "mysql" })
+    .values({ k: "a", n: 1 }).whereOp("k", "=", "a").toSql();
+  check("insertSelectWhere mysql backtick quoting",
+        my.sql === "INSERT INTO ledger (`k`, `n`) SELECT ?, ? WHERE `k` = ?");
+  rejects("insertSelectWhere RETURNING refused on mysql", function () {
+    return sql.insertSelectWhere("ledger", { dialect: "mysql" })
+      .values({ k: "a" }).whereOp("k", "=", "a").returning(["k"]).toSql();
+  }, "sql-builder/returning-unsupported");
+
+  // Safety default: an un-guarded conditional insert THROWS (like update/delete);
+  // allowNoWhere() opts in deliberately.
+  rejects("insertSelectWhere without where throws (no-where default)", function () {
+    return sql.insertSelectWhere("ledger").values({ k: "a", n: 1 }).toSql();
+  }, "sql-builder/no-where");
+  var noWhere = sql.insertSelectWhere("ledger").values({ k: "a", n: 1 }).allowNoWhere().toSql();
+  check("insertSelectWhere allowNoWhere() emits a guard-less SELECT",
+        noWhere.sql === 'INSERT INTO ledger ("k", "n") SELECT ?, ?' && noWhere.params.length === 2);
+
+  // No values() -> empty-values; values() missing a declared column -> missing-column;
+  // an extra key not in the declared column set -> extra-column (no silent data drop).
+  rejects("insertSelectWhere without values throws", function () {
+    return sql.insertSelectWhere("ledger").columns(["k"]).whereOp("k", "=", "a").toSql();
+  }, "sql-builder/empty-values");
+  rejects("insertSelectWhere positional value-count mismatch", function () {
+    return sql.insertSelectWhere("ledger").columns(["k", "n"]).values(["only-one"]);
+  }, "sql-builder/value-count");
+  rejects("insertSelectWhere row missing a declared column", function () {
+    return sql.insertSelectWhere("ledger").columns(["k", "n"]).values({ k: "a" });
+  }, "sql-builder/missing-column");
+  // extra-column only fires against an EXPLICIT column set (an inferred set
+  // can't have an extra key) — declare ["k","n"] first, then the ghost key.
+  rejects("insertSelectWhere row with an extra column", function () {
+    return sql.insertSelectWhere("ledger").columns(["k", "n"]).values({ k: "a", n: 1, ghost: 2 })
+      .whereOp("k", "=", "a").toSql();
+  }, "sql-builder/extra-column");
+
+  // The output gate still fires: a NUL byte in a bound cell value is refused
+  // by _assertEmittable, same as every other verb.
+  rejects("insertSelectWhere NUL in a cell value refused by the output gate", function () {
+    return sql.insertSelectWhere("ledger").values({ k: "x" + NUL + "y", n: 1 })
+      .whereOp("n", "=", 1).toSql();
+  }, "sql-builder/null-byte-param");
+
+  // Sub-builder dialect-mismatch is refused (a mysql guard sub spliced into a
+  // default-sqlite parent has baked the wrong quote char).
+  rejects("insertSelectWhere guard sub dialect-mismatch refused", function () {
+    return sql.insertSelectWhere("ledger")
+      .values({ k: "a", n: 1 })
+      .whereExists(sql.select("other", { dialect: "mysql" }).columns(["id"])).toSql();
+  }, "sql-builder/dialect-mismatch");
+
+  // toExternalSql translates ? -> $N on postgres at the boundary (direct-driver path).
+  var ext = sql.insertSelectWhere("ledger", { dialect: "postgres" })
+    .values({ k: "a", n: 1 }).whereOp("k", "=", "a").toExternalSql("postgres");
+  check("insertSelectWhere toExternalSql postgres $N",
+        ext.sql.indexOf("$1") !== -1 && ext.sql.indexOf("$2") !== -1 &&
+          ext.sql.indexOf("$3") !== -1 && ext.sql.indexOf("?") === -1);
 }
 
 module.exports = { run: run };

package/lib/vendor/blamejs/test/layer-0-primitives/structured-fields.test.js

@@ -50,6 +50,42 @@ function testSplitTopLevelSemi() {
         threw instanceof TypeError);
 }
 
+function testParseTagList() {
+  var ptl = b.structuredFields.parseTagList;
+  // Default: `;` sep, `=` kv, lower-cased keys, raw values.
+  check("parseTagList: simple ;/= list, keys lower-cased",
+    JSON.stringify(ptl("v=DKIM1; K=rsa; p=ABC")) ===
+      JSON.stringify([["v", "DKIM1"], ["k", "rsa"], ["p", "ABC"]]));
+  // Empty entries + entries without a kv separator are skipped.
+  check("parseTagList: empty + no-kv entries skipped",
+    JSON.stringify(ptl("a=1; ; novalue ;b=2")) ===
+      JSON.stringify([["a", "1"], ["b", "2"]]));
+  // Repeated keys are PRESERVED as pairs (no last-wins collapse) —
+  // MTA-STS relies on this for repeated mx: lines.
+  check("parseTagList: repeated keys preserved as pairs",
+    JSON.stringify(ptl("mx=a; mx=b; mx=c")) ===
+      JSON.stringify([["mx", "a"], ["mx", "b"], ["mx", "c"]]));
+  // unfold collapses CRLF+WSP folds to a space before splitting (DKIM FWS).
+  check("parseTagList: unfold collapses folded value",
+    JSON.stringify(ptl("p=ABC\r\n DEF", { unfold: true, stripValueWs: true })) ===
+      JSON.stringify([["p", "ABCDEF"]]));
+  // stripValueWs removes all whitespace inside a value (DKIM/ARC FWS).
+  check("parseTagList: stripValueWs removes internal whitespace",
+    JSON.stringify(ptl("p=A B\tC", { stripValueWs: true })) ===
+      JSON.stringify([["p", "ABC"]]));
+  // Regex sep + colon kv (MTA-STS shape), value whitespace kept.
+  check("parseTagList: regex sep + colon kv",
+    JSON.stringify(ptl("version: STSv1\r\nmode: enforce\nmx: a", { sep: /\r?\n/, kvSep: ":" })) ===
+      JSON.stringify([["version", "STSv1"], ["mode", "enforce"], ["mx", "a"]]));
+  // lowerKey:false keeps original key case; first `=` wins (value may hold `=`).
+  check("parseTagList: lowerKey:false preserves case, first kvSep wins",
+    JSON.stringify(ptl("Key=a=b=c", { lowerKey: false })) ===
+      JSON.stringify([["Key", "a=b=c"]]));
+  // Non-string input is coerced (String()) — empty/garbage yields [].
+  check("parseTagList: empty string → []",
+    JSON.stringify(ptl("")) === JSON.stringify([]));
+}
+
 function testRefuseControlBytes() {
   var SfError = b.structuredFields.refuseControlBytes;
   // Generate a generic framework-error-shaped class for the test.
@@ -178,12 +214,56 @@ function testUnquoteSfString() {
         b.structuredFields.unquoteSfString(null) === null);
 }
 
+function testForEachKeyValue() {
+  // Bare entries (no kvSep → null value) are skipped; surviving values trimmed;
+  // index reflects the kvps position (so the skipped bare entry leaves a gap).
+  var kvps = b.structuredFields.parseKeyValuePieces("a = 1 ; b ; c=3".split(";"));
+  var seen = [];
+  b.structuredFields.forEachKeyValue(kvps, function (key, value, i) {
+    seen.push([key, value, i]);
+  });
+  check("forEachKeyValue: skips bare (null-value) entries", seen.length === 2);
+  check("forEachKeyValue: trims surviving values + passes key",
+        seen[0][0] === "a" && seen[0][1] === "1" &&
+        seen[1][0] === "c" && seen[1][1] === "3");
+  check("forEachKeyValue: index reflects kvps position (bare skipped)",
+        seen[0][2] === 0 && seen[1][2] === 2);
+
+  // A handler `return` skips the current entry — `continue` semantics.
+  var kept = [];
+  b.structuredFields.forEachKeyValue(
+    b.structuredFields.parseKeyValuePieces("x=1; y=2; z=3".split(";")),
+    function (key) { if (key === "y") return; kept.push(key); });
+  check("forEachKeyValue: handler return skips like continue", kept.join(",") === "x,z");
+
+  // Non-function handler throws at the wiring (config-time tier).
+  var threw = null;
+  try { b.structuredFields.forEachKeyValue([], "nope"); } catch (e) { threw = e; }
+  check("forEachKeyValue: non-function handler throws TypeError", threw instanceof TypeError);
+}
+
+function testUnfoldHeaderContinuations() {
+  // RFC 5322 header unfolding: a CRLF (or bare LF) followed by WSP is
+  // folding whitespace — unfold collapses each run to a single space so a
+  // wrapped header value (DKIM/DMARC/Authentication-Results, etc.) parses
+  // as one logical line.
+  check("unfoldHeaderContinuations collapses CRLF+WSP to a single space",
+    b.structuredFields.unfoldHeaderContinuations("v=DKIM1;\r\n  k=rsa") === "v=DKIM1; k=rsa");
+  check("unfoldHeaderContinuations handles bare LF + tab",
+    b.structuredFields.unfoldHeaderContinuations("a=1;\n\tb=2") === "a=1; b=2");
+  check("unfoldHeaderContinuations leaves an unfolded value unchanged",
+    b.structuredFields.unfoldHeaderContinuations("a=1; b=2") === "a=1; b=2");
+}
+
 async function run() {
   testSplitTopLevelComma();
   testSplitTopLevelSemi();
+  testParseTagList();
+  testForEachKeyValue();
   testRefuseControlBytes();
   testContainsControlBytes();
   testUnquoteSfString();
+  testUnfoldHeaderContinuations();
 }
 
 module.exports = { run: run };

package/lib/vendor/blamejs/test/layer-0-primitives/validate-opts-shape.test.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * validateOpts.shape — declarative opts validator that collapses the
+ * per-factory `requireObject + requireNonEmptyString + optionalPositiveFinite
+ * + ...` preamble into one schema-driven call.
+ *
+ * Covers: top-level object requirement; each rule token dispatching to the
+ * right underlying check (required/optional string, string-array, boolean,
+ * positive-int/finite, non-negative, function, plain-object); the
+ * dependency-with-methods rule (required + optional); unknown-rule-throws; that
+ * a valid opts object passes and is returned.
+ *
+ * Run standalone: node test/layer-0-primitives/validate-opts-shape.test.js
+ */
+var helpers = require("../helpers");
+var check   = helpers.check;
+var validateOpts = require("../../lib/validate-opts");
+var { WebhookDispatcherError, defineClass } = require("../../lib/framework-error");
+
+var E = WebhookDispatcherError;
+var CODE = "test/bad-opt";
+
+function _throws(fn, re) {
+  try { fn(); return false; }
+  catch (e) { return re ? re.test(e.message || "") : true; }
+}
+
+function run() {
+  // top-level: opts must be an object.
+  check("non-object opts throws", _throws(function () {
+    validateOpts.shape(null, { a: "required-string" }, "t", E, CODE);
+  }, /must be an object/));
+
+  // required-string
+  check("required-string missing throws", _throws(function () {
+    validateOpts.shape({}, { a: "required-string" }, "t", E, CODE);
+  }, /non-empty string/));
+  check("required-string present passes",
+    validateOpts.shape({ a: "x" }, { a: "required-string" }, "t", E, CODE).a === "x");
+
+  // optional-* absent is fine
+  check("optional-string absent ok", (function () {
+    validateOpts.shape({}, { a: "optional-string" }, "t", E, CODE); return true;
+  })());
+  check("optional-positive-finite bad throws", _throws(function () {
+    validateOpts.shape({ n: -1 }, { n: "optional-positive-finite" }, "t", E, CODE);
+  }));
+  check("optional-positive-int bad throws", _throws(function () {
+    validateOpts.shape({ n: 1.5 }, { n: "optional-positive-int" }, "t", E, CODE);
+  }));
+  check("optional-boolean bad throws", _throws(function () {
+    validateOpts.shape({ b: "yes" }, { b: "optional-boolean" }, "t", E, CODE);
+  }));
+  check("optional-function bad throws", _throws(function () {
+    validateOpts.shape({ f: 42 }, { f: "optional-function" }, "t", E, CODE);
+  }));
+  check("optional-non-negative bad throws", _throws(function () {
+    validateOpts.shape({ n: -5 }, { n: "optional-non-negative" }, "t", E, CODE);
+  }));
+
+  // optional-date: present-but-invalid throws; absent ok; valid passes.
+  check("optional-date non-Date throws", _throws(function () {
+    validateOpts.shape({ at: "2020-01-01" }, { at: "optional-date" }, "t", E, CODE);
+  }, /valid Date/));
+  check("optional-date Invalid Date throws", _throws(function () {
+    validateOpts.shape({ at: new Date("nope") }, { at: "optional-date" }, "t", E, CODE);
+  }, /valid Date/));
+  check("optional-date absent ok", (function () {
+    validateOpts.shape({}, { at: "optional-date" }, "t", E, CODE); return true;
+  })());
+  check("optional-date valid Date passes",
+    validateOpts.shape({ at: new Date(0) }, { at: "optional-date" }, "t", E, CODE).at instanceof Date);
+  // direct optionalDate: returns the value when absent / valid; throws the
+  // `<label> must be a valid Date` message (byte-identical to the old hand-rolls).
+  check("optionalDate(undefined) returns undefined",
+    validateOpts.optionalDate(undefined, "x.at", E, CODE) === undefined);
+  check("optionalDate(validDate) returns it", (function () {
+    var d = new Date(0); return validateOpts.optionalDate(d, "x.at", E, CODE) === d;
+  })());
+  check("optionalDate(InvalidDate) throws '<label> must be a valid Date'", _throws(function () {
+    validateOpts.optionalDate(new Date("nope"), "x.verify: opts.at", E, CODE);
+  }, /^x\.verify: opts\.at must be a valid Date$/));
+
+  // string-array: per-element validation
+  check("optional-string-array bad element throws", _throws(function () {
+    validateOpts.shape({ a: ["ok", 3] }, { a: "optional-string-array" }, "t", E, CODE);
+  }));
+  check("optional-string-array valid passes", (function () {
+    validateOpts.shape({ a: ["x", "y"] }, { a: "optional-string-array" }, "t", E, CODE); return true;
+  })());
+
+  // required-object field
+  check("required-object missing throws", _throws(function () {
+    validateOpts.shape({}, { cfg: "required-object" }, "t", E, CODE);
+  }));
+
+  // dependency with methods
+  check("methods dep non-object throws", _throws(function () {
+    validateOpts.shape({ db: 5 }, { db: { methods: ["query"] } }, "t", E, CODE);
+  }));
+  check("methods dep missing method throws", _throws(function () {
+    validateOpts.shape({ db: {} }, { db: { methods: ["query", "transaction"] } }, "t", E, CODE);
+  }, /query/));
+  check("methods dep complete passes", (function () {
+    validateOpts.shape({ db: { query: function () {}, transaction: function () {} } },
+      { db: { methods: ["query", "transaction"] } }, "t", E, CODE); return true;
+  })());
+  check("optional methods dep absent ok", (function () {
+    validateOpts.shape({}, { db: { methods: ["query"], optional: true } }, "t", E, CODE); return true;
+  })());
+
+  // requireMethods permanent flag — a config-time dependency check whose
+  // failure is non-retryable forwards `permanent` to the framework error's
+  // third constructor argument. Uses a GENERIC error class (arg3 = permanent)
+  // so the flag is observable (alwaysPermanent classes set it unconditionally).
+  var PermTestError = defineClass("ValidateOptsPermTestError");
+  check("requireMethods without permanent → permanent falsy", (function () {
+    try { validateOpts.requireMethods({}, ["query"], "x.db", PermTestError, "C"); return false; }
+    catch (e) { return e.permanent === false; }
+  })());
+  check("requireMethods permanent=true → error.permanent true", (function () {
+    try { validateOpts.requireMethods({}, ["query"], "x.db", PermTestError, "C", true); return false; }
+    catch (e) { return e.permanent === true; }
+  })());
+  check("requireMethods permanent=true on missing method → permanent true", (function () {
+    try { validateOpts.requireMethods({ query: function () {} }, ["query", "tx"], "x.db", PermTestError, "C", true); return false; }
+    catch (e) { return e.permanent === true && e.code === "C"; }
+  })());
+  check("shape methods rule permanent → error.permanent true", (function () {
+    try { validateOpts.shape({ db: 5 }, { db: { methods: ["query"], permanent: true } }, "t", PermTestError, "C"); return false; }
+    catch (e) { return e.permanent === true; }
+  })());
+
+  // per-field code override preserves a distinct code per field
+  check("per-field code override preserved", (function () {
+    try {
+      validateOpts.shape({ a: "ok" }, {
+        a: { rule: "required-string", code: "BAD_A" },
+        b: { rule: "required-string", code: "BAD_B" },
+      }, "t", E, CODE);
+      return false;
+    } catch (e) { return e.code === "BAD_B"; }   // b is missing → its own code
+  })());
+  check("per-field label override preserved", (function () {
+    try {
+      validateOpts.shape({}, { a: { rule: "required-string", label: "custom.path" } }, "t", E, CODE);
+      return false;
+    } catch (e) { return /custom\.path/.test(e.message); }
+  })());
+
+  // arbitrary validator function — the universal hatch
+  check("function rule runs + can throw", _throws(function () {
+    validateOpts.shape({ a: 5 }, {
+      a: function (v, l, e, c) { if (v > 3) throw e.factory(c, l + " too big"); },
+    }, "t", E, CODE);
+  }, /too big/));
+  check("function rule receives label/errorClass/code", (function () {
+    var seen = null;
+    validateOpts.shape({ a: 1 }, {
+      a: function (v, l, e, c) { seen = { l: l, hasFactory: typeof e.factory === "function", c: c }; },
+    }, "t", E, CODE);
+    return seen && seen.l === "t: a" && seen.hasFactory && seen.c === CODE;
+  })());
+
+  // nested sub-object shape
+  check("nested shape validates sub-object field", _throws(function () {
+    validateOpts.shape({ srv: { issuer: "x" } }, {
+      srv: { shape: { issuer: "required-string", jwksUri: "required-string" } },
+    }, "t", E, CODE);   // jwksUri missing
+  }, /jwksUri|non-empty string/));
+  check("nested shape passes when complete", (function () {
+    validateOpts.shape({ srv: { issuer: "x", jwksUri: "y" } }, {
+      srv: { shape: { issuer: "required-string", jwksUri: "required-string" } },
+    }, "t", E, CODE);
+    return true;
+  })());
+  check("optional nested shape absent ok", (function () {
+    validateOpts.shape({}, { srv: { shape: { issuer: "required-string" }, optional: true } }, "t", E, CODE);
+    return true;
+  })());
+
+  // mandatory exhaustive: an undeclared opt is always rejected
+  check("undeclared opt rejected (mandatory exhaustive)", _throws(function () {
+    validateOpts.shape({ known: "x", typo: 1 }, { known: "required-string" }, "t", E, CODE);
+  }, /unknown opt "typo"/));
+  check("options.allow permits a pass-through key", (function () {
+    validateOpts.shape({ known: "x", fwd: 1 }, { known: "required-string" },
+      "t", E, CODE, { allow: ["fwd"] });
+    return true;
+  })());
+  check("exhaustive has no opt-out (only allow)", _throws(function () {
+    // even passing a (now-ignored) exhaustive:false cannot disable the contract
+    validateOpts.shape({ known: "x", extra: 1 }, { known: "required-string" },
+      "t", E, CODE, { exhaustive: false });
+  }, /unknown opt "extra"/));
+
+  // numeric-bounds int tokens (finite — reject Infinity, unlike optional-positive-int)
+  check("optional-positive-finite-int rejects Infinity", _throws(function () {
+    validateOpts.shape({ n: Infinity }, { n: "optional-positive-finite-int" }, "t", E, CODE);
+  }));
+  check("optional-positive-finite-int rejects 0", _throws(function () {
+    validateOpts.shape({ n: 0 }, { n: "optional-positive-finite-int" }, "t", E, CODE);
+  }));
+  check("optional-positive-finite-int accepts a positive int", (function () {
+    validateOpts.shape({ n: 1024 }, { n: "optional-positive-finite-int" }, "t", E, CODE);
+    return true;
+  })());
+  check("optional-non-negative-finite-int accepts 0", (function () {
+    validateOpts.shape({ n: 0 }, { n: "optional-non-negative-finite-int" }, "t", E, CODE);
+    return true;
+  })());
+
+  // unknown rule is the author's bug — throws loudly
+  check("unknown rule token throws", _throws(function () {
+    validateOpts.shape({}, { a: "bogus-rule" }, "t", E, CODE);
+  }, /unknown shape rule/));
+
+  // a full mixed schema passes and returns opts
+  var opts = { externalDb: { query: function () {}, transaction: function () {} },
+               name: "svc", maxAttempts: 8, dryRun: false, hook: function () {} };
+  check("mixed valid schema returns opts", validateOpts.shape(opts, {
+    externalDb:  { methods: ["query", "transaction"] },
+    name:        "required-string",
+    maxAttempts: "optional-positive-finite",
+    dryRun:      "optional-boolean",
+    hook:        "optional-function",
+  }, "svc", E, CODE) === opts);
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  try { run(); console.log("[validate-opts-shape] OK — " + helpers.getChecks() + " checks passed"); }
+  catch (e) { console.error("FAIL:", e && e.stack || e); process.exit(1); }
+}