@blamejs/core 0.7.81 → 0.7.83

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.83** (2026-05-06) — `b.auth.oauth.endSessionUrl()` (OpenID Connect RP-Initiated Logout) + `b.auth.oauth.pushAuthorizationRequest()` (RFC 9126 PAR). **`endSessionUrl({ idTokenHint?, postLogoutRedirectUri?, state?, logoutHint?, uiLocales?, clientId?, extraParams? })`** builds the URL the operator's `/logout` route redirects the user-agent to so the IdP terminates the session and bounces back to the operator's app. The IdP's `end_session_endpoint` is read from the OIDC discovery document or operator-supplied at `create({ endSessionEndpoint })`. **`pushAuthorizationRequest({ state?, nonce?, prompt?, loginHint?, maxAge?, extraParams? })`** POSTs the authorization-request parameters directly to the IdP's PAR endpoint (mTLS or client-secret authenticated) and returns `{ url, state, nonce, verifier, challenge, requestUri, expiresIn }` — the browser-side redirect URL is `<authorizationEndpoint>?client_id=...&request_uri=...`. Defends against authorization-request parameter tampering by an MITM at the user-agent + against URL-length overflow on long authorization requests (request_uri reference is short). The PAR endpoint is read from the discovery doc's `pushed_authorization_request_endpoint` or operator-supplied at `create({ pushedAuthorizationRequestEndpoint })`. Both helpers throw `auth-oauth/no-end-session-endpoint` / `auth-oauth/no-par-endpoint` when neither the discovery doc nor the operator opts supply the endpoint.
+
+- **0.7.82** (2026-05-06) — `b.mail.bimi` — BIMI record builder + verifier (RFC 9091). BIMI publishes a sender's brand logo URL in DNS so receiving MTAs can render it next to the message in supported clients (Gmail, Yahoo, Apple Mail). **`b.mail.bimi.recordShape({ logoUrl, vmcUrl?, selector? })`** produces the canonical `v=BIMI1; l=https://...; a=https://...` TXT-record string per RFC 9091 §4. Both `l=` (SVG logo URL) and `a=` (Verified Mark Certificate URL per RFC 9091 §6) are HTTPS-required (refuses `http://`). All field values are CR/LF/NUL/semicolon-screened so a hostile URL can't inject a record-separator into the published TXT. **`b.mail.bimi.fetchPolicy(domain, { selector?, dnsLookup? })`** queries `<selector>._bimi.<domain>` (default selector `"default"`) and returns the structured record `{ v, l, a }` or `null` when no policy is published / record is malformed. **`b.mail.bimi.parseRecord(text)`** parses any operator-supplied TXT body — semicolon-separated `key=value` pairs per RFC 9091 §4. The framework does NOT validate the SVG / VMC contents against the RFC §5/§6 profiles — operators feed those to their own asset pipeline; the fetch primitive is a thin DNS lookup that returns the structured record so an operator dashboard or SMTP send-time preflight can verify the publication. BIMI is layered on a passing DMARC posture (the receiver requires DMARC quarantine/reject); operators with the existing `b.mail.dmarc` posture set up benefit from BIMI rendering immediately on receivers that honor it.
+
 - **0.7.81** (2026-05-06) — `b.middleware.hostAllowlist` — DNS rebinding defense. Refuses requests whose `Host` header doesn't match the operator-supplied allowlist; the DNS rebinding chain (attacker DNS flips evil.com → 127.0.0.1, browser still believes the URL string says "evil.com" so same-origin policy lets the JS read the response, but the operator's localhost is what actually serves) is closed by checking the post-DNS-resolution `Host` header on the framework's side. **`b.middleware.hostAllowlist({ hosts, denyStatus?, denyBody?, audit? })`** — operators pass an allowlist of canonical Host values (with or without port). Wildcard-leading entries (`*.example.com`) match any single label; `app.sub.example.com` does NOT match `*.example.com` (multi-label rejected by design — a wildcard certificate authority issues only single-label intermediate). Entries without a port match any port; entries with a port require exact match. Default `denyStatus: 421` (RFC 7540 §9.1.2 "Misdirected Request"); default `denyBody: "Misdirected Request"`. Audit emits `network.host_allowlist.denied` with the reason (`missing-host` / `host-not-in-allowlist`) and the actual Host value for triage. Operators running explicitly-public services that accept arbitrary subdomains (multi-tenant forum shapes) skip this middleware entirely; there's no per-request opt-out.
 
 - **0.7.80** (2026-05-06) — `b.middleware.securityTxt` (RFC 9116) + SQLite `secure_delete=ON` at DB boot. **`b.middleware.securityTxt({ contact, expires, encryption?, policy?, ack?, preferredLanguages?, hiring?, canonical?, alsoAtRoot?, audit? })`** serves a static body at `/.well-known/security.txt` (and root `/security.txt` when `alsoAtRoot: true`) per RFC 9116. Operators wire it on their app so security researchers know where to find the disclosure policy. The `Contact:` and `Expires:` fields are REQUIRED per §2.5; the framework throws at config-time when either is missing AND when `expires` is in the past (RFC 9116 §2.5.5). All field values are CR/LF/NUL-screened (header injection defense). Body is built once at create() and served with `Content-Length` + `Cache-Control: public, max-age=86400` + `X-Content-Type-Options: nosniff`. **SQLite `PRAGMA secure_delete=ON`** is now applied at `b.db.init` time alongside the existing PRAGMA block. SQLite normally just unlinks rows from the B-tree; the underlying page bytes survive on disk until a new write reuses the slot. With `secure_delete=ON`, freed pages are overwritten with zeros so a forensic recovery against the encrypted database file can't reconstruct deleted rows. The cost is one extra write per delete — already dominated by the framework's audit-chain emissions on every DSR erase / cascade fan-out.

package/lib/auth/oauth.js

@@ -349,6 +349,10 @@ function create(opts) {
     userinfoEndpoint:      opts.userinfoEndpoint      || (preset && preset.userinfoEndpoint)      || null,
     revocationEndpoint:    opts.revocationEndpoint    || (preset && preset.revocationEndpoint)    || null,
     jwksUri:               opts.jwksUri               || (preset && preset.jwksUri)               || null,
+    endSessionEndpoint:    opts.endSessionEndpoint    || (preset && preset.endSessionEndpoint)    || null,
+    pushedAuthorizationRequestEndpoint:
+                           opts.pushedAuthorizationRequestEndpoint ||
+                           (preset && preset.pushedAuthorizationRequestEndpoint) || null,
   };
 
   // Discovery + JWKS caches use b.cache.create + .wrap so concurrent
@@ -422,6 +426,8 @@ function create(opts) {
       userinfoEndpoint:      "userinfo_endpoint",
       revocationEndpoint:    "revocation_endpoint",
       jwksUri:               "jwks_uri",
+      endSessionEndpoint:    "end_session_endpoint",
+      pushedAuthorizationRequestEndpoint: "pushed_authorization_request_endpoint",
     })[name];
     var endpoint = config[snake];
     if (!endpoint) {
@@ -697,6 +703,105 @@ function create(opts) {
     return { header: header, claims: payload };
   }
 
+  // ---- OIDC RP-Initiated Logout (OpenID Connect Session Mgmt 1.0) ----
+  //
+  // The IdP exposes an `end_session_endpoint` in its discovery doc;
+  // the RP-initiated logout flow redirects the user to that endpoint
+  // with the id_token_hint + post_logout_redirect_uri so the IdP
+  // terminates the IdP session and bounces the user back to the
+  // operator's app. Operators wire this on their /logout route.
+  async function endSessionUrl(uopts) {
+    uopts = uopts || {};
+    var endpoint;
+    try { endpoint = await _resolveEndpoint("endSessionEndpoint"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-end-session-endpoint",
+        "endSessionUrl: IdP discovery doc has no end_session_endpoint " +
+        "(set opts.endSessionEndpoint on create() if the IdP doesn't publish it)");
+    }
+    var params = new URLSearchParams();
+    if (uopts.idTokenHint) params.set("id_token_hint", uopts.idTokenHint);
+    if (uopts.postLogoutRedirectUri) {
+      params.set("post_logout_redirect_uri", uopts.postLogoutRedirectUri);
+    }
+    if (uopts.state)        params.set("state", uopts.state);
+    if (uopts.logoutHint)   params.set("logout_hint", uopts.logoutHint);
+    if (uopts.uiLocales)    params.set("ui_locales", uopts.uiLocales);
+    if (uopts.clientId !== false) params.set("client_id", clientId);
+    if (uopts.extraParams && typeof uopts.extraParams === "object") {
+      var ek = Object.keys(uopts.extraParams);
+      for (var i = 0; i < ek.length; i++) params.set(ek[i], String(uopts.extraParams[ek[i]]));
+    }
+    var qs = params.toString();
+    if (qs.length === 0) return endpoint;
+    var sep = endpoint.indexOf("?") === -1 ? "?" : "&";
+    return endpoint + sep + qs;
+  }
+
+  // ---- OAuth 2.0 Pushed Authorization Requests (RFC 9126) ----
+  //
+  // PAR: the client POSTs the authorization-request parameters
+  // directly to the IdP's PAR endpoint (mTLS or client-secret
+  // authenticated) and gets back a `request_uri` it then puts in the
+  // browser-side redirect to /authorize. Defends against parameter
+  // tampering by an MITM at the user-agent + against URL-length
+  // overflow on long authorization requests.
+  async function pushAuthorizationRequest(uopts) {
+    uopts = uopts || {};
+    var endpoint;
+    try { endpoint = await _resolveEndpoint("pushedAuthorizationRequestEndpoint"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-par-endpoint",
+        "pushAuthorizationRequest: IdP discovery doc has no " +
+        "pushed_authorization_request_endpoint (set opts.pushedAuthorizationRequestEndpoint " +
+        "on create() if the IdP doesn't publish it)");
+    }
+    // Build the same param set authorizationUrl would emit, then POST
+    // it to PAR instead of putting it in the redirect URL.
+    var state = uopts.state || _generateRandomToken(STATE_NONCE_BYTES);
+    var nonce = uopts.nonce || (isOidc ? _generateRandomToken(STATE_NONCE_BYTES) : null);
+    var pkceVals = _generatePkce();
+    var body = new URLSearchParams();
+    body.set("response_type", "code");
+    body.set("client_id",     clientId);
+    body.set("redirect_uri",  redirectUri);
+    body.set("scope",         scope.join(" "));
+    body.set("state",         state);
+    if (nonce) body.set("nonce", nonce);
+    body.set("code_challenge",        pkceVals.challenge);
+    body.set("code_challenge_method", "S256");
+    if (responseMode) body.set("response_mode", responseMode);
+    if (uopts.prompt)    body.set("prompt", uopts.prompt);
+    if (uopts.loginHint) body.set("login_hint", uopts.loginHint);
+    if (uopts.maxAge != null) body.set("max_age", String(uopts.maxAge));
+    if (clientSecret) body.set("client_secret", clientSecret);
+    if (uopts.extraParams && typeof uopts.extraParams === "object") {
+      var ek = Object.keys(uopts.extraParams);
+      for (var i = 0; i < ek.length; i++) body.set(ek[i], String(uopts.extraParams[ek[i]]));
+    }
+    var rv = await _postForm(endpoint, body);
+    if (!rv || typeof rv.request_uri !== "string" || rv.request_uri.length === 0) {
+      throw new OAuthError("auth-oauth/par-bad-response",
+        "pushAuthorizationRequest: IdP did not return a request_uri (got " +
+        JSON.stringify(rv).slice(0, 200) + ")");                                 // allow:raw-byte-literal — error-message snippet length
+    }
+    // Build the browser-side redirect URL: /authorize?client_id=...&request_uri=...
+    var authzEndpoint = await _resolveEndpoint("authorizationEndpoint");
+    var qs = new URLSearchParams();
+    qs.set("client_id",   clientId);
+    qs.set("request_uri", rv.request_uri);
+    var sep = authzEndpoint.indexOf("?") === -1 ? "?" : "&";
+    return {
+      url:         authzEndpoint + sep + qs.toString(),
+      state:       state,
+      nonce:       nonce,
+      verifier:    pkceVals.verifier,
+      challenge:   pkceVals.challenge,
+      requestUri:  rv.request_uri,
+      expiresIn:   typeof rv.expires_in === "number" ? rv.expires_in : null,
+    };
+  }
+
   return {
     authorizationUrl:    authorizationUrl,
     exchangeCode:        exchangeCode,
@@ -705,6 +810,8 @@ function create(opts) {
     revokeToken:         revokeToken,
     verifyIdToken:       verifyIdToken,
     discover:            _discover,
+    endSessionUrl:           endSessionUrl,
+    pushAuthorizationRequest: pushAuthorizationRequest,
     // Diagnostic / power-user surface
     issuer:              issuer,
     clientId:            clientId,

package/lib/mail-bimi.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * BIMI — Brand Indicators for Message Identification (RFC 9091).
+ *
+ * BIMI records publish a sender's brand logo URL in DNS so receiving
+ * MTAs can render it next to the message in supported clients
+ * (Gmail, Yahoo, Apple Mail). The record format is:
+ *
+ *   default._bimi.<domain>  IN  TXT  "v=BIMI1; l=https://...; a=https://..."
+ *
+ * - `l=` URL to the SVG logo file (Tiny PS Profile per RFC 9091 §5)
+ * - `a=` URL to the Verified Mark Certificate (VMC) — RFC 9091 §6
+ *
+ * BIMI is layered on a passing DMARC posture (the receiver requires
+ * DMARC to be at quarantine or reject). No-op for senders without
+ * DMARC enforcement.
+ *
+ * Surface:
+ *   b.mail.bimi.recordShape({ logoUrl, vmcUrl?, selector? })  → string
+ *   b.mail.bimi.fetchPolicy(domain, opts?)                    → { v, l, a } | null
+ *   b.mail.bimi.parseRecord(text)                             → { v, l, a } | null
+ *
+ * The framework does NOT validate the SVG / VMC contents against the
+ * RFC 9091 §5/§6 profiles — operators feed those to their own asset
+ * pipeline. The fetch primitive is a thin DNS lookup that returns
+ * the structured record so an operator dashboard or SMTP send-time
+ * preflight can verify the publication.
+ */
+
+var dns = require("node:dns");
+var dnsPromises = dns.promises;
+var validateOpts = require("./validate-opts");
+var safeUrl = require("./safe-url");
+var C = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var BimiError = defineClass("BimiError", { alwaysPermanent: true });
+
+var BIMI_VERSION = "BIMI1";
+var BIMI_DEFAULT_SELECTOR = "default";
+var BIMI_RECORD_MAX_BYTES = C.BYTES.kib(2);
+
+function _validateUrl(url, label) {
+  // RFC 9091 §4.2 — `l=` and `a=` MUST be HTTPS URLs.
+  try {
+    safeUrl.parse(url, { allowedProtocols: ["https:"] });
+  } catch (e) {
+    throw new BimiError("mail-bimi/bad-" + label,
+      "bimi: " + label + " must be an https:// URL — got '" + url + "': " +
+      ((e && e.message) || String(e)));
+  }
+}
+
+function recordShape(opts) {
+  validateOpts.requireObject(opts, "bimi.recordShape", BimiError);
+  validateOpts(opts, ["logoUrl", "vmcUrl", "selector"], "bimi.recordShape");
+  validateOpts.requireNonEmptyString(opts.logoUrl,
+    "bimi.recordShape: logoUrl", BimiError, "mail-bimi/no-logo");
+  _validateUrl(opts.logoUrl, "logoUrl");
+  if (opts.vmcUrl !== undefined && opts.vmcUrl !== null) {
+    validateOpts.requireNonEmptyString(opts.vmcUrl,
+      "bimi.recordShape: vmcUrl", BimiError, "mail-bimi/bad-vmc");
+    _validateUrl(opts.vmcUrl, "vmcUrl");
+  }
+  // No CR/LF/NUL/semicolon — defense-in-depth so a hostile URL can't
+  // inject a record-separator sequence into the published TXT.
+  if (/[\r\n\0;]/.test(opts.logoUrl)) {
+    throw new BimiError("mail-bimi/bad-logo",
+      "bimi.recordShape: logoUrl contains forbidden control / record-separator characters");
+  }
+  if (opts.vmcUrl && /[\r\n\0;]/.test(opts.vmcUrl)) {
+    throw new BimiError("mail-bimi/bad-vmc",
+      "bimi.recordShape: vmcUrl contains forbidden control / record-separator characters");
+  }
+
+  var fields = ["v=" + BIMI_VERSION, "l=" + opts.logoUrl];
+  if (opts.vmcUrl) fields.push("a=" + opts.vmcUrl);
+  return fields.join("; ");
+}
+
+function parseRecord(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  if (text.length > BIMI_RECORD_MAX_BYTES) return null;                          // bound BEFORE parse — TXT-record sanity cap
+  // RFC 9091 §4 — semicolon-separated, key=value, leading "v=BIMI1".
+  var parts = text.split(";");
+  var rv = { v: null, l: null, a: null };
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i].trim();
+    if (p.length === 0) continue;
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var k = p.slice(0, eq).trim().toLowerCase();
+    var v = p.slice(eq + 1).trim();
+    if (k === "v" || k === "l" || k === "a") rv[k] = v;
+  }
+  if (rv.v !== BIMI_VERSION || !rv.l) return null;
+  return rv;
+}
+
+async function fetchPolicy(domain, opts) {
+  validateOpts.requireNonEmptyString(domain,
+    "bimi.fetchPolicy: domain", BimiError, "mail-bimi/bad-domain");
+  opts = opts || {};
+  var selector = opts.selector || BIMI_DEFAULT_SELECTOR;
+  var qname = selector + "._bimi." + domain;
+  var records;
+  try {
+    if (opts.dnsLookup) records = await opts.dnsLookup(qname, "TXT");
+    else records = await dnsPromises.resolveTxt(qname);
+  } catch (e) {
+    if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) return null;
+    throw new BimiError("mail-bimi/lookup-failed",
+      "bimi.fetchPolicy: TXT lookup for " + qname + " failed: " +
+      ((e && e.message) || String(e)));
+  }
+  // RFC 9091 §4.1 — a TXT lookup may return multiple chunks; pick
+  // the first record that begins with v=BIMI1.
+  for (var i = 0; i < (records || []).length; i += 1) {
+    var rec = records[i];
+    var s = Array.isArray(rec) ? rec.join("") : String(rec);
+    var parsed = parseRecord(s);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+module.exports = {
+  recordShape:  recordShape,
+  parseRecord:  parseRecord,
+  fetchPolicy:  fetchPolicy,
+  BIMI_VERSION: BIMI_VERSION,
+  BimiError:    BimiError,
+};

package/lib/mail.js

@@ -71,6 +71,7 @@ var httpClient = lazyRequire(function () { return require("./http-client"); });
 var guardEmail = lazyRequire(function () { return require("./guard-email"); });
 var mailDkim = require("./mail-dkim");
 var mailAuth = require("./mail-auth");
+var mailBimi = require("./mail-bimi");
 var mailUnsubscribe = require("./mail-unsubscribe");
 var net = lazyRequire(function () { return require("net"); });
 var nodeUrl = require("url");
@@ -1102,6 +1103,7 @@ module.exports = {
   dmarc:       mailAuth.dmarc,
   arc:         mailAuth.arc,
   authResults: mailAuth.authResults,
+  bimi:        mailBimi,
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.
   _buildRfc822ForTest: _buildRfc822,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.81",
+  "version": "0.7.83",
   "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:cff2cdad-8420-45be-b8ae-a4b9ec79c49a",
+  "serialNumber": "urn:uuid:2bb408b6-50d7-4fb3-acf9-332f7472bd70",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T05:43:30.523Z",
+    "timestamp": "2026-05-06T06:03:44.811Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.81",
+      "bom-ref": "@blamejs/core@0.7.83",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.81",
+      "version": "0.7.83",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.81",
+      "purl": "pkg:npm/%40blamejs/core@0.7.83",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.81",
+      "ref": "@blamejs/core@0.7.83",
       "dependsOn": []
     }
   ]