Bonus Abuse

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // Pass the hashed account id, never a raw email or user id.
  // forceCheckAuthenticatedUser resets the visit session first, so the claim
  // starts a fresh session keyed to a requestID you can act on.
  // The callback's first arg is the client IP the server saw (not a score);
  // the score is read server-side via the webhook or History API.
  mod.forceCheckAuthenticatedUser('8a9f-hashed-account-id', (ip, requestID) => {
    document.getElementById('shield-request-id').value = requestID;
  });
</script>

<form method="POST" action="/api/claim-bonus">
  <input type="hidden" id="shield-request-id" name="shieldRequestId" />
  <input type="text" name="bonusCode" placeholder="Bonus code" />
  <button type="submit">Claim bonus</button>
</form>

{
  "request_id": "13f84f05-7c2a-4e9b-9f1d-2a6b8c0e4d11",
  "device_id": "5eb7fd5c-2a1b-4c3d-9e8f-7a6b5c4d3e2f",
  "visitor_id": "161dfbad-8e7f-4a6b-9c5d-0e1f2a3b4c5d",
  "user_hid": "a1b2c3d4hasheduserid",
  "public_ip": { "ip": "203.0.113.42", "country": "NL" },
  "local_ip": { "ip": "10.4.7.19", "country": "PL" },
  "risk_score": 20,
    "signals": [
    { "name": "Datacenter IP", "weight": 10 },
    { "name": "Abuser Flag", "weight": 10 }
  ],
  "detection_flags": { "ip_mismatch": true, "datacenter_ip": true, "abuser": true },
  "observed_at": "2026-06-16T18:00:45Z"
}

app.post('/api/claim-bonus', async (req, res) => {
  const { accountId, bonusCode, shieldRequestId } = req.body;

  // 1. Your normal bonus checks first (code valid, not already claimed by this
  //    account, within the campaign window).
  if (!(await bonusIsClaimable(bonusCode, accountId))) {
    return res.status(409).json({ error: 'bonus_not_claimable' });
  }

  // 2. Read the scored result for this session (webhook cache, then History
  //    fallback). waitForScore is the shared helper.
  const shield = await waitForScore(shieldRequestId, 2000);
  const score    = shield?.score ?? 0;        // 0-100 anonymity of this claim
  const deviceId = shield?.device_id;

  // 3. The all-zero DeviceID is "no device", not a new one. A blocked or
  //    JS-disabled browser returns it with a score of 90 or higher — gate on the
  //    score and skip the device count for it.
  const NIL = '00000000-0000-0000-0000-000000000000';
  const usableDevice = deviceId && deviceId !== NIL;

  // 4. Link related accounts on the durable device_id: how many distinct
  //    accounts has this one machine already used to claim the bonus?
  let accountsOnDevice = 0;
  if (usableDevice) {
    const rows = await shieldHistory('device_id', deviceId, 100);
    accountsOnDevice = new Set(rows.map((r) => r.user_hid).filter(Boolean)).size;
  }

  // 5. YOUR code decides. Branch on the score band and the account count,
  //    never on a signal label string.
  if (score >= 60 || accountsOnDevice >= YOUR_ACCOUNT_LIMIT) {
    // Masked claim, or one device farming many accounts: hold for verification.
    return res.status(200).json({ requireVerification: true, reason: 'bonus_already_claimed_on_device' });
  }

  // Clean enough and a fresh device: credit the bonus.
  return grantBonus(req, res);
});

curl "https://account.shieldlabs.ai/api/v1/history/device_id/5eb7fd5c-2a1b-4c3d-9e8f-7a6b5c4d3e2f?limit=100" \
  -H "Authorization: Bearer sec_your_private_api_key"