Account Takeover

// Runs after your password check passes, before you issue the session.
async function takeoverRisk(userHid, risk) {
  const score    = risk.risk_score;           // 0-100, this login's Risk Score
  const deviceId = risk.device_id;
  const country  = risk.public_ip?.country;   // the public IP's country

  // The account's signed-in history. The login attempt is identified with
  // forceCheckAnonymous, so it is not part of it. Throws when the History read fails.
  const account = await accountView(userHid);

  // The all-zero Device ID is "no device", not a new one. Do not treat it as unseen.
  const usableDevice = deviceId && deviceId !== NIL_DEVICE;

  // Only an account with history can have a "new" device or country.
  const newDevice  = usableDevice && account.devices.size > 0 && !account.devices.has(deviceId);
  const newCountry = Boolean(country) && account.countries.size > 0 && !account.countries.has(country);

  // The account's worst band over its recent identifications.
  const accountWasDangerous = account.worstBand === 'Dangerous';

  // A heavy signal on an established account is itself takeover-shaped:
  // Tor (99), JavaScript Disabled (90), Browser Automation (60),
  // Anti-detect Browser (60), OS Mismatch (60). The flags are on the webhook
  // and on the History fallback; signals[] is on the webhook only.
  const flags = risk.detection_flags ?? {};
  const strongSignal =
    flags.tor || flags.javascript_disabled || flags.browser_automation ||
    flags.anti_detect_browser || flags.os_mismatch ||
    (risk.signals ?? []).some((s) => s.weight >= 60);

  return { score, newDevice, newCountry, accountWasDangerous, strongSignal };
}

curl "https://account.shieldlabs.ai/api/v1/history/user_hid/a1b2c3d4hasheduserid?limit=100" \
  -H "Authorization: Bearer sec_your_private_api_key"

app.post('/api/login', async (req, res) => {
  const { username, password, shieldlabsRequestId } = req.body;

  // 1. Your normal credential check first.
  const user = await verifyPassword(username, password);
  if (!user) return res.status(401).json({ error: 'invalid_credentials' });

  // 2. The guard. Missing data is not "clean": default an established account
  //    to a second factor. Every login attempt is identified with
  //    forceCheckAnonymous, so the identification carries "anonymous".
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk) {
    return res.status(200).json({ status: 'require_2fa', reason: 'no_identification' });
  }
  if (risk.user_hid !== 'anonymous') {
    return res.status(200).json({ status: 'require_2fa', reason: 'identification_mismatch' });
  }
  if (risk.risk_score > 100 || risk.device_id === NIL_DEVICE) {
    // The 999 rate-limit marker, or no usable device signals.
    return res.status(200).json({ status: 'require_2fa', reason: 'unverified_device' });
  }

  // 3. The device-and-location comparison unique to takeover.
  //    A failed History read is unverified: default to a second factor.
  const facts = await takeoverRisk(user.hashedId, risk).catch(() => null);
  if (!facts) {
    return res.status(200).json({ status: 'require_2fa', reason: 'history_unavailable' });
  }
  const { score, newDevice, newCountry, accountWasDangerous, strongSignal } = facts;

  // 4. Accounts with an Account takeover event, recorded when it arrives through
  //    the API or webhooks or when you review it in the analytics dashboard
  //    (your own store).
  const watched = await takeoverWatchlist.has(user.hashedId);

  // 5. Combine. Branch on the band and the boolean facts; signals[].name slugs
  //    are stable if one signal matters on its own. A heavy signal escalates alone.
  if (strongSignal || (newDevice && (newCountry || accountWasDangerous || score >= 60))) {
    await alertAccountOwner(user.id, risk);          // notify the real owner
    return res.status(200).json({ status: 'verify', method: 'strong' });
  }
  if (watched || newDevice || score >= 30) {
    return res.status(200).json({ status: 'require_2fa', method: 'otp' });
  }

  // Known device, clean login: issue the session, no extra friction.
  return issueSession(user, res);
});