feat: allow configuring cookie name and samesite attribute (#1872)

Author: guabu

src/server/client.ts

@@ -16,10 +16,11 @@ import { RequestCookies, ResponseCookies } from "./cookies"
 import {
   AbstractSessionStore,
   SessionConfiguration,
+  SessionCookieOptions,
 } from "./session/abstract-session-store"
 import { StatefulSessionStore } from "./session/stateful-session-store"
 import { StatelessSessionStore } from "./session/stateless-session-store"
-import { TransactionStore } from "./transaction-store"
+import { TransactionCookieOptions, TransactionStore } from "./transaction-store"
 
 interface Auth0ClientOptions {
   // authorization server configuration
@@ -88,6 +89,12 @@ interface Auth0ClientOptions {
    */
   session?: SessionConfiguration
 
+  // transaction cookie configuration
+  /**
+   * Configure the transaction cookie used to store the state of the authentication transaction.
+   */
+  transactionCookie?: TransactionCookieOptions
+
   // hooks
   /**
    * A method to manipulate the session before persisting it.
@@ -162,33 +169,43 @@ export class Auth0Client {
       options.clientAssertionSigningAlg ||
       process.env.AUTH0_CLIENT_ASSERTION_SIGNING_ALG
 
-    const cookieOptions = {
-      secure: false,
+    const sessionCookieOptions: SessionCookieOptions = {
+      name: options.session?.cookie?.name ?? "__session",
+      secure: options.session?.cookie?.secure ?? false,
+      sameSite: options.session?.cookie?.sameSite ?? "lax",
     }
+
+    const transactionCookieOptions: TransactionCookieOptions = {
+      prefix: options.transactionCookie?.prefix ?? "__txn_",
+      secure: options.transactionCookie?.secure ?? false,
+      sameSite: options.transactionCookie?.sameSite ?? "lax",
+    }
+
     if (appBaseUrl) {
       const { protocol } = new URL(appBaseUrl)
       if (protocol === "https:") {
-        cookieOptions.secure = true
+        sessionCookieOptions.secure = true
+        transactionCookieOptions.secure = true
       }
     }
 
     this.transactionStore = new TransactionStore({
       ...options.session,
       secret,
-      cookieOptions,
+      cookieOptions: transactionCookieOptions,
     })
 
     this.sessionStore = options.sessionStore
       ? new StatefulSessionStore({
           ...options.session,
           secret,
           store: options.sessionStore,
-          cookieOptions,
+          cookieOptions: sessionCookieOptions,
         })
       : new StatelessSessionStore({
           ...options.session,
           secret,
-          cookieOptions,
+          cookieOptions: sessionCookieOptions,
         })
 
     this.authClient = new AuthClient({

src/server/cookies.ts

@@ -40,7 +40,7 @@ export async function decrypt<T>(cookieValue: string, secret: string) {
 
 export interface CookieOptions {
   httpOnly: boolean
-  sameSite: "lax" | "strict"
+  sameSite: "lax" | "strict" | "none"
   secure: boolean
   path: string
   maxAge?: number

src/server/session/abstract-session-store.ts

@@ -6,6 +6,27 @@ import {
   ResponseCookies,
 } from "../cookies"
 
+export interface SessionCookieOptions {
+  /**
+   * The name of the session cookie.
+   *
+   * Default: `__session`.
+   */
+  name?: string
+  /**
+   * The sameSite attribute of the session cookie.
+   *
+   * Default: `lax`.
+   */
+  sameSite?: "strict" | "lax" | "none"
+  /**
+   * The secure attribute of the session cookie.
+   *
+   * Default: depends on the protocol of the application's base URL. If the protocol is `https`, then `true`, otherwise `false`.
+   */
+  secure?: boolean
+}
+
 export interface SessionConfiguration {
   /**
    * A boolean indicating whether rolling sessions should be used or not.
@@ -32,18 +53,25 @@ export interface SessionConfiguration {
    * Default: 1 day.
    */
   inactivityDuration?: number
+
+  /**
+   * The options for the session cookie.
+   */
+  cookie?: SessionCookieOptions
 }
 
 interface SessionStoreOptions extends SessionConfiguration {
   secret: string
   store?: SessionDataStore
 
-  cookieOptions?: Partial<Pick<CookieOptions, "secure">>
+  cookieOptions?: SessionCookieOptions
 }
 
+const SESSION_COOKIE_NAME = "__session"
+
 export abstract class AbstractSessionStore {
   public secret: string
-  public SESSION_COOKIE_NAME = "__session"
+  public sessionCookieName: string
 
   private rolling: boolean
   private absoluteDuration: number
@@ -70,9 +98,10 @@ export abstract class AbstractSessionStore {
     this.inactivityDuration = inactivityDuration
     this.store = store
 
+    this.sessionCookieName = cookieOptions?.name ?? SESSION_COOKIE_NAME
     this.cookieConfig = {
       httpOnly: true,
-      sameSite: "lax",
+      sameSite: cookieOptions?.sameSite ?? "lax",
       secure: cookieOptions?.secure ?? false,
       path: "/",
     }

src/server/session/stateful-session-store.test.ts

@@ -378,6 +378,106 @@ describe("Stateful Session Store", async () => {
         expect(cookie?.maxAge).toEqual(1800)
         expect(cookie?.secure).toEqual(true)
       })
+
+      it("should apply the sameSite attribute to the cookie", async () => {
+        const currentTime = Date.now()
+        const createdAt = Math.floor(currentTime / 1000)
+        const secret = await generateSecret(32)
+        const session: SessionData = {
+          user: { sub: "user_123" },
+          tokenSet: {
+            accessToken: "at_123",
+            refreshToken: "rt_123",
+            expiresAt: 123456,
+          },
+          internal: {
+            sid: "auth0-sid",
+            createdAt,
+          },
+        }
+        const store = {
+          get: vi.fn().mockResolvedValue(session),
+          set: vi.fn(),
+          delete: vi.fn(),
+        }
+
+        const requestCookies = new RequestCookies(new Headers())
+        const responseCookies = new ResponseCookies(new Headers())
+
+        const sessionStore = new StatefulSessionStore({
+          secret,
+          store,
+          rolling: true,
+          absoluteDuration: 3600,
+          inactivityDuration: 1800,
+
+          cookieOptions: {
+            sameSite: "strict",
+          },
+        })
+        await sessionStore.set(requestCookies, responseCookies, session)
+
+        const cookie = responseCookies.get("__session")
+        const cookieValue = await decrypt(cookie!.value, secret)
+
+        expect(cookie).toBeDefined()
+        expect(cookieValue).toHaveProperty("id")
+        expect(cookie?.path).toEqual("/")
+        expect(cookie?.httpOnly).toEqual(true)
+        expect(cookie?.sameSite).toEqual("strict")
+        expect(cookie?.maxAge).toEqual(1800)
+        expect(cookie?.secure).toEqual(false)
+      })
+
+      it("should apply the cookie name", async () => {
+        const currentTime = Date.now()
+        const createdAt = Math.floor(currentTime / 1000)
+        const secret = await generateSecret(32)
+        const session: SessionData = {
+          user: { sub: "user_123" },
+          tokenSet: {
+            accessToken: "at_123",
+            refreshToken: "rt_123",
+            expiresAt: 123456,
+          },
+          internal: {
+            sid: "auth0-sid",
+            createdAt,
+          },
+        }
+        const store = {
+          get: vi.fn().mockResolvedValue(session),
+          set: vi.fn(),
+          delete: vi.fn(),
+        }
+
+        const requestCookies = new RequestCookies(new Headers())
+        const responseCookies = new ResponseCookies(new Headers())
+
+        const sessionStore = new StatefulSessionStore({
+          secret,
+          store,
+          rolling: true,
+          absoluteDuration: 3600,
+          inactivityDuration: 1800,
+
+          cookieOptions: {
+            name: "my-session",
+          },
+        })
+        await sessionStore.set(requestCookies, responseCookies, session)
+
+        const cookie = responseCookies.get("my-session")
+        const cookieValue = await decrypt(cookie!.value, secret)
+
+        expect(cookie).toBeDefined()
+        expect(cookieValue).toHaveProperty("id")
+        expect(cookie?.path).toEqual("/")
+        expect(cookie?.httpOnly).toEqual(true)
+        expect(cookie?.sameSite).toEqual("lax")
+        expect(cookie?.maxAge).toEqual(1800)
+        expect(cookie?.secure).toEqual(false)
+      })
     })
   })
 

src/server/session/stateful-session-store.ts

@@ -1,6 +1,9 @@
 import { SessionData, SessionDataStore } from "../../types"
 import * as cookies from "../cookies"
-import { AbstractSessionStore } from "./abstract-session-store"
+import {
+  AbstractSessionStore,
+  SessionCookieOptions,
+} from "./abstract-session-store"
 
 // the value of the stateful session cookie containing a unique session ID to identify
 // the current session
@@ -17,7 +20,7 @@ interface StatefulSessionStoreOptions {
 
   store: SessionDataStore
 
-  cookieOptions?: Partial<Pick<cookies.CookieOptions, "secure">>
+  cookieOptions?: SessionCookieOptions
 }
 
 const generateId = () => {
@@ -51,7 +54,7 @@ export class StatefulSessionStore extends AbstractSessionStore {
   }
 
   async get(reqCookies: cookies.RequestCookies) {
-    const cookieValue = reqCookies.get(this.SESSION_COOKIE_NAME)?.value
+    const cookieValue = reqCookies.get(this.sessionCookieName)?.value
 
     if (!cookieValue) {
       return null
@@ -73,7 +76,7 @@ export class StatefulSessionStore extends AbstractSessionStore {
   ) {
     // check if a session already exists. If so, maintain the existing session ID
     let sessionId = null
-    const cookieValue = reqCookies.get(this.SESSION_COOKIE_NAME)?.value
+    const cookieValue = reqCookies.get(this.sessionCookieName)?.value
     if (cookieValue) {
       const sessionCookie = await cookies.decrypt<SessionCookieValue>(
         cookieValue,
@@ -101,22 +104,22 @@ export class StatefulSessionStore extends AbstractSessionStore {
     )
     const maxAge = this.calculateMaxAge(session.internal.createdAt)
 
-    resCookies.set(this.SESSION_COOKIE_NAME, jwe.toString(), {
+    resCookies.set(this.sessionCookieName, jwe.toString(), {
       ...this.cookieConfig,
       maxAge,
     })
     await this.store.set(sessionId, session)
 
     // to enable read-after-write in the same request for middleware
-    reqCookies.set(this.SESSION_COOKIE_NAME, jwe.toString())
+    reqCookies.set(this.sessionCookieName, jwe.toString())
   }
 
   async delete(
     reqCookies: cookies.RequestCookies,
     resCookies: cookies.ResponseCookies
   ) {
-    const cookieValue = reqCookies.get(this.SESSION_COOKIE_NAME)?.value
-    await resCookies.delete(this.SESSION_COOKIE_NAME)
+    const cookieValue = reqCookies.get(this.sessionCookieName)?.value
+    await resCookies.delete(this.sessionCookieName)
 
     if (!cookieValue) {
       return