@auth0/auth0-spa-js 2.5.0 → 2.6.0

package/src/MyAccountApiClient.ts

@@ -0,0 +1,158 @@
+import { AuthorizationParams } from './global';
+import { Fetcher } from './fetcher';
+
+interface ConnectRequest {
+  /** The name of the connection to link the account with (e.g., 'google-oauth2', 'facebook'). */
+  connection: string;
+  /** The URI to redirect to after the connection process completes. */
+  redirect_uri: string;
+  /** An opaque value used to maintain state between the request and callback. */
+  state?: string;
+  /** A string value used to associate a Client session with an ID Token, and to mitigate replay attacks. */
+  nonce?: string;
+  /** The PKCE code challenge derived from the code verifier. */
+  code_challenge?: string;
+  /** The method used to derive the code challenge. Required when code_challenge is provided. */
+  code_challenge_method?: 'S256';
+  authorization_params?: AuthorizationParams;
+}
+
+interface ConnectResponse {
+  /** The base URI to initiate the account connection flow. */
+  connect_uri: string;
+  /** The authentication session identifier. */
+  auth_session: string;
+  /** Parameters to be used with the connect URI. */
+  connect_params: {
+    /** The ticket identifier to be used with the connection URI. */
+    ticket: string;
+  };
+  /** The number of seconds until the ticket expires. */
+  expires_in: number;
+}
+
+interface CompleteRequest {
+  /** The authentication session identifier */
+  auth_session: string;
+  /** The authorization code returned from the connect flow */
+  connect_code: string;
+  /** The redirect URI used in the original request */
+  redirect_uri: string;
+  /** The PKCE code verifier */
+  code_verifier?: string;
+}
+
+export interface CompleteResponse {
+  /** The unique identifier of the connected account */
+  id: string;
+  /** The connection name */
+  connection: string;
+  /** The access type, always 'offline' */
+  access_type: 'offline';
+  /** Array of scopes granted */
+  scopes?: string[];
+  /** ISO date string of when the connected account was created */
+  created_at: string;
+  /** ISO date string of when the refresh token expires (optional) */
+  expires_at?: string;
+}
+
+// Validation error returned from MyAccount API
+export interface ErrorResponse {
+  type: string;
+  status: number;
+  title: string;
+  detail: string;
+  validation_errors?: {
+    detail: string;
+    field?: string;
+    pointer?: string;
+    source?: string;
+  }[];
+}
+
+/**
+ * Subset of the MyAccount API that handles the connect accounts flow.
+ */
+export class MyAccountApiClient {
+  constructor(
+    private myAccountFetcher: Fetcher<Response>,
+    private apiBase: string
+  ) {}
+
+  /**
+   * Get a ticket for the connect account flow.
+   */
+  async connectAccount(params: ConnectRequest): Promise<ConnectResponse> {
+    const res = await this.myAccountFetcher.fetchWithAuth(
+      `${this.apiBase}v1/connected-accounts/connect`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params)
+      }
+    );
+    return this._handleResponse(res);
+  }
+
+  /**
+   * Verify the redirect from the connect account flow and complete the connecting of the account.
+   */
+  async completeAccount(params: CompleteRequest): Promise<CompleteResponse> {
+    const res = await this.myAccountFetcher.fetchWithAuth(
+      `${this.apiBase}v1/connected-accounts/complete`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params)
+      }
+    );
+    return this._handleResponse(res);
+  }
+
+  private async _handleResponse(res: Response) {
+    let body: any;
+    try {
+      body = await res.text();
+      body = JSON.parse(body);
+    } catch (err) {
+      throw new MyAccountApiError({
+        type: 'invalid_json',
+        status: res.status,
+        title: 'Invalid JSON response',
+        detail: body || String(err)
+      });
+    }
+
+    if (res.ok) {
+      return body;
+    } else {
+      throw new MyAccountApiError(body);
+    }
+  }
+}
+
+export class MyAccountApiError extends Error {
+  public readonly type: string;
+  public readonly status: number;
+  public readonly title: string;
+  public readonly detail: string;
+  public readonly validation_errors?: ErrorResponse['validation_errors'];
+
+  constructor({
+    type,
+    status,
+    title,
+    detail,
+    validation_errors
+  }: ErrorResponse) {
+    super(detail);
+    this.name = 'MyAccountApiError';
+    this.type = type;
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.validation_errors = validation_errors;
+    Object.setPrototypeOf(this, MyAccountApiError.prototype);
+  }
+}

package/src/errors.ts

@@ -35,6 +35,24 @@ export class AuthenticationError extends GenericError {
   }
 }
 
+/**
+ * Thrown when handling the redirect callback for the connect flow fails, will be one of Auth0's
+ * Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
+ */
+export class ConnectError extends GenericError {
+  constructor(
+    error: string,
+    error_description: string,
+    public connection: string,
+    public state: string,
+    public appState: any = null
+  ) {
+    super(error, error_description);
+    //https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
+    Object.setPrototypeOf(this, ConnectError.prototype);
+  }
+}
+
 /**
  * Thrown when silent auth times out (usually due to a configuration issue) or
  * when network requests to the Auth server timeout.

package/src/fetcher.ts

@@ -114,10 +114,10 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     );
   }
 
-  protected async setAuthorizationHeader(
+  protected setAuthorizationHeader(
     request: Request,
     accessToken: string
-  ): Promise<void> {
+  ): void {
     request.headers.set(
       'authorization',
       `${this.config.dpopNonceId ? 'DPoP' : 'Bearer'} ${accessToken}`

package/src/global.ts

@@ -1,5 +1,6 @@
 import { ICache } from './cache';
 import type { Dpop } from './dpop/dpop';
+import { CompleteResponse } from './MyAccountApiClient';
 
 export interface AuthorizationParams {
   /**
@@ -265,10 +266,10 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
 
   /**
    * If provided, the SDK will load the token worker from this URL instead of the integrated `blob`. An example of when this is useful is if you have strict
-   * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module 
-   * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN 
+   * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module
+   * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN
    * `https://cdn.auth0.com/js/auth0-spa-js/<version>/auth0-spa-js.worker.production.js`.
-   * 
+   *
    * **Note**: The worker is only used when `useRefreshTokens: true`, `cacheLocation: 'memory'`, and the `cache` is not custom.
    */
   workerUrl?: string;
@@ -353,11 +354,26 @@ export interface RedirectLoginOptions<TAppState = any>
   openUrl?: (url: string) => Promise<void> | void;
 }
 
+/**
+ * The types of responses expected from the authorization server.
+ * - `code`: used for the standard login flow.
+ * - `connect_code`: used for the connect account flow.
+ */
+export enum ResponseType {
+  Code = 'code',
+  ConnectCode = 'connect_code'
+}
+
 export interface RedirectLoginResult<TAppState = any> {
   /**
    * State stored when the redirect request was made
    */
   appState?: TAppState;
+
+  /**
+   * The type of response, for login it will be `code`
+   */
+  response_type: ResponseType.Code;
 }
 
 export interface PopupLoginOptions extends BaseLoginOptions { }
@@ -523,12 +539,98 @@ export interface LogoutOptions extends LogoutUrlOptions {
   openUrl?: false | ((url: string) => Promise<void> | void);
 }
 
+export interface RedirectConnectAccountOptions<TAppState = any> {
+  /**
+   * The name of the connection to link (e.g. 'google-oauth2').
+   */
+  connection: string;
+
+  /**
+   * Additional authorization parameters for the request.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   authorization_params: {
+   *     scope: 'https://www.googleapis.com/auth/calendar'
+   *     access_type: 'offline'
+   *   }
+   * });
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'github',
+   *   authorization_params: {
+   *     scope: 'repo user',
+   *     audience: 'https://api.github.com'
+   *   }
+   * });
+   */
+  authorization_params?: AuthorizationParams;
+
+  /**
+   * The URI to redirect back to after connecting the account.
+   */
+  redirectUri?: string;
+
+  /**
+   * Optional application state to persist through the transaction.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   appState: { returnTo: '/settings' }
+   * });
+   */
+  appState?: TAppState;
+
+  /**
+   * Optional function to handle the redirect URL.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   openUrl: async (url) => { myBrowserApi.open(url); }
+   * });
+   */
+  openUrl?: (url: string) => Promise<void>;
+}
+
+/**
+ * The result returned after a successful account connection redirect.
+ *
+ * Combines the redirect login result (including any persisted app state)
+ * with the complete response from the My Account API.
+ *
+ * @template TAppState - The type of application state persisted through the transaction.
+ * @example
+ * const result = await auth0.connectAccountWithRedirect(options);
+ * console.log(result.appState); // Access persisted app state
+ * console.log(result.connection);   // The connection of the account you connected to.
+ * console.log(result.response_type === 'connect_code');   // The response type will be 'connect_code'
+ */
+export type ConnectAccountRedirectResult<TAppState = any> = CompleteResponse & {
+  /**
+   * State stored when the redirect request was made
+   */
+  appState?: TAppState;
+
+  /**
+   * The type of response, for connect account it will be `connect_code`
+   */
+  response_type: ResponseType.ConnectCode;
+};
+
 /**
  * @ignore
  */
 export interface AuthenticationResult {
   state: string;
   code?: string;
+  /**
+   * This is for the redirect from the connect account flow.
+   */
+  connect_code?: string;
   error?: string;
   error_description?: string;
 }

package/src/index.ts

@@ -23,6 +23,7 @@ export async function createAuth0Client(options: Auth0ClientOptions) {
 export { Auth0Client };
 
 export {
+  ConnectError,
   GenericError,
   AuthenticationError,
   TimeoutError,
@@ -48,3 +49,7 @@ export {
 } from './cache';
 
 export { type FetcherConfig } from './fetcher';
+
+export {
+  MyAccountApiError
+} from './MyAccountApiClient';

package/src/transaction-manager.ts

@@ -2,7 +2,7 @@ import { ClientStorage } from './storage';
 
 const TRANSACTION_STORAGE_KEY_PREFIX = 'a0.spajs.txs';
 
-interface Transaction {
+export interface LoginTransaction {
   nonce: string;
   scope: string;
   audience: string;
@@ -11,6 +11,19 @@ interface Transaction {
   redirect_uri?: string;
   organization?: string;
   state?: string;
+  response_type: 'code';
+}
+
+export interface ConnectAccountTransaction {
+  appState?: any;
+  audience?: string;
+  auth_session: string;
+  code_verifier: string;
+  redirect_uri: string;
+  scope?: string;
+  state: string;
+  connection: string;
+  response_type: 'connect_code';
 }
 
 export class TransactionManager {
@@ -24,14 +37,14 @@ export class TransactionManager {
     this.storageKey = `${TRANSACTION_STORAGE_KEY_PREFIX}.${this.clientId}`;
   }
 
-  public create(transaction: Transaction) {
+  public create<T extends Object = LoginTransaction>(transaction: T) {
     this.storage.save(this.storageKey, transaction, {
       daysUntilExpire: 1,
       cookieDomain: this.cookieDomain
     });
   }
 
-  public get(): Transaction | undefined {
+  public get<T extends Object = LoginTransaction>(): T | undefined {
     return this.storage.get(this.storageKey);
   }
 
@@ -40,4 +53,4 @@ export class TransactionManager {
       cookieDomain: this.cookieDomain
     });
   }
-}
+}

package/src/utils.ts

@@ -24,6 +24,7 @@ export const parseAuthenticationResult = (
   return {
     state: searchParams.get('state')!,
     code: searchParams.get('code') || undefined,
+    connect_code: searchParams.get('connect_code') || undefined,
     error: searchParams.get('error') || undefined,
     error_description: searchParams.get('error_description') || undefined
   };

package/src/version.ts

@@ -1 +1 @@
-export default '2.5.0';
+export default '2.6.0';