@frank-auth/react
Version:
Flexible and customizable React UI components for Frank Authentication
268 lines • 8.39 kB
TypeScript
import { MFAMethod, MFAVerifyResponse } from '@frank-auth/client';
import { AuthError } from '../provider/types';
export interface UseMFAReturn {
mfaMethods: MFAMethod[];
isEnabled: boolean;
isRequired: boolean;
primaryMethod: MFAMethod | null;
backupCodes: string[];
isLoaded: boolean;
isLoading: boolean;
error: AuthError | null;
setupTOTP: () => Promise<MFASetupData>;
setupSMS: (phoneNumber: string) => Promise<MFASetupData>;
setupEmail: (email?: string) => Promise<MFASetupData>;
setupWebAuthn: () => Promise<MFASetupData>;
verifySetup: (method: string, code: string, methodId?: string) => Promise<MFAMethod>;
verifyMFA: (method: string, code: string, token: string) => Promise<MFAVerifyResponse>;
removeMFAMethod: (methodId: string) => Promise<void>;
setPrimaryMethod: (methodId: string) => Promise<void>;
regenerateBackupCodes: () => Promise<string[]>;
hasTOTP: boolean;
hasSMS: boolean;
hasEmail: boolean;
hasWebAuthn: boolean;
hasBackupCodes: boolean;
availableMethods: MFAMethodType[];
disable: () => Promise<void>;
enable: () => Promise<void>;
refreshMethods: () => Promise<void>;
}
export interface MFASetupData {
method: string;
qrCode?: string;
secret?: string;
backupCodes?: string[];
challenge?: any;
verificationRequired: boolean;
}
export type MFAMethodType = 'totp' | 'sms' | 'email' | 'webauthn' | 'backup_codes';
export declare const MFA_METHOD_CONFIGS: {
readonly totp: {
readonly name: "Authenticator App";
readonly description: "Use an authenticator app like Google Authenticator or Authy";
readonly icon: "📱";
readonly setupSteps: readonly ["Install an authenticator app on your phone", "Scan the QR code or enter the secret key", "Enter the 6-digit code from your app"];
};
readonly sms: {
readonly name: "SMS";
readonly description: "Receive codes via text message";
readonly icon: "💬";
readonly setupSteps: readonly ["Enter your phone number", "Wait for the verification code", "Enter the code to confirm"];
};
readonly email: {
readonly name: "Email";
readonly description: "Receive codes via email";
readonly icon: "✉️";
readonly setupSteps: readonly ["Confirm your email address", "Wait for the verification code", "Enter the code to confirm"];
};
readonly webauthn: {
readonly name: "Security Key";
readonly description: "Use a hardware security key or biometric authentication";
readonly icon: "🔐";
readonly setupSteps: readonly ["Insert your security key or prepare biometric authentication", "Follow your browser's authentication prompts", "Confirm the registration"];
};
readonly backup_codes: {
readonly name: "Backup Codes";
readonly description: "Single-use codes for emergency access";
readonly icon: "🔢";
readonly setupSteps: readonly ["Save these codes in a secure location", "Each code can only be used once", "Generate new codes when running low"];
};
};
/**
* Multi-Factor Authentication hook providing comprehensive MFA management
*
* @example Basic MFA setup
* ```tsx
* import { useMFA } from '@frank-auth/react';
*
* function MFASetup() {
* const {
* isEnabled,
* setupTOTP,
* verifySetup,
* mfaMethods,
* isLoading
* } = useMFA();
*
* const [setupData, setSetupData] = useState(null);
* const [verificationCode, setVerificationCode] = useState('');
*
* const handleSetupTOTP = async () => {
* try {
* const data = await setupTOTP();
* setSetupData(data);
* } catch (error) {
* console.error('Setup failed:', error);
* }
* };
*
* const handleVerifySetup = async () => {
* try {
* await verifySetup('totp', verificationCode);
* alert('MFA setup complete!');
* setSetupData(null);
* } catch (error) {
* console.error('Verification failed:', error);
* }
* };
*
* if (isEnabled) {
* return (
* <div>
* <h3>MFA is enabled</h3>
* <p>Active methods: {mfaMethods.length}</p>
* </div>
* );
* }
*
* return (
* <div>
* {!setupData ? (
* <button onClick={handleSetupTOTP} disabled={isLoading}>
* Setup Authenticator App
* </button>
* ) : (
* <div>
* <img src={setupData.qrCode} alt="QR Code" />
* <p>Secret: {setupData.secret}</p>
* <input
* value={verificationCode}
* onChange={(e) => setVerificationCode(e.target.value)}
* placeholder="Enter 6-digit code"
* />
* <button onClick={handleVerifySetup}>
* Verify & Enable
* </button>
* </div>
* )}
* </div>
* );
* }
* ```
*
* @example MFA verification during login
* ```tsx
* function MFAVerification({ mfaToken, onSuccess }) {
* const { verifyMFA, availableMethods } = useMFA();
* const [selectedMethod, setSelectedMethod] = useState('totp');
* const [code, setCode] = useState('');
*
* const handleVerify = async () => {
* try {
* const result = await verifyMFA(selectedMethod, code, mfaToken);
* if (result.success) {
* onSuccess(result.session);
* }
* } catch (error) {
* console.error('MFA verification failed:', error);
* }
* };
*
* return (
* <div>
* <h3>Enter your verification code</h3>
* <select
* value={selectedMethod}
* onChange={(e) => setSelectedMethod(e.target.value)}
* >
* {availableMethods.map(method => (
* <option key={method} value={method}>
* {MFA_METHOD_CONFIGS[method].name}
* </option>
* ))}
* </select>
* <input
* value={code}
* onChange={(e) => setCode(e.target.value)}
* placeholder="Enter code"
* />
* <button onClick={handleVerify}>Verify</button>
* </div>
* );
* }
* ```
*
* @example MFA method management
* ```tsx
* function MFAManagement() {
* const {
* mfaMethods,
* removeMFAMethod,
* setPrimaryMethod,
* regenerateBackupCodes,
* backupCodes
* } = useMFA();
*
* return (
* <div>
* <h3>Your MFA Methods</h3>
* {mfaMethods.map(method => (
* <div key={method.id}>
* <span>{method.type} - {method.name}</span>
* {method.isPrimary && <span>(Primary)</span>}
* <button onClick={() => setPrimaryMethod(method.id)}>
* Set as Primary
* </button>
* <button onClick={() => removeMFAMethod(method.id)}>
* Remove
* </button>
* </div>
* ))}
*
* <h4>Backup Codes</h4>
* <ul>
* {backupCodes.map((code, index) => (
* <li key={index}>{code}</li>
* ))}
* </ul>
* <button onClick={regenerateBackupCodes}>
* Generate New Backup Codes
* </button>
* </div>
* );
* }
* ```
*/
export declare function useMFA(): UseMFAReturn;
/**
* Hook for TOTP (Time-based One-Time Password) management
*/
export declare function useTOTP(): {
isEnabled: boolean;
method: MFAMethod | undefined;
setup: () => Promise<MFASetupData>;
verify: (code: string) => Promise<MFAMethod>;
remove: (() => Promise<void>) | undefined;
isLoading: boolean;
error: AuthError | null;
};
/**
* Hook for SMS MFA management
*/
export declare function useSMSMFA(): {
isEnabled: boolean;
method: MFAMethod | undefined;
setup: (phoneNumber: string) => Promise<MFASetupData>;
verify: (code: string) => Promise<MFAMethod>;
remove: (() => Promise<void>) | undefined;
phoneNumber: string | null;
isLoading: boolean;
error: AuthError | null;
};
/**
* Hook for backup codes management
*/
export declare function useBackupCodes(): {
codes: string[];
unusedCodes: string[];
usedCodes: string[];
hasBackupCodes: boolean;
regenerate: () => Promise<string[]>;
remainingCodes: number;
totalCodes: number;
isRunningLow: boolean;
isLoading: boolean;
error: AuthError | null;
};
//# sourceMappingURL=use-mfa.d.ts.map