migration: openid-client and jose migration

.github/actions/build/action.yml

@@ -5,7 +5,7 @@ inputs:
   node:
     description: The Node version to use
     required: false
-    default: 18
+    default: 24
 
 runs:
   using: composite

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
   rl-scanner:
     uses: ./.github/workflows/rl-secure.yml
     with:
-      node-version: 18 ## depends if build requires node else we can remove this.
+      node-version: 24 ## depends if build requires node else we can remove this.
       artifact-name: 'express-openid-connect.tgz' ## Will change respective to Repository
     secrets:
       RLSECURE_LICENSE: ${{ secrets.RLSECURE_LICENSE }}
@@ -32,7 +32,7 @@ jobs:
     uses: ./.github/workflows/npm-release.yml
     needs: rl-scanner ## this is important as this will not let release job to run until rl-scanner is done
     with:
-      node-version: 22
+      node-version: 24
       require-build: false
     secrets:
       github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -18,7 +18,7 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 env:
-  NODE_VERSION: 18
+  NODE_VERSION: 22
   CACHE_KEY: '${{ github.ref }}-${{ github.run_id }}-${{ github.run_attempt }}'
 
 jobs:

V3_MIGRATION_GUIDE.md

@@ -0,0 +1,190 @@
+# V3 Migration Guide
+
+`v3.x` upgrades the underlying OpenID Connect and JWT dependencies (`openid-client` v4 → v6, `jose` v2 → v6) to their latest major versions, bringing improved security, performance, and standards compliance.
+
+**Important:** While this is a major version bump for the library, **there are ZERO breaking changes to the public API**. Your application code does not need to change.
+
+---
+
+**Public API:** No breaking changes - all configuration, middleware, and context APIs work exactly the same  
+**Node.js Version:** Now requires `^20.19.0 || ^22.12.0 || >= 23.0.0` (previously Node.js 14+)  
+**Module Support:** Works with BOTH CommonJS and ESM apps
+
+---
+
+## Breaking Changes
+
+### Node.js Version Requirement
+
+**The only breaking change is the specific Node.js version requirement.**
+
+| Version | Minimum Node.js                         | Status  |
+| ------- | --------------------------------------- | ------- |
+| v2.x    | Node.js 14+                             | Old     |
+| v3.x    | `^20.19.0 \|\| ^22.12.0 \|\| >= 23.0.0` | **New** |
+
+#### Why These Specific Versions?
+
+The updated dependencies (`openid-client` v6 and `jose` v6) are **ESM-only packages**.
+
+Node.js added `require(ESM)` support in:
+
+- **v20.19.0** (backported to v20.x LTS)
+- **v22.12.0** (backported to v22.x LTS)
+- **v23.0.0+** (included by default)
+
+There is **no workaround** - you must upgrade to a supported Node.js version.
+
+#### Module System Support
+
+**Works with BOTH CommonJS and ESM apps** - same Node.js requirements for both:
+
+```javascript
+// CommonJS - Works on supported Node.js versions
+const { auth } = require('express-openid-connect');
+
+// ESM - Works on supported Node.js versions
+import { auth } from 'express-openid-connect';
+```
+
+**Note:** ESM apps need `"type": "module"` in `package.json` but have identical Node.js version requirements as CommonJS apps.
+
+### Configuration
+
+All configuration options work exactly as before. No changes needed.
+
+```js
+const { auth } = require('express-openid-connect');
+
+// This configuration works EXACTLY the same in v3.x
+app.use(
+  auth({
+    authRequired: false,
+    auth0Logout: true,
+    baseURL: 'https://example.com',
+    clientID: 'YOUR_CLIENT_ID',
+    issuerBaseURL: 'https://YOUR_DOMAIN',
+    secret: 'LONG_RANDOM_STRING',
+
+    // All these options still work
+    idpLogout: true,
+    idTokenSigningAlg: 'RS256',
+    clientAuthMethod: 'client_secret_post',
+    pushedAuthorizationRequests: true,
+    // ... etc
+  }),
+);
+```
+
+### Middleware
+
+All middleware functions work identically.
+
+```js
+const { auth, requiresAuth } = require('express-openid-connect');
+
+// All these work EXACTLY the same
+app.use(auth(config));
+app.get('/admin', requiresAuth(), (req, res) => {
+  res.send('Admin page');
+});
+```
+
+### Request Context (req.oidc)
+
+The entire `req.oidc` API remains unchanged.
+
+```js
+// Before (v2.x)
+app.get('/profile', async (req, res) => {
+  const user = req.oidc.user;
+  const claims = req.oidc.idTokenClaims;
+  const isAuthenticated = req.oidc.isAuthenticated();
+  const idToken = req.oidc.idToken;
+  const accessToken = req.oidc.accessToken;
+  const refreshToken = req.oidc.refreshToken;
+  const userInfo = await req.oidc.fetchUserInfo();
+
+  res.oidc.login({});
+  res.oidc.logout({});
+});
+
+// After (v3.x) - SAME
+app.get('/profile', async (req, res) => {
+  const user = req.oidc.user;
+  const claims = req.oidc.idTokenClaims;
+  const isAuthenticated = req.oidc.isAuthenticated();
+  const idToken = req.oidc.idToken;
+  const accessToken = req.oidc.accessToken;
+  const refreshToken = req.oidc.refreshToken;
+  const userInfo = await req.oidc.fetchUserInfo();
+
+  res.oidc.login({});
+  res.oidc.logout({});
+});
+```
+
+### Routes
+
+Custom route configuration remains unchanged.
+
+```js
+// This works the same in v3.x
+app.use(
+  auth({
+    routes: {
+      login: '/custom/login',
+      logout: '/custom/logout',
+      callback: '/custom/callback',
+      postLogoutRedirect: '/custom/post-logout',
+    },
+  }),
+);
+```
+
+### Session Handling
+
+Session configuration, custom stores, and lifecycle hooks all work the same.
+
+```js
+// Session configuration - UNCHANGED
+app.use(
+  auth({
+    session: {
+      rolling: true,
+      rollingDuration: 86400,
+      absoluteDuration: 86400 * 7,
+      store: customStore, // Custom session stores still work
+    },
+  }),
+);
+```
+
+### Authentication Methods
+
+All client authentication methods continue to work:
+
+```js
+// All these still work in v3.x
+const config = {
+  clientAuthMethod: 'client_secret_basic',
+  clientAuthMethod: 'client_secret_post',
+  clientAuthMethod: 'client_secret_jwt',
+  clientAuthMethod: 'private_key_jwt',
+  clientAuthMethod: 'none',
+};
+```
+
+---
+
+```bash
+node --version
+```
+
+**Required:** `v20.19.0+`, `v22.12.0+`, or `v23.0.0+`
+
+If your version is older:
+
+- **v20.0.0 - v20.18.0** → Upgrade to v20.19.0+
+- **v22.0.0 - v22.11.0** → Upgrade to v22.12.0+
+- **v18.x or earlier** → Upgrade to v22.12.0+ (recommended LTS)

end-to-end/custom-token-exchange.test.js

@@ -1,6 +1,6 @@
 const { assert } = require('chai');
 const nock = require('nock');
-const { JWT } = require('jose');
+const { SignJWT, importJWK } = require('jose');
 const puppeteer = require('puppeteer');
 const provider = require('./fixture/oidc-provider');
 const { privateJWK } = require('./fixture/jwk');
@@ -67,19 +67,15 @@ describe('custom token exchange', async () => {
        * live JWKS endpoint. { allowUnmocked: true } is required so that nock still
        * passes through the provider's discovery and JWKS GET requests.
        */
-      const downstreamToken = JWT.sign(
-        {
-          aud: 'https://api.example.com/products',
-          scope: 'read:products',
-        },
-        privateJWK,
-        {
-          issuer: 'http://localhost:3001',
-          algorithm: 'RS256',
-          expiresIn: '1h',
-          header: { kid: 'key-1' },
-        },
-      );
+      const privateKey = await importJWK(privateJWK, 'RS256');
+      const downstreamToken = await new SignJWT({
+        aud: 'https://api.example.com/products',
+        scope: 'read:products',
+      })
+        .setProtectedHeader({ alg: 'RS256', kid: 'key-1' })
+        .setIssuer('http://localhost:3001')
+        .setExpirationTime('1h')
+        .sign(privateKey);
 
       nock('http://localhost:3001', { allowUnmocked: true })
         .post('/token')

end-to-end/fixture/helpers.js

@@ -2,7 +2,7 @@ const path = require('path');
 const crypto = require('crypto');
 const sinon = require('sinon');
 const express = require('express');
-const { JWT } = require('jose');
+const jose = require('jose');
 const { privateJWK } = require('./jwk');
 const request = require('request-promise-native').defaults({ json: true });
 
@@ -93,24 +93,24 @@ const logout = async (page) => {
 };
 
 const logoutTokenTester = (clientId, sid, sub) => async (req, res) => {
-  const logoutToken = JWT.sign(
-    {
-      events: {
-        'http://schemas.openid.net/event/backchannel-logout': {},
-      },
-      ...(sid && { sid: req.oidc.user.sid }),
-      ...(sub && { sub: req.oidc.user.sub }),
-    },
-    privateJWK,
-    {
-      issuer: `http://localhost:${process.env.PROVIDER_PORT || 3001}`,
-      audience: clientId,
-      iat: true,
-      jti: crypto.randomBytes(16).toString('hex'),
-      algorithm: 'RS256',
-      header: { typ: 'logout+jwt' },
+  // Create private key from JWK for signing
+  const privateKey = await jose.importJWK(privateJWK, 'RS256');
+
+  const claims = {
+    events: {
+      'http://schemas.openid.net/event/backchannel-logout': {},
     },
-  );
+    ...(sid && { sid: req.oidc.user.sid }),
+    ...(sub && { sub: req.oidc.user.sub }),
+  };
+
+  const logoutToken = await new jose.SignJWT(claims)
+    .setProtectedHeader({ alg: 'RS256', typ: 'logout+jwt' })
+    .setIssuer(`http://localhost:${process.env.PROVIDER_PORT || 3001}`)
+    .setAudience(clientId)
+    .setIssuedAt()
+    .setJti(crypto.randomBytes(16).toString('hex'))
+    .sign(privateKey);
 
   res.send(`
     <pre style="border: 1px solid #ccc; padding: 10px; white-space: break-spaces; background: whitesmoke;">curl -X POST http://localhost:3000/backchannel-logout -d "logout_token=${logoutToken}"</pre>