@blamejs/core 0.8.42 → 0.8.49

package/lib/dark-patterns.js

@@ -1,63 +1,28 @@
 "use strict";
 /**
- * FTC Dark-Patterns / Click-to-Cancel UX-parity attestation.
+ * @module b.darkPatterns
+ * @nav    Compliance
+ * @title  Dark Patterns
  *
- * The FTC's Negative Option Rule (effective 2024; expanded 2025-2026
- * via state click-to-cancel laws) requires that the steps to cancel a
- * subscription / withdraw consent be no more burdensome than the
- * steps to subscribe / grant consent. The standard breakdown:
+ * @intro
+ *   FTC dark-patterns compliance — refusal helpers for fake-urgency,
+ *   confirm-shaming, drip-pricing, hidden-cost, sneak-into-basket
+ *   patterns.
  *
- *   - prominence parity        — same call-to-action visibility
- *   - click-count parity       — cancel <= signup
- *   - contrast / font parity   — accessible-text contrast and font
- *                                weight match
- *   - method parity            — operator that signed up over the web
- *                                must let the subject cancel over the
- *                                web (not phone-only)
- *   - confirmation parity      — single-confirmation if signup was
- *                                single-confirmation
+ *   The FTC's Negative Option Rule (effective 2024; expanded 2025-26
+ *   via state click-to-cancel laws) requires that the steps to cancel
+ *   a subscription be no more burdensome than the steps to subscribe.
+ *   The framework can't measure pixel-level UI parity from server
+ *   code; what it ships is an attestation primitive: operators record
+ *   a signup-flow snapshot (clicks, CTA text + font weight + contrast
+ *   ratio, confirmations, channel, login requirement) and a matching
+ *   cancel-flow snapshot. The framework computes the parity verdict
+ *   against a posture (`ftc-2024` / `ca-sb942` / `strict`), audits
+ *   the result, and ships a middleware that refuses cancel-route
+ *   traffic with HTTP 451 when no passing attestation is on file.
  *
- * The framework can't measure pixel-level UI parity from server code.
- * What it CAN do is provide a primitive that:
- *
- *   1. Records an operator-attested signup-flow snapshot (clicks,
- *      visible call-to-action text, font weight, contrast ratio).
- *   2. Records an attested cancel-flow snapshot.
- *   3. Computes the parity verdict and emits an audit trail.
- *   4. Refuses to emit a "consent-withdrawn" event in postures that
- *      require parity if the snapshots show degradation.
- *
- * Public API:
- *
- *   darkPatterns.recordSignupFlow(opts) -> snapshot
- *   darkPatterns.recordCancelFlow(opts) -> snapshot
- *     opts: {
- *       channel:     "web" | "mobile" | "phone" | "email" | "in-person",
- *       clickCount:  integer 1..50,
- *       cta:         { text, fontWeight, contrastRatio },
- *       confirmations: integer 0..10,
- *       requiresLogin: bool,
- *       resourceId:  operator-supplied id linking signup<->cancel,
- *     }
- *
- *   darkPatterns.assertParity(signup, cancel, opts) -> { ok, breaches }
- *     opts:
- *       toleranceClicks      — how many extra cancel clicks tolerated
- *                              (default 0).
- *       toleranceContrast    — minimum contrast ratio absolute value
- *                              required of cancel (default 4.5 — AA).
- *       posture              — "ftc-2024" | "ca-sb942" | "strict".
- *       errorClass           — DarkPatternsError (mapped to McpError
- *                              namespace? no — uses a dedicated class).
- *
- *   darkPatterns.attest(opts) -> { id, signupFlow, cancelFlow, verdict, signedAt }
- *     One-shot composer used by operators that capture both flows
- *     during a regression test of their UI.
- *
- *   darkPatterns.middleware(opts) -> middleware(req, res, next)
- *     Attached to the cancel-flow endpoint. Verifies the operator has
- *     a parity attestation on file (via opts.lookupAttestation) and
- *     refuses with 451 (legal reasons) if missing.
+ * @card
+ *   FTC dark-patterns compliance — refusal helpers for fake-urgency, confirm-shaming, drip-pricing, hidden-cost, sneak-into-basket patterns.
  */
 
 var audit = require("./audit");
@@ -144,6 +109,39 @@ function _validateFlowOpts(opts, label, errorClass) {
   }
 }
 
+/**
+ * @primitive b.darkPatterns.recordSignupFlow
+ * @signature b.darkPatterns.recordSignupFlow(opts)
+ * @since     0.8.44
+ * @related   b.darkPatterns.recordCancelFlow, b.darkPatterns.assertParity, b.darkPatterns.attest
+ *
+ * Capture a frozen snapshot of an operator-attested signup flow.
+ * Validates every input strictly: channel must be one of the allowed
+ * channels, click count is an integer 1..50, CTA carries a non-empty
+ * label plus CSS font weight 100..1000 and WCAG contrast 1..21,
+ * confirmations are an integer 0..10. The frozen result feeds
+ * `assertParity` paired with the matching cancel-flow snapshot.
+ *
+ * @opts
+ *   channel:        "web" | "mobile" | "phone" | "email" | "in-person" | "mail",
+ *   clickCount:     number,                // integer 1..50
+ *   cta:            { text: string, fontWeight: number, contrastRatio: number },
+ *   confirmations:  number,                // integer 0..10
+ *   requiresLogin:  boolean,
+ *   resourceId:     string,                // links signup<->cancel
+ *
+ * @example
+ *   var signup = b.darkPatterns.recordSignupFlow({
+ *     channel:       "web",
+ *     clickCount:    2,
+ *     cta:           { text: "Subscribe", fontWeight: 700, contrastRatio: 7.2 },
+ *     confirmations: 1,
+ *     requiresLogin: false,
+ *     resourceId:    "plan-pro-2026",
+ *   });
+ *   signup.kind;          // → "signup"
+ *   signup.clickCount;    // → 2
+ */
 function recordSignupFlow(opts) {
   _validateFlowOpts(opts, "SignupFlow", DarkPatternsError);
   return Object.freeze({
@@ -162,6 +160,37 @@ function recordSignupFlow(opts) {
   });
 }
 
+/**
+ * @primitive b.darkPatterns.recordCancelFlow
+ * @signature b.darkPatterns.recordCancelFlow(opts)
+ * @since     0.8.44
+ * @related   b.darkPatterns.recordSignupFlow, b.darkPatterns.assertParity, b.darkPatterns.attest
+ *
+ * Capture a frozen snapshot of the cancel-flow counterpart. Same
+ * validation discipline and field shape as `recordSignupFlow` so the
+ * two snapshots are directly comparable. The `resourceId` MUST match
+ * the signup snapshot's `resourceId`; `assertParity` enforces this.
+ *
+ * @opts
+ *   channel:        "web" | "mobile" | "phone" | "email" | "in-person" | "mail",
+ *   clickCount:     number,                // integer 1..50
+ *   cta:            { text: string, fontWeight: number, contrastRatio: number },
+ *   confirmations:  number,                // integer 0..10
+ *   requiresLogin:  boolean,
+ *   resourceId:     string,                // must match signup
+ *
+ * @example
+ *   var cancel = b.darkPatterns.recordCancelFlow({
+ *     channel:       "web",
+ *     clickCount:    2,
+ *     cta:           { text: "Cancel subscription", fontWeight: 700, contrastRatio: 7.2 },
+ *     confirmations: 1,
+ *     requiresLogin: false,
+ *     resourceId:    "plan-pro-2026",
+ *   });
+ *   cancel.kind;          // → "cancel"
+ *   cancel.resourceId;    // → "plan-pro-2026"
+ */
 function recordCancelFlow(opts) {
   _validateFlowOpts(opts, "CancelFlow", DarkPatternsError);
   return Object.freeze({
@@ -180,6 +209,45 @@ function recordCancelFlow(opts) {
   });
 }
 
+/**
+ * @primitive b.darkPatterns.assertParity
+ * @signature b.darkPatterns.assertParity(signup, cancel, opts)
+ * @since     0.8.44
+ * @related   b.darkPatterns.recordSignupFlow, b.darkPatterns.recordCancelFlow, b.darkPatterns.attest
+ *
+ * Compare a signup snapshot against a cancel snapshot under a named
+ * posture. Reports every parity breach: extra clicks beyond
+ * `toleranceClicks`, channel mismatch, contrast below the posture
+ * floor or degraded by more than 0.5 vs signup, font-weight
+ * regression, added confirmations, login required only on cancel.
+ * Returns `{ ok, breaches, posture }`. Postures: `ftc-2024` (FTC
+ * baseline), `ca-sb942` (California stricter), `strict` (contrast
+ * floor 7.0).
+ *
+ * @opts
+ *   posture:           "ftc-2024" | "ca-sb942" | "strict",
+ *   toleranceClicks:   number,             // override posture default
+ *   toleranceContrast: number,             // override posture default
+ *   errorClass:        Error,              // override DarkPatternsError
+ *
+ * @example
+ *   var signup = b.darkPatterns.recordSignupFlow({
+ *     channel: "web", clickCount: 2,
+ *     cta: { text: "Subscribe", fontWeight: 700, contrastRatio: 7.2 },
+ *     confirmations: 1, requiresLogin: false, resourceId: "plan-pro-2026",
+ *   });
+ *   var cancel = b.darkPatterns.recordCancelFlow({
+ *     channel: "web", clickCount: 5,
+ *     cta: { text: "Cancel", fontWeight: 400, contrastRatio: 3.0 },
+ *     confirmations: 3, requiresLogin: true, resourceId: "plan-pro-2026",
+ *   });
+ *   var verdict = b.darkPatterns.assertParity(signup, cancel, { posture: "ftc-2024" });
+ *   verdict.ok;                            // → false
+ *   verdict.breaches.map(function (b2) { return b2.kind; });
+ *   // → ["click-count", "contrast-below-floor", "contrast-degradation",
+ *   //    "font-weight-degradation", "confirmation-step-added",
+ *   //    "login-required-only-for-cancel"]
+ */
 function assertParity(signup, cancel, opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || DarkPatternsError;
@@ -261,6 +329,42 @@ function assertParity(signup, cancel, opts) {
   return { ok: breaches.length === 0, breaches: breaches, posture: postureName };
 }
 
+/**
+ * @primitive b.darkPatterns.attest
+ * @signature b.darkPatterns.attest(opts)
+ * @since     0.8.44
+ * @related   b.darkPatterns.recordSignupFlow, b.darkPatterns.recordCancelFlow, b.darkPatterns.assertParity, b.darkPatterns.middleware
+ *
+ * One-shot composer used by operators that capture both flows during
+ * a UI regression test: builds the two snapshots, runs `assertParity`,
+ * and emits an audit row keyed `darkpatterns.attest` whose outcome is
+ * `success` on parity-clean or `denied` on any breach. Returns the
+ * full attestation envelope (id, both snapshots, verdict, signedAt)
+ * suitable for persistence and lookup by the cancel-route middleware.
+ *
+ * @opts
+ *   signup:  recordSignupFlow opts shape,
+ *   cancel:  recordCancelFlow opts shape,
+ *   posture: "ftc-2024" | "ca-sb942" | "strict",
+ *   audit:   boolean,                      // default true
+ *
+ * @example
+ *   var att = b.darkPatterns.attest({
+ *     signup: {
+ *       channel: "web", clickCount: 2,
+ *       cta: { text: "Subscribe", fontWeight: 700, contrastRatio: 7.2 },
+ *       confirmations: 1, requiresLogin: false, resourceId: "plan-pro-2026",
+ *     },
+ *     cancel: {
+ *       channel: "web", clickCount: 2,
+ *       cta: { text: "Cancel subscription", fontWeight: 700, contrastRatio: 7.2 },
+ *       confirmations: 1, requiresLogin: false, resourceId: "plan-pro-2026",
+ *     },
+ *     posture: "ftc-2024",
+ *   });
+ *   att.verdict.ok;     // → true
+ *   att.id;             // → "plan-pro-2026"
+ */
 function attest(opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || DarkPatternsError;
@@ -292,6 +396,33 @@ function attest(opts) {
   };
 }
 
+/**
+ * @primitive b.darkPatterns.middleware
+ * @signature b.darkPatterns.middleware(opts)
+ * @since     0.8.44
+ * @related   b.darkPatterns.attest, b.darkPatterns.assertParity
+ *
+ * Mount on the cancel-route handler. Resolves a `resourceId` from
+ * the inbound request via the operator's `resourceIdFromReq`, looks
+ * up the corresponding attestation via `lookupAttestation`, and
+ * refuses with HTTP 451 (Unavailable for Legal Reasons) when no
+ * attestation exists or the on-file verdict shows a parity breach.
+ * Audits the refusal under `darkpatterns.cancel_blocked`.
+ *
+ * @opts
+ *   lookupAttestation: function (resourceId) -> attestation | Promise,
+ *   resourceIdFromReq: function (req) -> string,
+ *   errorClass:        Error,              // override DarkPatternsError
+ *
+ * @example
+ *   var attestations = new Map();
+ *   var mw = b.darkPatterns.middleware({
+ *     resourceIdFromReq: function (req) { return req.headers["x-plan-id"]; },
+ *     lookupAttestation: function (id) { return attestations.get(id); },
+ *   });
+ *   // mount mw on the DELETE /subscription handler — refuses with 451
+ *   // when the operator has no passing parity attestation on file.
+ */
 function middleware(opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || DarkPatternsError;

package/lib/db-query.js

@@ -30,9 +30,20 @@ var { Readable } = require("node:stream");
 var C = require("./constants");
 var cryptoField = require("./crypto-field");
 var { generateToken } = require("./crypto");
+var safeJson = require("./safe-json");
+var safeJsonPath = require("./safe-jsonpath");
 var safeSql = require("./safe-sql");
 
-var ALLOWED_OPS = new Set(["=", "!=", "<>", "<", "<=", ">", ">=", "IS", "IS NOT", "LIKE", "IN"]);
+// "@>" / "?" / "?|" / "?&" are JSONB containment + key-existence
+// operators. Routed through safeJsonPath validation before binding so
+// operator-supplied values can't smuggle NUL / control / bidi
+// characters into the JSON-shape comparison.
+var ALLOWED_OPS = new Set([
+  "=", "!=", "<>", "<", "<=", ">", ">=", "IS", "IS NOT", "LIKE", "IN",
+  "@>", "?", "?|", "?&",
+]);
+var JSONB_CONTAINMENT_OPS = new Set(["@>"]);
+var JSONB_KEY_OPS         = new Set(["?", "?|", "?&"]);
 
 class Query {
   constructor(database, tableName) {
@@ -103,6 +114,49 @@ class Query {
     if (!ALLOWED_OPS.has(op)) {
       throw new Error("invalid where operator: " + op);
     }
+    // D-M4 — JSONB / JSON-path injection guard. Routes operator-
+    // supplied JSONB containment + key-existence values through
+    // safe-jsonpath before they reach the engine. Bound via `?`
+    // placeholder so the value still doesn't interpolate; this is
+    // the second line of defense — refuses NUL / control / bidi /
+    // zero-width that some drivers silently strip out of JSON
+    // round-trip but the engine processes verbatim.
+    if (JSONB_CONTAINMENT_OPS.has(op)) {
+      if (typeof value === "string") {
+        // Operator passed pre-stringified JSON; parse + validate the
+        // shape, refuse on bad shape / control chars / depth bomb.
+        var parsed;
+        try { parsed = safeJson.parse(value); }
+        catch (e) {
+          throw new Error("where '" + op + "' value: invalid JSON string: " +
+            ((e && e.message) || String(e)));
+        }
+        safeJsonPath.validateContainment(parsed);
+      } else {
+        safeJsonPath.validateContainment(value);
+        // Bind the canonical-shape JSON so the driver sees the same
+        // bytes we validated. JSON.stringify here is safe — the
+        // shape was just walked end-to-end.
+        value = JSON.stringify(value);
+      }
+    }
+    if (JSONB_KEY_OPS.has(op)) {
+      if (op === "?") {
+        if (typeof value !== "string") {
+          throw new Error("where '?' requires a string key (got " + (typeof value) + ")");
+        }
+        safeJsonPath.validateKey(value);
+      } else {
+        // ?| / ?& take a Postgres text[] of keys. Caller passes a JS
+        // array; each element validated as a single key.
+        if (!Array.isArray(value) || value.length === 0) {
+          throw new Error("where '" + op + "' requires a non-empty array of string keys");
+        }
+        for (var ki = 0; ki < value.length; ki++) {
+          safeJsonPath.validateKey(value[ki]);
+        }
+      }
+    }
     // Sealed-field translation: rewrite predicate to use derived hash if available
     if (this._isSealedField(field)) {
       var lookup = cryptoField.lookupHash(this._cryptoFieldKey(), field, value);
@@ -294,9 +348,24 @@ class Query {
   // the bound table's sealedFields registration before it lands in the
   // operator's pipeline. For large result sets (audit exports, backup
   // table dumps) this avoids materializing the full rowset in memory.
-  stream() {
+  // D-M5 — streamLimit ceiling enforced from the module-level db
+  // config; per-call opts.streamLimit overrides for one-off bumps.
+  stream(opts) {
     var sql = "SELECT " + this._projection() + " FROM " + this._quotedTable() +
               this._whereClause() + this._orderLimitOffset();
+    var perCallLimit;
+    // db.js exports getStreamLimit so this module reads the live
+    // ceiling without bouncing through the lib's circular load.
+    var dbModule = require("./db");                                                                    // allow:inline-require — circular-load defense (db imports db-query)
+    perCallLimit = dbModule.getStreamLimit();
+    if (opts && opts.streamLimit !== undefined) {
+      if (typeof opts.streamLimit !== "number" || !isFinite(opts.streamLimit) ||
+          opts.streamLimit <= 0 || Math.floor(opts.streamLimit) !== opts.streamLimit) {
+        throw new Error("Query.stream: opts.streamLimit must be a positive finite integer; got " +
+          JSON.stringify(opts.streamLimit));
+      }
+      perCallLimit = opts.streamLimit;
+    }
     var stmt = this._db.prepare(sql);
     var key = this._cryptoFieldKey();
     var iter;
@@ -306,12 +375,20 @@ class Query {
       setImmediate(function () { r.destroy(e); });
       return r;
     }
+    var emitted = 0;
     return new Readable({
       objectMode: true,
       read: function () {
         try {
+          if (emitted >= perCallLimit) {
+            this.destroy(new Error("Query.stream: emitted " + emitted +
+              " rows, exceeding streamLimit " + perCallLimit +
+              ". Pass opts.streamLimit higher OR raise via db.init({ streamLimit })."));
+            return;
+          }
           var step = iter.next();
           if (step.done) { this.push(null); return; }
+          emitted += 1;
           this.push(cryptoField.unsealRow(key, step.value));
         } catch (e) {
           this.destroy(e);