@depup/express-openid-connect 2.19.4-depup.0

package/lib/hooks/getLoginState.js

@@ -0,0 +1,51 @@
+const base64url = require('base64url');
+const debug = require('../debug')('getLoginState');
+
+/**
+ * Generate the state value for use during login transactions. It is used to store the intended
+ * return URL after the user authenticates. State is not used to carry unique PRNG values here
+ * because the library utilizes either nonce or PKCE for CSRF protection.
+ *
+ * @param {RequestHandler} req
+ * @param {object} options
+ *
+ * @return {object}
+ */
+function defaultState(req, options) {
+  const state = { returnTo: options.returnTo || req.originalUrl };
+  debug('adding default state %O', state);
+  return state;
+}
+
+/**
+ * Prepare a state object to send.
+ *
+ * @param {object} stateObject
+ *
+ * @return {string}
+ */
+function encodeState(stateObject = {}) {
+  // this filters out nonce, code_verifier, and max_age from the state object so that the values are
+  // only stored in its dedicated transient cookie
+  const { nonce, code_verifier, max_age, ...filteredState } = stateObject;
+  return base64url.encode(JSON.stringify(filteredState));
+}
+
+/**
+ * Decode a state value.
+ *
+ * @param {string} stateValue
+ *
+ * @return {object}
+ */
+function decodeState(stateValue) {
+  try {
+    return JSON.parse(base64url.decode(stateValue));
+  } catch {
+    return false;
+  }
+}
+
+module.exports.defaultState = defaultState;
+module.exports.encodeState = encodeState;
+module.exports.decodeState = decodeState;

package/lib/once.js

@@ -0,0 +1,19 @@
+/**
+ * Given a callback, return a wrapped callback that will only run once regardless of calls.
+ */
+function once(callback) {
+  let called = false;
+  let value;
+
+  return (...args) => {
+    if (!called) {
+      value = callback(...args);
+    }
+
+    called = true;
+
+    return value;
+  };
+}
+
+module.exports = { once };

package/lib/transientHandler.js

@@ -0,0 +1,155 @@
+const { generators } = require('openid-client');
+const {
+  signCookie: generateCookieValue,
+  verifyCookie: getCookieValue,
+  getKeyStore,
+} = require('./crypto');
+const COOKIES = require('./cookies');
+
+class TransientCookieHandler {
+  constructor({ secret, session, legacySameSiteCookie }) {
+    let [current, keystore] = getKeyStore(secret);
+
+    if (keystore.size === 1) {
+      keystore = current;
+    }
+    this.currentKey = current;
+    this.keyStore = keystore;
+    this.sessionCookieConfig = (session && session.cookie) || {};
+    this.legacySameSiteCookie = legacySameSiteCookie;
+  }
+
+  /**
+   * Set a cookie with a value or a generated nonce.
+   *
+   * @param {String} key Cookie name to use.
+   * @param {Object} req Express Request object.
+   * @param {Object} res Express Response object.
+   * @param {Object} opts Options object.
+   * @param {String} opts.sameSite SameSite attribute of "None," "Lax," or "Strict". Default is "None."
+   * @param {String} opts.value Cookie value. Omit this key to store a generated value.
+   * @param {Boolean} opts.legacySameSiteCookie Should a fallback cookie be set? Default is true.
+   *
+   * @return {String} Cookie value that was set.
+   */
+  store(
+    key,
+    req,
+    res,
+    { sameSite = 'None', value = this.generateNonce() } = {}
+  ) {
+    const isSameSiteNone = sameSite === 'None';
+    const { domain, path, secure } = this.sessionCookieConfig;
+    const basicAttr = {
+      httpOnly: true,
+      secure,
+      domain,
+      path,
+    };
+
+    {
+      const cookieValue = generateCookieValue(key, value, this.currentKey);
+      // Set the cookie with the SameSite attribute and, if needed, the Secure flag.
+      res.cookie(key, cookieValue, {
+        ...basicAttr,
+        sameSite,
+        secure: isSameSiteNone ? true : basicAttr.secure,
+      });
+    }
+
+    if (isSameSiteNone && this.legacySameSiteCookie) {
+      const cookieValue = generateCookieValue(
+        `_${key}`,
+        value,
+        this.currentKey
+      );
+      // Set the fallback cookie with no SameSite or Secure attributes.
+      res.cookie(`_${key}`, cookieValue, basicAttr);
+    }
+
+    return value;
+  }
+
+  /**
+   * Get a cookie value then delete it.
+   *
+   * @param {String} key Cookie name to use.
+   * @param {Object} req Express Request object.
+   * @param {Object} res Express Response object.
+   *
+   * @return {String|undefined} Cookie value or undefined if cookie was not found.
+   */
+  getOnce(key, req, res) {
+    if (!req[COOKIES]) {
+      return undefined;
+    }
+
+    const { secure, sameSite } = this.sessionCookieConfig;
+
+    let value = getCookieValue(key, req[COOKIES][key], this.keyStore);
+    this.deleteCookie(key, res, { secure, sameSite });
+
+    if (this.legacySameSiteCookie) {
+      const fallbackKey = `_${key}`;
+      if (!value) {
+        value = getCookieValue(
+          fallbackKey,
+          req[COOKIES][fallbackKey],
+          this.keyStore
+        );
+      }
+      this.deleteCookie(fallbackKey, res);
+    }
+
+    return value;
+  }
+
+  /**
+   * Generates a nonce value.
+   *
+   * @return {String}
+   */
+  generateNonce() {
+    return generators.nonce();
+  }
+
+  /**
+   * Generates a code_verifier value.
+   *
+   * @return {String}
+   */
+  generateCodeVerifier() {
+    return generators.codeVerifier();
+  }
+
+  /**
+   * Calculates a code_challenge value for a given codeVerifier
+   *
+   * @param {String} codeVerifier Code Verifier to calculate the code_challenge value from.
+   *
+   * @return {String}
+   */
+  calculateCodeChallenge(codeVerifier) {
+    return generators.codeChallenge(codeVerifier);
+  }
+
+  /**
+   * Clears the cookie from the browser by setting an empty value and an expiration date in the past
+   *
+   * @param {String} name Cookie name
+   * @param {Object} res Express Response object
+   * @param {Object?} opts Optional SameSite and Secure cookie options for modern browsers
+   */
+  deleteCookie(name, res, opts = {}) {
+    const { domain, path } = this.sessionCookieConfig;
+    const { sameSite, secure } = opts;
+    res.clearCookie(name, {
+      domain,
+      path,
+      sameSite,
+      secure,
+    });
+  }
+}
+
+module.exports = TransientCookieHandler;

package/lib/utils/promisifyCompat.js

@@ -0,0 +1,90 @@
+const utilPromisify = require('util-promisify');
+
+/**
+ * Checks if a method follows callback-based pattern
+ * @param {Function} method - The method to check
+ * @returns {boolean} True if method appears to be callback-based
+ */
+function isCallbackBasedMethod(method) {
+  const paramCount = method.length;
+
+  // Must have at least 2 parameters for callback pattern
+  if (paramCount < 2) {
+    return false;
+  }
+
+  const methodSource = method.toString();
+  const callbackPatterns = ['cb', 'callback'];
+
+  return callbackPatterns.some((pattern) => methodSource.includes(pattern));
+}
+
+/**
+ * Checks if a method is declared as async
+ * @param {Function} method - The method to check
+ * @returns {boolean} True if method is async
+ */
+function isAsyncFunction(method) {
+  return method.constructor.name === 'AsyncFunction';
+}
+/**
+ * Safely promisify store methods to avoid Node.js deprecation warnings.
+ * Uses util-promisify with additional safety checks to prevent hanging.
+ *
+ * @param {Function} method - The method to potentially promisify
+ * @param {Object} context - The context to bind the method to
+ * @returns {Function} Promise-based function
+ * @throws {TypeError} When method is not a function
+ */
+function safePromisify(method, context) {
+  if (typeof method !== 'function') {
+    throw new TypeError('Expected method to be a function');
+  }
+
+  // 1. Async functions - require callbacks
+  if (isAsyncFunction(method) && isCallbackBasedMethod(method)) {
+    return function (...args) {
+      return new Promise((resolve, reject) => {
+        // Add callback as last argument
+        const callback = (err, result) => {
+          if (err) reject(err);
+          else resolve(result);
+        };
+        method.call(context, ...args, callback);
+      });
+    };
+  }
+  // 2. Async functions - these are already Promise-based
+  if (isAsyncFunction(method)) {
+    return method.bind(context);
+  }
+
+  // 3. Functions that clearly return Promises (without calling them)
+  const methodSource = method.toString();
+  const directPromisePatterns = [
+    'return Promise.resolve',
+    'return Promise.reject',
+    'return new Promise',
+  ];
+
+  const returnsDirectPromise = directPromisePatterns.some((pattern) =>
+    methodSource.includes(pattern),
+  );
+
+  if (returnsDirectPromise) {
+    return method.bind(context);
+  }
+
+  // 3. For all other cases, use util-promisify safely
+  // util-promisify should handle:
+  // - Callback-based methods: promisifies them without deprecation warnings
+  // - Promise-returning methods: returns them as-is
+  try {
+    return utilPromisify(method).bind(context);
+  } catch {
+    // Fallback to treating as already Promise-based if util-promisify fails
+    return method.bind(context);
+  }
+}
+
+module.exports = safePromisify;

package/lib/weakCache.js

@@ -0,0 +1,8 @@
+const map = new WeakMap();
+
+function instance(ctx) {
+  if (!map.has(ctx)) map.set(ctx, {});
+  return map.get(ctx);
+}
+
+module.exports = instance;

package/middleware/attemptSilentLogin.js

@@ -0,0 +1,66 @@
+const debug = require('../lib/debug')('attemptSilentLogin');
+const COOKIES = require('../lib/cookies');
+const weakRef = require('../lib/weakCache');
+
+const COOKIE_NAME = 'skipSilentLogin';
+
+const cancelSilentLogin = (req, res) => {
+  const {
+    config: {
+      session: {
+        cookie: { secure, domain, path, sameSite },
+      },
+    },
+  } = weakRef(req.oidc);
+  res.cookie(COOKIE_NAME, true, {
+    httpOnly: true,
+    secure,
+    domain,
+    path,
+    sameSite,
+  });
+};
+
+const resumeSilentLogin = (req, res) => {
+  const {
+    config: {
+      session: {
+        cookie: { domain, path, sameSite, secure },
+      },
+    },
+  } = weakRef(req.oidc);
+  res.clearCookie(COOKIE_NAME, {
+    httpOnly: true,
+    domain,
+    path,
+    sameSite,
+    secure,
+  });
+};
+
+module.exports = function attemptSilentLogin() {
+  return (req, res, next) => {
+    if (!req.oidc) {
+      next(
+        new Error('req.oidc is not found, did you include the auth middleware?')
+      );
+      return;
+    }
+
+    const silentLoginAttempted = !!(req[COOKIES] || {})[COOKIE_NAME];
+
+    if (
+      !silentLoginAttempted &&
+      !req.oidc.isAuthenticated() &&
+      req.accepts('html')
+    ) {
+      debug('Attempting silent login');
+      cancelSilentLogin(req, res);
+      return res.oidc.silentLogin();
+    }
+    next();
+  };
+};
+
+module.exports.cancelSilentLogin = cancelSilentLogin;
+module.exports.resumeSilentLogin = resumeSilentLogin;

package/middleware/auth.js

@@ -0,0 +1,129 @@
+const express = require('express');
+
+const debug = require('../lib/debug')('auth');
+const { get: getConfig } = require('../lib/config');
+const { requiresAuth } = require('./requiresAuth');
+const attemptSilentLogin = require('./attemptSilentLogin');
+const TransientCookieHandler = require('../lib/transientHandler');
+const { RequestContext, ResponseContext } = require('../lib/context');
+const appSession = require('../lib/appSession');
+const isLoggedOut = require('../lib/hooks/backchannelLogout/isLoggedOut');
+
+const enforceLeadingSlash = (path) => {
+  return path.split('')[0] === '/' ? path : '/' + path;
+};
+
+/**
+ * Returns a router with two routes /login and /callback
+ *
+ * @param {Object} [params] The parameters object; see index.d.ts for types and descriptions.
+ *
+ * @returns {express.Router} the router
+ */
+const auth = function (params) {
+  const config = getConfig(params);
+  debug('configuration object processed, resulting configuration: %O', config);
+  const router = new express.Router();
+  const transient = new TransientCookieHandler(config);
+
+  router.use(appSession(config));
+
+  // Express context and OpenID Issuer discovery.
+  router.use(async (req, res, next) => {
+    req.oidc = new RequestContext(config, req, res, next);
+    res.oidc = new ResponseContext(config, req, res, next, transient);
+    next();
+  });
+
+  // Login route, configurable with routes.login
+  if (config.routes.login) {
+    const path = enforceLeadingSlash(config.routes.login);
+    debug('adding GET %s route', path);
+    router.get(path, express.urlencoded({ extended: false }), (req, res) =>
+      res.oidc.login({ returnTo: config.baseURL })
+    );
+  } else {
+    debug('login handling route not applied');
+  }
+
+  // Logout route, configurable with routes.logout
+  if (config.routes.logout) {
+    const path = enforceLeadingSlash(config.routes.logout);
+    debug('adding GET %s route', path);
+    router.get(path, (req, res) => res.oidc.logout());
+  } else {
+    debug('logout handling route not applied');
+  }
+
+  // Callback route, configured with routes.callback.
+  if (config.routes.callback) {
+    const path = enforceLeadingSlash(config.routes.callback);
+    debug('adding GET %s route', path);
+    router.get(path, (req, res) => res.oidc.callback());
+    debug('adding POST %s route', path);
+    router.post(path, express.urlencoded({ extended: false }), (req, res) =>
+      res.oidc.callback()
+    );
+  } else {
+    debug('callback handling route not applied');
+  }
+
+  if (config.backchannelLogout) {
+    const path = enforceLeadingSlash(config.routes.backchannelLogout);
+    debug('adding POST %s route', path);
+    router.post(path, express.urlencoded({ extended: false }), (req, res) =>
+      res.oidc.backchannelLogout()
+    );
+
+    if (config.backchannelLogout.isLoggedOut !== false) {
+      const isLoggedOutFn = config.backchannelLogout.isLoggedOut || isLoggedOut;
+      router.use(async (req, res, next) => {
+        if (!req.oidc.isAuthenticated()) {
+          next();
+          return;
+        }
+        try {
+          const loggedOut = await isLoggedOutFn(req, config);
+          if (loggedOut) {
+            req[config.session.name] = undefined;
+          }
+          next();
+        } catch (e) {
+          next(e);
+        }
+      });
+    }
+  }
+
+  if (config.authRequired) {
+    debug(
+      'authentication is required for all routes this middleware is applied to'
+    );
+    router.use(requiresAuth());
+  } else {
+    debug(
+      'authentication is not required for any of the routes this middleware is applied to ' +
+        'see and apply `requiresAuth` middlewares to your protected resources'
+    );
+  }
+  if (config.attemptSilentLogin) {
+    debug("silent login will be attempted on end-user's initial HTML request");
+    router.use(attemptSilentLogin());
+  }
+
+  return router;
+};
+
+/**
+ * Used for instantiating a custom session store. eg
+ *
+ * ```js
+ * const { auth } = require('express-openid-connect');
+ * const MemoryStore = require('memorystore')(auth);
+ * ```
+ *
+ * @constructor
+ */
+auth.Store = function () {};
+
+module.exports = auth;

package/middleware/requiresAuth.js

@@ -0,0 +1,133 @@
+const createError = require('http-errors');
+const debug = require('../lib/debug')('requiresAuth');
+
+const defaultRequiresLogin = (req) => !req.oidc.isAuthenticated();
+
+/**
+ * Returns a middleware that checks whether an end-user is authenticated.
+ * If end-user is not authenticated `res.oidc.login()` is triggered for an HTTP
+ * request that can perform a redirect.
+ */
+async function requiresLoginMiddleware(requiresLoginCheck, req, res, next) {
+  if (!req.oidc) {
+    next(
+      new Error('req.oidc is not found, did you include the auth middleware?')
+    );
+    return;
+  }
+
+  if (requiresLoginCheck(req)) {
+    if (!res.oidc.errorOnRequiredAuth && req.accepts('html')) {
+      debug(
+        'authentication requirements not met with errorOnRequiredAuth() returning false, calling res.oidc.login()'
+      );
+      return res.oidc.login();
+    }
+    debug(
+      'authentication requirements not met with errorOnRequiredAuth() returning true, calling next() with an Unauthorized error'
+    );
+    next(
+      createError.Unauthorized('Authentication is required for this route.')
+    );
+    return;
+  }
+
+  debug('authentication requirements met, calling next()');
+
+  next();
+}
+
+module.exports.requiresAuth = function requiresAuth(
+  requiresLoginCheck = defaultRequiresLogin
+) {
+  return requiresLoginMiddleware.bind(undefined, requiresLoginCheck);
+};
+
+function checkJSONprimitive(value) {
+  if (
+    typeof value !== 'string' &&
+    typeof value !== 'number' &&
+    typeof value !== 'boolean' &&
+    value !== null
+  ) {
+    throw new TypeError('"expected" must be a string, number, boolean or null');
+  }
+}
+
+module.exports.claimEquals = function claimEquals(claim, expected) {
+  // check that claim is a string value
+  if (typeof claim !== 'string') {
+    throw new TypeError('"claim" must be a string');
+  }
+  // check that expected is a JSON supported primitive
+  checkJSONprimitive(expected);
+
+  const authenticationCheck = (req) => {
+    if (defaultRequiresLogin(req)) {
+      return true;
+    }
+    const { idTokenClaims } = req.oidc;
+    if (!(claim in idTokenClaims)) {
+      return true;
+    }
+    const actual = idTokenClaims[claim];
+    if (actual !== expected) {
+      return true;
+    }
+
+    return false;
+  };
+  return requiresLoginMiddleware.bind(undefined, authenticationCheck);
+};
+
+module.exports.claimIncludes = function claimIncludes(claim, ...expected) {
+  // check that claim is a string value
+  if (typeof claim !== 'string') {
+    throw new TypeError('"claim" must be a string');
+  }
+  // check that all expected are JSON supported primitives
+  expected.forEach(checkJSONprimitive);
+
+  const authenticationCheck = (req) => {
+    if (defaultRequiresLogin(req)) {
+      return true;
+    }
+    const { idTokenClaims } = req.oidc;
+    if (!(claim in idTokenClaims)) {
+      return true;
+    }
+
+    let actual = idTokenClaims[claim];
+    if (typeof actual === 'string') {
+      actual = actual.split(' ');
+    } else if (!Array.isArray(actual)) {
+      debug(
+        'unexpected claim type. expected array or string, got %o',
+        typeof actual
+      );
+      return true;
+    }
+
+    actual = new Set(actual);
+
+    return !expected.every(Set.prototype.has.bind(actual));
+  };
+  return requiresLoginMiddleware.bind(undefined, authenticationCheck);
+};
+
+module.exports.claimCheck = function claimCheck(func) {
+  // check that func is a function
+  if (typeof func !== 'function' || func.constructor.name !== 'Function') {
+    throw new TypeError('"claimCheck" expects a function');
+  }
+  const authenticationCheck = (req) => {
+    if (defaultRequiresLogin(req)) {
+      return true;
+    }
+
+    const { idTokenClaims } = req.oidc;
+
+    return !func(req, idTokenClaims);
+  };
+  return requiresLoginMiddleware.bind(undefined, authenticationCheck);
+};

package/middleware/unauthorizedHandler.js

@@ -0,0 +1,15 @@
+/**
+ * Returns a middleware that start the login transaction on
+ * Unauthorized errors (i.e. errors with statusCode === 401)
+ *
+ * This middleware needs to be included after your application
+ * routes.
+ */
+module.exports = function () {
+  return (err, req, res, next) => {
+    if (err.statusCode === 401) {
+      return res.oidc.login();
+    }
+    next(err);
+  };
+};