feat: refactor online access implementation to use refreshTokenMode and enforce type checks

Author: subhankarmaiti

__tests__/Auth0Client/onlineAccess.test.ts

@@ -84,43 +84,64 @@ describe('Auth0Client', () => {
   });
 
   describe('online access — configuration validation', () => {
-    it('throws InvalidConfigurationError when onlineAccess is true but useDpop is unset', () => {
+    it('throws InvalidConfigurationError when online but useRefreshTokens is unset', () => {
       expect(() =>
-        setup({ onlineAccess: true } as any)
+        setup({ refreshTokenMode: 'online', useDpop: true } as any)
       ).toThrow(InvalidConfigurationError);
     });
 
-    it('throws InvalidConfigurationError when onlineAccess is true but useDpop is false', () => {
+    it('error message tells the customer to pass useRefreshTokens: true', () => {
       expect(() =>
-        setup({ onlineAccess: true, useDpop: false } as any)
+        setup({ refreshTokenMode: 'online', useDpop: true } as any)
+      ).toThrow(/useRefreshTokens: true/);
+    });
+
+    it('throws InvalidConfigurationError when online but useDpop is unset', () => {
+      expect(() =>
+        setup({ refreshTokenMode: 'online', useRefreshTokens: true } as any)
+      ).toThrow(InvalidConfigurationError);
+    });
+
+    it('throws InvalidConfigurationError when online but useDpop is false', () => {
+      expect(() =>
+        setup({
+          refreshTokenMode: 'online',
+          useRefreshTokens: true,
+          useDpop: false
+        } as any)
       ).toThrow(InvalidConfigurationError);
     });
 
     it('error message tells the customer to pass useDpop: true', () => {
-      expect(() => setup({ onlineAccess: true } as any)).toThrow(
-        /useDpop: true/
-      );
+      expect(() =>
+        setup({ refreshTokenMode: 'online', useRefreshTokens: true } as any)
+      ).toThrow(/useDpop: true/);
     });
 
-    it('does not throw when onlineAccess is true and useDpop is true', () => {
+    it('does not throw when online with useRefreshTokens: true and useDpop: true', () => {
       expect(() =>
-        setup({ onlineAccess: true, useDpop: true } as any)
+        setup({
+          refreshTokenMode: 'online',
+          useRefreshTokens: true,
+          useDpop: true
+        } as any)
       ).not.toThrow();
     });
 
-    it('leaves behavior unchanged when onlineAccess is unset (no DPoP required)', () => {
+    it('leaves behavior unchanged when refreshTokenMode is unset (no DPoP required)', () => {
       expect(() => setup()).not.toThrow();
     });
 
-    it('leaves behavior unchanged when onlineAccess is false (no DPoP required)', () => {
-      expect(() => setup({ onlineAccess: false } as any)).not.toThrow();
+    it('leaves behavior unchanged when refreshTokenMode is offline (no DPoP required)', () => {
+      expect(() => setup({ refreshTokenMode: 'offline' } as any)).not.toThrow();
     });
   });
 
   describe('online access — scope injection', () => {
     it('injects online_access (and not offline_access) when online', () => {
       const auth0 = setup({
-        onlineAccess: true,
+        refreshTokenMode: 'online',
+        useRefreshTokens: true,
         useDpop: true,
         authorizationParams: {
           scope: 'profile email test-scope'
@@ -155,7 +176,8 @@ describe('Auth0Client', () => {
   describe('online access — refresh-token routing', () => {
     it('routes silent renewal through the refresh_token grant when online', async () => {
       const auth0 = setup({
-        onlineAccess: true,
+        refreshTokenMode: 'online',
+        useRefreshTokens: true,
         useDpop: true,
         cacheLocation: 'localstorage'
       } as any);
@@ -179,7 +201,8 @@ describe('Auth0Client', () => {
   describe('online access — non-rotation', () => {
     it('does NOT rotate the stored refresh token when online', async () => {
       const auth0 = setup({
-        onlineAccess: true,
+        refreshTokenMode: 'online',
+        useRefreshTokens: true,
         useDpop: true,
         cacheLocation: 'localstorage'
       } as any);

__tests__/Auth0Client/onlineAccess.types.test.ts

@@ -1,14 +1,14 @@
 /**
  * Compile-time enforcement of the online-access option, via `createAuth0Client`
- * overloads (the interface itself stays a plain, non-breaking optional boolean).
+ * overloads (the interface itself stays plain, non-breaking optional fields).
  *
  * These assertions are validated by ts-jest's type checker at test time: each
  * `@ts-expect-error` MUST sit over a genuine type error, or TypeScript reports an
  * unused-directive error and the suite fails. The runtime safety net (the
  * `InvalidConfigurationError` throw) is covered separately in onlineAccess.test.ts.
  *
- * The overloads only narrow on a literal `onlineAccess: true`, so these cover the
- * common literal mistakes a TS user would make at the call site.
+ * The overloads only narrow on a literal `refreshTokenMode: 'online'`, so these cover
+ * the common literal mistakes a TS user would make at the call site.
  */
 import { createAuth0Client } from '../../src';
 
@@ -18,40 +18,49 @@ const base = {
 };
 
 describe('createAuth0Client — online access type enforcement', () => {
-  it('requires useDpop: true and forbids useRefreshTokens when onlineAccess is true', () => {
+  it('requires useRefreshTokens: true and useDpop: true when refreshTokenMode is online', () => {
     // Compile-only — never invoked. Wrapped in a never-true guard so the calls
     // are type-checked but do not execute (no DOM/crypto needed).
     const _typecheck = async () => {
       // Valid combo.
-      await createAuth0Client({ ...base, onlineAccess: true, useDpop: true });
+      await createAuth0Client({
+        ...base,
+        refreshTokenMode: 'online',
+        useRefreshTokens: true,
+        useDpop: true
+      });
+
+      // Missing useRefreshTokens → compile error.
+      // @ts-expect-error refreshTokenMode: 'online' requires useRefreshTokens: true
+      await createAuth0Client({ ...base, refreshTokenMode: 'online', useDpop: true });
 
       // Missing useDpop → compile error.
-      // @ts-expect-error onlineAccess: true requires useDpop: true
-      await createAuth0Client({ ...base, onlineAccess: true });
+      // @ts-expect-error refreshTokenMode: 'online' requires useDpop: true
+      await createAuth0Client({
+        ...base,
+        refreshTokenMode: 'online',
+        useRefreshTokens: true
+      });
 
       // useDpop: false → compile error.
-      // @ts-expect-error onlineAccess: true requires useDpop: true (not false)
-      await createAuth0Client({ ...base, onlineAccess: true, useDpop: false });
-
-      // useRefreshTokens alongside online → compile error (it injects offline_access).
-      // @ts-expect-error useRefreshTokens conflicts with onlineAccess
+      // @ts-expect-error refreshTokenMode: 'online' requires useDpop: true (not false)
       await createAuth0Client({
         ...base,
-        onlineAccess: true,
-        useDpop: true,
-        useRefreshTokens: true
+        refreshTokenMode: 'online',
+        useRefreshTokens: true,
+        useDpop: false
       });
     };
     void _typecheck;
 
     expect(true).toBe(true);
   });
 
-  it('leaves the legacy (non-online) call unconstrained', () => {
+  it('leaves the legacy (offline / non-online) call unconstrained', () => {
     const _typecheck = async () => {
       // Legacy combos remain valid — the overloads must not constrain them.
       await createAuth0Client({ ...base, useRefreshTokens: true, useDpop: false });
-      await createAuth0Client({ ...base, onlineAccess: false, useRefreshTokens: true });
+      await createAuth0Client({ ...base, refreshTokenMode: 'offline', useRefreshTokens: true });
     };
     void _typecheck;
 

__tests__/index.test.ts

@@ -90,7 +90,7 @@ const setup = async (
     domain: TEST_DOMAIN,
     clientId: TEST_CLIENT_ID,
     ...clientOptions
-  } as Auth0ClientOptions & { onlineAccess?: false };
+  } as Auth0ClientOptions & { refreshTokenMode?: 'offline' };
 
   const auth0 = callConstructor
     ? await createAuth0Client(opts)

src/Auth0Client.ts

@@ -191,30 +191,32 @@ export class Auth0Client {
       scope: DEFAULT_SCOPE
     },
     useRefreshTokensFallback: false,
-    useFormData: true
+    useFormData: true,
+    refreshTokenMode: 'offline',
   };
 
   /**
    * Validates the online-access configuration and returns whether online mode is enabled.
    *
-   * Online access requires DPoP, so `onlineAccess: true` without `useDpop: true` throws.
+   * Online mode (`refreshTokenMode: 'online'`) is a refresh-token grant, so it requires
+   * `useRefreshTokens: true`, and it requires DPoP, so `useDpop: true` is mandatory.
    */
   private resolveOnlineAccess(options: Auth0ClientOptions): boolean {
 
-    if (options.onlineAccess !== true) {
+    if (options.refreshTokenMode !== 'online') {
       return false;
     }
 
-    if (options.useRefreshTokens == true) {
+    if (options.useRefreshTokens !== true) {
       throw new InvalidConfigurationError(
-        '`onlineAccess: true` requires useRefreshTokens to be false.',
-        'Set `useRefreshTokens: false`.'
+        '`refreshTokenMode: "online"` requires the refresh-token grant.',
+        'Set `useRefreshTokens: true`.'
       );
     }
 
     if (options.useDpop !== true) {
       throw new InvalidConfigurationError(
-        '`onlineAccess: true` requires DPoP, which is missing or disabled.',
+        '`refreshTokenMode: "online"` requires DPoP, which is missing or disabled.',
         'Set `useDpop: true` (DPoP is mandatory for online access).'
       );
     }
@@ -350,11 +352,12 @@ export class Auth0Client {
       this
     );
 
-    // Don't use web workers unless using refresh tokens in memory
+    // Don't use web workers unless using refresh tokens in memory.
+    // Online mode requires `useRefreshTokens: true`, so it is covered here too.
     if (
       typeof window !== 'undefined' &&
       window.Worker &&
-      (this.options.useRefreshTokens || this.onlineAccess) &&
+      this.options.useRefreshTokens &&
       cacheLocation === CACHE_LOCATION_MEMORY
     ) {
       if (this.options.workerUrl) {
@@ -1020,7 +1023,7 @@ export class Auth0Client {
           }
         }
 
-        const authResult = (this.options.useRefreshTokens || this.onlineAccess)
+        const authResult = this.options.useRefreshTokens
           ? await this._getTokenUsingRefreshToken(getTokenOptions)
           : await this._getTokenFromIFrame(getTokenOptions);
 
@@ -1237,7 +1240,7 @@ export class Auth0Client {
    * await auth0.revokeRefreshToken({ audience: 'https://api2.example.com' });
    */
   public async revokeRefreshToken(options: RevokeRefreshTokenOptions = {}): Promise<void> {
-    if (!this.options.useRefreshTokens && !this.onlineAccess) {
+    if (!this.options.useRefreshTokens) {
       return;
     }
 

src/errors.ts

@@ -30,7 +30,7 @@ export class GenericError extends Error {
 
 /**
  * Thrown at construction time when the Auth0Client is configured with an invalid combination
- * of options (e.g. `onlineAccess: true` without `useDpop: true`). Carries a `suggestion` with
+ * of options (e.g. `refreshTokenMode: 'online'` without `useDpop: true`). Carries a `suggestion` with
  * the exact configuration change to make.
  */
 export class InvalidConfigurationError extends GenericError {

src/global.ts

@@ -313,18 +313,22 @@ export interface Auth0ClientOptions {
   useDpop?: boolean;
 
   /**
-   * Opt in to Online Refresh Tokens (ORTs): non-rotating refresh tokens bound to
-   * the Auth0 session lifetime. When `true`, the SDK injects the `online_access`
-   * scope, routes token renewal through the refresh_token grant, and stores the
-   * (non-rotating) refresh token in the existing cache.
+   * Selects the refresh-token variant used when `useRefreshTokens: true`.
    *
-   * Online access requires DPoP — you must also set `useDpop: true`. Do NOT set
-   * `useRefreshTokens` alongside it: that injects `offline_access`, which conflicts
-   * with `online_access`.
+   * - `'offline'` (default): rotating offline refresh tokens, requested via the
+   *   `offline_access` scope. This is the existing behavior.
+   * - `'online'`: non-rotating Online Refresh Tokens (ORTs), bound to the Auth0
+   *   session lifetime, requested via the `online_access` scope. When the session
+   *   ends or is revoked, the ORT becomes invalid.
    *
-   * Defaults to `false` — when unset or `false` the SDK behaves exactly as before.
+   * Online mode requires `useRefreshTokens: true` (it is a kind of refresh-token
+   * grant) and `useDpop: true` (DPoP is mandatory for online access). The
+   * `online_access` and `offline_access` scopes are mutually exclusive — online
+   * mode never injects `offline_access`.
+   *
+   * Defaults to `'offline'` — when unset the SDK behaves exactly as before.
    */
-  onlineAccess?: boolean;
+  refreshTokenMode?: 'offline' | 'online';
 
   /**
    * Configures automatic handling of interactive authentication errors.

src/index.ts

@@ -6,21 +6,21 @@ import './global';
 export * from './global';
 
 /**
- * Online access requires DPoP and is incompatible with `useRefreshTokens` (which
- * requests `offline_access`). When `onlineAccess` is the literal `true`, the compiler
- * requires `useDpop: true` and forbids `useRefreshTokens`. This only narrows on a literal
- * `true`; dynamic values, casts, and plain JS are covered by the runtime check in the
+ * Online mode (`refreshTokenMode: 'online'`) is a refresh-token grant and requires DPoP.
+ * When `refreshTokenMode` is the literal `'online'`, the compiler requires both
+ * `useRefreshTokens: true` and `useDpop: true`. This only narrows on the literal `'online'`;
+ * dynamic values, casts, and plain JS are covered by the runtime check in the
  * `Auth0Client` constructor.
  */
 export async function createAuth0Client(
   options: Auth0ClientOptions & {
-    onlineAccess: true;
+    refreshTokenMode: 'online';
+    useRefreshTokens: true;
     useDpop: true;
-    useRefreshTokens?: never;
   }
 ): Promise<Auth0Client>;
 export async function createAuth0Client(
-  options: Auth0ClientOptions & { onlineAccess?: false }
+  options: Auth0ClientOptions & { refreshTokenMode?: 'offline' }
 ): Promise<Auth0Client>;
 /**
  * Asynchronously creates the Auth0Client instance and calls `checkSession`.