Use Case Tutorials

import { app, waitForScore, accountView, band, NIL_DEVICE } from './shieldlabs-helpers.js';

// The API returns only the number. Bands: Trusted 0-29, Suspicious 30-59, Dangerous 60-100.
function actionFor(score, flags, account) {
  // Automation is worth a challenge on its own; the flags work on the webhook
  // and on the History fallback alike.
  const automated = flags.browser_automation || flags.javascript_disabled;

  if (band(score) === 'Dangerous' || automated) return 'challenge'; // block, review or require verification
  if (band(score) === 'Suspicious') return 'review';                // step-up challenge or a second look
  if (account?.worstBand === 'Dangerous') return 'review';          // Trusted now, Dangerous history
  return 'allow';                                                   // Trusted: pass through, no friction
}

app.post('/api/protected-action', async (req, res) => {
  const { shieldlabsRequestId } = req.body;
  const userHid = req.user?.hashedId; // the hashed id you pass to the snippet; absent for guests

  // The guard every tutorial handler starts with.
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk) return res.status(202).json({ status: 'review', reason: 'no_identification' });
  if (userHid && risk.user_hid !== userHid) {
    return res.status(202).json({ status: 'review', reason: 'identification_mismatch' });
  }
  if (risk.risk_score > 100) {
    return res.status(202).json({ status: 'review', reason: 'rate_limit_marker' }); // the 999 marker
  }
  if (risk.device_id === NIL_DEVICE) {
    return res.status(202).json({ status: 'review', reason: 'no_usable_device' }); // no usable device signals
  }
  const flags = risk.detection_flags ?? {};
  const signals = risk.signals ?? []; // null on the History fallback; log them with your decision

  // The account behind the action, without the identification being decided.
  // A failed History read is unverified, so route the action to review.
  let account = null;
  if (userHid) {
    try {
      account = await accountView(userHid, { excludeRequestId: risk.request_id });
    } catch {
      return res.status(202).json({ status: 'review', reason: 'history_unavailable' });
    }
  }

  const action = actionFor(risk.risk_score, flags, account);
  await saveDecision(risk.request_id, action, signals); // your own audit record
  return res.status(action === 'allow' ? 200 : 202).json({ status: action });
});

import crypto from 'crypto';
import express from 'express';

const scoreCache = new Map(); // use a shared store or your datastore in production
const SECRET = process.env.SHIELDLABS_WEBHOOK_SECRET; // whsec_… for this endpoint

// Keep the raw body so the bytes you hash match the bytes that were signed.
const app = express();
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
app.use(express.urlencoded({ extended: false })); // the tutorials' HTML forms post urlencoded bodies

// Webhook handler: verify, respond fast, then store keyed by request_id.
app.post('/shieldlabs/webhook', (req, res) => {
  const received = req.get('X-Shield-Signature') ?? '';
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', SECRET).update(req.rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }
  res.status(200).end();

  const envelope = req.body; // { event_type, schema_version, created_at, data }
  // Only identification.scored carries an identification; skip service events.
  if (envelope.event_type !== 'identification.scored') return;

  const identification = envelope.data; // the identification lives under `data`
  // Idempotent on request_id: storing the same identification twice is safe,
  // but do not double-apply business effects.
  scoreCache.set(identification.request_id, identification);
  setTimeout(() => scoreCache.delete(identification.request_id), 5 * 60 * 1000);
});

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Returns the webhook `data` for requestId, or a History row mapped by
// fromHistoryRow, or null when requestId is empty, nothing is found or the read fails.
async function waitForScore(requestId, timeoutMs) {
  if (!requestId) return null; // the snippet did not run, or the check was skipped
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (scoreCache.has(requestId)) return scoreCache.get(requestId);
    await sleep(100);
  }
  // The webhook has not arrived in time: read the identification from the History API.
  try {
    const [row] = await shieldlabsHistory('request_id', requestId, 1);
    return row ? fromHistoryRow(row) : null;
  } catch {
    return null; // a failed read is unverified, never clean
  }
}

// History rows are flat. Map the fields the tutorials read to the webhook names.
function fromHistoryRow(r) {
  return {
    request_id: r.request_id,
    session_id: r.session_id,
    cookie_id: r.cookie_id,
    visitor_id: r.visitor_id,
    device_id: r.device_id,
    user_hid: r.user_hid,
    domain: r.domain,
    risk_score: r.score,
    public_ip: { ip: r.ip, country: r.country },
    local_ip: null, // History has no local_ip object: treat it as unknown, not clean
    connection_type: r.connection_type,
    os: r.os,
    browser: r.browser,
    device_type: r.device_type,
    signals: null, // History carries score_details (a JSON string), not signals[]
    // History has no browser_vpn_proxy or ip_mismatch flag.
    detection_flags: {
      vpn: r.is_vpn,
      privacy_relay: r.is_privacy_relay,
      tor: r.is_tor,
      proxy: r.is_proxy,
      datacenter_ip: r.is_datacenter,
      abuser: r.is_abuser,
      os_mismatch: r.is_os_mismatch,
      os_not_detected: r.is_os_not_detected,
      timezone_mismatch: r.is_timezone_mismatch,
      anti_detect_browser: r.is_antidetect,
      browser_automation: r.is_browser_automation,
      javascript_disabled: r.is_js_disabled,
      incognito: r.is_incognito,
      search_bot: r.is_search_bot,
      suspicious_paid_click: Boolean(r.is_suspicious_paid_click),
      stun_not_checked: r.is_stun_not_checked,
      check_incomplete: r.check_incomplete,
    },
    traffic_source: {
      channel: r.traffic_channel,
      referrer_domain: r.referrer_domain,
      landing_url: r.entry_url,
      utm_source: r.utm_source,
      utm_medium: r.utm_medium,
      utm_campaign: r.utm_campaign,
      utm_content: r.utm_content,
      utm_term: r.utm_term,
      click_id_type: r.click_id_type,
    },
    source: 'history',
  };
}

// Host without /api; every path starts with /api/v1/.
const HISTORY_BASE = process.env.SHIELDLABS_API_URL ?? 'https://account.shieldlabs.ai';
const API_KEY = process.env.SHIELDLABS_API_KEY; // sec_… Private API Key of this domain

// Returns the History `data` array (rows are flat: score, score_details, ip, country, is_* flags).
// limit is 1-100, newest first; page with offset until fewer than `limit` rows come back.
async function shieldlabsHistory(searchType, value, limit = 20, offset = 0) {
  const url = new URL(
    `${HISTORY_BASE}/api/v1/history/${searchType}/${encodeURIComponent(value)}`
  );
  url.searchParams.set('limit', String(limit));
  url.searchParams.set('offset', String(offset));
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!res.ok) throw new Error(`history lookup failed: ${res.status}`);
  const body = await res.json();
  return body.data ?? [];
}

// 'Trusted' | 'Suspicious' | 'Dangerous'. Callers guard score > 100 (the 999 marker).
function band(score) {
  if (score >= 60) return 'Dangerous';
  if (score >= 30) return 'Suspicious';
  return 'Trusted';
}

const NIL_DEVICE = '00000000-0000-0000-0000-000000000000';

// The account view: the newest 100 identifications of one user, rolled up.
// Skips the 999 rate-limit marker and, optionally, the identification being decided
// or the whole current session; the all-zero Device ID is never counted as a device.
// Page with offset for longer histories.
async function accountView(userHid, { excludeRequestId, excludeSessionId } = {}) {
  const rows = (await shieldlabsHistory('user_hid', userHid, 100)).filter(
    (r) =>
      r.score <= 100 &&
      r.request_id !== excludeRequestId &&
      (!excludeSessionId || r.session_id !== excludeSessionId)
  );
  const worst = rows.length ? Math.max(...rows.map((r) => r.score)) : null;
  return {
    identifications: rows.length,
    worstBand: worst === null ? null : band(worst),
    devices: new Set(rows.map((r) => r.device_id).filter((d) => d && d !== NIL_DEVICE)),
    visitors: new Set(rows.map((r) => r.visitor_id).filter(Boolean)),
    publicIps: new Set(rows.map((r) => r.ip).filter(Boolean)),
    countries: new Set(rows.map((r) => r.country).filter(Boolean)),
  };
}

// Distinct accounts seen on one device (newest 100 identifications).
// Anonymous checks carry "anonymous" as user_hid, which is not an account.
async function accountsBehindDevice(deviceId) {
  if (!deviceId || deviceId === NIL_DEVICE) return 0;
  const rows = await shieldlabsHistory('device_id', deviceId, 100);
  const hids = rows.map((r) => r.user_hid).filter((h) => h && h !== 'anonymous');
  return new Set(hids).size;
}

export {
  app,
  waitForScore,
  fromHistoryRow,
  shieldlabsHistory,
  band,
  accountView,
  accountsBehindDevice,
  NIL_DEVICE,
};