A unified, framework-agnostic authentication toolkit designed for React Native and Expo applications, with full compatibility for React web. Built on a lightweight, zero-dependency state machine, it provides headless utilities and hooks for One-Time Password (OTP) code delivery, deep-link / magic-link token parsing, and native biometric authentication.
Install the package using your preferred package manager:
npm install @salatech/auth-toolkitCore state machine, OTP utilities, and web components require zero external dependencies. Install peer dependencies only for the native features you use:
Required for link listener utilities and automatic URL token parsing:
npx expo install expo-linkingRequired for Face ID, Touch ID, and Android Biometric Prompt:
npx expo install expo-local-authenticationRequired only if rendering OtpInputNative (web apps use OtpInput with zero native dependencies):
npx expo install react-nativeFor 90% of use cases (sending an OTP code, entering it, and logging in), use useOtpLogin:
import { useState } from 'react';
import { View, Button, TextInput } from 'react-native';
import { useOtpLogin, OtpInputNative } from '@salatech/auth-toolkit';
export function LoginScreen() {
const [phone, setPhone] = useState('');
const [code, setCode] = useState('');
const { status, error, resendIn, sendOtp, verifyOtp, clearError, reset } = useOtpLogin({
onSendOtp: async (recipient) => { await api.sendOtp(recipient); },
onVerifyOtp: async (submittedCode) => { return (await api.verify(phone, submittedCode)).token; },
onVerified: (token) => { router.replace('/dashboard'); },
});
if (status === 'idle') return <Button title="Send Code" onPress={() => sendOtp(phone)} />;
if (status === 'pending' || status === 'verifying') return (
<View>
<OtpInputNative value={code} onChange={setCode} onEditStart={clearError} onComplete={verifyOtp} />
<Button title={resendIn > 0 ? `Resend (${resendIn}s)` : 'Resend'} disabled={resendIn > 0} onPress={() => sendOtp(phone)} />
</View>
);
return <Button title="Reset" onPress={reset} />;
}For advanced authentication orchestration supporting hybrid OTP, magic links, and Face ID:
import { useState } from 'react';
import { View, Text, TextInput, Button, StyleSheet } from 'react-native';
import { useAuthFlow, OtpInputNative } from '@salatech/auth-toolkit';
export function AdvancedAuthScreen() {
const [phone, setPhone] = useState('');
const [code, setCode] = useState('');
const {
status,
state,
resendIn,
sendOtp,
verifyOtp,
clearError,
authenticateWithBiometrics,
reset,
} = useAuthFlow({
strategy: 'hybrid', // 'otp' | 'deep-link' | 'biometric' | 'hybrid'
cooldownSeconds: 60,
codeLength: 6,
onSendOtp: async (recipient) => {
await fetch('/api/auth/send-otp', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ phone: recipient }),
});
},
onVerifyOtp: async (submittedCode) => {
const res = await fetch('/api/auth/verify-otp', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ phone, code: submittedCode }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.message || 'Verification failed');
return data.accessToken;
},
onBiometricSuccess: async () => {
// Exchange biometric confirmation for a server session token:
const res = await fetch('/api/auth/biometric-login', { method: 'POST' });
const data = await res.json();
return data.accessToken;
},
onVerified: (token) => {
console.log('Successfully authenticated. Token:', token);
},
onError: (err) => {
console.error('Auth error:', err.message);
},
});
return (
<View style={styles.container}>
{status === 'idle' && (
<View>
<Text style={styles.label}>Phone Number</Text>
<TextInput
style={styles.input}
value={phone}
onChangeText={setPhone}
placeholder="+1234567890"
keyboardType="phone-pad"
/>
<Button title="Send Code" onPress={() => sendOtp(phone)} />
<Button
title="Sign in with Face ID"
onPress={() => authenticateWithBiometrics({ promptMessage: 'Unlock MyApp' })}
/>
</View>
)}
{(status === 'pending' || status === 'verifying') && (
<View>
<Text style={styles.label}>Enter 6-Digit Code</Text>
{state.error && <Text style={styles.errorText}>{state.error.message}</Text>}
<OtpInputNative
length={6}
value={code}
onChange={setCode}
onEditStart={clearError}
onComplete={(c) => verifyOtp(c)}
/>
<Button
title={resendIn > 0 ? `Resend Code (${resendIn}s)` : 'Resend Code'}
disabled={resendIn > 0}
onPress={() => sendOtp(phone)}
/>
<Button title="Cancel" onPress={reset} />
</View>
)}
{status === 'success' && (
<View>
<Text style={styles.successText}>Authenticated!</Text>
<Button title="Log Out" onPress={reset} />
</View>
)}
{status === 'error' && (
<View>
<Text style={styles.errorText}>A fatal error occurred.</Text>
<Button title="Try Again" onPress={reset} />
</View>
)}
</View>
);
}
const styles = StyleSheet.create({
container: { padding: 24 },
label: { fontSize: 16, marginBottom: 8 },
input: { borderWidth: 1, borderColor: '#ccc', padding: 12, marginBottom: 16 },
successText: { fontSize: 18, color: 'green', marginBottom: 16 },
errorText: { fontSize: 16, color: 'red', marginBottom: 16 },
});expo-linking, expo-local-authentication, and react-native are optional peer dependencies.
- If using magic/deep links:
npx expo install expo-linking. - If using Face ID / biometrics:
npx expo install expo-local-authentication. - If building a React Web app: import
OtpInputinstead ofOtpInputNative— noreact-nativepeer dependency is needed.
Native biometric checks (authenticateBiometric) only verify local device hardware unlock. They do not mint a server session.
- Always provide
onBiometricSuccess: async () => fetchServerSession()to exchange the device check for a real JWT or auth token. - If
onBiometricSuccessis omitted,state.dataisnullandonVerifiedis called without a token.
When an entered OTP code is incorrect, the state machine dispatches VERIFY_FAILURE.
- The status stays
'pending'(it does not jump to'error'). - The error is placed in
state.errorso you can display an inline error message. - Wire
onEditStart={clearError}on yourOtpInput/OtpInputNativeso the error message automatically clears as soon as the user starts editing their code.
Calling sendOtp() while cooldown is active (resendIn > 0) is a no-op.
- Always disable your resend button in the UI:
disabled={resendIn > 0}.
addDeepLinkListener only fires for links received while the app is running. Also handle the launch link:
useEffect(() => {
getInitialAuthDeepLink().then((url) => url && handleDeepLink(url));
return addDeepLinkListener(handleDeepLink);
}, [handleDeepLink]);Links without a token are reported through onError but do not change the auth state, so it is safe to forward every incoming URL.
sendOtp, verifyOtp, and authenticateWithBiometrics automatically guard against concurrent double-submits while requests are in flight.
Authentication status transitions follow a deterministic state machine managed by authReducer:
+-----------------------------------+
| |
v |
[ idle ] -----------------+ |
| | |
SEND_CODE | |
| VERIFY_SUCCESS |
v (biometric/link) |
[ sending ] | |
| | |
CODE_SENT | |
| | |
v | |
[ pending ] <---------------+ |
| | | |
VERIFY_CODE +-----------+ | |
| | | |
v VERIFY_FAILURE |
[ verifying ] ----------+ | |
| | | |
VERIFY_SUCCESS SET_ERROR | |
| | | |
v v v RESET
[ success ] [ error ] ----------------------+
idle: Ready for input.sending: Code dispatch in progress.pending: Code sent. Awaiting user input.verifying: Code verification in progress.success: Verification successful; authenticated payload is available instate.data.error: Terminal failure; details instate.error.
Always prefer canonical imports from the package root:
import {
useOtpLogin,
useAuthFlow,
OtpInput,
OtpInputNative,
AuthStateMachine,
OtpManager,
AuthError,
parseAuthDeepLink,
addDeepLinkListener,
getInitialAuthDeepLink,
isBiometricAvailable,
authenticateBiometric,
} from '@salatech/auth-toolkit';For specialized bundle optimization or non-React environments, subpaths are supported:
import { AuthStateMachine, authReducer, AuthError } from '@salatech/auth-toolkit/core';
import { OtpManager } from '@salatech/auth-toolkit/otp';
import { useAuthFlow, useOtpLogin } from '@salatech/auth-toolkit/hooks';
import { OtpInput, OtpInputNative } from '@salatech/auth-toolkit/ui';
import { parseAuthDeepLink, addDeepLinkListener } from '@salatech/auth-toolkit/deep-link';
import { isBiometricAvailable, authenticateBiometric } from '@salatech/auth-toolkit/biometric';Minimal hook for standard OTP login flows.
onSendOtp: (recipient: string) => Promise<void>(Required)onVerifyOtp: (code: string) => Promise<TToken>(Required)onVerified?: (token?: TToken) => voidonError?: (error: Error) => voidcodeLength?: number(Default:6)cooldownSeconds?: number(Default:60)
status:'idle' | 'sending' | 'pending' | 'verifying' | 'success' | 'error'error:Error | nullresendIn:number(remaining cooldown in seconds)sendOtp:(recipient: string) => Promise<void>verifyOtp:(code: string) => Promise<void>clearError:() => voidreset:() => void
Comprehensive auth hook supporting OTP, deep links, and biometrics.
strategy?: 'otp' | 'deep-link' | 'biometric' | 'hybrid'(Default:'hybrid')cooldownSeconds?: number(Default:60)codeLength?: number(Default:6)tokenParamName?: string(Default:'token')onSendOtp?: (recipient: string) => Promise<void>onVerifyOtp?: (code: string) => Promise<TToken>onBiometricSuccess?: () => Promise<TToken> | TTokenonVerified?: (token?: TToken) => voidonError?: (error: Error) => void
status:AuthStatusstate:AuthState<TToken, Error>resendIn:numbersendOtp:(recipient: string) => Promise<void>verifyOtp:(code: string) => Promise<void>handleDeepLink:(url: string) => voidauthenticateWithBiometrics:(options?: BiometricOptions) => Promise<boolean>clearError:() => voidreset:() => void
length?: number: Number of digit boxes (Default:6).value: string: Current OTP code string.onChange: (value: string) => void: Change handler.onComplete?: (code: string) => void: Fired when all boxes are filled.disabled?: boolean: Disables input fields (Default:false).autoFocus?: boolean: Focuses first box on mount (Default:true).onEditStart?: () => void: Fired on user typing; connect toclearError().
containerStyle?: React.CSSPropertiesinputStyle?: React.CSSProperties
containerStyle?: objectinputStyle?: object
Zero-dependency state machine container.
getState(): AuthState<TData, TError>dispatch(action: AuthAction<TData, TError>): AuthState<TData, TError>subscribe(listener: AuthStateMachineListener<TData, TError>): () => void
Standard error class with machine-readable error codes:
export type AuthErrorCode =
| 'INVALID_CODE'
| 'COOLDOWN_ACTIVE'
| 'STRATEGY_DISABLED'
| 'MISSING_DEPENDENCY'
| 'NO_HANDLER'
| 'AUTH_FAILED';
// COOLDOWN_ACTIVE and STRATEGY_DISABLED are reserved; the hooks currently no-op in those cases.parseAuthDeepLink(url: string, tokenParamName?: string): DeepLinkParseResultaddDeepLinkListener(callback: (url: string) => void): () => void(links received while the app is running)getInitialAuthDeepLink(): Promise<string | null>(the link that cold-started the app; call once on startup)isBiometricAvailable(): Promise<boolean>(resolvesfalsewhenexpo-local-authenticationis not installed)authenticateBiometric(options?: BiometricOptions): Promise<BiometricResult>
# Run unit and integration tests
npm test
# Run static type checks
npm run typecheck
# Build ESM, CJS, and .d.ts artifacts
npm run buildDistributed under the MIT License. See LICENSE for details.
Copyright (c) 2026 Salatech