[v8] Add dynamic import wrapper for jose to support Node.js 20.15-20.18 (#1371)

The jose library is ESM-only and cannot be loaded via require() in
Node.js versions before 20.19.0. This adds a dynamic import wrapper that
works across all Node.js 20+ versions using import() which is supported
in both ESM and CJS.

Breaking changes:
- UserManagement.jwks getter changed to async UserManagement.getJWKS()
method
- CookieSession.jwks property removed (uses UserManagement.getJWKS()
instead)

The wrapper enables:
- Lazy loading of jose (only when JWT methods are called)
- Support for all Node.js 20.x versions
- Smaller bundle size (no jose bundling needed)
- Clean migration path when Node 20 reaches EOL (April 2026)

Also updates:
- Minimum Node version to 20.15.0 (conservative choice within 20.x)
- tsup config: removes redundant external arrays (not needed with
bundle: false)

## Description

## Documentation

Does this require changes to the WorkOS Docs? E.g. the [API
Reference](https://workos.com/docs/reference) or code snippets need
updates.

```
[ ] Yes
```

If yes, link a related docs PR and add a docs maintainer as a reviewer.
Their approval is required.

Author: nicknisi

package-lock.json

@@ -9,7 +9,7 @@
     "workos"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.15.0"
   },
   "type": "module",
   "main": "./lib/cjs/index.cjs",

package.json

@@ -1,4 +1,3 @@
-import { createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
 import { OauthException } from '../common/exceptions/oauth.exception';
 import {
   AccessToken,
@@ -12,14 +11,14 @@ import {
 } from './interfaces';
 import { UserManagement } from './user-management';
 import { unsealData } from 'iron-session';
+import { getJose } from '../utils/jose';
 
 type RefreshOptions = {
   cookiePassword?: string;
   organizationId?: string;
 };
 
 export class CookieSession {
-  private jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
   private userManagement: UserManagement;
   private cookiePassword: string;
   private sessionData: string;
@@ -36,8 +35,6 @@ export class CookieSession {
     this.userManagement = userManagement;
     this.cookiePassword = cookiePassword;
     this.sessionData = sessionData;
-
-    this.jwks = this.userManagement.jwks;
   }
 
   /**
@@ -86,6 +83,8 @@ export class CookieSession {
       };
     }
 
+    const { decodeJwt } = await getJose();
+
     const {
       sid: sessionId,
       org_id: organizationId,
@@ -120,6 +119,7 @@ export class CookieSession {
    * @returns An object indicating whether the refresh was successful or not. If successful, it will include the new sealed session data.
    */
   async refresh(options: RefreshOptions = {}): Promise<RefreshSessionResponse> {
+    const { decodeJwt } = await getJose();
     const session = await unsealData<SessionCookieData>(this.sessionData, {
       password: this.cookiePassword,
     });
@@ -224,14 +224,16 @@ export class CookieSession {
   }
 
   private async isValidJwt(accessToken: string): Promise<boolean> {
-    if (!this.jwks) {
+    const { jwtVerify } = await getJose();
+    const jwks = await this.userManagement.getJWKS();
+    if (!jwks) {
       throw new Error(
         'Missing client ID. Did you provide it when initializing WorkOS?',
       );
     }
 
     try {
-      await jwtVerify(accessToken, this.jwks);
+      await jwtVerify(accessToken, jwks);
       return true;
     } catch (e) {
       return false;

src/user-management/session.ts

@@ -1,5 +1,4 @@
 import { sealData, unsealData } from 'iron-session';
-import { createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
 import * as clientUserManagement from '../client/user-management';
 import { PaginationOptions } from '../common/interfaces/pagination-options.interface';
 import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';
@@ -152,9 +151,12 @@ import { deserializeOrganizationMembership } from './serializers/organization-me
 import { serializeSendInvitationOptions } from './serializers/send-invitation-options.serializer';
 import { serializeUpdateOrganizationMembershipOptions } from './serializers/update-organization-membership-options.serializer';
 import { CookieSession } from './session';
+import { getJose } from '../utils/jose';
 
 export class UserManagement {
-  private _jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
+  private _jwks:
+    | ReturnType<typeof import('jose').createRemoteJWKSet>
+    | undefined;
   public clientId: string | undefined;
 
   constructor(private readonly workos: WorkOS) {
@@ -163,7 +165,10 @@ export class UserManagement {
     this.clientId = clientId;
   }
 
-  get jwks(): ReturnType<typeof createRemoteJWKSet> | undefined {
+  async getJWKS(): Promise<
+    ReturnType<typeof import('jose').createRemoteJWKSet> | undefined
+  > {
+    const { createRemoteJWKSet } = await getJose();
     if (!this.clientId) {
       return;
     }
@@ -421,10 +426,14 @@ export class UserManagement {
       throw new Error('Cookie password is required');
     }
 
-    if (!this.jwks) {
+    const jwks = await this.getJWKS();
+
+    if (!jwks) {
       throw new Error('Must provide clientId to initialize JWKS');
     }
 
+    const { decodeJwt } = await getJose();
+
     if (!sessionData) {
       return {
         authenticated: false,
@@ -477,12 +486,14 @@ export class UserManagement {
   }
 
   private async isValidJwt(accessToken: string): Promise<boolean> {
-    if (!this.jwks) {
+    const jwks = await this.getJWKS();
+    const { jwtVerify } = await getJose();
+    if (!jwks) {
       throw new Error('Must provide clientId to initialize JWKS');
     }
 
     try {
-      await jwtVerify(accessToken, this.jwks);
+      await jwtVerify(accessToken, jwks);
       return true;
     } catch (e) {
       return false;
@@ -520,6 +531,8 @@ export class UserManagement {
       throw new Error('Cookie password is required');
     }
 
+    const { decodeJwt } = await getJose();
+
     const { org_id: organizationIdFromAccessToken } = decodeJwt<AccessToken>(
       authenticationResponse.accessToken,
     );

src/user-management/user-management.ts

@@ -0,0 +1,17 @@
+let _josePromise: Promise<typeof import('jose')> | undefined;
+
+/**
+ * Dynamically imports the jose library using import() to support Node.js 20.0-20.18.
+ *
+ * The jose library is ESM-only and cannot be loaded via require() in Node.js versions
+ * before 20.19.0. This wrapper uses dynamic import() which works in both ESM and CJS
+ * across all Node.js 20+ versions.
+ *
+ * This workaround can be removed when Node.js 20 reaches end-of-life (April 2026),
+ * at which point we can bump to Node.js 22+ and use direct imports.
+ *
+ * @returns Promise that resolves to the jose module
+ */
+export function getJose() {
+  return (_josePromise ??= import('jose'));
+}

src/utils/jose.ts

@@ -18,24 +18,21 @@ export default defineConfig([
     target: 'es2022',
     sourcemap: true,
     clean: true,
-    dts: { 
+    dts: {
       resolve: true,
       compilerOptions: {
         lib: ['dom', 'es2022'],
         types: ['node'],
       },
     },
     bundle: false,
-    external: ['iron-session', 'jose', 'leb', 'pluralize'],
     outExtension() {
       return { js: '.js' };
     },
     esbuildOptions(options) {
       options.keepNames = true;
     },
-    esbuildPlugins: [
-      fixImportsPlugin()
-    ]
+    esbuildPlugins: [fixImportsPlugin()],
   },
   // CJS build
   {
@@ -53,23 +50,20 @@ export default defineConfig([
     target: 'es2022',
     sourcemap: true,
     clean: false, // Don't clean, keep ESM files
-    dts: { 
+    dts: {
       resolve: true,
       compilerOptions: {
         lib: ['dom', 'es2022'],
         types: ['node'],
       },
     },
     bundle: false,
-    external: ['iron-session', 'jose', 'leb', 'pluralize'],
     outExtension() {
       return { js: '.cjs', dts: '.d.cts' };
     },
     esbuildOptions(options) {
       options.keepNames = true;
     },
-    esbuildPlugins: [
-      fixImportsPlugin()
-    ]
-  }
-]);
+    esbuildPlugins: [fixImportsPlugin()],
+  },
+]);