Case Study: Hardware-Locked SMS Relay Gateway with Tampermonkey Sync

Executive Summary

In enterprise web automation, receiving SMS verification codes or automated alerts from physical mobile devices into browser environments presents a major infrastructure bottleneck. Relying on manual human entry breaks automation pipelines, while public webhooks introduce severe privacy risks.

This case study breaks down an automated SMS Relay & Security Vault system consisting of a mobile utility app, a Supabase backend server (https://sms-prd.vercel.app/), and a custom Tampermonkey browser script. The system features strict server-generated 1-to-1 license key device locking and targeted sender filtering.

The Problem & Engineering Constraints

When building a mobile SMS relay, three primary security and logistical constraints must be solved:

1. 1.Strict Device Access Control: The mobile application must not be usable by unauthorized third parties. Each app instance must require a valid license key generated directly from the backend server.
2. 2.1-to-1 Key Locking: Once a key is registered on a specific mobile device, it must become permanently locked to that device ID to prevent unauthorized multi-device sharing.
3. 3.Privacy & Targeted Forwarding: The utility must ignore personal SMS messages and exclusively forward incoming notifications from designated enterprise senders (e.g., *Gerry*).

Architectural Breakdown

+-------------------------------------------------------------------+
| PHYSICAL ANDROID MOBILE DEVICE                                    |
| - 24/7 Background SMS Listener (Sender Filter: "Gerry")           |
| - Server-Validated License Key Device Lock                        |
+-------------------------------------------------------------------+
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
        [ SIM-to-SIM RELAY ]            [ HTTP WEBHOOK RELAY ]
                                                 │
                                                 ▼
                                  +----------------------------------+
                                  | SUPABASE BACKEND SERVER          |
                                  | - License Validation DB          |
                                  | - Encrypted Message Logs         |
                                  +----------------------------------+
                                                 │
                                                 ▼
                                  +----------------------------------+
                                  | TAMPERMONKEY BROWSER SCRIPT      |
                                  | - Real-Time Webhook Consumer     |
                                  | - Automated Web Form Auto-Fill   |
                                  +----------------------------------+

Key Technical Features

1. Server-Side License Key Authentication

To prevent unauthorized usage, the mobile application remains locked upon installation. The user must input a unique activation key generated from the Supabase admin server.

When the user enters the key:

1. 1.Transmission: The mobile app sends an activation request payload containing the key and unique hardware Device ID.
2. 2.Verification: The Supabase API checks if the key code exists, is marked active, and has not yet been claimed.
3. 3.Hardware Locking: On successful validation, the key record is permanently tagged as claimed and bound to the requesting Device ID.
4. 4.Access Rejection: Any future requests from other devices using the same license key are blocked by backend RLS rules.

// Backend License Key Registration Logic (Supabase API)
export async function registerDeviceKey(activationKey, deviceId) {
  // 1. Fetch key record
  const { data: keyRecord, error } = await supabase
    .from('license_keys')
    .select('*')
    .eq('key_code', activationKey)
    .single();

  if (error || !keyRecord) {
    return { success: false, message: 'Invalid License Key' };
  }

  // 2. Check if key is already claimed by another device
  if (keyRecord.is_claimed) {
    if (keyRecord.bound_device_id !== deviceId) {
      return { success: false, message: 'Key is already locked to another device.' };
    }
    return { success: true, message: 'Device authenticated.' };
  }

  // 3. Bind key to this device permanently
  await supabase
    .from('license_keys')
    .update({ 
      is_claimed: true, 
      bound_device_id: deviceId, 
      activated_at: new Date().toISOString() 
    })
    .eq('id', keyRecord.id);

  return { success: true, message: 'Device registered successfully.' };
}

2. Dual Forwarding Mechanisms (SIM vs Webhook)

Inside the application UI, the user configures the target destination and permissions:

• Option A (SIM-to-SIM): Forwards incoming SMS directly to a secondary physical phone number via standard cellular network.
• Option B (SIM-to-Webhook): Relays the raw SMS content, timestamp, and sender ID as a JSON payload over HTTPS to the backend server endpoint.

3. Real-Time Tampermonkey Browser Auto-Fill

To complete the automation loop in web browsers:

• Operator Userscript: A lightweight Tampermonkey userscript runs inside the active browser session.
• Polling & Listening: The script monitors the Supabase webhook endpoint for newly arrived verification codes.
• Zero-Touch Autofill: Automatically extracts the numeric verification string and populates active form fields in real-time.

Production Links & Repositories

• Backend Server Dashboard: sms-prd.vercel.app
• GitHub Repository: github.com/aisquadx5-alt/sms

Lessons Learned

• Hardware Locking Prevents Abuse: Enforcing server-side key-to-device binding at the database level eliminates unauthorized app distribution.
• Targeted Filtering Preserves Privacy: Filtering at the background broadcast receiver level ensures that only designated transactional SMS messages leave the device, keeping personal messages completely untouched.