SMS Pumping

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // Anonymous signup / phone-verify form: no account yet.
  mod.checkAnonymous(undefined, (ip, requestID) => {
    document.getElementById('shield-request-id').value = requestID;
  });
</script>

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

  // Pull the ShieldLabs result for this session (snake_case, as the
  // webhook and account History API deliver it).
  const shield   = await waitForScore(shieldRequestId, 1500);
  const deviceId = shield?.device_id;
  const localIp  = shield?.local_ip?.ip;   // real network IP, not the public one
  const score    = shield?.score ?? 0;        // 0–100

  // A blocked or JS-disabled session can return an all-zero DeviceID.
  // Treat that as "device unknown": fall back to the local IP counter
  // instead of letting many distinct sessions collapse onto one zero key.
  const ZERO_DEVICE = '00000000-0000-0000-0000-000000000000';
  const deviceKey = (deviceId && deviceId !== ZERO_DEVICE) ? deviceId : null;

  // YOUR counters, in YOUR datastore. ShieldLabs supplies the keys, not the tally.
  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. A masked session asking for paid codes is the typical pumping shape.
  if (score >= 60) {
    return res.status(200).json({ action: 'require_captcha' }); // High band
  }

  // Clear enough to send the SMS. YOUR provider, YOUR call.
  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"

async function deviceAccountFanOut(deviceId) {
  const rows = await shieldHistory('device_id', deviceId, 100);
  return new Set(rows.map((r) => r.user_hid).filter(Boolean)).size; // distinct accounts
}

if ((await deviceAccountFanOut(deviceId)) >= YOUR_ACCOUNT_FANOUT_LIMIT) {
  return res.status(429).json({ action: 'rate_limited' });
}