Ban Evasion (Ban Enforcement)

// Call it from your webhook handler for each identification.scored webhook,
// after the signature check. History has no Local IP search, so keep each
// signed-in account's local IPs in your own store as the webhooks arrive.
async function recordLocalIp(data) {
  if (data.user_hid && data.user_hid !== 'anonymous' && data.local_ip?.ip) {
    await localIpsByAccount.add(data.user_hid, data.local_ip.ip);
  }
}

// At ban time, ban what travels with the account, not only its last session.
async function banUser(accountId, userHid, reason) {
  await markAccountBanned(accountId, reason);

  // Every device this account has used: the shared accountView helper reads the
  // account's identifications by user_hid (newest 100; page with offset for
  // long-lived accounts). The all-zero Device ID is never counted as a device.
  const account = await accountView(userHid);
  for (const deviceId of account.devices) {
    await banlist.addDevice(deviceId, { accountId, reason });
  }

  // Every local IP you recorded for the account, as a soft key. It is the
  // address the browser itself reports, which often stays the same when a VPN
  // or proxy rotates the public IP.
  for (const localIp of await localIpsByAccount.get(userHid)) {
    await banlist.addLocalIp(localIp, { accountId, reason });
  }
}

app.post('/api/session-open', async (req, res) => {
  const { shieldlabsRequestId } = req.body;

  // Session start is a guest flow: there is no User HID to match yet.
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk || risk.risk_score > 100 || risk.device_id === NIL_DEVICE) {
    // No identification, the 999 rate-limit marker, or no usable device
    // signals: route to review, never auto-ban and never auto-allow.
    return res.json({ action: 'review', reason: 'device_unknown' });
  }
  const deviceId = risk.device_id;
  const localIp  = risk.local_ip?.ip; // the address the browser reports; often stable when the public IP rotates
  const flags    = risk.detection_flags ?? {};

  // The core check: is this device on the banlist, whatever the cookie says?
  if (await banlist.hasDevice(deviceId)) {
    return res.json({ action: 'block', reason: 'banned_device_returned' });
  }

  // Defense in depth: same local IP as a banned session, on a new device.
  // Weaker on its own (a shared router, an office NAT), so review, do not block.
  if (localIp && (await banlist.hasLocalIp(localIp))) {
    return res.json({ action: 'review', reason: 'banned_local_ip' });
  }

  // A masked return on a new device. detection_flags holds the booleans,
  // including informational ones such as ip_mismatch, so compare the two IP
  // countries rather than branching on that flag alone.
  const countryDiffers =
    risk.local_ip?.country && risk.public_ip?.country &&
    risk.local_ip.country !== risk.public_ip.country;
  if (flags.anti_detect_browser || flags.browser_automation || countryDiffers) {
    return res.json({ action: 'review', reason: 'masked_return' });
  }

  return res.json({ action: 'allow' });
});