replace iron-session with iron-webcrypto

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|@noble|@scure|jose)/)',
   ],
 };

package-lock.json

@@ -41,7 +41,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "iron-session": "^8.0.4",
+    "iron-webcrypto": "^1.2.1",
     "jose": "~6.1.0"
   },
   "devDependencies": {

package.json

@@ -0,0 +1,116 @@
+import {
+  seal as ironSeal,
+  unseal as ironUnseal,
+  defaults,
+} from 'iron-webcrypto';
+
+// Extract the precise Crypto type that iron-webcrypto expects
+type IronCrypto = Parameters<typeof ironSeal>[0];
+
+// Cast globalThis.crypto to iron-webcrypto's expected type
+// Runtime-safe: DOM Crypto is fully compatible with iron-webcrypto's _Crypto
+const ironCrypto: IronCrypto = globalThis.crypto as unknown as IronCrypto;
+
+const VERSION_DELIMITER = '~';
+const CURRENT_MAJOR_VERSION = 2;
+
+interface SealOptions {
+  password: string;
+  ttl?: number;
+}
+
+interface UnsealOptions {
+  password: string;
+  ttl?: number;
+}
+
+/**
+ * Parse an iron-session seal to extract the version
+ */
+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 };
+}
+
+/**
+ * Seal (encrypt) data in a format compatible with iron-session.
+ *
+ * @param data - The data to seal
+ * @param options - Sealing options
+ * @param options.password - Password for encryption (must be at least 32 characters)
+ * @param options.ttl - Time to live in seconds (default: 0 = no expiration)
+ * @returns The sealed string
+ */
+export async function sealData(
+  data: unknown,
+  { password, ttl = 0 }: SealOptions,
+): Promise<string> {
+  const passwordObj = {
+    id: '1',
+    secret: password,
+  };
+
+  const seal = await ironSeal(ironCrypto, data, passwordObj, {
+    ...defaults,
+    ttl: ttl * 1000, // Convert seconds to milliseconds
+  });
+
+  // Add the version delimiter exactly like iron-session does
+  return `${seal}${VERSION_DELIMITER}${CURRENT_MAJOR_VERSION}`;
+}
+
+/**
+ * Unseal (decrypt) data that was sealed with iron-session or sealData.
+ *
+ * @param encryptedData - The sealed string to decrypt
+ * @param options - Unsealing options
+ * @param options.password - Password for decryption
+ * @param options.ttl - Time to live in seconds (default: 0 = no expiration check)
+ * @returns The unsealed data, or empty object if unsealing fails
+ */
+export async function unsealData<T = unknown>(
+  encryptedData: string,
+  { password, ttl = 0 }: UnsealOptions,
+): Promise<T> {
+  const { sealWithoutVersion, tokenVersion } = parseSeal(encryptedData);
+
+  // Format password as a map like iron-session expects
+  const passwordMap = { 1: password };
+
+  let data: unknown;
+  try {
+    data =
+      (await ironUnseal(ironCrypto, sealWithoutVersion, passwordMap, {
+        ...defaults,
+        ttl: ttl * 1000,
+      })) ?? {};
+  } catch (error) {
+    // Match iron-session's behavior: return empty object for known errors
+    if (
+      error instanceof Error &&
+      /^(Expired seal|Bad hmac value|Cannot find password|Incorrect number of sealed components)/.test(
+        error.message,
+      )
+    ) {
+      return {} as T;
+    }
+    throw error;
+  }
+
+  // Handle token version for backwards compatibility
+  if (tokenVersion === 2) {
+    return data as T;
+  } else if (tokenVersion !== null) {
+    // For older token versions, extract the persistent property
+    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';