Account Takeover

// 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?.deviceID;
  const country  = shield?.country;

  // Pull the account's recent sessions. Each returned row bills 1 request,
  // so cap the limit and reserve this read for accounts worth protecting.
  const rows = await shieldHistory('user_hid', userHid, 50);

  const knownDevices   = new Set(rows.map((r) => r.DeviceID).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);

  return { score, newDevice, newCountry };
}

curl "https://api.shieldlabs.ai/{domain}:{secret}/history/user_hid/a1b2c3d4hasheduserid?limit=50"

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; fall back to a History read by request_id.
  //    waitForScore and the webhook handler are the shared Cookbook helper.
  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 } = await takeoverRisk(user.hashedId, shield);

  // 4. Combine. A new device plus a new country, or a new device on an
  //    anonymized session, escalates. Branch on the Score band and the
  //    boolean facts above, never on a Details Description label string.
  if (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);
});