@auth0/auth0-server-js 1.0.1 → 1.0.2

package/README.md

@@ -53,7 +53,7 @@ The `AUTH0_REDIRECT_URI` is needed to tell Auth0 what URL to redirect back to af
 
 ### 3. Configuring the Store
 
-The `auth0-server-js` SDK does not come with a built-in store for both transaction and state data, **it's required to provide a persistent solution** that fits your use-case.
+The `auth0-server-js` SDK comes with a built-in store for both transaction and state data, however **it's required to provide it a CookieHandler implementation** that fits your use-case.
 The goal of `auth0-server-js` is to provide a flexible API that allows you to use any storage mechanism you prefer, but is mostly designed to work with cookie and session-based storage kept in mind.
 
 The SDK methods accept an optional `storeOptions` object that can be used to pass additional options to the storage methods, such as Request / Response objects, allowing to control cookies in the storage layer.
@@ -72,7 +72,7 @@ import { FastifyReply, FastifyRequest } from 'fastify';
 import { CookieSerializeOptions } from '@fastify/cookie';
 import { 
   AbstractStateStore,
-  TransactionStore,
+  AbstractTransactionStore,
   ServerClient,
   StateData,
   TransactionData
@@ -83,105 +83,37 @@ export interface StoreOptions {
   reply: FastifyReply;
 }
 
-const auth0 = new ServerClient<StoreOptions>({
-  transactionStore: new StatelessTransactionStore({ secret: options.secret }),
-  stateStore: new StatelessStateStore({ secret: options.secret }),
-});
-
-export class StatelessTransactionStore implements TransactionStore<StoreOptions> {
-  async set(identifier: string, transactionData: TransactionData, removeIfExists?: boolean, options?: StoreOptions): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    // Note that `removeIfExists` is not used in Stateless storage, but it's kept for compatibility with Stateful storage.
-
-    const maxAge = 60 * 60;
-    const cookieOpts: CookieSerializeOptions = { httpOnly: true, sameSite: 'lax', path: '/', maxAge };
-
-    options.reply.setCookie(identifier, JSON.stringify(transactionData), cookieOpts);
-  }
-
-  async get(identifier: string, options?: StoreOptions): Promise<TransactionData | undefined> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    const cookieValue = options.request.cookies[identifier];
-    
-    if (cookieValue) {
-      return JSON.parse(cookieValue) as TransactionData;
-    }
-  }
-
-  async delete(identifier: string, options?: StoreOptions | undefined): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    options?.reply.clearCookie(identifier);
+export class FastifyCookieHandler implements CookieHandler<StoreOptions> {
+  setCookie(
+    name: string,
+    value: string,
+    options?: CookieSerializeOptions,
+    storeOptions?: StoreOptions
+  ): void {
+    // Handle storeOptions being undefined if needed.
+    storeOptions!.reply.setCookie(name, value, options || {});
   }
-}
 
-export class StatelessStateStore extends AbstractStateStore<StoreOptions> {
-  async set(
-    identifier: string,
-    stateData: StateData,
-    removeIfExists?: boolean,
-    options?: StoreOptions | undefined
-  ): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    // Note that `removeIfExists` is not used in Stateless storage, but it's kept for compatibility with Stateful storage.
-
-    const maxAge = ?; // Set the max age of the cookie
-    const cookieOpts: CookieSerializeOptions = {
-      httpOnly: true,
-      sameSite: 'lax',
-      path: '/',
-      secure: 'auto',
-      maxAge,
-    };
-    const expiration = Math.floor(Date.now() / 1000 + maxAge);
-    const encryptedStateData = await this.encrypt(identifier, stateData, expiration);
-
-    options.reply.setCookie(identifier, encryptedStateData, cookieOpts);
+  getCookie(name: string, storeOptions?: StoreOptions): string | undefined {
+    // Handle storeOptions being undefined if needed.
+    return storeOptions!.request.cookies?.[name];
   }
 
-  async get(identifier: string, options?: StoreOptions | undefined): Promise<StateData | undefined> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    const encryptedStateData = options.request.cookies[identifier];
-
-    if (encryptedStateData) {
-      return (await this.decrypt(identifier, encryptedStateData)) as StateData;
-    }
+  getCookies(storeOptions?: StoreOptions): Record<string, string> {
+    // Handle storeOptions being undefined if needed.
+    return storeOptions!.request.cookies as Record<string, string>;
   }
 
-  async delete(identifier: string, options?: StoreOptions | undefined): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    options?.reply.clearCookie(identifier);
-  }
-
-  deleteByLogoutToken(): Promise<void> {
-    throw new Error(
-      'Backchannel logout is not available when using Stateless Storage. Use Stateful Storage instead.'
-    );
+  deleteCookie(name: string, storeOptions?: StoreOptions): void {
+    // Handle storeOptions being undefined if needed.
+    storeOptions!.reply.clearCookie(name);
   }
 }
+
+const auth0 = new ServerClient<StoreOptions>({
+  transactionStore: new CookieTransactionStore({ secret: options.secret }, new FastifyCookieHandler()),
+  stateStore: new StatelessStateStore({ secret: options.secret }, new FastifyCookieHandler()),
+});
 ```
 
 #### Stateful Store
@@ -207,113 +139,41 @@ export interface StoreOptions {
   reply: FastifyReply;
 }
 
-const auth0 = new ServerClient<StoreOptions>({
-  transactionStore: new StatelessTransactionStore({ secret: '<secret>' }),
-  stateStore: new StatefulStateStore({ secret: '<secret>' }),
-});
-
-export class StatefulStateStore extends AbstractSessionStore {
-  async set(
-    identifier: string,
-    stateData: StateData,
-    removeIfExists?: boolean,
-    options?: StoreOptions | undefined
-  ): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    let sessionId = await this.getSessionId(identifier, options);
-
-    // If this is a new session created by a new login we need to remove the old session
-    // from the store and regenerate the session ID to prevent session fixation.
-    if (sessionId && removeIfExists) {
-      // Delete the session from the store by the sessionId.
-      // await yourDeleteSessionLogic(sessionId);
-      sessionId = generateId();
-    }
-
-    if (!sessionId) {
-      sessionId = generateId();
-    }
-
-    const maxAge = ?; // Set the max age of the cookie
-    const cookieOpts: CookieSerializeOptions = {
-      httpOnly: true,
-      sameSite: 'lax',
-      path: '/',
-      secure: 'auto',
-      maxAge,
-    };
-    const expiration = Date.now() / 1000 + maxAge;
-    const encryptedStateData = await this.encrypt<{ id: string }>(
-      identifier,
-      {
-        id: sessionId,
-      },
-      expiration
-    );
-
-    // Save the stateData in the store, identified by the sessionId.
-    // await yourSaveSessionLogic(sessionId, stateData);
-
-    options.reply.setCookie(identifier, encryptedStateData, cookieOpts);
-  }
-
-  async get(identifier: string, options?: StoreOptions | undefined): Promise<StateData | undefined> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    const sessionId = await this.getSessionId(identifier, options);
-
-    if (sessionId) {
-      // Retrieve the stateData from the store, identified by the sessionId.
-      // const stateData = await yourGetSessionLogic(sessionId);
-
-      // If we have a session cookie, but no `stateData`, we should remove the cookie.
-      if (!stateData) {
-        options?.reply.clearCookie(identifier);
-      }
-
-      return stateData;
-    }
+export class FastifyCookieHandler implements CookieHandler<StoreOptions> {
+  setCookie(
+    name: string,
+    value: string,
+    options?: CookieSerializeOptions,
+    storeOptions?: StoreOptions,
+  ): void {
+    // Handle storeOptions being undefined if needed.
+    storeOptions!.reply.setCookie(name, value, options || {});
   }
 
-  async delete(identifier: string, options?: StoreOptions | undefined): Promise<void> {
-    // We can not handle cookies in Fastify when the `StoreOptions` are not provided.
-    if (!options) {
-      throw new Error();
-    }
-
-    const sessionId = await this.getSessionId(identifier, options);
-
-    if (sessionId) {
-      // Delete the session from the store by the sessionId.
-      // await yourDeleteSessionLogic(sessionId);
-    }
-
-    options?.reply.clearCookie(identifier);
+  getCookie(name: string, storeOptions?: StoreOptions): string | undefined {
+    // Handle storeOptions being undefined if needed.
+    return storeOptions!.request.cookies?.[name];
   }
 
-  private async getSessionId(identifier: string, options: StoreOptions) {
-    const cookieValue = options.request.cookies[identifier];
-    if (cookieValue) {
-      const sessionCookie = await this.decrypt<{ id: string }>(identifier, cookieValue);
-      return sessionCookie.id;
-    }
+  getCookies(storeOptions?: StoreOptions): Record<string, string> {
+    // Handle storeOptions being undefined if needed.
+    return storeOptions!.request.cookies as Record<string, string>;
   }
 
-  deleteByLogoutToken(claims: LogoutTokenClaims, options?: StoreOptions | undefined): Promise<void> {
-    // Delete the session from the store by the LogoutTokenClaims (sub and sid)
-    // await yourDeleteSessionByLogoutTokenLogic(sessionId);
+  deleteCookie(name: string, storeOptions?: StoreOptions): void {
+    // Handle storeOptions being undefined if needed.
+    storeOptions!.reply.clearCookie(name);
   }
 }
+
+const auth0 = new ServerClient<StoreOptions>({
+  transactionStore: new CookieTransactionStore({ secret: options.secret }, new FastifyCookieHandler()),
+  stateStore: new StatefulStateStore({ secret: options.secret }, new FastifyCookieHandler()),
+});
+
 ```
 
-Note that `storeOptions` is optional, but required when wanting to interact with the framework to set cookies. Here's how to pass the `storeOptions` to `startInteractiveLogin()` in a Fastify application:
+Note that `storeOptions` is optional in the SDK's methods, but required when wanting to interact with the framework to set cookies. Here's how to pass the `storeOptions` to `startInteractiveLogin()` in a Fastify application:
 
 ```ts
 fastify.get('/auth/login', async (request, reply) => {
@@ -324,7 +184,7 @@ fastify.get('/auth/login', async (request, reply) => {
 });
 ```
 
-Because storage systems in Web Applications are mostly cookie-based, the `storeOptions` object is used to pass the `request` and `reply` objects to the storage methods, allowing to control cookies in the storage layer. It's expected to pass this to every interaction with the SDK.
+Because storage systems in Web Applications are mostly cookie-based, the `storeOptions` object is used to pass the `request` and `reply` (in the case of Fastify, as per the example) objects to the storage methods, allowing to control cookies in the storage layer. It's expected to pass this to every interaction with the SDK.
 
 ### 4. Add login to your Application (interactive)
 

package/dist/index.cjs

@@ -23,11 +23,14 @@ __export(index_exports, {
   AbstractStateStore: () => AbstractStateStore,
   AbstractTransactionStore: () => AbstractTransactionStore,
   BackchannelLogoutError: () => BackchannelLogoutError,
+  CookieTransactionStore: () => CookieTransactionStore,
   MissingRequiredArgumentError: () => MissingRequiredArgumentError,
   MissingSessionError: () => MissingSessionError,
   MissingTransactionError: () => MissingTransactionError,
   ServerClient: () => ServerClient,
-  StartLinkUserError: () => StartLinkUserError
+  StartLinkUserError: () => StartLinkUserError,
+  StatefulStateStore: () => StatefulStateStore,
+  StatelessStateStore: () => StatelessStateStore
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -544,15 +547,198 @@ var AbstractTransactionStore = class extends AbstractStore {
     super(options);
   }
 };
+
+// src/store/cookie-transaction-store.ts
+var CookieTransactionStore = class extends AbstractTransactionStore {
+  #cookieHandler;
+  constructor(options, cookieHandler) {
+    super(options);
+    this.#cookieHandler = cookieHandler;
+  }
+  async set(identifier, transactionData, removeIfExists, options) {
+    const maxAge = 60 * 60;
+    const cookieOpts = { httpOnly: true, sameSite: "lax", path: "/", maxAge };
+    const expiration = Math.floor(Date.now() / 1e3 + maxAge);
+    const encryptedStateData = await this.encrypt(identifier, transactionData, expiration);
+    this.#cookieHandler.setCookie(identifier, encryptedStateData, cookieOpts, options);
+  }
+  async get(identifier, options) {
+    const cookieValue = this.#cookieHandler.getCookie(identifier, options);
+    if (cookieValue) {
+      return await this.decrypt(identifier, cookieValue);
+    }
+  }
+  async delete(identifier, options) {
+    this.#cookieHandler.deleteCookie(identifier, options);
+  }
+};
+
+// src/store/abstract-session-store.ts
+var AbstractSessionStore = class extends AbstractStateStore {
+  #rolling;
+  #absoluteDuration;
+  #inactivityDuration;
+  constructor(options) {
+    super(options);
+    this.#rolling = options.rolling ?? true;
+    this.#absoluteDuration = options.absoluteDuration ?? 60 * 60 * 24 * 3;
+    this.#inactivityDuration = options.inactivityDuration ?? 60 * 60 * 24 * 1;
+  }
+  /**
+   * calculateMaxAge calculates the max age of the session based on createdAt and the rolling and absolute durations.
+   */
+  calculateMaxAge(createdAt) {
+    if (!this.#rolling) {
+      return this.#absoluteDuration;
+    }
+    const now = Date.now() / 1e3 | 0;
+    const expiresAt = Math.min(now + this.#inactivityDuration, createdAt + this.#absoluteDuration);
+    const maxAge = expiresAt - now;
+    return maxAge > 0 ? maxAge : 0;
+  }
+};
+
+// src/store/stateful-state-store.ts
+var generateId = () => {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+};
+var StatefulStateStore = class extends AbstractSessionStore {
+  #store;
+  #cookieOptions;
+  #cookieHandler;
+  constructor(options, cookieHandler) {
+    super(options);
+    this.#store = options.store;
+    this.#cookieOptions = options.cookie;
+    this.#cookieHandler = cookieHandler;
+  }
+  async set(identifier, stateData, removeIfExists, options) {
+    let sessionId = await this.getSessionId(identifier, options);
+    if (sessionId && removeIfExists) {
+      await this.#store.delete(sessionId);
+      sessionId = generateId();
+    }
+    sessionId ??= generateId();
+    const maxAge = this.calculateMaxAge(stateData.internal.createdAt);
+    const cookieOpts = {
+      httpOnly: true,
+      sameSite: this.#cookieOptions?.sameSite ?? "lax",
+      path: "/",
+      secure: this.#cookieOptions?.secure,
+      maxAge
+    };
+    const expiration = Date.now() / 1e3 + maxAge;
+    const encryptedStateData = await this.encrypt(
+      identifier,
+      {
+        id: sessionId
+      },
+      expiration
+    );
+    await this.#store.set(sessionId, stateData);
+    this.#cookieHandler.setCookie(identifier, encryptedStateData, cookieOpts, options);
+  }
+  async get(identifier, options) {
+    const sessionId = await this.getSessionId(identifier, options);
+    if (sessionId) {
+      const stateData = await this.#store.get(sessionId);
+      if (!stateData) {
+        this.#cookieHandler.deleteCookie(identifier, options);
+      }
+      return stateData;
+    }
+  }
+  async delete(identifier, options) {
+    const sessionId = await this.getSessionId(identifier, options);
+    if (sessionId) {
+      await this.#store.delete(sessionId);
+    }
+    this.#cookieHandler.deleteCookie(identifier, options);
+  }
+  async getSessionId(identifier, options) {
+    const cookieValue = this.#cookieHandler.getCookie(identifier, options);
+    if (cookieValue) {
+      const sessionCookie = await this.decrypt(identifier, cookieValue);
+      return sessionCookie.id;
+    }
+  }
+  deleteByLogoutToken(claims, options) {
+    return this.#store.deleteByLogoutToken(claims, options);
+  }
+};
+
+// src/store/stateless-state-store.ts
+var StatelessStateStore = class extends AbstractSessionStore {
+  #cookieHandler;
+  constructor(options, cookieHandler) {
+    super(options);
+    this.#cookieHandler = cookieHandler;
+  }
+  async set(identifier, stateData, removeIfExists, options) {
+    const maxAge = this.calculateMaxAge(stateData.internal.createdAt);
+    const cookieOpts = {
+      httpOnly: true,
+      sameSite: "lax",
+      path: "/",
+      secure: true,
+      maxAge
+    };
+    const expiration = Math.floor(Date.now() / 1e3 + maxAge);
+    const encryptedStateData = await this.encrypt(identifier, stateData, expiration);
+    const chunkSize = 3072;
+    const chunkCount = Math.ceil(encryptedStateData.length / chunkSize);
+    const chunks = [...Array(chunkCount).keys()].map((i) => ({
+      value: encryptedStateData.substring(i * chunkSize, (i + 1) * chunkSize),
+      name: `${identifier}.${i}`
+    }));
+    chunks.forEach((chunk) => {
+      this.#cookieHandler.setCookie(chunk.name, chunk.value, cookieOpts, options);
+    });
+    const existingCookieKeys = this.getCookieKeys(identifier, options);
+    const cookieKeysToRemove = existingCookieKeys.filter((key) => !chunks.some((chunk) => chunk.name === key));
+    cookieKeysToRemove.forEach((key) => {
+      this.#cookieHandler.deleteCookie(key, options);
+    });
+  }
+  async get(identifier, options) {
+    const cookieKeys = this.getCookieKeys(identifier, options);
+    const encryptedStateData = cookieKeys.map((key) => ({
+      index: parseInt(key.split(".")[1], 10),
+      value: this.#cookieHandler.getCookie(key, options)
+    })).sort((a, b) => a.index - b.index).map((item) => item.value).join("");
+    if (encryptedStateData) {
+      return await this.decrypt(identifier, encryptedStateData);
+    }
+  }
+  async delete(identifier, options) {
+    const cookieKeys = this.getCookieKeys(identifier, options);
+    for (const key of cookieKeys) {
+      this.#cookieHandler.deleteCookie(key, options);
+    }
+  }
+  deleteByLogoutToken() {
+    throw new Error(
+      "Backchannel logout is not available when using Stateless Storage. Use Stateful Storage by providing a `sessionStore`"
+    );
+  }
+  getCookieKeys(identifier, options) {
+    return Object.keys(this.#cookieHandler.getCookies(options)).filter((key) => key.startsWith(identifier));
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AbstractStateStore,
   AbstractTransactionStore,
   BackchannelLogoutError,
+  CookieTransactionStore,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
   ServerClient,
-  StartLinkUserError
+  StartLinkUserError,
+  StatefulStateStore,
+  StatelessStateStore
 });
 //# sourceMappingURL=index.cjs.map