SMS / OTP Bridge
The SMS/OTP Bridge feature simulates SMS verification and OTP (One-Time Password) functionality, allowing you to test authentication flows without real phone numbers or SMS services. This feature intercepts SDK calls and network requests to provide virtual phone numbers and mock OTPs.
Overview
This feature provides three modes for SMS/OTP simulation:
- Off: Disables SMS/OTP simulation entirely
- Virtual (Local Mock): Uses a fixed pool of virtual numbers and generates mock OTPs locally
- Bridge (API Integration): Integrates with platform API for advanced SMS routing (Pro tier)
Target Users
- Frontend developers implementing phone authentication
- QA engineers testing SMS verification flows
- Security researchers testing OTP security
- Product managers evaluating authentication providers
Use Cases
- Test Firebase Phone Auth without real SMS
- Test Clerk.dev authentication flows
- Test generic SMS verification implementations
- Debug reCAPTCHA integration issues
- Test OTP validation logic
- Verify phone input detection UI
How It Works
Technical Implementation
The feature uses SDK-level interception for maximum reliability:
SDK Interception:
- Firebase Auth SDK (
signInWithPhoneNumber,RecaptchaVerifier) - Clerk.dev SDK (
signInWithPhoneNumber) - Generic fetch/XHR interception for fallback
Network Interception:
window.fetchoverride for HTTP requestsXMLHttpRequestoverride for legacy applications- reCAPTCHA network request blocking
Virtual Mode (Local Mock)
In Virtual mode, the engine:
-
Virtual Number Pool: Uses fixed numbers:
+1 555 012 3456+1 555 987 6543+1 555 246 8135+44 20 7946 0958+33 1 42 86 83 33
-
Phone Input Detection: Automatically detects phone input fields using:
- CSS selectors (
input[type="tel"],input[autocomplete="tel"]) - Name attributes (
phone,mobile,msisdn) - Placeholder text matching
- Fuzzy label detection
- CSS selectors (
-
Virtual Number Notification: Displays iOS/Android-styled toast with:
- Virtual phone number
- Copy button
- Auto-dismiss after 60 seconds
-
OTP Generation: Generates 6-digit random OTP and displays in notification
reCAPTCHA Mocking
The feature includes stealth reCAPTCHA mocking:
grecaptcha Override:
- Patches
window.grecaptchaobject - Mocks
render(),execute(),reset(),getResponse() - Returns mock token:
emuluxe-mock-recaptcha-token
Firebase RecaptchaVerifier Override:
- Replaces
firebase.auth.RecaptchaVerifierclass - Immediate token resolution without rendering
- Hardened against bot detection
Stealth Injection:
- Uses Symbol for injection marker (not discoverable via Object.keys)
- Hardens patched functions to appear native
- Polls silently for grecaptcha appearance
Bridge Mode (API Integration)
In Bridge mode, the engine:
- Communicates with Platform API for virtual number assignment
- Routes OTP requests through platform infrastructure
- Supports advanced features like real SMS forwarding
- Requires Pro tier authentication
Authentication Flow Interception
Firebase Phone Auth:
- Intercepts
signInWithPhoneNumber(phoneNumber, verifier) - Checks if phone matches virtual number
- Returns mock
ConfirmationResult - Generates mock OTP on verification
- Validates OTP against generated code
Clerk.dev:
- Intercepts
/v1/client/sign_in_attemptsrequests - Returns mock sign-in attempt ID
- Generates mock OTP on verification
- Validates OTP against generated code
Generic SMS:
- Intercepts POST requests containing phone numbers
- Matches against virtual number pool
- Generates mock OTP
- Returns success response
Architecture-Specific Implementation
Web Platform (Primary)
Location: src/engines/sms-simulation-engine.js
The Web Platform implementation includes:
- Dynamic script injection with stealth markers
- Platform API integration for Bridge mode
- Session-based configuration management
- iOS/Android-styled notifications
Key Features:
- Symbol-based injection for stealth
- Hardened function patching against bot detection
- MutationObserver for phone input detection
- Auto-dismissing notifications
Chrome Extension
Location: engine/sms-simulation-engine.js
The extension implementation mirrors the platform with:
- MAIN world injection via content scripts
- chrome.storage for configuration persistence
- Extension panel for SMS inbox display
- Background script for API relay
Key Differences:
- Uses chrome.runtime messaging
- SMS inbox UI in extension panel
- Integrates with device simulation context
VS Code Extension
Location: src/extension.ts (UI controls only)
The VS Code extension provides:
- UI controls for mode selection (Off/Virtual/Bridge)
- Virtual number display
- OTP inbox list
- Delegates actual simulation to platform
Integration: Sends commands to platform via vscode.postMessage, which then injects the engine.
Testing Guide
Enabling the Feature
Web Platform:
- Open Device Settings panel
- Navigate to "SMS / OTP Bridge" section
- Select mode: Off, Virtual, or Bridge
- For Virtual mode, virtual number is auto-assigned
- For Bridge mode, ensure Pro tier and valid authentication
Chrome Extension:
- Click Emuluxe toolbar icon
- Expand "SMS / OTP Bridge" control
- Use segmented control to select mode
- View virtual number and OTP inbox
VS Code Extension:
- Open Emuluxe panel (Cmd+Alt+E)
- Navigate to Device Features
- Toggle SMS/OTP Bridge controls
- View virtual number and OTPs in sidebar
Testing with Firebase Phone Auth
Steps:
- Enable SMS/OTP Bridge in Virtual mode
- Navigate to Firebase Phone Auth demo
- Enter virtual number:
+1 555 012 3456 - Click "Verify"
- reCAPTCHA is automatically bypassed
- OTP appears in notification
- Enter OTP to complete verification
Expected Behavior:
- reCAPTCHA widget may render but is automatically solved
- Virtual number notification appears when phone input is detected
- OTP notification appears after verification request
- Verification succeeds with mock OTP
Testing with Clerk.dev
Steps:
- Enable SMS/OTP Bridge in Virtual mode
- Navigate to Clerk.dev authentication demo
- Enter virtual number
- Click "Send code"
- OTP appears in notification
- Enter OTP to complete sign-in
Expected Behavior:
- Clerk sign-in attempt created successfully
- OTP generated and displayed
- Verification succeeds with mock OTP
Testing with Generic SMS Flows
Steps:
- Enable SMS/OTP Bridge in Virtual mode
- Navigate to any site with SMS verification
- Enter virtual number
- Request verification code
- OTP appears in notification
- Enter OTP to complete
Expected Behavior:
- POST requests intercepted and mocked
- Generic success response returned
- OTP generated and displayed
reCAPTCHA Bypass Verification
Verification Steps:
- Open browser DevTools Console
- Look for
[Emuluxe SMS]debug messages - Check that grecaptcha is mocked:
window.grecaptcha.getResponse() // Returns "emuluxe-mock-recaptcha-token" - Verify no reCAPTCHA network errors in Network tab
Expected Behavior:
- reCAPTCHA network requests blocked
- Mock token returned to application
- No 401 errors from reCAPTCHA endpoints
Common Issues and Troubleshooting
Issue: Virtual number notification doesn't appear
- Cause: Phone input not detected or already dismissed
- Fix: Reload page, manually dismiss notification, check input field attributes
Issue: OTP not generated after verification request
- Cause: Request not intercepted or number doesn't match
- Fix: Check console for interception logs, verify number format matches virtual pool
Issue: reCAPTCHA error appears
- Cause: grecaptcha not loaded or not patched in time
- Fix: Reload page, check for grecaptcha polling in console
Issue: Firebase Auth fails with "invalid-verification-code"
- Cause: OTP entered incorrectly or generated for different request
- Fix: Use latest OTP from notification, wait for new OTP if expired
Issue: Clerk sign-in fails
- Cause: Clerk SDK not intercepted or version mismatch
- Fix: Check console for Clerk interception logs, verify SDK version
Issue: Bridge mode fails with "Plan limit reached"
- Cause: Free tier attempting Bridge mode
- Fix: Upgrade to Pro tier or use Virtual mode
Recommended Testing Sites
Firebase Phone Auth
Firebase Auth Demo - https://firebase.google.com/docs/auth/web/phone-auth
- Official Firebase documentation demo
- Test phone number verification
- Verify reCAPTCHA integration
- Check OTP validation
FirebaseUI Web Demo - https://github.com/firebase/firebaseui-web
- Full FirebaseUI authentication flow
- Test phone sign-in with reCAPTCHA
- Verify UI states and error handling
Clerk.dev Authentication
Clerk Authentication Playground - https://clerk.com/docs/quickstarts
- Clerk's official demo environment
- Test phone number authentication
- Verify SMS verification flow
- Check error handling
Generic SMS Testing
Twilio Phone Verification Demo - https://www.twilio.com/docs/verify
- Twilio's verification demo
- Test generic SMS flows
- Verify OTP input validation
- Check UI feedback
Auth0 Phone Verification - https://auth0.com/docs/authenticate/phone-sms
- Auth0's SMS verification demo
- Test phone number input
- Verify OTP entry flow
- Check error states
Benefits for Users
Test Authentication Flows Without Real SMS
- No need for real phone numbers
- No SMS service costs
- Instant OTP generation
- No dependency on carrier networks
Test OTP Validation Logic
- Verify OTP format validation
- Test OTP expiration handling
- Check retry logic
- Validate error messages
Debug reCAPTCHA Integration Issues
- Bypass reCAPTCHA during development
- Test reCAPTCHA error handling
- Verify reCAPTCHA token usage
- Debug reCAPTCHA UI issues
Test Multiple Authentication Providers
- Test Firebase, Clerk, and generic flows
- Compare provider implementations
- Validate consistent behavior
- Test provider switching
Stealth Mode for Bot Detection
- Undetectable by Cloudflare Turnstile
- Hardened function patching
- Symbol-based injection
- No discoverable markers
iOS/Android-Styled Notifications
- Authentic mobile notification look
- Device-specific styling
- Auto-dismiss behavior
- Copy functionality for convenience