@blamejs/core 0.7.18 → 0.7.20

package/lib/middleware/attach-user.js

@@ -1,157 +1,157 @@
-"use strict";
-/**
- * attach-user middleware — populates req.user (and req.session) from a
- * verified session token.
- *
- * Token sources, tried in order:
- *   1. Cookie named opts.cookieName (default "blamejs_session")
- *   2. Authorization: Bearer <token> header
- * The first one that produces a verified session wins. Operators who
- * want only one path can disable the other via opts.tokenFrom.
- *
- * Sealed cookies (access-gated): when opts.sealed is true and opts.vault
- * is provided, the cookie value is read via cookies.readSealed (which
- * vault-unseals and recovers the original session token). Without the
- * framework's vault key no client can hand-craft a valid cookie, so the
- * API is unreachable via curl-with-arbitrary-cookies. Default off for
- * back-compat with apps that put the raw token in the cookie.
- *
- * The framework can't know the application's user schema, so the
- * middleware delegates user-record loading to opts.userLoader — an
- * async function `(verifiedSession) => user | null`. Operators
- * typically look up by userId in their own users table.
- *
- * Failure modes (none of which throw):
- *   - No token in either source → req.user = null, next()
- *   - Sealed cookie present but unsealable → req.user = null, next()
- *   - Token present but session.verify rejects → req.user = null, next()
- *   - Session valid but userLoader returns null/undefined → req.user
- *     = null, next() + audit emit (with outcome=failure)
- *
- * Always calls next() — the gating decision is downstream's job (use
- * middleware.requireAuth for that). This middleware only ATTACHES.
- *
- * Options:
- *   {
- *     cookieName:  'blamejs_session'                 (cookie name to read)
- *     tokenFrom:   'both' | 'cookie' | 'header'      (default 'both')
- *     sealed:      false                             (use cookies.readSealed)
- *     vault:       b.vault                           (required when sealed)
- *     userLoader:  async (verifiedSession) => user   (REQUIRED)
- *     audit:       true                              (emit user-load audits)
- *   }
- */
-var lazyRequire = require("../lazy-require");
-var cookies = require("../cookies");
-var requestHelpers = require("../request-helpers");
-var validateOpts = require("../validate-opts");
-var session = lazyRequire(function () { return require("../session"); });
-var audit   = lazyRequire(function () { return require("../audit"); });
-
-// Back-compat helper: read a single named cookie from a Cookie: header
-// string. Delegates to cookies.parse so the parser is one place.
-function _readCookie(cookieHeader, name) {
-  if (!cookieHeader || typeof cookieHeader !== "string") return null;
-  var jar = cookies.parse(cookieHeader);
-  return Object.prototype.hasOwnProperty.call(jar, name) ? jar[name] : null;
-}
-
-function _readBearer(authHeader) {
-  if (!authHeader || typeof authHeader !== "string") return null;
-  // case-insensitive scheme match
-  var m = authHeader.match(/^Bearer\s+(.+)$/i);
-  return m ? m[1].trim() : null;
-}
-
-function create(opts) {
-  opts = opts || {};
-  validateOpts(opts, [
-    "cookieName", "tokenFrom", "sealed", "vault", "userLoader", "audit",
-  ], "middleware.attachUser");
-  if (typeof opts.userLoader !== "function") {
-    throw new Error("middleware.attachUser: opts.userLoader is required " +
-      "(async function (verifiedSession) → user | null)");
-  }
-  var cookieName = opts.cookieName || "blamejs_session";
-  var tokenFrom  = opts.tokenFrom  || "both";
-  var auditOn    = opts.audit !== false;
-  var sealed     = !!opts.sealed;
-  if (sealed && (!opts.vault || typeof opts.vault.unseal !== "function")) {
-    throw new Error("middleware.attachUser: opts.sealed requires opts.vault " +
-      "with a .unseal method (typically b.vault)");
-  }
-  // Cookie reader: instance bound to the operator's vault when sealed,
-  // otherwise the stateless plain reader.
-  var cookieJar = sealed ? cookies.create({ vault: opts.vault }) : null;
-
-  return async function attachUser(req, res, next) {
-    req.user = null;
-    req.session = null;
-
-    var token = null;
-    if (tokenFrom === "cookie" || tokenFrom === "both") {
-      token = sealed
-        ? cookieJar.readSealed(req, cookieName)
-        : _readCookie(req.headers && req.headers.cookie, cookieName);
-    }
-    if (!token && (tokenFrom === "header" || tokenFrom === "both")) {
-      token = _readBearer(req.headers && req.headers.authorization);
-    }
-    if (!token) return next();
-
-    var verified;
-    try {
-      verified = await session().verify(token);
-    } catch (_e) {
-      // session.verify is tolerant — shouldn't normally throw, but if it
-      // does (DB hiccup), don't propagate; treat as "no user" and let
-      // downstream require-auth produce a 401.
-      return next();
-    }
-    if (!verified) return next();
-
-    var user;
-    try {
-      user = await opts.userLoader(verified);
-    } catch (e) {
-      // userLoader threw — treat as "no user" but record so the
-      // operator can investigate. Don't surface to the response.
-      if (auditOn) {
-        try {
-          audit().emit({
-            action:   "auth.session.user_loader_threw",
-            outcome:  "failure",
-            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
-            reason:   (e && e.message) || String(e),
-          });
-        } catch (_ignored) { /* audit best-effort */ }
-      }
-      return next();
-    }
-    if (!user) {
-      // Session valid but user record is gone (deleted) or rejected
-      // (suspended, etc.). Record + don't attach.
-      if (auditOn) {
-        try {
-          audit().emit({
-            action:   "auth.session.user_unloadable",
-            outcome:  "failure",
-            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
-          });
-        } catch (_ignored) { /* audit best-effort */ }
-      }
-      return next();
-    }
-
-    req.user = user;
-    req.session = verified;
-    return next();
-  };
-}
-
-module.exports = {
-  create:       create,
-  // Exported for tests and operator-side cookie reading
-  _readCookie:  _readCookie,
-  _readBearer:  _readBearer,
-};
+"use strict";
+/**
+ * attach-user middleware — populates req.user (and req.session) from a
+ * verified session token.
+ *
+ * Token sources, tried in order:
+ *   1. Cookie named opts.cookieName (default "blamejs_session")
+ *   2. Authorization: Bearer <token> header
+ * The first one that produces a verified session wins. Operators who
+ * want only one path can disable the other via opts.tokenFrom.
+ *
+ * Sealed cookies (access-gated): when opts.sealed is true and opts.vault
+ * is provided, the cookie value is read via cookies.readSealed (which
+ * vault-unseals and recovers the original session token). Without the
+ * framework's vault key no client can hand-craft a valid cookie, so the
+ * API is unreachable via curl-with-arbitrary-cookies. Default off for
+ * back-compat with apps that put the raw token in the cookie.
+ *
+ * The framework can't know the application's user schema, so the
+ * middleware delegates user-record loading to opts.userLoader — an
+ * async function `(verifiedSession) => user | null`. Operators
+ * typically look up by userId in their own users table.
+ *
+ * Failure modes (none of which throw):
+ *   - No token in either source → req.user = null, next()
+ *   - Sealed cookie present but unsealable → req.user = null, next()
+ *   - Token present but session.verify rejects → req.user = null, next()
+ *   - Session valid but userLoader returns null/undefined → req.user
+ *     = null, next() + audit emit (with outcome=failure)
+ *
+ * Always calls next() — the gating decision is downstream's job (use
+ * middleware.requireAuth for that). This middleware only ATTACHES.
+ *
+ * Options:
+ *   {
+ *     cookieName:  'blamejs_session'                 (cookie name to read)
+ *     tokenFrom:   'both' | 'cookie' | 'header'      (default 'both')
+ *     sealed:      false                             (use cookies.readSealed)
+ *     vault:       b.vault                           (required when sealed)
+ *     userLoader:  async (verifiedSession) => user   (REQUIRED)
+ *     audit:       true                              (emit user-load audits)
+ *   }
+ */
+var lazyRequire = require("../lazy-require");
+var cookies = require("../cookies");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var session = lazyRequire(function () { return require("../session"); });
+var audit   = lazyRequire(function () { return require("../audit"); });
+
+// Back-compat helper: read a single named cookie from a Cookie: header
+// string. Delegates to cookies.parse so the parser is one place.
+function _readCookie(cookieHeader, name) {
+  if (!cookieHeader || typeof cookieHeader !== "string") return null;
+  var jar = cookies.parse(cookieHeader);
+  return Object.prototype.hasOwnProperty.call(jar, name) ? jar[name] : null;
+}
+
+function _readBearer(authHeader) {
+  if (!authHeader || typeof authHeader !== "string") return null;
+  // case-insensitive scheme match
+  var m = authHeader.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "cookieName", "tokenFrom", "sealed", "vault", "userLoader", "audit",
+  ], "middleware.attachUser");
+  if (typeof opts.userLoader !== "function") {
+    throw new Error("middleware.attachUser: opts.userLoader is required " +
+      "(async function (verifiedSession) → user | null)");
+  }
+  var cookieName = opts.cookieName || "blamejs_session";
+  var tokenFrom  = opts.tokenFrom  || "both";
+  var auditOn    = opts.audit !== false;
+  var sealed     = !!opts.sealed;
+  if (sealed && (!opts.vault || typeof opts.vault.unseal !== "function")) {
+    throw new Error("middleware.attachUser: opts.sealed requires opts.vault " +
+      "with a .unseal method (typically b.vault)");
+  }
+  // Cookie reader: instance bound to the operator's vault when sealed,
+  // otherwise the stateless plain reader.
+  var cookieJar = sealed ? cookies.create({ vault: opts.vault }) : null;
+
+  return async function attachUser(req, res, next) {
+    req.user = null;
+    req.session = null;
+
+    var token = null;
+    if (tokenFrom === "cookie" || tokenFrom === "both") {
+      token = sealed
+        ? cookieJar.readSealed(req, cookieName)
+        : _readCookie(req.headers && req.headers.cookie, cookieName);
+    }
+    if (!token && (tokenFrom === "header" || tokenFrom === "both")) {
+      token = _readBearer(req.headers && req.headers.authorization);
+    }
+    if (!token) return next();
+
+    var verified;
+    try {
+      verified = await session().verify(token);
+    } catch (_e) {
+      // session.verify is tolerant — shouldn't normally throw, but if it
+      // does (DB hiccup), don't propagate; treat as "no user" and let
+      // downstream require-auth produce a 401.
+      return next();
+    }
+    if (!verified) return next();
+
+    var user;
+    try {
+      user = await opts.userLoader(verified);
+    } catch (e) {
+      // userLoader threw — treat as "no user" but record so the
+      // operator can investigate. Don't surface to the response.
+      if (auditOn) {
+        try {
+          audit().emit({
+            action:   "auth.session.user_loader_threw",
+            outcome:  "failure",
+            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
+            reason:   (e && e.message) || String(e),
+          });
+        } catch (_ignored) { /* audit best-effort */ }
+      }
+      return next();
+    }
+    if (!user) {
+      // Session valid but user record is gone (deleted) or rejected
+      // (suspended, etc.). Record + don't attach.
+      if (auditOn) {
+        try {
+          audit().emit({
+            action:   "auth.session.user_unloadable",
+            outcome:  "failure",
+            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
+          });
+        } catch (_ignored) { /* audit best-effort */ }
+      }
+      return next();
+    }
+
+    req.user = user;
+    req.session = verified;
+    return next();
+  };
+}
+
+module.exports = {
+  create:       create,
+  // Exported for tests and operator-side cookie reading
+  _readCookie:  _readCookie,
+  _readBearer:  _readBearer,
+};

package/lib/middleware/bearer-auth.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * bearer-auth middleware — extracts `Authorization: Bearer <token>`,
+ * runs an operator-supplied verifier, and attaches the result to
+ * `req.user`. Distinct from `attachUser` (which reads session cookies)
+ * — this is the API-token / JWT / OAuth-access-token path.
+ *
+ * Mount this for routes that accept bearer tokens. Operators that
+ * accept BOTH cookie sessions AND bearer tokens mount both: bearerAuth
+ * runs first; if no Bearer header, it calls next() so attachUser /
+ * requireAuth can take over. If a Bearer header IS present but invalid,
+ * bearerAuth rejects with 401 immediately (avoids the
+ * "is this a bearer or a cookie session?" collision in attach-user.js).
+ *
+ *   var bearer = b.middleware.bearerAuth({
+ *     verify: async function (token) {
+ *       // operator-supplied: return a user object or null/throw
+ *       var rec = await b.apiKey.verify(token);
+ *       return rec ? { id: rec.ownerId, scopes: rec.scopes } : null;
+ *     },
+ *     audit:        true,                  // default
+ *     scheme:       "Bearer",              // default; some ops use "Token"
+ *     errorMessage: "Bearer token required.",
+ *   });
+ *   router.use("/api", bearer);
+ *
+ * Verify result shape:
+ *   - object truthy → req.user = result; next()
+ *   - null / undefined / false → 401 (token invalid)
+ *   - throws an Error with .code === "auth-bearer/expired" → 401 + WWW-Authenticate
+ *
+ * Audit: `auth.bearer.success` on accept; `auth.bearer.failure` with
+ * reason on reject. Both carry actor context (clientIp, userAgent,
+ * route).
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _writeUnauthorized(res, scheme, message, realm) {
+  if (res.headersSent) return;
+  var body = JSON.stringify({ error: message });
+  var challenge = scheme + (realm ? ' realm="' + realm + '"' : "");
+  res.writeHead(401, {                                                           // allow:raw-byte-literal — HTTP 401 status
+    "Content-Type":     "application/json; charset=utf-8",
+    "Content-Length":   Buffer.byteLength(body),
+    "WWW-Authenticate": challenge,
+  });
+  res.end(body);
+}
+
+function _extractToken(req, scheme) {
+  var h = req.headers && req.headers.authorization;
+  if (typeof h !== "string" || h.length === 0) return null;
+  var prefix = scheme + " ";
+  if (h.length <= prefix.length) return null;
+  if (h.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()) return null;
+  var token = h.slice(prefix.length).trim();
+  return token.length > 0 ? token : null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "verify", "audit", "scheme", "errorMessage", "realm",
+    "tokenAttachKey", "userAttachKey",
+  ], "middleware.bearerAuth");
+
+  if (typeof opts.verify !== "function") {
+    throw new AuthError("auth-bearer/missing-verify",
+      "middleware.bearerAuth requires a verify(token) function — operators MUST supply " +
+      "the verification path (b.apiKey.verify / b.auth.jwt.verifyExternal / custom)");
+  }
+  var auditOn       = opts.audit !== false;
+  var scheme        = opts.scheme || "Bearer";
+  var errorMessage  = opts.errorMessage || "Bearer token required.";
+  var realm         = opts.realm || null;
+  var tokenAttach   = opts.tokenAttachKey || "bearerToken";
+  var userAttach    = opts.userAttachKey || "user";
+
+  function _emitAudit(action, outcome, req, reason) {
+    if (!auditOn) return;
+    try {
+      var actor = requestHelpers.extractActorContext(req);
+      audit().safeEmit({
+        action: action, outcome: outcome,
+        metadata: Object.assign({}, actor, {
+          route:  req.url,
+          method: req.method,
+          reason: reason || null,
+        }),
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  function _emitObs(metric, n, tags) {
+    try { observability().count(metric, n, tags || {}); }
+    catch (_e) { /* best-effort */ }
+  }
+
+  return async function bearerAuth(req, res, next) {
+    var token = _extractToken(req, scheme);
+    if (!token) {
+      // No Bearer header — fall through. Cookie-based session middleware
+      // running after this can attach a user via the cookie path.
+      return next();
+    }
+
+    var user;
+    try {
+      user = await opts.verify(token);
+    } catch (e) {
+      var code = (e && e.code) || "auth-bearer/verify-failed";
+      _emitAudit("auth.bearer.failure", "failure", req, code);
+      _emitObs("auth.bearer.rejected", 1, { reason: code });
+      // Per RFC 6750 §3 — `Bearer error="invalid_token"` is the
+      // standardized challenge for verifier-rejected tokens.
+      var challenge = scheme + ' error="invalid_token"' +
+        (realm ? ', realm="' + realm + '"' : "");
+      if (!res.headersSent) {
+        var body = JSON.stringify({ error: errorMessage });
+        res.writeHead(401, {                                                     // allow:raw-byte-literal — HTTP 401 status
+          "Content-Type":     "application/json; charset=utf-8",
+          "Content-Length":   Buffer.byteLength(body),
+          "WWW-Authenticate": challenge,
+        });
+        res.end(body);
+      }
+      return;
+    }
+
+    if (!user) {
+      _emitAudit("auth.bearer.failure", "failure", req, "verifier-returned-null");
+      _emitObs("auth.bearer.rejected", 1, { reason: "verifier-null" });
+      _writeUnauthorized(res, scheme, errorMessage, realm);
+      return;
+    }
+
+    req[tokenAttach] = token;
+    req[userAttach]  = user;
+    _emitAudit("auth.bearer.success", "success", req, null);
+    _emitObs("auth.bearer.accepted", 1, {});
+    next();
+  };
+}
+
+module.exports = { create: create };