Step-up authentication (risk-based 2FA)

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

  // Run a check for the account that is logging in.
  // The browser does NOT compute the Risk Score. The first callback arg is the
  // client IP the server saw for this call (not a score); requestID is your
  // join key to the webhook you receive server-side.
  // Use forceCheckAuthenticatedUser instead for a fresh read at submit.
  mod.checkAuthenticatedUser('a1b2c3d4hasheduserid', (ip, requestID) => {
    document.getElementById('shield-request-id').value = requestID;
  });
</script>

<form id="login-form" method="POST" action="/api/login">
  <input type="hidden" id="shield-request-id" name="shieldRequestId" />
  <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, 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 up to ~2s for the webhook; fall back to the History API by request_id.
  const shield = await waitForScore(shieldRequestId, 2000);

  // 3. No result yet is not the same as "clean". Default to requiring 2FA
  //    rather than letting a login through on missing data.
  if (!shield) {
    return res.status(200).json({ status: 'require_2fa', reason: 'verifying' });
  }

  const score = shield.score;

  // YOUR threshold ladder. Branch on the Score and its band, never on the
  // signal label text, which is a human-readable string that can change.
  // The bands are a guide, not a rule.
  if (score >= 60) {
    // High: strong anonymity signals folded into the score. Require
    // your strongest factor, or hold and alert the account owner.
    await alertAccountOwner(user.id, shield);
    return res.status(200).json({ status: 'verify', method: 'strong' });
  }

  if (score >= 30) {
    // Medium: one moderate signal or several overlapping. Require a second factor.
    return res.status(200).json({ status: 'require_2fa', method: 'otp' });
  }

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