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.fetch override for HTTP requests
• XMLHttpRequest override for legacy applications
• reCAPTCHA network request blocking

Virtual Mode (Local Mock)

In Virtual mode, the engine:

1. 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

2. 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

3. Virtual Number Notification: Displays iOS/Android-styled toast with:

   • Virtual phone number
   • Copy button
   • Auto-dismiss after 60 seconds

4. OTP Generation: Generates 6-digit random OTP and displays in notification

reCAPTCHA Mocking

The feature includes stealth reCAPTCHA mocking:

grecaptcha Override:

• Patches window.grecaptcha object
• Mocks render(), execute(), reset(), getResponse()
• Returns mock token: emuluxe-mock-recaptcha-token

Firebase RecaptchaVerifier Override:

• Replaces firebase.auth.RecaptchaVerifier class
• 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:

1. Communicates with Platform API for virtual number assignment
2. Routes OTP requests through platform infrastructure
3. Supports advanced features like real SMS forwarding
4. Requires Pro tier authentication

Authentication Flow Interception

Firebase Phone Auth:

1. Intercepts signInWithPhoneNumber(phoneNumber, verifier)
2. Checks if phone matches virtual number
3. Returns mock ConfirmationResult
4. Generates mock OTP on verification
5. Validates OTP against generated code

Clerk.dev:

1. Intercepts /v1/client/sign_in_attempts requests
2. Returns mock sign-in attempt ID
3. Generates mock OTP on verification
4. Validates OTP against generated code

Generic SMS:

1. Intercepts POST requests containing phone numbers
2. Matches against virtual number pool
3. Generates mock OTP
4. 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:

1. Open Device Settings panel
2. Navigate to "SMS / OTP Bridge" section
3. Select mode: Off, Virtual, or Bridge
4. For Virtual mode, virtual number is auto-assigned
5. For Bridge mode, ensure Pro tier and valid authentication

Chrome Extension:

1. Click Emuluxe toolbar icon
2. Expand "SMS / OTP Bridge" control
3. Use segmented control to select mode
4. View virtual number and OTP inbox

VS Code Extension:

1. Open Emuluxe panel (Cmd+Alt+E)
2. Navigate to Device Features
3. Toggle SMS/OTP Bridge controls
4. View virtual number and OTPs in sidebar

Testing with Firebase Phone Auth

Steps:

1. Enable SMS/OTP Bridge in Virtual mode
2. Navigate to Firebase Phone Auth demo
3. Enter virtual number: +1 555 012 3456
4. Click "Verify"
5. reCAPTCHA is automatically bypassed
6. OTP appears in notification
7. 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:

1. Enable SMS/OTP Bridge in Virtual mode
2. Navigate to Clerk.dev authentication demo
3. Enter virtual number
4. Click "Send code"
5. OTP appears in notification
6. 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:

1. Enable SMS/OTP Bridge in Virtual mode
2. Navigate to any site with SMS verification
3. Enter virtual number
4. Request verification code
5. OTP appears in notification
6. Enter OTP to complete

Expected Behavior:

• POST requests intercepted and mocked
• Generic success response returned
• OTP generated and displayed

reCAPTCHA Bypass Verification

Verification Steps:

1. Open browser DevTools Console
2. Look for [Emuluxe SMS] debug messages
3. Check that grecaptcha is mocked:

   window.grecaptcha.getResponse() // Returns "emuluxe-mock-recaptcha-token"
   

4. 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