[v8] Replace iron-session with iron-webcrypto v2 (#1416)

## Summary
- Replaces `iron-session` dependency with direct `iron-webcrypto` v2.0.0
- Creates lightweight `seal.ts` wrapper providing iron-session
compatible API
- Reduces dependency footprint while maintaining backwards compatibility

## Changes
- Add `src/common/crypto/seal.ts` with `sealData` and `unsealData`
functions
- Update `package.json` to use `iron-webcrypto` ^2.0.0
- Update `jest.config.cjs` to transform ESM-only `uint8array-extras`
dependency
- Update imports in session and user-management modules

Author: nicknisi

jest.config.cjs

@@ -13,6 +13,6 @@ module.exports = {
     '^.+\\.m?js$': '<rootDir>/jest-transform-esm.cjs',
   },
   transformIgnorePatterns: [
-    'node_modules/(?!(iron-session|uncrypto|cookie-es|@noble|@scure|jose)/)',
+    'node_modules/(?!(iron-webcrypto|uint8array-extras|@noble|@scure|jose)/)',
   ],
 };

package-lock.json

@@ -41,10 +41,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "iron-session": "^8.0.4",
+    "iron-webcrypto": "^2.0.0",
     "jose": "~6.1.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "@babel/plugin-transform-modules-commonjs": "^7.26.3",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
@@ -71,8 +72,7 @@
     "tsdown": "^0.17.0",
     "tsx": "^4.20.6",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.46.0",
-    "@arethetypeswrong/cli": "^0.18.2"
+    "typescript-eslint": "^8.46.0"
   },
   "exports": {
     ".": {

package.json

@@ -0,0 +1,117 @@
+import { sealData, unsealData } from './seal';
+
+describe('seal', () => {
+  const password = 'test-password-at-least-32-characters-long';
+
+  describe('sealData', () => {
+    it('seals data and appends version delimiter', async () => {
+      const data = { foo: 'bar' };
+      const sealed = await sealData(data, { password });
+
+      expect(sealed).toContain('~2');
+      expect(sealed.startsWith('Fe26.2*')).toBe(true);
+    });
+  });
+
+  describe('unsealData', () => {
+    it('round-trips seal/unseal', async () => {
+      const data = { userId: '123', email: '[email protected]' };
+      const sealed = await sealData(data, { password });
+      const unsealed = await unsealData<typeof data>(sealed, { password });
+
+      expect(unsealed).toEqual(data);
+    });
+
+    it('round-trips complex nested data', async () => {
+      const data = {
+        user: { id: '123', name: 'Test' },
+        roles: ['admin', 'user'],
+        metadata: { nested: { deep: true } },
+      };
+      const sealed = await sealData(data, { password });
+      const unsealed = await unsealData<typeof data>(sealed, { password });
+
+      expect(unsealed).toEqual(data);
+    });
+
+    it('returns empty object for bad password', async () => {
+      const data = { foo: 'bar' };
+      const sealed = await sealData(data, { password });
+      const unsealed = await unsealData(sealed, {
+        password: 'wrong-password-at-least-32-characters',
+      });
+
+      expect(unsealed).toEqual({});
+    });
+
+    it('returns empty object for tampered seal', async () => {
+      const data = { foo: 'bar' };
+      const sealed = await sealData(data, { password });
+      // Tamper with the sealed data
+      const tampered = sealed.replace('Fe26.2', 'Fe26.2tampered');
+      const unsealed = await unsealData(tampered, { password });
+
+      expect(unsealed).toEqual({});
+    });
+
+    it('handles legacy tokens with persistent field (version 1)', async () => {
+      // Manually construct a v1-style token that would have persistent wrapper
+      const data = { persistent: { userId: '123' } };
+      const sealed = await sealData(data, { password });
+      // Replace ~2 with ~1 to simulate v1 token
+      const v1Sealed = sealed.replace('~2', '~1');
+
+      const unsealed = await unsealData<{ userId: string }>(v1Sealed, {
+        password,
+      });
+      expect(unsealed).toEqual({ userId: '123' });
+    });
+
+    it('handles tokens without version delimiter', async () => {
+      const data = { foo: 'bar' };
+      const sealed = await sealData(data, { password });
+      // Remove version delimiter to simulate pre-versioned token
+      const noVersion = sealed.split('~')[0];
+
+      const unsealed = await unsealData<typeof data>(noVersion, { password });
+      expect(unsealed).toEqual(data);
+    });
+  });
+
+  describe('iron-session compatibility', () => {
+    // This test verifies that tokens sealed with this implementation
+    // produce the same format as iron-session (Fe26.2 prefix with ~2 suffix)
+    it('produces iron-session compatible format', async () => {
+      const data = { userId: '123' };
+      const sealed = await sealData(data, { password });
+
+      // Verify format: Fe26.2*...*~2
+      const parts = sealed.split('~');
+      expect(parts).toHaveLength(2);
+      expect(parts[1]).toBe('2');
+
+      const ironPart = parts[0];
+      expect(ironPart.startsWith('Fe26.2*')).toBe(true);
+
+      // Iron format has 8 asterisk-delimited components
+      const components = ironPart.split('*');
+      expect(components).toHaveLength(8);
+      expect(components[0]).toBe('Fe26.2');
+    });
+
+    // Verify that tokens can be round-tripped and maintain the expected format
+    // This ensures compatibility with iron-session which uses the same Fe26.2 format
+    it('can unseal self-generated tokens (simulates iron-session compatibility)', async () => {
+      const data = { userId: '123', email: '[email protected]' };
+      const sealed = await sealData(data, { password });
+
+      // Verify the format matches iron-session's expected output
+      expect(sealed).toMatch(
+        /^Fe26\.2\*1\*[^*]+\*[^*]+\*[^*]+\*\*[^*]+\*[^*]+~2$/,
+      );
+
+      const unsealed = await unsealData<typeof data>(sealed, { password });
+      expect(unsealed).toEqual(data);
+    });
+  });
+});

src/common/crypto/seal.spec.ts

@@ -0,0 +1,82 @@
+import {
+  seal as ironSeal,
+  unseal as ironUnseal,
+  defaults,
+} from 'iron-webcrypto';
+
+const VERSION_DELIMITER = '~';
+const CURRENT_MAJOR_VERSION = 2;
+
+interface SealOptions {
+  password: string;
+}
+
+interface UnsealOptions {
+  password: string;
+}
+
+function parseSeal(seal: string): {
+  sealWithoutVersion: string;
+  tokenVersion: number | null;
+} {
+  const [sealWithoutVersion = '', tokenVersionAsString] =
+    seal.split(VERSION_DELIMITER);
+  const tokenVersion =
+    tokenVersionAsString == null ? null : parseInt(tokenVersionAsString, 10);
+  return { sealWithoutVersion, tokenVersion };
+}
+
+export async function sealData(
+  data: unknown,
+  { password }: SealOptions,
+): Promise<string> {
+  const passwordObj = {
+    id: '1',
+    secret: password,
+  };
+
+  const seal = await ironSeal(data, passwordObj, {
+    ...defaults,
+    ttl: 0,
+    encode: JSON.stringify,
+  });
+
+  return `${seal}${VERSION_DELIMITER}${CURRENT_MAJOR_VERSION}`;
+}
+
+export async function unsealData<T = unknown>(
+  encryptedData: string,
+  { password }: UnsealOptions,
+): Promise<T> {
+  const { sealWithoutVersion, tokenVersion } = parseSeal(encryptedData);
+
+  const passwordMap = { 1: password };
+
+  let data: unknown;
+  try {
+    data =
+      (await ironUnseal(sealWithoutVersion, passwordMap, {
+        ...defaults,
+        ttl: 0,
+      })) ?? {};
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      /^(Expired seal|Bad hmac value|Cannot find password|Incorrect number of sealed components|Wrong mac prefix)/.test(
+        error.message,
+      )
+    ) {
+      return {} as T;
+    }
+    throw error;
+  }
+
+  if (tokenVersion === 2) {
+    return data as T;
+  } else if (tokenVersion !== null) {
+    const record = data as Record<string, unknown>;
+    return (record.persistent ?? data) as T;
+  }
+
+  return data as T;
+}

src/common/crypto/seal.ts

@@ -1,7 +1,7 @@
 import { WorkOS } from '../workos';
 import { CookieSession } from './session';
 import * as jose from 'jose';
-import { sealData } from 'iron-session';
+import { sealData } from '../common/crypto/seal';
 import userFixture from './fixtures/user.json';
 import fetch from 'jest-fetch-mock';
 import { fetchOnce } from '../common/utils/test-utils';

src/user-management/session.spec.ts

@@ -10,7 +10,7 @@ import {
   SessionCookieData,
 } from './interfaces';
 import { UserManagement } from './user-management';
-import { unsealData } from 'iron-session';
+import { unsealData } from '../common/crypto/seal';
 import { getJose } from '../utils/jose';
 
 type RefreshOptions = {

src/user-management/session.ts

@@ -21,7 +21,7 @@ import passwordResetFixture from './fixtures/password_reset.json';
 import userFixture from './fixtures/user.json';
 import identityFixture from './fixtures/identity.json';
 import * as jose from 'jose';
-import { sealData } from 'iron-session';
+import { sealData } from '../common/crypto/seal';
 
 jest.mock('jose', () => ({
   ...jest.requireActual('jose'),

src/user-management/user-management.spec.ts

@@ -1,4 +1,4 @@
-import { sealData, unsealData } from 'iron-session';
+import { sealData, unsealData } from '../common/crypto/seal';
 import * as clientUserManagement from '../client/user-management';
 import { PaginationOptions } from '../common/interfaces/pagination-options.interface';
 import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';