feat(next): external storage

.changeset/wise-colts-guess.md

@@ -0,0 +1,45 @@
+---
+"@logto/next": minor
+---
+
+support custom external session storage
+
+Add `sessionWrapper` to the config, you can implement your own session wrapper to support custom external session storage.
+
+Take a look at the example below:
+
+```ts
+import { MemorySessionWrapper } from './storage';
+
+export const config = {
+  // ...
+  sessionWrapper: new MemorySessionWrapper(),
+};
+```
+
+```ts
+import { randomUUID } from 'node:crypto';
+
+import { type SessionWrapper, type SessionData } from '@logto/next';
+
+export class MemorySessionWrapper implements SessionWrapper {
+  private readonly storage = new Map<string, unknown>();
+
+  async wrap(data: unknown, _key: string): Promise<string> {
+    const sessionId = randomUUID();
+    this.storage.set(sessionId, data);
+    return sessionId;
+  }
+
+  async unwrap(value: string, _key: string): Promise<SessionData> {
+    if (!value) {
+      return {};
+    }
+
+    const data = this.storage.get(value);
+    return data ?? {};
+  }
+}
+```
+
+You can implement your own session wrapper to support custom external session storage like Redis, Memcached, etc.

packages/next/edge/index.ts

@@ -113,7 +113,8 @@ export default class LogtoClient extends BaseClient {
     const responseCookies = new ResponseCookies(headers);
 
     this.storage = new CookieStorage({
-      encryptionKey: this.config.cookieSecret,
+      encryptionKey: this.config.cookieSecret ?? '',
+      sessionWrapper: this.config.sessionWrapper,
       cookieKey: `logto_${this.config.appId}`,
       isSecure: this.config.cookieSecure,
       getCookie: (name) => {

packages/next/server-actions/client.ts

@@ -105,7 +105,8 @@ export default class LogtoClient extends BaseClient {
   async createNodeClient({ ignoreCookieChange }: { ignoreCookieChange?: boolean } = {}) {
     const { cookies } = await import('next/headers');
     this.storage = new CookieStorage({
-      encryptionKey: this.config.cookieSecret,
+      encryptionKey: this.config.cookieSecret ?? '',
+      sessionWrapper: this.config.sessionWrapper,
       cookieKey: `logto_${this.config.appId}`,
       isSecure: this.config.cookieSecure,
       getCookie: async (...args) => {

packages/next/src/index.test.ts

@@ -15,7 +15,6 @@ const configs: LogtoNextConfig = {
   cookieSecure: process.env.NODE_ENV === 'production',
 };
 
-const save = vi.fn();
 const signIn = vi.fn();
 const handleSignInCallback = vi.fn();
 const getIdTokenClaims = vi.fn(() => ({

packages/next/src/index.ts

@@ -44,13 +44,19 @@ export type {
   InteractionMode,
   LogtoErrorCode,
   UserInfoResponse,
+  SessionWrapper,
+  SessionData,
 } from '@logto/node';
 
 export default class LogtoClient extends LogtoNextBaseClient {
   constructor(config: LogtoNextConfig) {
     super(config, {
       NodeClient,
     });
+
+    if (!config.sessionWrapper && !config.cookieSecret) {
+      throw new Error('cookieSecret is required when using default session wrapper');
+    }
   }
 
   handleSignIn: (
@@ -204,7 +210,9 @@ export default class LogtoClient extends LogtoNextBaseClient {
     response: ServerResponse
   ): Promise<NodeClient> {
     this.storage = new CookieStorage({
-      encryptionKey: this.config.cookieSecret,
+      // The type checking is done in the constructor, encryptionKey is required when using default session wrapper
+      encryptionKey: this.config.cookieSecret ?? '',
+      sessionWrapper: this.config.sessionWrapper,
       cookieKey: `logto_${this.config.appId}`,
       isSecure: this.config.cookieSecure,
       getCookie: (name) => {

packages/next/src/types.ts

@@ -1,11 +1,18 @@
-import type { LogtoConfig } from '@logto/node';
+import type { LogtoConfig, SessionWrapper } from '@logto/node';
 import type NodeClient from '@logto/node';
 import { type NextApiRequest, type NextApiResponse } from 'next';
 
 export type LogtoNextConfig = LogtoConfig & {
-  cookieSecret: string;
   cookieSecure: boolean;
   baseUrl: string;
+  /**
+   * Can be provided to use custom session wrapper,
+   * for example, to use external storage solutions,
+   * you can save the session data in external storage and return a key in the sessionWrapper.wrap method,
+   * then use the key to get the session data from external storage in the sessionWrapper.unwrap method.
+   */
+  sessionWrapper?: SessionWrapper;
+  cookieSecret?: string;
 };
 
 export type Adapters = {

packages/node/src/utils/cookie-storage.test.ts

@@ -91,6 +91,29 @@ describe('CookieStorage', () => {
     const cookie = await storage.config.getCookie('foo');
     expect(await unwrapSession(cookie ?? '', encryptionKey)).toEqual({});
   });
+
+  it('should support custom sessionWrapper', async () => {
+    // Use JSON.stringify/parse to simulate the sessionWrapper
+    const mockSessionWrapper = {
+      wrap: vi.fn(async (data) => JSON.stringify(data)),
+      unwrap: vi.fn(async (data: string) => (data ? JSON.parse(data) : {})),
+    };
+
+    const storage = new TestCookieStorage({
+      ...createCookieConfig(encryptionKey),
+      sessionWrapper: mockSessionWrapper,
+    });
+
+    await storage.init();
+    await storage.setItem(PersistKey.AccessToken, 'test-token');
+
+    expect(mockSessionWrapper.wrap).toHaveBeenCalled();
+    expect(mockSessionWrapper.unwrap).toHaveBeenCalled();
+    expect(storage.data).toEqual({ [PersistKey.AccessToken]: 'test-token' });
+
+    const cookie = await storage.config.getCookie('logtoCookies');
+    expect(cookie).toBe(JSON.stringify({ [PersistKey.AccessToken]: 'test-token' }));
+  });
 });
 
 describe('CookieStorage concurrency', () => {

packages/node/src/utils/cookie-storage.ts

@@ -7,12 +7,8 @@ import { wrapSession, unwrapSession, type SessionData } from './session.js';
 // eslint-disable-next-line @typescript-eslint/ban-types
 type Nullable<T> = T | null;
 
-export type CookieConfig = {
-  /** The encryption key to encrypt the session data. It should be a random string. */
-  encryptionKey: string;
-  /** The name of the cookie key. Default to `logtoCookies`. */
+export type CookieConfigBase = {
   cookieKey?: string;
-  /** Set to true in https */
   isSecure?: boolean;
   getCookie: (name: string) => Promise<string | undefined> | string | undefined;
   setCookie: (
@@ -22,6 +18,26 @@ export type CookieConfig = {
   ) => Promise<void> | void;
 };
 
+export type SessionWrapper = {
+  wrap: (data: SessionData, key: string) => Promise<string>;
+  unwrap: (value: string, key: string) => Promise<SessionData>;
+};
+
+export type CookieConfig = CookieConfigBase &
+  (
+    | {
+        /** Required when using default session wrapper */
+        encryptionKey: string;
+        sessionWrapper?: never;
+      }
+    | {
+        /** Optional when custom sessionWrapper is provided */
+        encryptionKey?: string;
+        /** Custom session wrapper can be used to implement external storage solutions */
+        sessionWrapper: SessionWrapper;
+      }
+  );
+
 /**
  * A storage that persists data in cookies with encryption.
  */
@@ -47,15 +63,29 @@ export class CookieStorage implements Storage<PersistKey> {
   protected sessionData: SessionData = {};
   protected saveQueue = new PromiseQueue();
 
+  /**
+   * Handles the wrapping and unwrapping of session data.
+   * Can be provided via config or defaults to using wrapSession/unwrapSession functions.
+   * Users can implement custom storage solutions by providing their own sessionWrapper.
+   */
+  protected sessionWrapper: SessionWrapper;
+
   constructor(public config: CookieConfig) {
-    if (!config.encryptionKey) {
-      throw new TypeError('The `encryptionKey` string is required for `CookieStorage`');
+    if (!config.sessionWrapper && !config.encryptionKey) {
+      throw new TypeError(
+        'Either `sessionWrapper` or `encryptionKey` must be provided for `CookieStorage`'
+      );
     }
+
+    this.sessionWrapper = config.sessionWrapper ?? {
+      wrap: wrapSession,
+      unwrap: unwrapSession,
+    };
   }
 
   async init() {
-    const { encryptionKey } = this.config;
-    this.sessionData = await unwrapSession(
+    const { encryptionKey = '' } = this.config;
+    this.sessionData = await this.sessionWrapper.unwrap(
       (await this.config.getCookie(this.cookieKey)) ?? '',
       encryptionKey
     );
@@ -86,8 +116,8 @@ export class CookieStorage implements Storage<PersistKey> {
   }
 
   protected async write(data = this.sessionData) {
-    const { encryptionKey } = this.config;
-    const value = await wrapSession(data, encryptionKey);
+    const { encryptionKey = '' } = this.config;
+    const value = await this.sessionWrapper.wrap(data, encryptionKey);
     await this.config.setCookie(this.cookieKey, value, this.cookieOptions);
   }
 }