Acting on results

// A baseline ladder. Tune the cut-points per action context (see scenarios below).
function defaultAction(score) {
  if (score < 10) return 'allow';        // Trusted, no risk signals: no friction
  if (score < 30) return 'allow_log';    // Trusted, minor risk signal: allow, but log it
  if (score < 60) return 'challenge';    // Suspicious: step-up or review
  return 'review_or_block';              // Dangerous: block, review, or verify
}

// Hard rules on the strongest tells, applied before the band ladder.
// The complete handler below calls it after the 999 guard and your own records.
function hardRule({ detection_flags, signals }) {
  const f = detection_flags ?? {};
  const slugs = (signals ?? []).map((s) => s.name);
  // Always step up on the strongest tells, even when the band looks low.
  if (f.tor || f.anti_detect_browser || f.browser_automation || f.abuser || slugs.includes('proxy_routed_antidetect')) return 'verify';
  return null; // no hard rule: fall through to the band ladder
}

function onSignup({ score }) {
  if (score >= 60) return 'reject_or_manual_review';
  if (score >= 30) return 'email_verify_or_captcha';
  return 'allow'; // Trusted: create the account
}

function onLogin({ score }) {
  if (score >= 60) return 'block_require_recovery';
  if (score >= 30) return 'require_2fa';
  return 'allow';
}

function onWithdrawal({ score }) {
  if (score >= 60) return 'manual_review_hold';
  if (score >= 10) return 'extra_verification'; // verify early on money out
  return 'allow';
}

app.post('/shieldlabs/webhook', express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }), async (req, res) => {
  // Verify X-Shield-Signature over req.rawBody first. See /setup/webhooks.
  if (!verifySignature(req)) return res.status(401).end();

  res.status(200).end();           // acknowledge fast (~1s timeout, no retries)
  if (req.body.event_type !== 'identification.scored') return;   // skip webhook.ping
  applyDecision(req.body.data).catch(console.error);
});

// payload is body.data of an identification.scored webhook, or a History API row.
async function applyDecision(payload) {
  // The webhook names the Risk Score `risk_score`; a History API row names it `score`.
  // Normalize so a webhook and a History fallback converge on one shape.
  // A History row has no `signals` and no `detection_flags` (it carries is_* flags),
  // so the hard rules only see webhook data.
  const { request_id, signals, detection_flags, device_id, user_hid } = payload;
  const riskScore = payload.risk_score ?? payload.score;

  // The step this identification belongs to (signup, login, checkout, ...).
  // Record it when the snippet's onInitialized callback returns the requestID.
  const action = await db.pendingChecks.actionFor(request_id);

  // Upsert keyed on request_id: the webhook and a History fallback converge.
  await db.checks.upsert({ requestID: request_id, riskScore, signals, userHid: user_hid });

  // Compute the decision idempotently; do not re-charge, re-email, or re-block.
  // decide() is the complete handler below.
  const decision = await decide({ request_id, riskScore, signals, detection_flags, device_id, user_hid, action });
  await db.decisions.upsert({ requestID: request_id, decision });
}

curl "https://account.shieldlabs.ai/api/v1/history/request_id/13f84f05-2c4a-4d8e-9b1a-6f2e7c9d0a55?limit=1" \
  -H "Authorization: Bearer sec_your_private_api_key"

const HISTORY = 'https://account.shieldlabs.ai/api/v1/history';
const NIL_DEVICE = '00000000-0000-0000-0000-000000000000';

// The account layer: the worst band of the user's earlier identifications and
// the devices it has used. History reads are free and limited to 15 requests
// per second per domain, so cache this per user.
// A shorter form of the accountView() helper on the use case tutorials hub.
async function readAccount(userHid, currentRequestId) {
  if (!userHid || userHid === 'anonymous') return null;
  const res = await fetch(`${HISTORY}/user_hid/${encodeURIComponent(userHid)}?limit=100`, {
    headers: { Authorization: `Bearer ${process.env.SHIELDLABS_API_KEY}` },
  });
  // A failed read is unverified: throw, and let the caller route the action to review.
  if (!res.ok) throw new Error(`history lookup failed: ${res.status}`);
  const { data = [] } = await res.json();
  // Skip this identification and the 999 marker. A row with the all-zero Device ID
  // still counts toward the band, but never as a device.
  const earlier = data.filter(
    (row) => row.request_id !== currentRequestId && row.score <= 100,
  );
  const worst = earlier.reduce((max, row) => Math.max(max, row.score), 0);
  return {
    band: worst >= 60 ? 'Dangerous' : worst >= 30 ? 'Suspicious' : 'Trusted',
    devices: new Set(earlier.map((row) => row.device_id).filter((d) => d && d !== NIL_DEVICE)),
    seen: earlier.length > 0,
  };
}

function bandLadder(riskScore, action) {
  // Per-action cut-points from the scenario tables above.
  const cuts = {
    signup:     { challenge: 30, block: 60 },
    login:      { challenge: 30, block: 60 },
    checkout:   { challenge: 30, block: 60 },
    withdrawal: { challenge: 10, block: 60 }, // strictest: react early
    kyc:        { challenge: 30, block: 60 },
    content:    { challenge: 30, block: 60 },
  }[action] || { challenge: 30, block: 60 };

  if (riskScore >= cuts.block) return 'block_or_manual_review';
  if (riskScore >= cuts.challenge) return 'challenge';
  return 'allow';
}

async function decide({ request_id, riskScore, signals, detection_flags, device_id, user_hid, action }) {
  // 999 is the rate-limit marker, not a 0 to 100 Risk Score; an all-zero Device ID
  // carries no usable device signals. Route both to review.
  if (riskScore > 100 || device_id === NIL_DEVICE) return 'manual_review';

  // Your own records: a banned device, or an account you acted on after a
  // High-Risk Event (from the API, webhooks or the analytics dashboard).
  if (knownBadDevice(device_id) || flaggedAccount(user_hid)) return 'block_or_manual_review';

  // Hard rules on the strongest tells (the Flag-level override above).
  const hard = hardRule({ detection_flags, signals });
  if (hard) return hard;

  // Log the fired risk signals for review (a History row has score_details instead).
  logSignals(signals ?? []);

  const decision = bandLadder(riskScore, action);

  // The account layer: on a sensitive step, a clean identification on a risky
  // account, or on a device the account has never used, earns a challenge.
  const sensitive = ['login', 'checkout', 'withdrawal'].includes(action);
  if (decision === 'allow' && sensitive) {
    let account;
    try {
      account = await readAccount(user_hid, request_id);
    } catch {
      return 'manual_review'; // a failed account read is unverified, never clean
    }
    if (account?.seen && (account.band === 'Dangerous' || !account.devices.has(device_id))) {
      return 'challenge';
    }
  }
  return decision;
}