Step-up authentication (risk-based 2FA)

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  const form = document.getElementById('login-form');

  // The browser does NOT compute the Risk Score. onInitialized gives the
  // requestID, the join key to the webhook you receive server-side. It fires
  // when the check starts, before the snippet sends it, so start the fresh
  // identification when the form comes into use and let the form submit normally.
  // Every attempt is identified anonymously: the User HID comes after sign-in.
  const identify = () => {
    mod.forceCheckAnonymous({
      onInitialized: (result) => {
        if (result.status === 'initialized') {
          document.getElementById('shieldlabs-request-id').value = result.requestID;
        }
      },
    });
  };
  if (form.contains(document.activeElement)) identify(); // already focused (autofocus)
  else form.addEventListener('focusin', identify, { once: true });
</script>

<form id="login-form" method="POST" action="/api/login">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <input type="text" name="username" placeholder="Username" />
  <input type="password" name="password" placeholder="Password" />
  <button type="submit">Sign in</button>
</form>

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. Wait up to ~2s for the webhook; the helper falls back to the History API.
  const risk = await waitForScore(shieldlabsRequestId, 2000);

  // 3. The guard. No result is not the same as "clean": default to 2FA rather
  //    than letting a login through on missing data. Every login attempt is
  //    identified with forceCheckAnonymous, so the identification carries "anonymous".
  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' });
  }

  // 4. The account behind the login: its worst band over its signed-in history,
  //    and the accounts with an Account takeover event, recorded in your own store
  //    when it arrives through the API or webhooks or when you review it in the
  //    analytics dashboard.
  //    A failed History read is unverified: default to 2FA.
  const account = await accountView(user.hashedId).catch(() => null);
  if (!account) {
    return res.status(200).json({ status: 'require_2fa', reason: 'history_unavailable' });
  }
  const watched = await takeoverWatchlist.has(user.hashedId);

  // The threshold ladder. Branch on the band, and on signals[].name slugs
  // when one signal matters on its own. The bands are a guide, not a rule.
  const loginBand = band(risk.risk_score);
  if (loginBand === 'Dangerous') {
    // Strong risk signals folded into the score. Require your strongest
    // factor, or hold and alert the account owner.
    await alertAccountOwner(user.id, risk);
    return res.status(200).json({ status: 'verify', method: 'strong' });
  }

  if (loginBand === 'Suspicious' || watched || account.worstBand === 'Dangerous') {
    // One moderate signal or several overlapping, or a risky account. Require a second factor.
    return res.status(200).json({ status: 'require_2fa', method: 'otp' });
  }

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