squarefi-bff-api-module 1.36.19 → 1.36.21

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { squarefi_bff_api_client } from './api';
 export * from './utils/apiClientFactory';
-export { setAccessTokenProvider, setOnTwoFactorRequired, setOnUnauthorized, type AccessTokenProvider, type ResolveTokenOptions, type TwoFactorRequiredHandler, type UnauthorizedHandler, } from './utils/accessTokenProvider';
+export { setAccessTokenProvider, setOnReverificationRequired, setOnUnauthorized, type AccessTokenProvider, type ResolveTokenOptions, type ReverificationHandler, type ReverificationMeta, type UnauthorizedHandler, } from './utils/accessTokenProvider';
 export * from './utils/tokensFactory';
 export * from './utils/fileStorage';
 export * from './constants';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { squarefi_bff_api_client } from './api';
 export * from './utils/apiClientFactory';
-export { setAccessTokenProvider, setOnTwoFactorRequired, setOnUnauthorized, } from './utils/accessTokenProvider';
+export { setAccessTokenProvider, setOnReverificationRequired, setOnUnauthorized, } from './utils/accessTokenProvider';
 export * from './utils/tokensFactory';
 export * from './utils/fileStorage';
 export * from './constants';

package/dist/utils/accessTokenProvider.d.ts

@@ -4,7 +4,14 @@ export type ResolveTokenOptions = {
 };
 export type AccessTokenProvider = (options?: ResolveTokenOptions) => Promise<string | null | undefined>;
 export type UnauthorizedHandler = () => void;
-export type TwoFactorRequiredHandler = () => void;
+/** Details the backend attaches to a step-up (2FA reverification) rejection. */
+export type ReverificationMeta = Record<string, unknown>;
+/**
+ * Handler that performs a step-up reverification (e.g. re-entering an already-enrolled second
+ * factor). Resolves `true` once the user has re-verified so the original request can be retried,
+ * or `false` if the reverification was cancelled or failed.
+ */
+export type ReverificationHandler = (meta: ReverificationMeta) => Promise<boolean>;
 /**
  * Register an external source of the access token (e.g. Clerk `getToken`).
  * When set, the API clients stop reading tokens from localStorage and delegate
@@ -18,14 +25,15 @@ export declare const setAccessTokenProvider: (provider: AccessTokenProvider | nu
  */
 export declare const setOnUnauthorized: (handler: UnauthorizedHandler | null) => void;
 /**
- * Register a callback invoked when the backend rejects a request because
- * two-factor authentication is required but not yet satisfied (HTTP 403 with a
- * `two_factor_required` error code). The consumer typically redirects the user
- * to the 2FA setup flow. Pass `null` to unregister.
+ * Register a handler invoked when the backend rejects a request because a step-up 2FA
+ * reverification is required (HTTP `403` with a `two_factor_reverification_required` code). The
+ * handler drives the provider-specific re-verification (e.g. Clerk) and resolves `true` on success
+ * so the API client retries the original request once. Pass `null` to unregister.
  */
-export declare const setOnTwoFactorRequired: (handler: TwoFactorRequiredHandler | null) => void;
+export declare const setOnReverificationRequired: (handler: ReverificationHandler | null) => void;
 /** Whether an external token provider is active (Clerk mode). */
 export declare const isExternalAuthMode: () => boolean;
 export declare const resolveAccessToken: (options?: ResolveTokenOptions) => Promise<string | null>;
 export declare const triggerUnauthorized: () => void;
-export declare const triggerTwoFactorRequired: () => void;
+/** Invokes the registered reverification handler; resolves `false` when none is registered. */
+export declare const triggerReverification: (meta: ReverificationMeta) => Promise<boolean>;

package/dist/utils/accessTokenProvider.js

@@ -1,7 +1,7 @@
 import { getFromLocalStorage } from './storage';
 let accessTokenProvider = null;
 let unauthorizedHandler = null;
-let twoFactorRequiredHandler = null;
+let reverificationHandler = null;
 let inFlightRefresh = null;
 /**
  * Register an external source of the access token (e.g. Clerk `getToken`).
@@ -20,13 +20,13 @@ export const setOnUnauthorized = (handler) => {
     unauthorizedHandler = handler;
 };
 /**
- * Register a callback invoked when the backend rejects a request because
- * two-factor authentication is required but not yet satisfied (HTTP 403 with a
- * `two_factor_required` error code). The consumer typically redirects the user
- * to the 2FA setup flow. Pass `null` to unregister.
+ * Register a handler invoked when the backend rejects a request because a step-up 2FA
+ * reverification is required (HTTP `403` with a `two_factor_reverification_required` code). The
+ * handler drives the provider-specific re-verification (e.g. Clerk) and resolves `true` on success
+ * so the API client retries the original request once. Pass `null` to unregister.
  */
-export const setOnTwoFactorRequired = (handler) => {
-    twoFactorRequiredHandler = handler;
+export const setOnReverificationRequired = (handler) => {
+    reverificationHandler = handler;
 };
 /** Whether an external token provider is active (Clerk mode). */
 export const isExternalAuthMode = () => accessTokenProvider !== null;
@@ -58,6 +58,5 @@ export const resolveAccessToken = async (options) => {
 export const triggerUnauthorized = () => {
     unauthorizedHandler?.();
 };
-export const triggerTwoFactorRequired = () => {
-    twoFactorRequiredHandler?.();
-};
+/** Invokes the registered reverification handler; resolves `false` when none is registered. */
+export const triggerReverification = (meta) => reverificationHandler ? reverificationHandler(meta) : Promise.resolve(false);

package/dist/utils/apiClientFactory.js

@@ -3,11 +3,11 @@ import { isTMA } from '@telegram-apps/sdk-react';
 import axios from 'axios';
 import { telegramSignUpPath, telegramSignInPath, refreshTokenPath } from '../api/auth';
 import { AppEnviroment, ResponseStatus } from '../constants';
-import { isExternalAuthMode, resolveAccessToken, triggerTwoFactorRequired, triggerUnauthorized, } from './accessTokenProvider';
+import { isExternalAuthMode, resolveAccessToken, triggerReverification, triggerUnauthorized, } from './accessTokenProvider';
 import { deleteTokens, getTokens, refreshTokens } from './tokensFactory';
 // eslint-disable-next-line no-constant-condition
-// Backend signals that a still-unsatisfied 2FA requirement blocks the request with this error code.
-const TWO_FACTOR_REQUIRED_ERROR_CODE = 'two_factor_required';
+// Backend signals that a sensitive request needs a fresh second-factor verification with this code.
+const TWO_FACTOR_REVERIFICATION_CODE = 'two_factor_reverification_required';
 const apiV1BaseURL = process.env.API_URL ?? 'ENV variable API_URL is not defined';
 const apiV2BaseURL = process.env.API_V2_URL ?? 'ENV variable API_V2_URL is not defined';
 const apiTOTPBaseURL = process.env.API_TOTP_URL ?? 'ENV variable API_TOTP_URL is not defined';
@@ -43,10 +43,22 @@ export const createApiClient = ({ baseURL, isBearerToken, tenantId }) => {
         if (typeof window === 'undefined') {
             return Promise.reject(error);
         }
+        // Step-up 2FA: the backend rejects a sensitive request until the user re-verifies their
+        // second factor. Hand off to the consumer's reverification handler and retry once on success.
         if (error?.response?.status === ResponseStatus.FORBIDDEN &&
-            error?.response?.data?.code === TWO_FACTOR_REQUIRED_ERROR_CODE) {
-            triggerTwoFactorRequired();
-            return Promise.reject(error);
+            error?.response?.data?.code === TWO_FACTOR_REVERIFICATION_CODE &&
+            !error?.response?.config.context?.isRetryRequest) {
+            const { response, config: failedRequestConfig } = error;
+            return triggerReverification(response.data).then((didReverify) => {
+                if (!didReverify) {
+                    return Promise.reject(error);
+                }
+                failedRequestConfig.context = {
+                    ...failedRequestConfig.context,
+                    isRetryRequest: true,
+                };
+                return instance(failedRequestConfig);
+            });
         }
         if (error?.response?.status === ResponseStatus.UNAUTHORIZED &&
             !error?.response?.config.context?.bypassUnauthorizedHandler) {
@@ -189,9 +201,6 @@ export const createFetchApiClient = ({ baseURL, isBearerToken, tenantId }) => {
             let errorMessage = `HTTP error! status: ${response.status}`;
             try {
                 const errorData = await response.json();
-                if (response.status === ResponseStatus.FORBIDDEN && errorData?.code === TWO_FACTOR_REQUIRED_ERROR_CODE) {
-                    triggerTwoFactorRequired();
-                }
                 errorMessage = errorData.message || errorData.error || errorMessage;
             }
             catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.36.19",
+  "version": "1.36.21",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",