Loyalty Fraud

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

  // The Device ID and Risk Score reach your server by webhook;
  // result.requestID joins them. onInitialized fires when the check starts,
  // before the snippet sends it, so it only stores the request ID and the form
  // submits normally. With no request ID, your backend holds the reward.
  // Pass the hashed account id, never a raw email.
  const identify = () => {
    mod.forceCheckAuthenticatedUser('8a9f-hashed-account-id', {
      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="reward-form" method="POST" action="/api/loyalty/redeem">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <input type="text" name="rewardId" placeholder="Reward" />
  <button type="submit">Redeem points</button>
</form>

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"

import { app, waitForScore, band, accountView, accountsBehindDevice, NIL_DEVICE } from '../../shieldlabs-helpers.js';

app.post('/api/loyalty/redeem', async (req, res) => {
  const { rewardId, shieldlabsRequestId } = req.body;
  const accountId = req.user.id;
  const userHid = req.user.hashedId; // the member's hashed id, as passed to the snippet

  // 1. Your normal program checks first (member owns the points, perk is
  //    eligible, within the campaign window).
  if (!(await rewardIsRedeemable(rewardId, accountId))) {
    return res.status(409).json({ error: 'reward_not_redeemable' });
  }

  // 2. The guard: read this action's identification. No identification is
  //    unverified, never clean.
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk) {
    return res.json({ requireVerification: true, reason: 'no_identification' });
  }
  if (risk.user_hid !== userHid) {
    return res.json({ requireVerification: true, reason: 'identification_mismatch' });
  }
  if (risk.risk_score > 100) {
    // The 999 rate-limit marker.
    return res.json({ requireVerification: true, reason: 'rate_limit_marker' });
  }

  // 3. The member: the High-Risk Event you recorded for it (your own store,
  //    written when the event arrives through the API or webhooks or when you
  //    review it in the analytics dashboard), then its earlier identifications.
  const mark = await memberMarks.get(userHid); // your own record, e.g. { event: 'Account takeover', confidence: 'high' }
  if (mark?.event === 'Account takeover') {
    // Points drain: the real member confirms it is them before any redemption.
    return mark.confidence === 'high'
      ? res.status(403).json({ error: 'redemptions_locked', reason: 'account_recovery' })
      : res.json({ requireReauthentication: true, reason: 'takeover_review' });
  }
  if (mark?.confidence === 'high') {
    return res.status(403).json({ error: 'reward_denied', reason: 'held_for_review' });
  }
  // A failed History read is unverified: hold the reward.
  const member = await accountView(userHid, { excludeRequestId: risk.request_id }).catch(() => null);
  if (!member) return res.json({ requireVerification: true, reason: 'history_unavailable' });
  if (mark || member.worstBand === 'Dangerous') {
    return res.json({ requireVerification: true, reason: 'risky_member' });
  }

  // 4. An all-zero Device ID means no usable device signals reached ShieldLabs:
  //    there is no device to count members on, so hold the reward.
  if (risk.device_id === NIL_DEVICE) {
    return res.json({ requireVerification: true, reason: 'no_device' });
  }

  // 5. Distinct member accounts behind this one device ("anonymous" is not an account).
  const accountsOnDevice = await accountsBehindDevice(risk.device_id).catch(() => null);
  if (accountsOnDevice === null) {
    return res.json({ requireVerification: true, reason: 'history_unavailable' });
  }
  if (accountsOnDevice >= YOUR_ACCOUNT_LIMIT) {
    return res.json({ requireVerification: true, reason: 'accounts_linked_to_device' });
  }

  // 6. The action itself, from the band and the IP countries, never from a
  //    label string. A masked network on a device other members use is the
  //    farm tell (local_ip is null on the History fallback).
  const countriesDiffer = Boolean(
    risk.local_ip?.country && risk.public_ip?.country
      && risk.local_ip.country !== risk.public_ip.country
  );
  if (band(risk.risk_score) === 'Dangerous' || (countriesDiffer && accountsOnDevice > 1)) {
    return res.json({ requireVerification: true, reason: 'risk_signals' });
  }
  if (band(risk.risk_score) === 'Suspicious') {
    await flagForReview(accountId, risk.device_id, risk); // Suspicious: grant, but watch
  }

  // Trusted, a clean member, one account on the device: award the reward.
  return grantReward(req, res);
});