Returning Visitor Recognition

// Call this from a flow you already trust: a successful login, a confirmed
// purchase, an email verification. `risk` is what waitForScore returns.
async function rememberTrustedDevice(accountId, risk) {
  // Remember only a clean webhook identification of this account.
  // A History fallback row has no `signals`, so it is skipped.
  if (!Array.isArray(risk.signals)) return;
  // hashAccountId: the same hashing you apply before passing the id to the snippet.
  if (risk.user_hid !== hashAccountId(accountId)) return;
  if (!risk.device_id || risk.device_id === NIL_DEVICE) return;
  if (risk.risk_score >= 30 || risk.signals.some((s) => s.weight > 0)) return;

  await trustedDevices.add({ accountId, deviceId: risk.device_id, firstSeen: Date.now() });
}

app.post('/api/enter', async (req, res) => {
  const { shieldlabsRequestId } = req.body;
  const accountId = req.user?.id; // the signed-in account
  if (!accountId) return res.json({ recognized: false });

  // Read the identification from your webhook cache (the shared `waitForScore`
  // helper), falling back to a History API read by request_id.
  const risk = await waitForScore(shieldlabsRequestId, 2000);

  // No identification, a History fallback row (no `signals`), or an
  // identification of another account: run the normal flow.
  if (!risk || !Array.isArray(risk.signals)) return res.json({ recognized: false });
  if (risk.user_hid !== hashAccountId(accountId)) return res.json({ recognized: false });
  if (!risk.device_id || risk.device_id === NIL_DEVICE) return res.json({ recognized: false });

  // Trusted band (0-29) with no positive-weight risk signal: an ordinary,
  // unmasked moment. The 999 rate-limit marker is never clean.
  const isClean = risk.risk_score < 30 && !risk.signals.some((s) => s.weight > 0);
  const isKnownDevice = await trustedDevices.has(accountId, risk.device_id);
  // Accounts you marked after a High-Risk Event reached you through the API,
  // webhooks or the analytics dashboard.
  const isMarked = await markedAccounts.has(accountId);

  if (isClean && isKnownDevice && !isMarked) {
    // Recognized return: lighten the experience.
    return res.json({ recognized: true, deviceId: risk.device_id });
  }

  // New device, a Risk Score that is not clean, or a marked account: your normal flow.
  return res.json({ recognized: false });
});