Coupon Abuse

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // Rendered by your server: the shopper's hashed account id, or null for guest checkout.
  const hashedAccountId = '8a9f-hashed-account-id';
  const form = document.getElementById('coupon-form');

  // 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 discount.
  const onInitialized = (result) => {
    if (result.status === 'initialized') {
      document.getElementById('shieldlabs-request-id').value = result.requestID;
    }
  };
  // A fresh identification for this apply-code, started when the form comes into use.
  const identify = () => {
    if (hashedAccountId) {
      mod.forceCheckAuthenticatedUser(hashedAccountId, { onInitialized });
    } else {
      mod.forceCheckAnonymous({ onInitialized });
    }
  };
  if (form.contains(document.activeElement)) identify(); // already focused (autofocus)
  else form.addEventListener('focusin', identify, { once: true });
</script>

<form id="coupon-form" method="POST" action="/api/apply-coupon">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <input type="text" name="couponCode" placeholder="Coupon code" />
  <button type="submit">Apply code</button>
</form>

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

app.post('/api/apply-coupon', async (req, res) => {
  const { couponCode, shieldlabsRequestId } = req.body;
  const userHid = req.user?.hashedId ?? null; // the hashed id you pass to the snippet; null for guests

  // 1. Your own commerce checks first: code exists, in its valid window,
  //    not already marked spent (for single-use codes), within cart rules.
  const coupon = await lookupCoupon(couponCode);
  if (!coupon || !coupon.active) {
    return res.status(409).json({ error: 'Coupon not valid' });
  }
  if (coupon.singleUse && coupon.spent) {
    // A single-use code applied again is reuse on its face: refuse outright.
    return res.status(409).json({ error: 'Coupon already redeemed' });
  }

  // 2. The guard: read this apply-code's identification. 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 (userHid && 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 ?? {};

  // 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 honoring.
  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 shoppers: weigh it
  // against the account and the redemption count in the next steps.
  const masked = flags.vpn || flags.proxy || flags.privacy_relay
    || flags.browser_vpn_proxy || flags.datacenter_ip;
  return countAndDecide(req, res, risk, coupon, userHid, masked);
});

// Returns why the discount 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) return marked === 'high' ? 'marked_high' : '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';
  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 redemptionsFromDevice(deviceId, couponCode) {
  const rows = await shieldlabsHistory('device_id', deviceId, 100);
  // Your own store records which coupon each request_id redeemed. Join the
  // device's identifications to your redemption log for this code.
  return countYourRedemptions(rows.map((r) => r.request_id), couponCode);
}

async function countAndDecide(req, res, risk, coupon, userHid, masked) {
  // 1. Signed-in shoppers: the account behind the apply-code (previous step).
  if (userHid) {
    // A failed History read is unverified: the discount waits for verification.
    const hold = await accountHold(userHid, risk).catch(() => 'history_unavailable');
    if (hold === 'marked_high') {
      return res.status(409).json({ error: 'discount_refused', 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 on, so hold the discount for verification.
  if (risk.device_id === NIL_DEVICE) {
    return res.status(200).json({ requireVerification: true, reason: 'no_device' });
  }

  // 3. Count this code's redemptions off this one device and Local IP.
  //    local_ip.ip is empty when not captured; local_ip is null on the History fallback.
  const localIp = risk.local_ip?.ip;
  const fromDevice = await redemptionsFromDevice(risk.device_id, coupon.code).catch(() => null);
  if (fromDevice === null) {
    return res.status(200).json({ requireVerification: true, reason: 'history_unavailable' });
  }
  // From your own redemption log: the History API has no Local IP search.
  const fromLocal = localIp ? await redemptionsFromLocalIp(localIp, coupon.code) : 0;

  // YOUR_PER_CUSTOMER_LIMIT is your policy (usually 1 for a one-per-customer
  // code). A single-use code already spent was refused upstream. A masked
  // apply-code on a device that already redeemed this code also waits.
  if (fromDevice >= YOUR_PER_CUSTOMER_LIMIT || fromLocal >= YOUR_PER_NETWORK_LIMIT
    || (masked && fromDevice > 0)) {
    return res.status(200).json({ requireVerification: true, reason: 'code_already_redeemed_here' });
  }

  // Clear: honor the discount and record the redemption against this device.
  return honorDiscount(req, res, { deviceId: risk.device_id, requestId: risk.request_id });
}