Account Takeover (ATO)

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

  const rows = await shieldHistory('user_hid', userHid, 50); // your own recent sessions
  const knownDevices   = new Set(rows.map((r) => r.device_id).filter(Boolean));
  const knownCountries = new Set(rows.map((r) => r.country).filter(Boolean));

  // The all-zero DeviceID is "no device", not a new one. Do not treat it as
  // unseen, or every blocked or JS-disabled login looks like a fresh device.
  const NIL = '00000000-0000-0000-0000-000000000000';
  const usableDevice = deviceId && deviceId !== NIL;

  const newDevice  = usableDevice && !knownDevices.has(deviceId);
  const newCountry = country && knownCountries.size > 0 && !knownCountries.has(country);

  // A High-weight environment signal on an established account is itself
  // takeover-shaped: Anti-detect Browser (60), OS Mismatch (60),
  // JavaScript Disabled (90). Read them off the same cached payload.
  const strongSignal = (shield?.signals ?? []).some((s) => s.weight >= 60);

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

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

app.post('/api/login', async (req, res) => {
  const { username, password, shieldRequestId } = 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. Wait briefly for the score; the helper falls back to History by request_id.
  const shield = await waitForScore(shieldRequestId, 2000);
  if (!shield) {
    // Missing data is not "clean". Default an established account to a second factor.
    return res.status(200).json({ status: 'require_2fa', reason: 'verifying' });
  }

  // 3. The device-and-location comparison unique to takeover.
  const { score, newDevice, newCountry, strongSignal } =
    await takeoverRisk(user.hashedId, shield);

  // 4. Combine. Branch on the Score band and the boolean facts, never on a
  //    signal label string. A High-weight environment signal escalates alone.
  if (strongSignal || (newDevice && (newCountry || score >= 60))) {
    await alertAccountOwner(user.id, shield);          // notify the real owner
    return res.status(200).json({ status: 'verify', method: 'strong' });
  }
  if (newDevice || score >= 30) {
    return res.status(200).json({ status: 'require_2fa', method: 'otp' });
  }

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