SMS Pumping

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  const form = document.getElementById('otp-form');

  // onInitialized fires when the check starts, before the snippet sends it.
  // Start the fresh identification when the form comes into use, so it is sent
  // while the user fills the form, and let the form submit normally.
  const identify = () => {
    // No account yet: forceCheckAnonymous. Signed in: forceCheckAuthenticatedUser.
    mod.forceCheckAnonymous({
      onInitialized: (result) => {
        if (result.status === 'initialized') {
          document.getElementById('shieldlabs-request-id').value = result.requestID;
        }
      },
    });
  };
  if (form.contains(document.activeElement)) identify(); // already focused (autofocus)
  else form.addEventListener('focusin', identify, { once: true });
</script>

<form id="otp-form" method="POST" action="/api/request-otp">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <input type="tel" name="phone" placeholder="Phone number" />
  <button type="submit">Send code</button>
</form>

app.post('/api/request-otp', async (req, res) => {
  const { phone, shieldlabsRequestId } = req.body;

  // Pull the ShieldLabs result for this session: the webhook `data` object
  // (the shared helper maps a History fallback to the same field names).
  const risk = await waitForScore(shieldlabsRequestId, 1500);
  if (!risk || risk.risk_score > 100) {
    // No identification (the snippet did not run, or a script skipped it) or
    // the 999 rate-limit marker: unverified, so no paid SMS without a CAPTCHA.
    return res.status(200).json({ action: 'require_captcha' });
  }
  const deviceId = risk.device_id;
  const localIp  = risk.local_ip?.ip;   // the address the browser reports, not the public IP
  const flags    = risk.detection_flags ?? {};

  // An all-zero Device ID means no usable device signals reached ShieldLabs.
  // Fall back to the local IP counter instead of letting many distinct
  // sessions collapse onto one zero key, and hold the send for a CAPTCHA.
  const deviceKey = deviceId !== NIL_DEVICE ? deviceId : null;

  // Your counters, in your datastore, keyed on what ShieldLabs returns.
  const perDevice = deviceKey ? await bumpSendCount(`otp:dev:${deviceKey}`) : 0; // 1h window
  const perLocal  = localIp   ? await bumpSendCount(`otp:lip:${localIp}`)   : 0; // 1h window

  // 1. One device (or one local network) flooding the verify flow,
  //    even across rotated public IPs and cleared cookies.
  if (perDevice > YOUR_DEVICE_SEND_LIMIT || perLocal > YOUR_LOCAL_IP_SEND_LIMIT) {
    return res.status(429).json({ action: 'rate_limited' });
  }

  // 2. No usable device, a bot, or a masked session asking for paid codes.
  if (!deviceKey || flags.browser_automation || flags.javascript_disabled ||
      band(risk.risk_score) === 'Dangerous') {
    return res.status(200).json({ action: 'require_captcha' });
  }

  // Clear enough to send the SMS through your provider.
  await sendVerificationSms(phone);
  return res.json({ action: 'sent' });
});

curl "https://account.shieldlabs.ai/api/v1/history/device_id/5eb7fd5c-1c5e-4a9f-9b21-7d2e8c0a1234?limit=100" \
  -H "Authorization: Bearer sec_your_private_api_key"

// Call it inside the request-otp handler, after the guard; a non-null result is the action.
async function fanOutAction(deviceId) {
  const accounts = await accountsBehindDevice(deviceId).catch(() => null);
  if (accounts === null) return 'require_captcha'; // a failed History read is unverified
  if (accounts >= YOUR_ACCOUNT_FANOUT_LIMIT) return 'rate_limited';
  return null;
}