@blamejs/core 0.8.29 → 0.8.31

package/index.js

@@ -105,6 +105,8 @@ var secCyber = require("./lib/sec-cyber");
 var iabTcf = require("./lib/iab-tcf");
 var fapi2 = require("./lib/fapi2");
 var contentCredentials = require("./lib/content-credentials");
+var aiPref = require("./lib/ai-pref");
+var fdx = require("./lib/fdx");
 var safeUrl = require("./lib/safe-url");
 var safeRedirect = require("./lib/safe-redirect");
 var pick = require("./lib/pick");
@@ -297,6 +299,8 @@ module.exports = {
   iabTcf:           iabTcf,
   fapi2:            fapi2,
   contentCredentials: contentCredentials,
+  aiPref:           aiPref,
+  fdx:              fdx,
   safeUrl:          safeUrl,
   safeRedirect:     safeRedirect,
   pick:             pick,

package/lib/ai-pref.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * b.aiPref — IETF AIPREF Working Group Content-Usage HTTP response
+ * header + robots.txt grammar + Cloudflare Content Signals Policy +
+ * Pay-Per-Crawl (HTTP 402) coordination.
+ *
+ * IETF AIPREF (Authors / Information Providers' Preference for AI
+ * Use) draft-ietf-aipref-attach-04 (deadline ⏰ 2026-08) defines a
+ * machine-readable Content-Usage HTTP response header that signals
+ * the operator's AI-training / AI-inference / AI-snippet preferences
+ * to crawlers. Cloudflare's Content Signals Policy + Pay-Per-Crawl
+ * (HTTP 402) is the de-facto baseline that Cloudflare adopted ahead
+ * of the IETF spec finalizing.
+ *
+ * Public API:
+ *
+ *   b.aiPref.middleware(opts) -> middleware(req, res, next)
+ *     opts:
+ *       train:          "allow" | "deny" | "paid" — default "deny"
+ *       infer:          "allow" | "deny" | "paid" — default "allow"
+ *       snippet:        "allow" | "deny"          — default "allow"
+ *       price:          { amountUsd, perTokens? } when any of
+ *                       train/infer is "paid".
+ *       cloudflareSignals: bool, default true — emit the Cloudflare
+ *                       Content-Signals header alongside Content-Usage.
+ *       robotsContext:  "default" | "<user-agent>" — emit
+ *                       per-user-agent rules in robots.txt rather
+ *                       than the catch-all default.
+ *
+ *   b.aiPref.robotsBlock(opts) -> string
+ *     Returns a robots.txt block per AIPREF §3 grammar:
+ *
+ *       User-agent: GPTBot
+ *       Content-Usage: train=deny, infer=allow, snippet=allow
+ *
+ *   b.aiPref.serializeHeader(opts) -> string
+ *     Returns the Content-Usage HTTP response header value.
+ *
+ *   b.aiPref.parseHeader(value) -> { train, infer, snippet, price? }
+ *     Parses an inbound Content-Usage header (used when the framework
+ *     plays the role of crawler: respect declared preferences).
+ *
+ *   b.aiPref.refusePaidCrawl(req, res, opts)
+ *     Convenience: emits HTTP 402 Payment Required with the price
+ *     manifest in the Cloudflare-compatible JSON body.
+ */
+
+var audit = require("./audit");
+var requestHelpers = require("./request-helpers");
+var { defineClass } = require("./framework-error");
+var AiPrefError = defineClass("AiPrefError", { alwaysPermanent: true });
+
+var TRAIN_VALUES   = ["allow", "deny", "paid"];
+var INFER_VALUES   = ["allow", "deny", "paid"];
+var SNIPPET_VALUES = ["allow", "deny"];
+
+function _validate(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw AiPrefError.factory("BAD_OPTS",
+      "aiPref: opts required");
+  }
+  var train   = opts.train   || "deny";
+  var infer   = opts.infer   || "allow";
+  var snippet = opts.snippet || "allow";
+  if (TRAIN_VALUES.indexOf(train) === -1) {
+    throw AiPrefError.factory("BAD_TRAIN", "aiPref: train must be one of " + TRAIN_VALUES.join(", "));
+  }
+  if (INFER_VALUES.indexOf(infer) === -1) {
+    throw AiPrefError.factory("BAD_INFER", "aiPref: infer must be one of " + INFER_VALUES.join(", "));
+  }
+  if (SNIPPET_VALUES.indexOf(snippet) === -1) {
+    throw AiPrefError.factory("BAD_SNIPPET", "aiPref: snippet must be one of " + SNIPPET_VALUES.join(", "));
+  }
+  if ((train === "paid" || infer === "paid") &&
+      (!opts.price || typeof opts.price.amountUsd !== "number" ||
+       !isFinite(opts.price.amountUsd) || opts.price.amountUsd <= 0)) {
+    throw AiPrefError.factory("BAD_PRICE",
+      "aiPref: price.amountUsd (positive finite number) required when train or infer is 'paid'");
+  }
+  return { train: train, infer: infer, snippet: snippet, price: opts.price || null };
+}
+
+function serializeHeader(opts) {
+  var v = _validate(opts);
+  // RFC 8941 structured-fields list of token=token pairs. AIPREF §4.2.
+  var parts = [
+    "train=" + v.train,
+    "infer=" + v.infer,
+    "snippet=" + v.snippet,
+  ];
+  if (v.price) {
+    parts.push('price-usd=' + v.price.amountUsd.toFixed(6));
+    if (typeof v.price.perTokens === "number" && isFinite(v.price.perTokens) && v.price.perTokens > 0) {
+      parts.push("per-tokens=" + Math.floor(v.price.perTokens));
+    }
+  }
+  return parts.join(", ");
+}
+
+function parseHeader(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw AiPrefError.factory("BAD_HEADER", "aiPref.parseHeader: value required");
+  }
+  if (value.length > 1024) {                                                                   // allow:raw-byte-literal — header value cap, not bytes
+    throw AiPrefError.factory("HEADER_TOO_LARGE",
+      "aiPref.parseHeader: value exceeds 1024 chars");
+  }
+  var out = { train: null, infer: null, snippet: null, price: null };
+  var pairs = value.split(",");
+  for (var i = 0; i < pairs.length; i += 1) {
+    var p = pairs[i].trim();
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var k = p.slice(0, eq).trim().toLowerCase();
+    var val = p.slice(eq + 1).trim();
+    if (k === "train"      && TRAIN_VALUES.indexOf(val) !== -1)   out.train = val;
+    else if (k === "infer"   && INFER_VALUES.indexOf(val) !== -1) out.infer = val;
+    else if (k === "snippet" && SNIPPET_VALUES.indexOf(val) !== -1) out.snippet = val;
+    else if (k === "price-usd") {
+      var amt = parseFloat(val);
+      if (isFinite(amt) && amt > 0) out.price = Object.assign({ amountUsd: amt }, out.price || {});
+    } else if (k === "per-tokens") {
+      var pt = parseInt(val, 10);
+      if (isFinite(pt) && pt > 0) out.price = Object.assign({ perTokens: pt }, out.price || {});
+    }
+  }
+  return out;
+}
+
+function robotsBlock(opts) {
+  var v = _validate(opts);
+  var ua = opts.userAgent || "*";
+  if (typeof ua !== "string" || ua.length === 0 || ua.length > 256) {                          // allow:raw-byte-literal — UA-string cap, not bytes
+    throw AiPrefError.factory("BAD_USER_AGENT",
+      "aiPref.robotsBlock: userAgent must be 1-256 char string (or omit for *)");
+  }
+  return "User-agent: " + ua + "\n" +
+         "Content-Usage: " + serializeHeader(v) + "\n";
+}
+
+function _cfSignalsHeader(v) {
+  // Cloudflare Content Signals Policy emits a header named
+  // `cf-content-signals` with a similar grammar. As of Cloudflare's
+  // 2025-12 beta the canonical key names are: `ai-training`,
+  // `ai-inference`, `ai-snippet`. Keep close to that vocabulary.
+  var parts = [
+    "ai-training=" + v.train,
+    "ai-inference=" + v.infer,
+    "ai-snippet=" + v.snippet,
+  ];
+  if (v.price) parts.push("price-usd=" + v.price.amountUsd.toFixed(6));
+  return parts.join("; ");
+}
+
+function middleware(opts) {
+  var v = _validate(opts);
+  var emitCf = opts.cloudflareSignals !== false;
+  var header = serializeHeader(v);
+  var cfHeader = emitCf ? _cfSignalsHeader(v) : null;
+
+  return function aiPrefMw(req, res, next) {
+    if (typeof res.setHeader === "function") {
+      res.setHeader("Content-Usage", header);
+      if (cfHeader) res.setHeader("CF-Content-Signals", cfHeader);
+    }
+    if (typeof next === "function") next();
+  };
+}
+
+function refusePaidCrawl(req, res, opts) {
+  if (!opts || !opts.price || typeof opts.price.amountUsd !== "number") {
+    throw AiPrefError.factory("BAD_PRICE",
+      "aiPref.refusePaidCrawl: opts.price.amountUsd required");
+  }
+  var body = JSON.stringify({
+    error:        "payment_required",
+    pricingModel: "pay-per-crawl",
+    price: {
+      amountUsd: opts.price.amountUsd,
+      perTokens: opts.price.perTokens || null,
+    },
+    contact: opts.contact || null,
+  });
+  if (typeof res.setHeader === "function") {
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", "no-store");
+  }
+  res.statusCode = 402;                                                                        // allow:raw-byte-literal — HTTP 402 Payment Required (RFC 9110)
+  res.end(body);
+  audit.safeEmit({
+    action:   "aipref.paid_crawl_refused",
+    outcome:  "denied",
+    metadata: {
+      ip:        requestHelpers.clientIp(req),
+      userAgent: req && req.headers && req.headers["user-agent"],
+      amountUsd: opts.price.amountUsd,
+    },
+  });
+}
+
+module.exports = {
+  middleware:        middleware,
+  serializeHeader:   serializeHeader,
+  parseHeader:       parseHeader,
+  robotsBlock:       robotsBlock,
+  refusePaidCrawl:   refusePaidCrawl,
+  TRAIN_VALUES:      TRAIN_VALUES.slice(),
+  INFER_VALUES:      INFER_VALUES.slice(),
+  SNIPPET_VALUES:    SNIPPET_VALUES.slice(),
+  AiPrefError:       AiPrefError,
+};

package/lib/audit.js

@@ -243,6 +243,8 @@ var FRAMEWORK_NAMESPACES = [
   "iabtcf",     // b.iabTcf (iabtcf.refused / iabtcf.accepted)
   "fapi2",      // b.fapi2 (fapi2.posture_asserted)
   "contentcredentials", // b.contentCredentials (contentcredentials.signed / verified)
+  "aipref",     // b.aiPref (aipref.paid_crawl_refused)
+  "fdx",        // b.fdx (fdx.bound / fdx.consent_receipt_issued)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/fdx.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * b.fdx — CFPB §1033 / Financial Data Exchange (FDX) consumer-
+ * financial-data sharing wrapper.
+ *
+ * CFPB §1033 (12 CFR §1033.121-461, final rule 2024-10-22) gives US
+ * consumers the right to authorize a third party to access their
+ * financial data through a covered data provider's developer
+ * interface. FDX (https://financialdataexchange.org) is the
+ * industry-standard schema + protocol the CFPB rule effectively
+ * codifies (FDX 6.0+ aligns with the §1033 final rule).
+ *
+ * Compliance deadline ⏰ 2026-04-01 already past for $250B+ asset-
+ * size banks. Mid-size banks 2026-04-01 to 2027-04-01. Small banks
+ * later. Every covered data provider should be live now.
+ *
+ * The framework can't be the operator's authorization server,
+ * resource server, or FDX-data origin (those are the operator's
+ * core banking system). What it CAN do:
+ *
+ *   - Bind the operator's authorization server config to the FAPI
+ *     2.0 profile (which §1033 effectively requires via the
+ *     security requirements in §1033.351).
+ *   - Validate FDX response shapes — refuse a payload that doesn't
+ *     match the FDX 6.0 schema for accounts / transactions /
+ *     statements / payment-networks.
+ *   - Emit a §1033-shape audit-chain event on every authorized data
+ *     access (the regulator-facing record).
+ *   - Generate the "consent receipt" the consumer gets from the
+ *     authorization server per §1033.401(b).
+ *
+ * Public API:
+ *
+ *   b.fdx.bind(opts) -> { fapi2Posture, schemaValidator, consent }
+ *     opts:
+ *       authServer: { issuer, jwksUri, fapi2 }
+ *       resources:  ["accounts" | "transactions" | "statements" |
+ *                    "payment-networks" | "rewards" | "tax-forms"]
+ *
+ *   b.fdx.validateResponse(resourceType, body) -> { valid, errors }
+ *     Validates an FDX response shape for the named resource.
+ *     Refuses extra-keys / missing-required.
+ *
+ *   b.fdx.consentReceipt(opts) -> string (JSON)
+ *     §1033.401(b) consent receipt the authorization server gives
+ *     the consumer at authorization time. Contains:
+ *       - data provider name + identifier
+ *       - data subject (consumer) reference
+ *       - third-party recipient name + duration
+ *       - data scopes (account ids, resources)
+ *       - revocation URL
+ *       - issued + expires timestamps
+ */
+
+var fapi2 = require("./fapi2");
+var C = require("./constants");
+var audit = require("./audit");
+var validateOpts = require("./validate-opts");
+var nb = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+var FdxError = defineClass("FdxError", { alwaysPermanent: true });
+
+var FDX_RESOURCES = [
+  "accounts",
+  "transactions",
+  "statements",
+  "payment-networks",
+  "rewards",
+  "tax-forms",
+];
+
+// FDX 6.0 minimum schemas — operator-facing required-field gates.
+// Not exhaustive validation (operators with strict needs route
+// through `b.safeSchema` against the full FDX OpenAPI spec).
+var FDX_SCHEMAS = {
+  accounts: {
+    required: ["accountId", "accountType", "accountNumberDisplay",
+               "currency", "currentBalance"],
+  },
+  transactions: {
+    required: ["transactionId", "accountId", "postedTimestamp",
+               "amount", "description", "transactionType"],
+  },
+  statements: {
+    required: ["statementId", "accountId", "statementDate", "amount"],
+  },
+  "payment-networks": {
+    required: ["paymentNetworkId", "name", "currency"],
+  },
+  rewards: {
+    required: ["rewardsProgramId", "accountId", "balance", "currency"],
+  },
+  "tax-forms": {
+    required: ["taxFormId", "taxYear", "formType"],
+  },
+};
+
+function bind(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw FdxError.factory("BAD_OPTS", "fdx.bind: opts required");
+  }
+  if (!opts.authServer || typeof opts.authServer !== "object") {
+    throw FdxError.factory("BAD_AUTH_SERVER",
+      "fdx.bind: authServer object required");
+  }
+  validateOpts.requireNonEmptyString(opts.authServer.issuer,
+    "fdx.bind: authServer.issuer", FdxError, "BAD_ISSUER");
+  validateOpts.requireNonEmptyString(opts.authServer.jwksUri,
+    "fdx.bind: authServer.jwksUri", FdxError, "BAD_JWKS_URI");
+
+  if (!Array.isArray(opts.resources) || opts.resources.length === 0) {
+    throw FdxError.factory("BAD_RESOURCES",
+      "fdx.bind: resources must be a non-empty array");
+  }
+  for (var i = 0; i < opts.resources.length; i += 1) {
+    if (FDX_RESOURCES.indexOf(opts.resources[i]) === -1) {
+      throw FdxError.factory("UNKNOWN_RESOURCE",
+        "fdx.bind: unknown resource '" + opts.resources[i] +
+        "' (allowed: " + FDX_RESOURCES.join(", ") + ")");
+    }
+  }
+
+  // §1033.351 security requirements ≈ FAPI 2.0 — assert the operator
+  // pinned the FAPI 2.0 profile. fapi2.assertOAuthConfig refuses
+  // PKCE-disabled / no-sender-constraint / etc.
+  var fapi2Opts = opts.authServer.fapi2 || { pkce: true, dpop: true, par: true };
+  fapi2.assertOAuthConfig(fapi2Opts);
+
+  audit.safeEmit({
+    action:   "fdx.bound",
+    outcome:  "success",
+    metadata: {
+      issuer:    opts.authServer.issuer,
+      resources: opts.resources.slice(),
+    },
+  });
+
+  return {
+    fapi2Posture:    "fapi-2.0",
+    schemaValidator: function (resourceType, body) {
+      return validateResponse(resourceType, body);
+    },
+    consent: {
+      receipt: function (consentOpts) {
+        return consentReceipt(Object.assign({
+          dataProvider: opts.authServer.issuer,
+        }, consentOpts || {}));
+      },
+    },
+  };
+}
+
+function validateResponse(resourceType, body) {
+  var schema = FDX_SCHEMAS[resourceType];
+  if (!schema) {
+    throw FdxError.factory("UNKNOWN_RESOURCE",
+      "fdx.validateResponse: unknown resource '" + resourceType + "'");
+  }
+  if (!body || typeof body !== "object") {
+    return { valid: false, errors: ["body-not-object"] };
+  }
+  // FDX responses are envelopes carrying an array under the resource
+  // name (e.g. { accounts: [...] }) OR a single record. Accept both.
+  var records = Array.isArray(body[resourceType]) ? body[resourceType] :
+                Array.isArray(body)               ? body :
+                [body];
+  var errors = [];
+  for (var i = 0; i < records.length; i += 1) {
+    var rec = records[i];
+    if (!rec || typeof rec !== "object") {
+      errors.push("record[" + i + "]: not-an-object");
+      continue;
+    }
+    for (var j = 0; j < schema.required.length; j += 1) {
+      var f = schema.required[j];
+      if (rec[f] === undefined || rec[f] === null) {
+        errors.push("record[" + i + "]: missing-" + f);
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors: errors };
+}
+
+function consentReceipt(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw FdxError.factory("BAD_OPTS", "fdx.consentReceipt: opts required");
+  }
+  validateOpts.requireNonEmptyString(opts.dataProvider,
+    "fdx.consentReceipt: dataProvider", FdxError, "BAD_DATA_PROVIDER");
+  validateOpts.requireNonEmptyString(opts.consumerRef,
+    "fdx.consentReceipt: consumerRef", FdxError, "BAD_CONSUMER_REF");
+  validateOpts.requireNonEmptyString(opts.thirdParty,
+    "fdx.consentReceipt: thirdParty", FdxError, "BAD_THIRD_PARTY");
+  validateOpts.requireNonEmptyString(opts.revocationUrl,
+    "fdx.consentReceipt: revocationUrl", FdxError, "BAD_REVOCATION_URL");
+  if (!Array.isArray(opts.scopes) || opts.scopes.length === 0) {
+    throw FdxError.factory("BAD_SCOPES",
+      "fdx.consentReceipt: scopes must be a non-empty array");
+  }
+  nb.requirePositiveFiniteIntIfPresent(opts.durationMs,
+    "fdx.consentReceipt: durationMs", FdxError, "BAD_DURATION");
+
+  var issuedAt = Date.now();
+  var expiresAt = issuedAt + (opts.durationMs || C.TIME.weeks(52));
+
+  var receipt = {
+    "@context":      "https://financialdataexchange.org/fdx/consent-receipt/1.0",
+    type:            "fdx.consent-receipt",
+    dataProvider:    opts.dataProvider,
+    consumer:        opts.consumerRef,
+    thirdParty:      opts.thirdParty,
+    scopes:          opts.scopes.slice(),
+    revocationUrl:   opts.revocationUrl,
+    issuedAt:        issuedAt,
+    expiresAt:       expiresAt,
+    issuedAtIso:     new Date(issuedAt).toISOString(),
+    expiresAtIso:    new Date(expiresAt).toISOString(),
+    citations:       ["cfpb-1033", "fdx-6.0"],
+  };
+  audit.safeEmit({
+    action:   "fdx.consent_receipt_issued",
+    outcome:  "success",
+    metadata: {
+      dataProvider:  opts.dataProvider,
+      consumer:      opts.consumerRef,
+      thirdParty:    opts.thirdParty,
+      scopes:        receipt.scopes,
+      durationMs:    expiresAt - issuedAt,
+    },
+  });
+  return receipt;
+}
+
+module.exports = {
+  bind:              bind,
+  validateResponse:  validateResponse,
+  consentReceipt:    consentReceipt,
+  FDX_RESOURCES:     FDX_RESOURCES.slice(),
+  FdxError:          FdxError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.29",
+  "version": "0.8.31",
   "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:34fc0ebb-9c11-4245-a15a-7919aa7897e2",
+  "serialNumber": "urn:uuid:bc3bc35a-2ad5-4132-8b74-52a9a51b8ca1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T14:08:07.987Z",
+    "timestamp": "2026-05-07T14:44:41.234Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.29",
+      "bom-ref": "@blamejs/core@0.8.31",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.29",
+      "version": "0.8.31",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.29",
+      "purl": "pkg:npm/%40blamejs/core@0.8.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.29",
+      "ref": "@blamejs/core@0.8.31",
       "dependsOn": []
     }
   ]