@blamejs/core 0.8.34 → 0.8.35

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.35** (2026-05-08) — `b.tcpa10dlc` + `b.iabMspa` primitives. **`b.tcpa10dlc`** — TCPA 10DLC consent-record audit. 47 USC §227 + 47 CFR §64.1200 + FCC 1:1 disclosure rule (effective 2025-01-27, vacated 11th Circuit IMC v. FCC 2025 but TCPA standard still applies). $500-$1,500/violation exposure. `recordConsent({phoneE164, brand, disclosureText, disclosurePartyKind, formUrl, ip, userAgent})` writes a tamper-evident audit row with the carrier-required fields; `lookup(phoneE164)` for the carrier "produce-on-demand" workflow; `revoke(phoneE164, reason)` records consumer-initiated opt-out with audit trail. **`b.iabMspa`** — IAB Multi-State Privacy Agreement / Global Privacy Platform (GPP) universal opt-out signal codec. `parseGpp(gppString)` decodes the framing (header + per-section payloads, section-id mapping for usnat / usca / usva / usco / usct / usut / usnv / usia / usde / usnj / ustx / usor / usmt / usnh). `checkOptOut(parsed, {dataUse, state})` returns `{ mustHonor, signals }` against operator-decoded section opt-outs (sale / sharing / targeted-ads / sensitive / child-data). `refuseProcessing(parsed, opts)` throws `IabMspaError` to halt the operator's data-flow at the same point a CCPA "do-not-sell" header would. `gpcFromHeaders(req)` reads the W3C `Sec-GPC: 1` browser signal — universal opt-out per CCPA / CPRA §1798.135(b)(1) and similar state laws.
+
 - **0.8.34** (2026-05-08) — `lib/middleware/body-parser.js` BiDi-strip regex uses Unicode-escape form (`\\u202A`-style) instead of literal codepoints to satisfy ESLint's `no-irregular-whitespace`. v0.8.33 publish workflow blocked on this; v0.8.33 tag exists on git but never reached npm — v0.8.34 cumulative includes the v0.8.33 G-class MEDIUM fixes.
 
 - **0.8.33** (2026-05-08) — HTTP/web G-class MEDIUM cleanup. Six RFC-cited refinements against shipped WebSocket / Permissions-Policy / JWT / body-parser / OAuth surfaces. **WS close-frame validation (RFC 6455 §5.5.1 + §7.4.2)** — `_handleClose` now refuses 1-byte close-frame payloads (malformed; pre-v0.8.33 silently accepted as clean close, evading anomaly detection) and validates the close-code against the §7.4.2 vocabulary (1000-1011 + 3000-4999 valid; 1004/1005/1006/1015 reserved/forbidden; everything else refused). **Permissions-Policy default expansion** — `b.middleware.securityHeaders` deny-by-default now covers `interest-cohort`, `attribution-reporting`, `bluetooth`, `hid`, `serial`, `idle-detection`, `local-fonts`, `compute-pressure`, `window-management`, `private-state-token-issuance`, `private-state-token-redemption`. **JWT typ assertion (RFC 8725 §3.11)** — `b.auth.jwt.verify({expectedTyp})` refuses tokens whose header.typ doesn't match (typ-confusion class). Case-insensitive match per RFC 8725. Unset `expectedTyp` skips the check (legacy token compatibility). **Multipart filename BiDi/RTL strip** — `_sanitizeFilename` now drops Trojan Source (CVE-2021-42574) BiDi formatting + zero-width codepoints from uploaded filenames before the basename hits the filesystem. **OAuth redirect_uri localhost exception (RFC 9700 §4.1.1)** — `b.auth.oauth.create({redirectUri})` now accepts `http://localhost` / `http://127.0.0.1` / `http://[::1]` without requiring `allowHttp: true` (which would loosen ALL operator-supplied URLs). HTTPS still required for non-loopback hosts.

package/index.js

@@ -107,6 +107,8 @@ var fapi2 = require("./lib/fapi2");
 var contentCredentials = require("./lib/content-credentials");
 var aiPref = require("./lib/ai-pref");
 var fdx = require("./lib/fdx");
+var tcpa10dlc = require("./lib/tcpa-10dlc");
+var iabMspa = require("./lib/iab-mspa");
 var safeUrl = require("./lib/safe-url");
 var safeRedirect = require("./lib/safe-redirect");
 var pick = require("./lib/pick");
@@ -301,6 +303,8 @@ module.exports = {
   contentCredentials: contentCredentials,
   aiPref:           aiPref,
   fdx:              fdx,
+  tcpa10dlc:        tcpa10dlc,
+  iabMspa:          iabMspa,
   safeUrl:          safeUrl,
   safeRedirect:     safeRedirect,
   pick:             pick,

package/lib/audit.js

@@ -245,6 +245,8 @@ var FRAMEWORK_NAMESPACES = [
   "contentcredentials", // b.contentCredentials (contentcredentials.signed / verified)
   "aipref",     // b.aiPref (aipref.paid_crawl_refused)
   "fdx",        // b.fdx (fdx.bound / fdx.consent_receipt_issued)
+  "tcpa10dlc",  // b.tcpa10dlc (tcpa10dlc.consent_recorded / consent_revoked)
+  "iabmspa",    // b.iabMspa (iabmspa.processing_refused)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/iab-mspa.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * b.iabMspa — IAB Multi-State Privacy Agreement / Global Privacy
+ * Platform (GPP) universal opt-out signal codec.
+ *
+ * GPP (https://github.com/InteractiveAdvertisingBureau/Global-
+ * Privacy-Platform) is the IAB's successor to the patchwork of
+ * per-state US privacy strings. A GPP string carries multiple
+ * sections separated by `~`, each tagged with a section ID. The
+ * MSPA-relevant sections are the US national + state sections
+ * (USNAT, USCA, USVA, USCO, USCT, USUT) carrying:
+ *
+ *   - SaleOptOut, SharingOptOut, TargetedAdvertisingOptOut, Sensitive-
+ *     DataProcessingOptOuts, KnownChildSensitiveData
+ *   - GPC (Global Privacy Control browser signal mirror)
+ *   - MSPA service-provider / opted-in flags
+ *
+ * Public API:
+ *
+ *   b.iabMspa.parseGpp(gppString) -> { header, sections }
+ *     header:  { version, sectionIds[], gpcSignal? }
+ *     sections: [{ id, optOuts: { sale, sharing, targetedAds, ... } }]
+ *
+ *   b.iabMspa.checkOptOut(parsed, opts) -> { mustHonor, signals }
+ *     opts: { dataUse: "sale" | "sharing" | "targeted-ads" |
+ *             "sensitive" | "child-data", state? }
+ *     Returns mustHonor=true when ANY in-scope section signals an
+ *     opt-out for the requested use; signals lists which section IDs
+ *     produced the verdict.
+ *
+ *   b.iabMspa.refuseProcessing(parsed, opts)
+ *     Throws IabMspaError when mustHonor → operator's data-flow code
+ *     halts at the same point a CCPA "do-not-sell" header would.
+ *
+ *   b.iabMspa.gpcFromHeaders(req) -> bool
+ *     Reads the W3C `Sec-GPC: 1` browser header (RFC draft-davidson-
+ *     httpbis-gpc-00). Universal opt-out per California CCPA / CPRA
+ *     §1798.135(b)(1) and Colorado, Connecticut, etc.
+ */
+
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+var IabMspaError = defineClass("IabMspaError", { alwaysPermanent: true });
+
+// GPP section IDs we recognize (subset — the full registry is at
+// https://iabtechlab.com/standards/global-privacy-platform/sections).
+var SECTION_IDS = {
+  7:  "usnat",  // US National Privacy
+  8:  "usca",   // California (CCPA / CPRA)                                                  // allow:raw-byte-literal — IAB GPP section ID, not bytes
+  9:  "usva",   // Virginia
+  10: "usco",   // Colorado
+  11: "usut",   // Utah
+  12: "usct",   // Connecticut
+  13: "usnv",   // Nevada
+  14: "usia",   // Iowa
+  15: "usde",   // Delaware
+  16: "usnj",   // New Jersey                                                               // allow:raw-byte-literal — IAB GPP section ID, not bytes
+  17: "ustx",   // Texas (TDPSA)
+  18: "usor",   // Oregon
+  19: "usmt",   // Montana
+  20: "usnh",   // New Hampshire
+};
+var ALL_SECTIONS = Object.keys(SECTION_IDS).map(Number);
+var DATA_USES = ["sale", "sharing", "targeted-ads", "sensitive", "child-data"];
+
+function parseGpp(gppString) {
+  if (typeof gppString !== "string" || gppString.length === 0) {
+    throw IabMspaError.factory("BAD_INPUT",
+      "iabMspa.parseGpp: gppString required");
+  }
+  if (gppString.length > 8192) {                                                              // allow:raw-byte-literal — GPP string cap, not bytes
+    throw IabMspaError.factory("INPUT_TOO_LARGE",
+      "iabMspa.parseGpp: gppString exceeds 8192 chars");
+  }
+  // GPP framing: <header>~<section1>~<section2>...
+  // The header carries a 6-bit version + an int-list of section IDs.
+  // A full GPP decoder is substantial — for the framework's
+  // refuse-on-opt-out usage we only need the header's section ID
+  // list + per-section opt-out flags. The decoder below is the
+  // simplest correct partial parse: it splits sections, identifies
+  // each by the leading section-ID claim in the header, and exposes
+  // per-section raw payloads for downstream operator-specific
+  // decoding.
+  var parts = gppString.split("~");
+  if (parts.length === 0) {
+    return { header: { version: null, sectionIds: [] }, sections: [] };
+  }
+  // The first segment is the header. We don't fully decode it here;
+  // operator-side libraries (iabtcf-core / @iabtechlab/gpp-cmp) own
+  // the binary tag layout. We do extract the trailing claim list
+  // when present (some GPP strings encode the list as a comma-
+  // separated trailer like `header,7,8,9`).
+  var header = { raw: parts[0], version: null, sectionIds: [] };
+  var sectionPayloads = parts.slice(1);
+  // Try to find a numeric-list tail in the header (heuristic).
+  var tailMatch = parts[0].match(/[A-Za-z0-9_-]+\.([0-9.]+)$/);
+  if (tailMatch) {
+    var ids = tailMatch[1].split(".").map(function (s) { return parseInt(s, 10); });
+    header.sectionIds = ids.filter(function (n) { return isFinite(n) && n > 0; });
+  }
+  // Build sections — pair sectionPayloads with sectionIds positionally.
+  var sections = [];
+  for (var i = 0; i < sectionPayloads.length; i += 1) {
+    var sid = header.sectionIds[i] || null;
+    sections.push({
+      id:       sid,
+      idLabel:  sid && SECTION_IDS[sid] || null,
+      raw:      sectionPayloads[i],
+      // Operator decodes the per-section payload. The framework
+      // surfaces a header-only `optOuts` shape that operators can
+      // override by fully decoding their binary section.
+      optOuts:  null,
+    });
+  }
+  return { header: header, sections: sections };
+}
+
+function checkOptOut(parsed, opts) {
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.sections)) {
+    throw IabMspaError.factory("BAD_PARSED",
+      "iabMspa.checkOptOut: parsed object required (call parseGpp first)");
+  }
+  if (!opts || DATA_USES.indexOf(opts.dataUse) === -1) {
+    throw IabMspaError.factory("BAD_DATA_USE",
+      "iabMspa.checkOptOut: opts.dataUse must be one of " + DATA_USES.join(", "));
+  }
+  var signals = [];
+  for (var i = 0; i < parsed.sections.length; i += 1) {
+    var s = parsed.sections[i];
+    if (opts.state && s.idLabel !== opts.state.toLowerCase()) continue;
+    if (!s.optOuts) continue;   // operator hasn't decoded the section
+    var hit = false;
+    if (opts.dataUse === "sale" && s.optOuts.sale === true) hit = true;
+    else if (opts.dataUse === "sharing" && s.optOuts.sharing === true) hit = true;
+    else if (opts.dataUse === "targeted-ads" && s.optOuts.targetedAds === true) hit = true;
+    else if (opts.dataUse === "sensitive" && s.optOuts.sensitive === true) hit = true;
+    else if (opts.dataUse === "child-data" && s.optOuts.childData === true) hit = true;
+    if (hit) signals.push(s.idLabel || ("section-" + s.id));
+  }
+  return { mustHonor: signals.length > 0, signals: signals };
+}
+
+function refuseProcessing(parsed, opts) {
+  var rv = checkOptOut(parsed, opts);
+  if (rv.mustHonor) {
+    audit.safeEmit({
+      action:   "iabmspa.processing_refused",
+      outcome:  "denied",
+      metadata: {
+        dataUse: opts.dataUse,
+        state:   opts.state || null,
+        signals: rv.signals,
+      },
+    });
+    throw IabMspaError.factory("OPT_OUT_HONORED",
+      "iabMspa: opt-out signal must be honored for dataUse='" + opts.dataUse +
+      "' (signals: " + rv.signals.join(", ") + ")");
+  }
+  return rv;
+}
+
+function gpcFromHeaders(req) {
+  if (!req || !req.headers) return false;
+  var h = req.headers["sec-gpc"];
+  return h === "1" || h === 1;
+}
+
+module.exports = {
+  parseGpp:           parseGpp,
+  checkOptOut:        checkOptOut,
+  refuseProcessing:   refuseProcessing,
+  gpcFromHeaders:     gpcFromHeaders,
+  SECTION_IDS:        Object.assign({}, SECTION_IDS),
+  ALL_SECTIONS:       ALL_SECTIONS.slice(),
+  DATA_USES:          DATA_USES.slice(),
+  IabMspaError:       IabMspaError,
+};

package/lib/tcpa-10dlc.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * b.tcpa10dlc — TCPA 10DLC (10-Digit Long Code) consent-record audit
+ * primitive + FCC 1:1 prior-express-written-consent disclosure
+ * snapshot.
+ *
+ * Background: the Telephone Consumer Protection Act (47 USC §227) +
+ * its FCC implementing rules (47 CFR §64.1200) require carrier-
+ * shaped consent records before sending marketing or
+ * automated-dialing-system text messages. Penalties: $500-$1,500
+ * per violation. The 10DLC ecosystem (carrier-vetted A2P SMS
+ * routes) layers an additional consent-record requirement: every
+ * carrier-registered campaign must produce, on demand, the consent
+ * record for any phone number it texted.
+ *
+ * FCC 1:1 rule (effective 2025-01-27 — reaffirmed 2025-12) caps
+ * disclosed parties to 1 per consent — operators that previously
+ * collected blanket consent for "trusted partner network" must
+ * record an individual consent per third-party recipient. The rule
+ * was vacated by the 11th Circuit IMC v. FCC 2025 ruling but the
+ * underlying TCPA standard still requires "prior express written
+ * consent" for marketing autodial; FCC enforcement priorities still
+ * favor 1:1.
+ *
+ * The framework can't be the operator's SMS provider or campaign
+ * registrar. What it CAN do:
+ *
+ *   - Capture the consent record in a tamper-evident audit-chain row
+ *     with the carrier-required fields (consumer phone, opt-in
+ *     timestamp, brand name, opt-in language verbatim, IP +
+ *     user-agent + form URL).
+ *   - Snapshot the 1:1 disclosure (single brand the consumer is
+ *     consenting to receive messages from).
+ *   - Support the carrier "produce on demand" workflow via
+ *     `b.tcpa10dlc.lookup(phoneE164)` — returns the consent record
+ *     for an audit response.
+ *
+ * Public API:
+ *
+ *   b.tcpa10dlc.recordConsent(opts) -> consentRecord
+ *     opts:
+ *       phoneE164:       "+15551234567" (E.164 format).
+ *       brand:           operator's registered brand name.
+ *       disclosureText:  the verbatim opt-in language shown to the
+ *                        consumer (regulator-facing record).
+ *       disclosurePartyKind: "first-party" | "carrier-affiliate" |
+ *                        "campaign-registrar" — the role the brand
+ *                        plays per the 1:1 rule.
+ *       formUrl:         operator's URL where consent was captured.
+ *       ip + userAgent:  consumer's network identifiers.
+ *       optInTimestamp:  Unix-ms (default Date.now()).
+ *       additional:      arbitrary operator-supplied metadata
+ *                        (campaign-id, traffic source, A/B test cell).
+ *
+ *   b.tcpa10dlc.lookup(phoneE164) -> consentRecord | null
+ *
+ *   b.tcpa10dlc.revoke(phoneE164, reason) -> { revoked, at }
+ *     Records the consumer-initiated opt-out. Carriers require
+ *     revocation traceability — the audit row is the regulator-
+ *     facing record.
+ */
+
+var validateOpts = require("./validate-opts");
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+var Tcpa10dlcError = defineClass("Tcpa10dlcError", { alwaysPermanent: true });
+
+var E164_RE = /^\+[1-9][0-9]{6,14}$/;                                                         // allow:raw-byte-literal — E.164 length range, not bytes
+var DISCLOSURE_PARTIES = ["first-party", "carrier-affiliate", "campaign-registrar"];
+
+var records = new Map();   // phoneE164 → record
+
+function recordConsent(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw Tcpa10dlcError.factory("BAD_OPTS",
+      "tcpa10dlc.recordConsent: opts required");
+  }
+  if (typeof opts.phoneE164 !== "string" || !E164_RE.test(opts.phoneE164)) {
+    throw Tcpa10dlcError.factory("BAD_PHONE",
+      "tcpa10dlc.recordConsent: phoneE164 must match " + E164_RE);
+  }
+  validateOpts.requireNonEmptyString(opts.brand,
+    "tcpa10dlc.recordConsent: brand", Tcpa10dlcError, "BAD_BRAND");
+  validateOpts.requireNonEmptyString(opts.disclosureText,
+    "tcpa10dlc.recordConsent: disclosureText", Tcpa10dlcError, "BAD_DISCLOSURE_TEXT");
+  validateOpts.requireNonEmptyString(opts.formUrl,
+    "tcpa10dlc.recordConsent: formUrl", Tcpa10dlcError, "BAD_FORM_URL");
+  if (DISCLOSURE_PARTIES.indexOf(opts.disclosurePartyKind) === -1) {
+    throw Tcpa10dlcError.factory("BAD_DISCLOSURE_PARTY",
+      "tcpa10dlc.recordConsent: disclosurePartyKind must be one of " +
+      DISCLOSURE_PARTIES.join(", "));
+  }
+
+  var optInAt = typeof opts.optInTimestamp === "number" ? opts.optInTimestamp : Date.now();
+  var record = Object.freeze({
+    phoneE164:           opts.phoneE164,
+    brand:               opts.brand,
+    disclosureText:      opts.disclosureText,
+    disclosurePartyKind: opts.disclosurePartyKind,
+    formUrl:             opts.formUrl,
+    ip:                  opts.ip || null,
+    userAgent:           opts.userAgent || null,
+    optInTimestamp:      optInAt,
+    optInTimestampIso:   new Date(optInAt).toISOString(),
+    revoked:             false,
+    revokedAt:           null,
+    revokedReason:       null,
+    additional:          opts.additional || null,
+    citations:           ["47-usc-227", "47-cfr-64.1200", "fcc-2024-1-1"],
+  });
+  records.set(opts.phoneE164, record);
+
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "tcpa10dlc.consent_recorded",
+      outcome:  "success",
+      metadata: {
+        phoneE164:           opts.phoneE164,
+        brand:               opts.brand,
+        disclosurePartyKind: opts.disclosurePartyKind,
+        formUrl:             opts.formUrl,
+        ip:                  opts.ip || null,
+      },
+    });
+  }
+  return record;
+}
+
+function lookup(phoneE164) {
+  if (typeof phoneE164 !== "string") return null;
+  return records.get(phoneE164) || null;
+}
+
+function revoke(phoneE164, reason) {
+  if (typeof phoneE164 !== "string" || !E164_RE.test(phoneE164)) {
+    throw Tcpa10dlcError.factory("BAD_PHONE",
+      "tcpa10dlc.revoke: phoneE164 must match " + E164_RE);
+  }
+  var existing = records.get(phoneE164);
+  if (!existing) {
+    throw Tcpa10dlcError.factory("NO_RECORD",
+      "tcpa10dlc.revoke: no consent record for " + phoneE164);
+  }
+  if (existing.revoked) {
+    return { revoked: true, at: existing.revokedAt };
+  }
+  var revokedAt = Date.now();
+  var updated = Object.freeze(Object.assign({}, existing, {
+    revoked:        true,
+    revokedAt:      revokedAt,
+    revokedAtIso:   new Date(revokedAt).toISOString(),
+    revokedReason:  typeof reason === "string" ? reason : null,
+  }));
+  records.set(phoneE164, updated);
+  audit.safeEmit({
+    action:   "tcpa10dlc.consent_revoked",
+    outcome:  "success",
+    metadata: {
+      phoneE164: phoneE164,
+      reason:    reason || null,
+    },
+  });
+  return { revoked: true, at: revokedAt };
+}
+
+function _resetForTest() { records.clear(); }
+
+module.exports = {
+  recordConsent:        recordConsent,
+  lookup:               lookup,
+  revoke:               revoke,
+  DISCLOSURE_PARTIES:   DISCLOSURE_PARTIES.slice(),
+  Tcpa10dlcError:       Tcpa10dlcError,
+  _resetForTest:        _resetForTest,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.34",
+  "version": "0.8.35",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:3be80324-29fb-478d-819e-0b32ffd604d7",
+  "serialNumber": "urn:uuid:0d7236d8-d7fd-4993-8139-83cff6ea1ce7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T15:22:30.612Z",
+    "timestamp": "2026-05-07T15:31:18.217Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.34",
+      "bom-ref": "@blamejs/core@0.8.35",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.34",
+      "version": "0.8.35",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.34",
+      "purl": "pkg:npm/%40blamejs/core@0.8.35",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.34",
+      "ref": "@blamejs/core@0.8.35",
       "dependsOn": []
     }
   ]