@auth0/auth0-server-js 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Auth0, Inc. <support@auth0.com> (http://auth0.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@ Using this SDK as-is in your application may not be trivial, as it is designed t
 
 ## Documentation
 
-- [Examples](https://github.com/auth0/auth0-server-js/blob/main/packages/auth0-server-js/EXAMPLES.md) - examples for your different use cases.
+- [Examples](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/EXAMPLES.md) - examples for your different use cases.
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
 
 ## Getting Started
@@ -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)
 
@@ -400,12 +260,12 @@ fastify.get('/auth/logout', async (request, reply) => {
 We appreciate feedback and contribution to this repo! Before you get started, please read the following:
 
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
-- [Auth0's code of conduct guidelines](https://github.com/auth0/auth0-server-js/blob/main/CODE-OF-CONDUCT.md)
-- [This repo's contribution guide](./../../CONTRIBUTING.md)
+- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
+- [This repo's contribution guide](https://github.com/auth0/auth0-auth-js/blob/main/CONTRIBUTING.md)
 
 ### Raise an issue
 
-To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-server-js/issues).
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-auth-js/issues).
 
 ## Vulnerability Reporting
 
@@ -424,5 +284,5 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
   Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
 </p>
 <p align="center">
-  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-server-js/blob/main/packages/auth0-auth-js/LICENSE"> LICENSE</a> file for more info.
+  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/LICENSE"> LICENSE</a> file for more info.
 </p>

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