@blamejs/core 0.7.106 → 0.8.0

package/lib/middleware/flag-context.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * flag-context middleware — extracts an OpenFeature evaluation context
+ * onto the request so downstream handlers and multiple flag clients
+ * can read a consistent context without re-deriving it per call.
+ *
+ *   var attachCtx = b.middleware.flagContext({
+ *     userKey: "x-user-id",                 // header to pull targetingKey from
+ *     extractAttributes: function (req) {   // operator-supplied augmentation
+ *       return { tenantId: req.tenantId, environment: process.env.NODE_ENV };
+ *     },
+ *   });
+ *   router.use(attachCtx);
+ *
+ *   // Downstream:
+ *   var ctx = req.flagCtx;                       // readonly Frozen object
+ *   var enabled = b.flagClient.getBoolean("foo", ctx);
+ *
+ * The middleware does NOT evaluate flags — it only constructs the
+ * context. Pair with `flag.middleware()` for the request-attached
+ * convenience accessor; or pass `req.flagCtx` directly to a flag
+ * client method for a more decoupled shape (e.g. when several flag
+ * clients with different providers share the same context).
+ */
+
+var validateOpts  = require("../validate-opts");
+var lazyRequire   = require("../lazy-require");
+var { defineClass } = require("../framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var contextMod = lazyRequire(function () { return require("../flag-evaluation-context"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "userKey", "userKeyHeader", "extractAttributes", "tenantKeyHeader",
+  ], "middleware.flagContext");
+  if (opts.extractAttributes != null && typeof opts.extractAttributes !== "function") {
+    throw new FlagError("flag/bad-opt",
+      "flagContext: extractAttributes must be a function");
+  }
+  var userKeyHeader = (typeof opts.userKeyHeader === "string" && opts.userKeyHeader.length > 0)
+    ? opts.userKeyHeader.toLowerCase()
+    : null;
+  var tenantKeyHeader = (typeof opts.tenantKeyHeader === "string" && opts.tenantKeyHeader.length > 0)
+    ? opts.tenantKeyHeader.toLowerCase()
+    : null;
+  var explicitUserKey = (typeof opts.userKey === "string" && opts.userKey.length > 0)
+    ? opts.userKey
+    : null;
+
+  return function flagContextMiddleware(req, res, next) {
+    var headers = req.headers || {};
+    var headerKey = userKeyHeader && typeof headers[userKeyHeader] === "string"
+      ? headers[userKeyHeader]
+      : null;
+    var fromReqOpts = {};
+    if (explicitUserKey)            fromReqOpts.userKey = explicitUserKey;
+    else if (headerKey)             fromReqOpts.userKey = headerKey;
+    var augment = {};
+    if (typeof opts.extractAttributes === "function") {
+      try {
+        var extra = opts.extractAttributes(req);
+        if (extra && typeof extra === "object") augment = extra;
+      } catch (_e) { /* drop-silent on extraction error */ }
+    }
+    if (tenantKeyHeader && typeof headers[tenantKeyHeader] === "string") {
+      augment.tenantId = headers[tenantKeyHeader];
+    }
+    fromReqOpts.extra = augment;
+    req.flagCtx = contextMod().fromRequest(req, fromReqOpts);
+    return next();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/index.js

@@ -16,7 +16,11 @@
  *   6. (your auth + business middleware + routes)
  *   7. errorHandler     — must be LAST so it catches everything that throws
  */
+var aiActDisclosure = require("./ai-act-disclosure");
 var apiEncrypt = require("./api-encrypt");
+var openapiServe = require("./openapi-serve");
+var asyncapiServe = require("./asyncapi-serve");
+var flagContext = require("./flag-context");
 var assetlinks = require("./assetlinks");
 var attachUser = require("./attach-user");
 var bearerAuth = require("./bearer-auth");
@@ -43,6 +47,7 @@ var requireAal = require("./require-aal");
 var requireAuth = require("./require-auth");
 var requireContentType = require("./require-content-type");
 var requireMethods = require("./require-methods");
+var requireStepUp = require("./require-step-up");
 var securityHeaders = require("./security-headers");
 var securityTxt = require("./security-txt");
 var spanHttpServer = require("./span-http-server");
@@ -65,6 +70,7 @@ module.exports = {
   requireAuth:      requireAuth.create,
   requireContentType: requireContentType.create,
   requireMethods:   requireMethods.create,
+  requireStepUp:    requireStepUp.create,
   csrfProtect:      csrfProtect.create,
   fetchMetadata:    fetchMetadata.create,
   gpc:              gpc.create,
@@ -78,6 +84,10 @@ module.exports = {
   sse:              sse.create,
   requestLog:       requestLog.create,
   apiEncrypt:       apiEncrypt,
+  aiActDisclosure:  aiActDisclosure.create,
+  openapiServe:     openapiServe.create,
+  asyncapiServe:    asyncapiServe.create,
+  flagContext:      flagContext.create,
   assetlinks:       assetlinks.create,
   dbRoleFor:        dbRoleFor.create,
   dpop:             dpop.create,
@@ -103,6 +113,7 @@ module.exports = {
     requireAuth:      requireAuth,
     requireContentType: requireContentType,
     requireMethods:   requireMethods,
+    requireStepUp:    requireStepUp,
     csrfProtect:      csrfProtect,
     fetchMetadata:    fetchMetadata,
     bodyParser:       bodyParser,
@@ -113,6 +124,10 @@ module.exports = {
     sse:              sse,
     requestLog:       requestLog,
     apiEncrypt:       apiEncrypt,
+    aiActDisclosure:  aiActDisclosure,
+    openapiServe:     openapiServe,
+    asyncapiServe:    asyncapiServe,
+    flagContext:      flagContext,
     assetlinks:       assetlinks,
     dbRoleFor:        dbRoleFor,
     dpop:             dpop,

package/lib/middleware/openapi-serve.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * openapi-serve middleware — expose an OpenAPI 3.1 document as a
+ * request-time JSON / YAML resource at a single mount point.
+ *
+ *   var openapi = b.openapi.create({ ... });
+ *   ...add paths / schemas / security...
+ *
+ *   var serve = b.middleware.openapiServe({
+ *     document: openapi,
+ *     pathJson: "/openapi.json",
+ *     pathYaml: "/openapi.yaml",
+ *     pretty:   true,
+ *     cacheControl: "public, max-age=300",
+ *   });
+ *   router.use(serve);
+ *
+ * The middleware ONLY responds to GET requests for the configured
+ * paths; everything else passes to next() unchanged. ETag is computed
+ * from the JSON-string SHA3-512 to allow conditional GET.
+ *
+ * If `accessControl: "public"` (the default), the middleware emits
+ * `Access-Control-Allow-Origin: *` so external doc tooling can fetch.
+ * For internal-only docs operators set `accessControl: "same-origin"`
+ * which omits the CORS header.
+ */
+
+var nodeCrypto    = require("crypto");
+var validateOpts  = require("../validate-opts");
+var lazyRequire   = require("../lazy-require");
+var { defineClass } = require("../framework-error");
+var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
+
+var openapiYaml   = lazyRequire(function () { return require("../openapi-yaml"); });
+var audit         = lazyRequire(function () { return require("../audit"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "document", "pathJson", "pathYaml", "pretty",
+    "cacheControl", "accessControl", "audit",
+  ], "middleware.openapiServe");
+  if (!opts.document || typeof opts.document.toJson !== "function") {
+    throw new OpenApiError("openapi/bad-document",
+      "openapiServe: document must be a builder created via b.openapi.create()");
+  }
+  var pathJson      = opts.pathJson || "/openapi.json";
+  var pathYaml      = opts.pathYaml || "/openapi.yaml";
+  var pretty        = opts.pretty === true ? 2 : 0;
+  var cacheControl  = (typeof opts.cacheControl === "string" && opts.cacheControl.length > 0)
+    ? opts.cacheControl : "public, max-age=300";
+  var accessControl = opts.accessControl || "public";
+  var auditOn       = opts.audit !== false;
+
+  if (typeof pathJson !== "string" || pathJson.charAt(0) !== "/") {
+    throw new OpenApiError("openapi/bad-path",
+      "openapiServe: pathJson must start with '/' - got " + JSON.stringify(pathJson));
+  }
+  if (typeof pathYaml !== "string" || pathYaml.charAt(0) !== "/") {
+    throw new OpenApiError("openapi/bad-path",
+      "openapiServe: pathYaml must start with '/' - got " + JSON.stringify(pathYaml));
+  }
+
+  var cachedDoc       = null;
+  var cachedJsonStr   = null;
+  var cachedYamlStr   = null;
+  var cachedJsonEtag  = null;
+  var cachedYamlEtag  = null;
+
+  function _rebuild() {
+    cachedDoc      = opts.document.toJson();
+    cachedJsonStr  = JSON.stringify(cachedDoc, null, pretty);
+    cachedYamlStr  = openapiYaml().toYaml(cachedDoc);
+    cachedJsonEtag = '"' + nodeCrypto.createHash("sha3-512").update(cachedJsonStr).digest("base64url").slice(0, 24) + '"';
+    cachedYamlEtag = '"' + nodeCrypto.createHash("sha3-512").update(cachedYamlStr).digest("base64url").slice(0, 24) + '"';
+  }
+  _rebuild();
+
+  function _writeBody(req, res, body, etag, contentType) {
+    var requestEtag = (req.headers && req.headers["if-none-match"]) || null;
+    if (requestEtag && requestEtag === etag) {
+      res.writeHead(304, { "ETag": etag, "Cache-Control": cacheControl });          // allow:raw-byte-literal — HTTP 304
+      res.end();
+      return;
+    }
+    var headers = {
+      "Content-Type":   contentType,
+      "Content-Length": Buffer.byteLength(body),
+      "Cache-Control":  cacheControl,
+      "ETag":           etag,
+    };
+    if (accessControl === "public") {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+    res.writeHead(200, headers);                                                    // allow:raw-byte-literal — HTTP 200
+    res.end(body);
+  }
+
+  var mw = function (req, res, next) {
+    if (typeof res.writeHead !== "function") return next();
+    var method = (req.method || "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return next();
+    var pathname = req.pathname;
+    if (typeof pathname !== "string") {
+      var url = req.url || "";
+      var qIdx = url.indexOf("?");
+      pathname = qIdx === -1 ? url : url.slice(0, qIdx);
+    }
+    if (pathname === pathJson) {
+      _writeBody(req, res, cachedJsonStr, cachedJsonEtag, "application/json; charset=utf-8");
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "openapi.document.served",
+            outcome: "success",
+            actor:   null,
+            metadata: { format: "json", path: pathname, bytes: cachedJsonStr.length },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return;
+    }
+    if (pathname === pathYaml) {
+      _writeBody(req, res, cachedYamlStr, cachedYamlEtag, "application/yaml; charset=utf-8");
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "openapi.document.served",
+            outcome: "success",
+            actor:   null,
+            metadata: { format: "yaml", path: pathname, bytes: cachedYamlStr.length },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return;
+    }
+    return next();
+  };
+  mw.forceRebuild = _rebuild;
+  return mw;
+}
+
+module.exports = { create: create };

package/lib/middleware/require-step-up.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * require-step-up middleware — gate routes per RFC 9470 OAuth 2.0
+ * Step-Up Authentication Challenge.
+ *
+ * Mounted AFTER attachUser / bearerAuth so the request carries the
+ * already-verified token claims.
+ *
+ *   var sensitiveStepUp = b.middleware.requireStepUp({
+ *     requirement: { acr: "high", maxAge: 300 },
+ *     realm:       "billing-api",
+ *   });
+ *   router.use("/billing/transfer", sensitiveStepUp);
+ *
+ * Failure shape (per RFC 9470 §3):
+ *   401 Unauthorized
+ *   WWW-Authenticate: Bearer error="insufficient_user_authentication",
+ *     error_description="...", acr_values="high", max_age="300"
+ *   Content-Type: application/json
+ *   { "error": "insufficient_user_authentication", "error_description": "..." }
+ *
+ * Operators with their own elevation grants pass `acceptGrant: true`
+ * and `grantHeader: "X-Step-Up-Grant"` (default) — the middleware
+ * checks for a valid b.auth.stepUp.grant token before evaluating the
+ * normal claims-based requirement, so a multi-step flow doesn't get
+ * step-up-prompted on every action.
+ *
+ * Options:
+ *   {
+ *     requirement:    { acr / acrValues / maxAge / requiredAmr / phishingResistant },
+ *     getClaims:      function(req) { return req.user.claims; },
+ *     realm:          "api",
+ *     audit:          true,
+ *     acceptGrant:    true,                         // default
+ *     grantHeader:    "X-Step-Up-Grant",            // default
+ *     grantScope:     null,                         // narrow grant by scope
+ *   }
+ *
+ * NEVER weaken the security default to fix a broken caller. Operators
+ * configure their IdP to emit `acr` / `auth_time` / `amr` correctly;
+ * the middleware does not silently default these to "good enough" on a
+ * missing claim.
+ */
+
+var lazyRequire    = require("../lazy-require");
+var validateOpts   = require("../validate-opts");
+var requestHelpers = require("../request-helpers");
+var { AuthError }  = require("../framework-error");
+
+var stepUp         = lazyRequire(function () { return require("../auth/step-up"); });
+var elevation      = lazyRequire(function () { return require("../auth/elevation-grant"); });
+var audit          = lazyRequire(function () { return require("../audit"); });
+
+var DEFAULT_GRANT_HEADER = "x-step-up-grant";
+
+function _defaultGetClaims(req) {
+  if (!req || typeof req !== "object") return null;
+  if (req.user && req.user.claims && typeof req.user.claims === "object") {
+    return req.user.claims;
+  }
+  if (req.user && typeof req.user === "object") {
+    return req.user;
+  }
+  return null;
+}
+
+function _writeChallenge(res, challenge, body, statusCode) {
+  if (res.headersSent) return;
+  var json = JSON.stringify(body);
+  res.writeHead(statusCode, {                                                      // allow:raw-byte-literal — HTTP status passthrough
+    "Content-Type":     "application/json; charset=utf-8",
+    "Content-Length":   Buffer.byteLength(json),
+    "WWW-Authenticate": challenge,
+  });
+  res.end(json);
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "requirement", "getClaims", "realm", "audit",
+    "acceptGrant", "grantHeader", "grantScope", "errorDescription",
+  ], "middleware.requireStepUp");
+
+  if (!opts.requirement || typeof opts.requirement !== "object") {
+    throw new AuthError("auth-stepUp/bad-requirement",
+      "middleware.requireStepUp: opts.requirement must be an object");
+  }
+  validateOpts.optionalFunction(opts.getClaims,
+    "middleware.requireStepUp: getClaims", AuthError, "auth-stepUp/bad-opt");
+
+  var realm        = (typeof opts.realm === "string" && opts.realm.length > 0)
+    ? opts.realm : "api";
+  var auditOn      = opts.audit !== false;
+  var getClaims    = (typeof opts.getClaims === "function")
+    ? opts.getClaims : _defaultGetClaims;
+  var acceptGrant  = opts.acceptGrant !== false;
+  var grantHeader  = (typeof opts.grantHeader === "string" && opts.grantHeader.length > 0)
+    ? opts.grantHeader.toLowerCase() : DEFAULT_GRANT_HEADER;
+  var grantScope   = (typeof opts.grantScope === "string" && opts.grantScope.length > 0)
+    ? opts.grantScope : null;
+  var errorDesc    = (typeof opts.errorDescription === "string" && opts.errorDescription.length > 0)
+    ? opts.errorDescription : null;
+
+  // Pre-validate the requirement so operator typos surface at boot, not
+  // on the first hot-path request.
+  var probe = stepUp().evaluate({ claims: { acr: "0" }, requirement: opts.requirement });
+  if (probe.error === "bad_requirement" || probe.error === "unknown_acr") {
+    throw new AuthError("auth-stepUp/bad-requirement",
+      "middleware.requireStepUp: " + (probe.reason || probe.error));
+  }
+
+  return function requireStepUpMiddleware(req, res, next) {
+    var headers = req.headers || {};
+
+    // Path 1: operator-issued elevation grant — short-circuit success.
+    if (acceptGrant) {
+      var grantToken = headers[grantHeader] || null;
+      if (typeof grantToken === "string" && grantToken.length > 0) {
+        var verifyOpts = {};
+        if (grantScope) verifyOpts.scope = grantScope;
+        var grantResult = elevation().verify(grantToken, verifyOpts);
+        if (grantResult.ok) {
+          if (auditOn) {
+            try {
+              audit().safeEmit({
+                action:  "auth.stepup.satisfied",
+                outcome: "success",
+                actor:   { userId: grantResult.payload.sub,
+                           clientIp: requestHelpers.clientIp(req) },
+                metadata: {
+                  reason: "grant",
+                  jti:    grantResult.payload.jti || null,
+                  scope:  grantResult.payload.scope,
+                  route:  req.url || null,
+                },
+              });
+            } catch (_e) { /* drop-silent */ }
+          }
+          if (req.user) req.user.stepUp = { byGrant: true, payload: grantResult.payload };
+          return next();
+        }
+        // Invalid grant — fall through to claims-based path; emit signal.
+        if (auditOn) {
+          try {
+            audit().safeEmit({
+              action:  "auth.stepup.grant.rejected",
+              outcome: "denied",
+              actor:   { clientIp: requestHelpers.clientIp(req) },
+              metadata: { error: grantResult.error, reason: grantResult.reason },
+            });
+          } catch (_e) { /* drop-silent */ }
+        }
+      }
+    }
+
+    // Path 2: claims-based evaluation.
+    var claims = getClaims(req);
+    var result = stepUp().evaluate({ claims: claims, requirement: opts.requirement });
+
+    if (result.ok) {
+      if (auditOn) stepUp().emitAuditSatisfied("requireStepUp", opts.requirement, result.presented, req);
+      if (req.user) req.user.stepUp = { byClaims: true, presented: result.presented };
+      return next();
+    }
+
+    if (auditOn) stepUp().emitAuditRequired("requireStepUp", opts.requirement, result.presented, req);
+
+    var challenge = stepUp().buildChallenge({
+      requirement:      opts.requirement,
+      realm:            realm,
+      error:            stepUp().INSUFFICIENT_USER_AUTHENTICATION,
+      errorDescription: errorDesc || undefined,
+    });
+    _writeChallenge(res,
+      challenge,
+      {
+        error:             stepUp().INSUFFICIENT_USER_AUTHENTICATION,
+        error_description: errorDesc || "A higher level of authentication is required",
+      },
+      401                                                                                  // allow:raw-byte-literal — HTTP 401
+    );
+  };
+}
+
+module.exports = { create: create };