Promo Abuse

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

  // An identification for this redemption, even inside the five-minute window,
  // started when the form comes into use. 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 treats the
  // redemption as unverified. 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="redeem-form" method="POST" action="/api/redeem">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <input type="text" name="couponCode" placeholder="Coupon code" />
  <button type="submit">Apply reward</button>
</form>

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

app.post('/api/redeem', async (req, res) => {
  const { couponCode, shieldlabsRequestId } = req.body;
  const accountId = req.user.id;
  const userHid = req.user.hashedId; // the hashed id you pass to the snippet

  // 1. Your normal redemption checks first (code valid, not already used by
  //    this account, within campaign window).
  if (!(await couponIsRedeemable(couponCode, accountId))) {
    return res.status(409).json({ error: 'Coupon not redeemable' });
  }

  // 2. The guard: read this redemption's identification (webhook cache, then
  //    History fallback). No identification is unverified, never clean.
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk) {
    return res.status(200).json({ requireVerification: true, reason: 'no_identification' });
  }
  if (risk.user_hid !== userHid) {
    return res.status(200).json({ requireVerification: true, reason: 'identification_mismatch' });
  }
  if (risk.risk_score > 100) {
    // The 999 rate-limit marker.
    return res.status(200).json({ requireVerification: true, reason: 'rate_limit_marker' });
  }
  const flags = risk.detection_flags ?? {};
  const signals = risk.signals ?? []; // null on the History fallback; log them with your decision

  // 3. Use detection_flags to tell which signal fired: a 30 from one signal is
  //    not a 30 from another. Dangerous, or automated: hold before granting.
  const automated = flags.browser_automation || flags.javascript_disabled;
  if (band(risk.risk_score) === 'Dangerous' || automated) {
    return res.status(200).json({ requireVerification: true, reason: 'risk_signals' });
  }

  // VPN, proxy or datacenter alone is common for real customers: weigh it
  // against the account and the device in the next steps.
  const masked = flags.vpn || flags.proxy || flags.privacy_relay
    || flags.browser_vpn_proxy || flags.datacenter_ip;
  return grantOrGate(req, res, risk, userHid, masked);
});

// Returns why the reward should wait, or null when the account looks clean.
async function accountHold(userHid, risk) {
  // Accounts with a Multi-accounting event, recorded in your own store when it
  // arrives through the API or webhooks or when you review it in the analytics
  // dashboard: null, 'medium' or 'high' (its confidence).
  const marked = await markedAccounts.get(userHid);
  if (marked === 'high') return 'deny';
  if (marked) return 'marked_account';

  // The account's earlier identifications (newest 100), without this one.
  const account = await accountView(userHid, { excludeRequestId: risk.request_id });
  if (account.worstBand === 'Dangerous') return 'dangerous_history';
  if (account.devices.size >= YOUR_DEVICE_LIMIT) return 'many_devices';
  return null;
}

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 grantOrGate(req, res, risk, userHid, masked) {
  // 1. The account behind the redemption (previous step).
  //    A failed History read is unverified: the reward waits for verification.
  const hold = await accountHold(userHid, risk).catch(() => 'history_unavailable');
  if (hold === 'deny') {
    return res.status(403).json({ error: 'reward_denied', reason: 'held_for_review' });
  }
  if (hold) {
    return res.status(200).json({ requireVerification: true, reason: hold });
  }

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

  // 3. Distinct accounts already seen on this device ("anonymous" is not an
  //    account). YOUR_ACCOUNT_LIMIT is your per-customer policy. A masked
  //    redemption on a device that already carries another account also waits.
  const accountsOnDevice = await accountsBehindDevice(risk.device_id).catch(() => null);
  if (accountsOnDevice === null) {
    return res.status(200).json({ requireVerification: true, reason: 'history_unavailable' });
  }
  if (accountsOnDevice >= YOUR_ACCOUNT_LIMIT || (masked && accountsOnDevice > 1)) {
    return res.status(200).json({ requireVerification: true, reason: 'reward_already_claimed_on_device' });
  }

  // 4. Clear: grant the reward.
  return grantReward(req, res);
}