Acting on the Risk Score

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

function decide(risk) {
  const f = risk.detection_flags ?? {};
  // Always step up on the strongest tells, even when the band looks low.
  if (f.tor || f.anti_detect_browser || f.abuser) return 'verify';
  return defaultAction(risk.risk_score);
}

function onSignup({ score }) {
  if (score >= 60) return 'reject_or_manual_review';
  if (score >= 30) return 'email_verify_or_captcha';
  return 'allow'; // Clean / Low: 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)
  applyDecision(req.body).catch(console.error);
});

async function applyDecision(payload) {
  // The webhook exposes the score as `risk_score`; the History API row exposes it
  // as `score`. Normalize so a webhook and a History fallback converge on one shape.
  const { request_id, signals, device_id } = payload;
  const score = payload.risk_score ?? payload.score;

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

  // Compute the decision idempotently; do not re-charge, re-email, or re-block.
  const decision = decide({ score, signals, device_id, 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"

function bandLadder(score, 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 (score >= cuts.block) return 'block_or_manual_review';
  if (score >= cuts.challenge) return 'challenge';
  return 'allow';
}

function decide({ score, signals, device_id, action }) {
  // 999 is a rate-limit ban marker, not a 0-100 score. Guard it before banding.
  if (score > 100) return 'block';

  // Your own data can override even a low score.
  if (knownBadDevice(device_id)) return 'block';

  // Log the fired signals for transparency; do not branch on the label text.
  logSignals(signals);

  // The per-action band ladder is the verdict.
  return bandLadder(score, action);
}