devn-bot-detector-server 0.1.0

package/dist/index.cjs

@@ -0,0 +1,912 @@
+'use strict';
+
+var devnBotDetectorCore = require('devn-bot-detector-core');
+var crypto = require('crypto');
+
+// src/BotDetectionServer.ts
+function secureId(prefix, bytes = 16) {
+  return `${prefix}_${crypto.randomBytes(bytes).toString("hex")}`;
+}
+var MemorySiteResolver = class {
+  constructor(entries = []) {
+    this.sites = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      this.sites.set(entry.siteKey, entry.site);
+    }
+  }
+  set(siteKey, site) {
+    this.sites.set(siteKey, site);
+  }
+  async resolveSite(siteKey) {
+    return this.sites.get(siteKey) ?? null;
+  }
+};
+var MemorySessionStore = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  async create(session) {
+    this.sessions.set(session.sessionId, {
+      ...session,
+      usedNonces: [...session.usedNonces]
+    });
+  }
+  async get(sessionId) {
+    const s = this.sessions.get(sessionId);
+    if (!s) return null;
+    return {
+      ...s,
+      usedNonces: [...s.usedNonces]
+    };
+  }
+  async update(session) {
+    this.sessions.set(session.sessionId, {
+      ...session,
+      usedNonces: [...session.usedNonces]
+    });
+  }
+  async invalidate(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+};
+var MemoryTokenRevocationStore = class {
+  constructor() {
+    this.revoked = /* @__PURE__ */ new Map();
+  }
+  isRevoked(tokenId) {
+    const expiresAt = this.revoked.get(tokenId);
+    if (!expiresAt) return false;
+    if (Date.now() >= expiresAt) {
+      this.revoked.delete(tokenId);
+      return false;
+    }
+    return true;
+  }
+  revoke(tokenId, ttlMs) {
+    this.revoked.set(tokenId, Date.now() + Math.max(1e3, ttlMs));
+  }
+};
+
+// src/rate-limit.ts
+var MemoryRateLimiter = class {
+  constructor() {
+    this.buckets = /* @__PURE__ */ new Map();
+  }
+  check(key, limit, windowMs) {
+    const now = Date.now();
+    let bucket = this.buckets.get(key);
+    if (!bucket || now >= bucket.resetAt) {
+      bucket = { count: 0, resetAt: now + windowMs };
+      this.buckets.set(key, bucket);
+    }
+    if (bucket.count >= limit) {
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfter: Math.max(1, Math.ceil((bucket.resetAt - now) / 1e3))
+      };
+    }
+    bucket.count += 1;
+    return {
+      allowed: true,
+      remaining: Math.max(0, limit - bucket.count)
+    };
+  }
+  /** Best-effort cleanup for long-running processes. */
+  prune() {
+    const now = Date.now();
+    for (const [key, bucket] of this.buckets) {
+      if (now >= bucket.resetAt) this.buckets.delete(key);
+    }
+  }
+};
+var AutomationDetector = (input) => {
+  const reasons = [];
+  const browser = input.telemetry.browser;
+  if (!browser) return reasons;
+  if (browser.webdriver) {
+    reasons.push({ code: "WEBDRIVER", weight: 25, detail: "navigator.webdriver true" });
+  }
+  const ua = browser.userAgent.toLowerCase();
+  if (ua.includes("headless") || ua.includes("phantomjs")) {
+    reasons.push({ code: "HEADLESS_UA", weight: 20 });
+  }
+  return reasons;
+};
+var HeadlessAdvancedDetector = (input) => {
+  const reasons = [];
+  const browser = input.telemetry.browser;
+  if (!browser) return reasons;
+  const renderer = (browser.webglRenderer || "").toLowerCase();
+  if (renderer.includes("swiftshader") || renderer.includes("llvmpipe") || renderer.includes("softpipe") || renderer.includes("mesa offscreen")) {
+    reasons.push({
+      code: "SOFTWARE_WEBGL",
+      weight: 22,
+      detail: "Software WebGL renderer detected (virtualized/headless)"
+    });
+  }
+  if (browser.userAgent.includes("Chrome") && browser.hasChrome === false) {
+    reasons.push({
+      code: "MISSING_CHROME_OBJ",
+      weight: 18,
+      detail: "UA reports Chrome but window.chrome is absent"
+    });
+  }
+  const ua = browser.userAgent.toLowerCase();
+  const isDesktop = !ua.includes("mobile") && !ua.includes("android") && !ua.includes("iphone") && !ua.includes("ipad") && !ua.includes("jsdom");
+  if (isDesktop && browser.pluginsCount === 0) {
+    reasons.push({ code: "ZERO_DESKTOP_PLUGINS", weight: 12 });
+  }
+  return reasons;
+};
+var EntropyDetector = (input) => {
+  const reasons = [];
+  const pointer = input.telemetry.pointer;
+  if (pointer && pointer.eventCount >= 25 && pointer.movementDistance > 350 && pointer.directionChanges === 0) {
+    reasons.push({
+      code: "LINEAR_POINTER_PATH",
+      weight: 20,
+      detail: "Unnatural linear pointer trajectory without direction variance"
+    });
+  }
+  return reasons;
+};
+var ActionRiskDetector = (input) => {
+  const reasons = [];
+  if (!input.action) return reasons;
+  const action = input.action.toLowerCase();
+  const sensitivePatterns = ["login", "checkout", "pay", "transfer", "signup", "reset_password"];
+  const isSensitive = sensitivePatterns.some((p) => action.includes(p));
+  if (isSensitive) {
+    const interaction = input.telemetry.interaction;
+    if (interaction && interaction.interactionCount === 0) {
+      reasons.push({
+        code: "SENSITIVE_ACTION_NO_INTERACTION",
+        weight: 25,
+        detail: `Sensitive action "${input.action}" attempted with 0 prior interactions`
+      });
+    } else if (interaction && interaction.timeToFirstInteraction != null && interaction.timeToFirstInteraction < 150 && interaction.interactionCount > 0) {
+      reasons.push({
+        code: "SENSITIVE_ACTION_SUB_HUMAN_SPEED",
+        weight: 20,
+        detail: `Sensitive action "${input.action}" executed under 150ms`
+      });
+    }
+  }
+  return reasons;
+};
+var VelocityDetector = (input) => {
+  const reasons = [];
+  if (input.sequence > 40 && input.sessionAgeMs < 1e4) {
+    reasons.push({ code: "HIGH_SEQUENCE_VELOCITY", weight: 30 });
+  }
+  const pointer = input.telemetry.pointer;
+  if (pointer && pointer.eventCount > 800 && pointer.activeDuration < 2e3) {
+    reasons.push({ code: "POINTER_VELOCITY", weight: 20 });
+  }
+  return reasons;
+};
+var TimingDetector = (input) => {
+  const reasons = [];
+  const kb = input.telemetry.keyboard;
+  if (kb && kb.keydownCount >= 12 && kb.timingVariance != null && kb.timingVariance < 1) {
+    reasons.push({ code: "KEYBOARD_TOO_UNIFORM", weight: 18 });
+  }
+  if (kb && kb.averageInterval != null && kb.averageInterval < 15 && kb.keydownCount >= 10) {
+    reasons.push({ code: "KEYBOARD_TOO_FAST", weight: 15 });
+  }
+  const interaction = input.telemetry.interaction;
+  if (interaction && interaction.timeToFirstInteraction != null && interaction.timeToFirstInteraction < 20 && interaction.interactionCount > 0) {
+    reasons.push({ code: "IMPOSSIBLE_TTFI", weight: 12 });
+  }
+  return reasons;
+};
+var InteractionDetector = (input) => {
+  const reasons = [];
+  const interaction = input.telemetry.interaction;
+  if (!interaction) return reasons;
+  if (interaction.interactionCount === 0) {
+    reasons.push({ code: "ZERO_INTERACTION", weight: 10 });
+  }
+  if (interaction.timeToFirstInteraction != null && interaction.timeToFirstInteraction > 200 && interaction.timeToFirstInteraction < 12e4) {
+    reasons.push({ code: "NATURAL_TTFI", weight: -8 });
+  }
+  if (interaction.interactionCount >= 3) {
+    reasons.push({ code: "MIXED_INTERACTION", weight: -6 });
+  }
+  return reasons;
+};
+var BrowserConsistencyDetector = (input) => {
+  const reasons = [];
+  const browser = input.telemetry.browser;
+  if (!browser) return reasons;
+  if (browser.languagesLength === 0) {
+    reasons.push({ code: "NO_LANGUAGES", weight: 8 });
+  }
+  if (browser.screenWidth <= 0 || browser.screenHeight <= 0) {
+    reasons.push({ code: "INVALID_SCREEN", weight: 10 });
+  }
+  if (input.request.userAgent && browser.userAgent) {
+    const reqUa = input.request.userAgent.slice(0, 64);
+    const telUa = browser.userAgent.slice(0, 64);
+    if (reqUa && telUa && reqUa !== telUa) {
+      reasons.push({ code: "UA_MISMATCH", weight: 15 });
+    }
+  }
+  return reasons;
+};
+var SessionDetector = (input) => {
+  const reasons = [];
+  if (input.sessionAgeMs < 50 && input.sequence > 1) {
+    reasons.push({ code: "SESSION_TOO_YOUNG", weight: 12 });
+  }
+  const pointer = input.telemetry.pointer;
+  if (pointer && pointer.eventCount >= 20 && pointer.directionChanges === 0) {
+    reasons.push({ code: "POINTER_NO_DIRECTION_CHANGE", weight: 10 });
+  }
+  if (pointer && pointer.movementDistance > 0 && pointer.directionChanges > 5) {
+    reasons.push({ code: "NATURAL_POINTER", weight: -8 });
+  }
+  const scroll = input.telemetry.scroll;
+  if (scroll && scroll.scrollCount > 0) {
+    reasons.push({ code: "HAS_SCROLL", weight: -4 });
+  }
+  const focus = input.telemetry.focus;
+  if (focus && (focus.focusCount > 0 || focus.blurCount > 0)) {
+    reasons.push({ code: "HAS_FOCUS_CHANGES", weight: -3 });
+  }
+  return reasons;
+};
+var DEFAULT_DETECTORS = [
+  AutomationDetector,
+  HeadlessAdvancedDetector,
+  EntropyDetector,
+  ActionRiskDetector,
+  VelocityDetector,
+  TimingDetector,
+  InteractionDetector,
+  BrowserConsistencyDetector,
+  SessionDetector
+];
+var RiskEngine = class {
+  constructor(options) {
+    if (Array.isArray(options)) {
+      this.detectors = options;
+      this.weights = {};
+    } else {
+      this.detectors = options?.detectors ?? DEFAULT_DETECTORS;
+      this.weights = options?.detectorWeights ?? {};
+    }
+  }
+  evaluate(input) {
+    const internalReasons = [];
+    for (const detector of this.detectors) {
+      for (const reason of detector(input)) {
+        const configuredWeight = this.weights[reason.code];
+        const weight = configuredWeight !== void 0 ? configuredWeight : reason.weight;
+        if (weight !== 0) {
+          internalReasons.push({ ...reason, weight });
+        }
+      }
+    }
+    let riskScore = 20;
+    for (const reason of internalReasons) {
+      riskScore += reason.weight;
+    }
+    riskScore = devnBotDetectorCore.clamp(riskScore, 0, 100);
+    const score = devnBotDetectorCore.clamp(100 - riskScore, 0, 100);
+    const confidence = devnBotDetectorCore.clamp(0.4 + Math.abs(score - 50) / 100, 0.4, 0.95);
+    const riskLevel = score >= 70 ? "low" : score >= 40 ? "medium" : "high";
+    return {
+      score,
+      confidence: Number(confidence.toFixed(2)),
+      riskLevel,
+      internalReasons
+    };
+  }
+};
+function b64url(input) {
+  const buf = typeof input === "string" ? Buffer.from(input, "utf8") : input;
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function fromB64url(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  return Buffer.from(padded + pad, "base64");
+}
+var TokenManager = class {
+  constructor(secret) {
+    this.secret = secret;
+    if (!secret || secret.length < 16) {
+      throw new Error("TokenManager requires a secret of at least 16 characters");
+    }
+  }
+  createRiskToken(payload) {
+    const body = b64url(JSON.stringify(payload));
+    const sig = b64url(crypto.createHmac("sha256", this.secret).update(body).digest());
+    return `rt_${body}.${sig}`;
+  }
+  verifyRiskToken(token, options) {
+    if (!token.startsWith("rt_")) return null;
+    const raw = token.slice(3);
+    const parts = raw.split(".");
+    if (parts.length !== 2) return null;
+    const [body, sig] = parts;
+    if (!body || !sig) return null;
+    const expected = b64url(crypto.createHmac("sha256", this.secret).update(body).digest());
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null;
+    try {
+      const payload = JSON.parse(fromB64url(body).toString("utf8"));
+      if (typeof payload.requestId !== "string" || typeof payload.siteId !== "string" || typeof payload.sessionId !== "string" || typeof payload.decision !== "string" || typeof payload.issuedAt !== "number" || typeof payload.expiresAt !== "number") {
+        return null;
+      }
+      const now = Date.now();
+      if (now >= payload.expiresAt) return null;
+      if (options?.expectedAction && payload.action !== options.expectedAction) {
+        return null;
+      }
+      if (options?.maxAgeMs != null && now - payload.issuedAt > options.maxAgeMs) {
+        return null;
+      }
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/BotDetectionServer.ts
+function debugLog(enabled, ...args) {
+  if (enabled) console.debug("[bot-detector-server]", ...args);
+}
+var BotDetectionServer = class {
+  constructor(options) {
+    if (!options.secret || options.secret.length < 16) {
+      throw new Error("BotDetectionServer requires secret (>= 16 chars)");
+    }
+    this.sessionDuration = options.sessionDuration ?? devnBotDetectorCore.DEFAULT_SESSION_DURATION_MS;
+    this.thresholds = devnBotDetectorCore.mergeRiskThresholds(options.riskThresholds);
+    this.actionThresholds = options.actionThresholds;
+    this.ipAllowlist = options.ipAllowlist ?? [];
+    this.ipDenylist = options.ipDenylist ?? [];
+    this.tokenRevocationStore = options.tokenRevocationStore;
+    this.enableRiskToken = options.enableRiskToken ?? true;
+    this.riskTokenDuration = options.riskTokenDuration ?? devnBotDetectorCore.DEFAULT_RISK_TOKEN_DURATION_MS;
+    this.trustProxy = options.trustProxy ?? false;
+    this.debug = options.debug ?? false;
+    this.maxTelemetryBytes = options.maxTelemetryBytes ?? devnBotDetectorCore.MAX_TELEMETRY_BYTES;
+    this.siteResolver = options.siteResolver ?? new MemorySiteResolver();
+    this.sessionStore = options.sessionStore ?? new MemorySessionStore();
+    this.rateLimiter = options.rateLimiter ?? new MemoryRateLimiter();
+    this.eventSink = options.eventSink;
+    this.tokens = new TokenManager(options.secret);
+    this.engine = new RiskEngine({ detectorWeights: options.detectorWeights });
+    this.customScoring = options.customScoring;
+    this.rateLimits = {
+      sitePerMinute: options.rateLimits?.sitePerMinute ?? 600,
+      sessionPerMinute: options.rateLimits?.sessionPerMinute ?? 60,
+      ipPerMinute: options.rateLimits?.ipPerMinute ?? 120
+    };
+  }
+  async getSite(siteKey) {
+    return this.siteResolver.resolveSite(siteKey);
+  }
+  validateHostname(hostname, site, request) {
+    const host = devnBotDetectorCore.normalizeHostname(hostname);
+    if (!devnBotDetectorCore.hostnameAllowed(host, site.allowedDomains)) return false;
+    const originHost = devnBotDetectorCore.extractHostnameFromOrigin(request?.origin);
+    if (originHost && !devnBotDetectorCore.hostnameAllowed(originHost, site.allowedDomains)) return false;
+    return true;
+  }
+  async createSession(input) {
+    const requestId = secureId("req");
+    const parsed = devnBotDetectorCore.validateCreateSessionRequest(input);
+    if (!parsed.ok) {
+      throw new devnBotDetectorCore.BotDetectorError("MALFORMED_REQUEST", parsed.message, requestId);
+    }
+    const site = await this.resolveActiveSite(input.siteKey, requestId);
+    if (!this.validateHostname(parsed.value.hostname, site, input.request)) {
+      throw new devnBotDetectorCore.BotDetectorError(
+        "INVALID_HOSTNAME",
+        "Hostname is not allowed for this site.",
+        requestId
+      );
+    }
+    const ip = this.resolveIp(input.request);
+    if (ip && devnBotDetectorCore.ipMatches(ip, this.ipDenylist)) {
+      throw new devnBotDetectorCore.BotDetectorError("IP_BLOCKED", "Access denied from this IP.", requestId);
+    }
+    await this.assertRateLimits(input.siteKey, void 0, input.request, requestId);
+    const now = Date.now();
+    const sessionId = secureId("ses");
+    const nonce = secureId("nonce", 12);
+    const expiresAt = now + this.sessionDuration;
+    const session = {
+      sessionId,
+      siteKey: input.siteKey,
+      siteId: site.siteId,
+      tenantId: site.tenantId,
+      nonce,
+      createdAt: now,
+      expiresAt,
+      hostname: devnBotDetectorCore.normalizeHostname(parsed.value.hostname),
+      sequence: 0,
+      usedNonces: []
+    };
+    await this.sessionStore.create(session);
+    await this.eventSink?.onSessionCreated?.(session);
+    debugLog(this.debug, "session created", { sessionId, siteId: site.siteId });
+    return {
+      sessionId,
+      nonce,
+      expiresAt: new Date(expiresAt).toISOString()
+    };
+  }
+  async analyze(input) {
+    const requestId = secureId("req");
+    const parsed = devnBotDetectorCore.validateAnalyzeRequest(input, this.maxTelemetryBytes);
+    if (!parsed.ok) {
+      const code = parsed.message.includes("bytes") || parsed.message.includes("forbidden") ? "INVALID_TELEMETRY" : "MALFORMED_REQUEST";
+      throw new devnBotDetectorCore.BotDetectorError(code, parsed.message, requestId);
+    }
+    const site = await this.resolveActiveSite(input.siteKey, requestId);
+    if (!this.validateHostname(parsed.value.hostname, site, input.request)) {
+      throw new devnBotDetectorCore.BotDetectorError(
+        "INVALID_HOSTNAME",
+        "Hostname is not allowed for this site.",
+        requestId
+      );
+    }
+    const session = await this.sessionStore.get(parsed.value.sessionId);
+    if (!session || session.siteKey !== input.siteKey) {
+      throw new devnBotDetectorCore.BotDetectorError("INVALID_SESSION", "Invalid or unknown session.", requestId);
+    }
+    if (Date.now() >= session.expiresAt) {
+      await this.sessionStore.invalidate(session.sessionId);
+      throw new devnBotDetectorCore.BotDetectorError("SESSION_EXPIRED", "Invalid or expired session.", requestId);
+    }
+    if (devnBotDetectorCore.normalizeHostname(session.hostname) !== devnBotDetectorCore.normalizeHostname(parsed.value.hostname)) {
+      throw new devnBotDetectorCore.BotDetectorError(
+        "INVALID_HOSTNAME",
+        "Hostname does not match session.",
+        requestId
+      );
+    }
+    if (parsed.value.sequence <= session.sequence) {
+      throw new devnBotDetectorCore.BotDetectorError(
+        "INVALID_SEQUENCE",
+        "Sequence replay or out of order.",
+        requestId
+      );
+    }
+    if (parsed.value.nonce && session.usedNonces.includes(parsed.value.nonce)) {
+      throw new devnBotDetectorCore.BotDetectorError("INVALID_NONCE", "Nonce has already been used.", requestId);
+    }
+    const ip = this.resolveIp(input.request);
+    if (ip && devnBotDetectorCore.ipMatches(ip, this.ipDenylist)) {
+      throw new devnBotDetectorCore.BotDetectorError("IP_BLOCKED", "Access denied from this IP.", requestId);
+    }
+    if (ip && devnBotDetectorCore.ipMatches(ip, this.ipAllowlist)) {
+      debugLog(this.debug, "allowlisted IP bypassed risk check", { ip });
+      const issuedAt = Date.now();
+      const tokenExpires = issuedAt + this.riskTokenDuration;
+      let riskToken2;
+      let expiresAt2;
+      if (this.enableRiskToken) {
+        riskToken2 = this.createRiskToken({
+          requestId,
+          siteId: site.siteId,
+          sessionId: session.sessionId,
+          decision: "allow",
+          issuedAt,
+          expiresAt: tokenExpires,
+          action: parsed.value.action,
+          score: 100
+        });
+        expiresAt2 = new Date(tokenExpires).toISOString();
+      }
+      return {
+        requestId,
+        score: 100,
+        confidence: 0.99,
+        decision: "allow",
+        riskLevel: "low",
+        action: parsed.value.action,
+        ...riskToken2 ? { riskToken: riskToken2 } : {},
+        ...expiresAt2 ? { expiresAt: expiresAt2 } : {},
+        timestamp: Date.now()
+      };
+    }
+    await this.assertRateLimits(input.siteKey, session.sessionId, input.request, requestId);
+    const evaluation = await this.calculateRisk({
+      telemetry: parsed.value.telemetry,
+      request: this.normalizeRequest(input.request),
+      sessionAgeMs: Date.now() - session.createdAt,
+      sequence: parsed.value.sequence,
+      action: parsed.value.action,
+      metadata: parsed.value.metadata
+    });
+    const effectiveThresholds = parsed.value.action && this.actionThresholds?.[parsed.value.action] ? devnBotDetectorCore.mergeRiskThresholds(this.actionThresholds[parsed.value.action]) : this.thresholds;
+    const decision = evaluation.decision ?? devnBotDetectorCore.decisionFromScore(evaluation.score, effectiveThresholds);
+    const riskLevel = evaluation.riskLevel ?? devnBotDetectorCore.riskLevelFromScore(evaluation.score);
+    let riskToken;
+    let expiresAt;
+    if (this.enableRiskToken) {
+      const issuedAt = Date.now();
+      const tokenExpires = issuedAt + this.riskTokenDuration;
+      riskToken = this.createRiskToken({
+        requestId,
+        siteId: site.siteId,
+        sessionId: session.sessionId,
+        decision,
+        issuedAt,
+        expiresAt: tokenExpires,
+        action: parsed.value.action,
+        score: evaluation.score
+      });
+      expiresAt = new Date(tokenExpires).toISOString();
+    }
+    const usedNonces = [...session.usedNonces];
+    if (parsed.value.nonce) {
+      usedNonces.push(parsed.value.nonce);
+      if (usedNonces.length > 32) usedNonces.splice(0, usedNonces.length - 32);
+    }
+    await this.sessionStore.update({
+      ...session,
+      sequence: parsed.value.sequence,
+      usedNonces,
+      nonce: secureId("nonce", 12)
+    });
+    const result = {
+      requestId,
+      score: evaluation.score,
+      confidence: evaluation.confidence,
+      decision,
+      riskLevel,
+      action: parsed.value.action,
+      ...riskToken ? { riskToken } : {},
+      ...expiresAt ? { expiresAt } : {},
+      timestamp: Date.now()
+    };
+    await this.eventSink?.onAnalysis?.(result);
+    debugLog(this.debug, "analyzed", {
+      requestId,
+      decision: result.decision,
+      score: result.score,
+      action: result.action
+    });
+    return result;
+  }
+  async calculateRisk(input) {
+    const base = this.engine.evaluate(input);
+    if (!this.customScoring) return base;
+    const custom = await this.customScoring(input);
+    const riskFromCustom = custom.risk ?? 0;
+    let score = base.score - riskFromCustom;
+    if (typeof custom.score === "number") score = custom.score;
+    score = Math.max(0, Math.min(100, Math.round(score)));
+    const internalReasons = [
+      ...base.internalReasons,
+      ...custom.internalReasons ?? [],
+      ...riskFromCustom ? [{ code: "CUSTOM_SCORING", weight: riskFromCustom }] : []
+    ];
+    return {
+      score,
+      confidence: custom.confidence ?? base.confidence,
+      riskLevel: custom.riskLevel ?? devnBotDetectorCore.riskLevelFromScore(score),
+      decision: custom.decision,
+      internalReasons
+    };
+  }
+  createRiskToken(payload) {
+    return this.tokens.createRiskToken(payload);
+  }
+  verifyRiskToken(token, options) {
+    return this.tokens.verifyRiskToken(token, options);
+  }
+  /**
+   * Validates risk token and consumes it (one-time use) if tokenRevocationStore is configured.
+   * Throws TOKEN_ALREADY_USED if already consumed or MALFORMED_REQUEST if invalid/expired.
+   */
+  async consumeRiskToken(token, options) {
+    const requestId = secureId("req");
+    const payload = this.verifyRiskToken(token, options);
+    if (!payload) {
+      throw new devnBotDetectorCore.BotDetectorError("MALFORMED_REQUEST", "Invalid or expired risk token.", requestId);
+    }
+    if (this.tokenRevocationStore) {
+      const revoked = await this.tokenRevocationStore.isRevoked(token);
+      if (revoked) {
+        throw new devnBotDetectorCore.BotDetectorError(
+          "TOKEN_ALREADY_USED",
+          "Risk token has already been consumed.",
+          requestId
+        );
+      }
+      const remainingTtl = Math.max(1e3, payload.expiresAt - Date.now());
+      await this.tokenRevocationStore.revoke(token, remainingTtl);
+    }
+    return payload;
+  }
+  async resolveActiveSite(siteKey, requestId) {
+    const site = await this.siteResolver.resolveSite(siteKey);
+    if (!site || site.status !== "active") {
+      throw new devnBotDetectorCore.BotDetectorError("INVALID_SITE_KEY", "Invalid or inactive site key.", requestId);
+    }
+    return site;
+  }
+  async assertRateLimits(siteKey, sessionId, request, requestId) {
+    const site = await this.rateLimiter.check(
+      `site:${siteKey}`,
+      this.rateLimits.sitePerMinute,
+      6e4
+    );
+    if (!site.allowed) {
+      throw new devnBotDetectorCore.BotDetectorError("RATE_LIMITED", "Rate limit exceeded.", requestId);
+    }
+    if (sessionId) {
+      const sess = await this.rateLimiter.check(
+        `session:${sessionId}`,
+        this.rateLimits.sessionPerMinute,
+        6e4
+      );
+      if (!sess.allowed) {
+        throw new devnBotDetectorCore.BotDetectorError("RATE_LIMITED", "Rate limit exceeded.", requestId);
+      }
+    }
+    const ip = this.resolveIp(request);
+    if (ip) {
+      const ipLimit = await this.rateLimiter.check(`ip:${ip}`, this.rateLimits.ipPerMinute, 6e4);
+      if (!ipLimit.allowed) {
+        throw new devnBotDetectorCore.BotDetectorError("RATE_LIMITED", "Rate limit exceeded.", requestId);
+      }
+    }
+  }
+  resolveIp(request) {
+    if (!request) return void 0;
+    if (this.trustProxy && request.forwardedFor) {
+      return request.forwardedFor.split(",")[0]?.trim();
+    }
+    return request.ip;
+  }
+  normalizeRequest(request) {
+    if (!request) return {};
+    return {
+      ...request.ip ? { ip: request.ip } : {},
+      ...request.userAgent ? { userAgent: request.userAgent } : {},
+      ...request.origin ? { origin: request.origin } : {},
+      ...request.host ? { host: request.host } : {},
+      ...this.trustProxy && request.forwardedFor ? { forwardedFor: request.forwardedFor } : {}
+    };
+  }
+};
+
+// src/adapters/redis.ts
+var RedisSessionStore = class {
+  constructor(client, options) {
+    this.client = client;
+    this.prefix = options?.prefix ?? "bd:sess:";
+    this.defaultTtl = options?.defaultTtlSeconds ?? 1800;
+  }
+  key(sessionId) {
+    return `${this.prefix}${sessionId}`;
+  }
+  async create(session) {
+    const remaining = Math.ceil((session.expiresAt - Date.now()) / 1e3);
+    const ttl = remaining > 0 ? remaining : this.defaultTtl;
+    await this.client.set(this.key(session.sessionId), JSON.stringify(session), "EX", ttl);
+  }
+  async get(sessionId) {
+    const data = await this.client.get(this.key(sessionId));
+    if (!data) return null;
+    try {
+      return JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  async update(session) {
+    const remaining = Math.ceil((session.expiresAt - Date.now()) / 1e3);
+    const ttl = remaining > 0 ? remaining : this.defaultTtl;
+    await this.client.set(this.key(session.sessionId), JSON.stringify(session), "EX", ttl);
+  }
+  async invalidate(sessionId) {
+    await this.client.del(this.key(sessionId));
+  }
+};
+var RedisRateLimiter = class {
+  constructor(client, options) {
+    this.client = client;
+    this.prefix = options?.prefix ?? "bd:rl:";
+  }
+  async check(key, limit, windowMs) {
+    const fullKey = `${this.prefix}${key}`;
+    const windowSec = Math.max(1, Math.ceil(windowMs / 1e3));
+    try {
+      if (typeof this.client.eval === "function") {
+        const lua = `
+          local current = redis.call('INCR', KEYS[1])
+          if current == 1 then
+            redis.call('EXPIRE', KEYS[1], ARGV[1])
+          end
+          return current
+        `;
+        const count2 = Number(await this.client.eval(lua, 1, fullKey, windowSec));
+        const allowed2 = count2 <= limit;
+        const remaining = Math.max(0, limit - count2);
+        return {
+          allowed: allowed2,
+          remaining,
+          ...allowed2 ? {} : { retryAfter: windowSec }
+        };
+      }
+      const raw = await this.client.get(fullKey);
+      const count = (raw ? parseInt(raw, 10) : 0) + 1;
+      await this.client.set(fullKey, String(count), "EX", windowSec);
+      const allowed = count <= limit;
+      return {
+        allowed,
+        remaining: Math.max(0, limit - count),
+        ...allowed ? {} : { retryAfter: windowSec }
+      };
+    } catch {
+      return { allowed: true, remaining: limit };
+    }
+  }
+};
+var RedisTokenRevocationStore = class {
+  constructor(client, options) {
+    this.client = client;
+    this.prefix = options?.prefix ?? "bd:revoked:";
+  }
+  async isRevoked(tokenId) {
+    const exists = await this.client.get(`${this.prefix}${tokenId}`);
+    return exists !== null;
+  }
+  async revoke(tokenId, ttlMs) {
+    const ttlSec = Math.max(1, Math.ceil(ttlMs / 1e3));
+    await this.client.set(`${this.prefix}${tokenId}`, "1", "EX", ttlSec);
+  }
+};
+async function verifyRequestRiskToken(server, request, options) {
+  const headerName = (options?.headerName ?? "x-risk-token").toLowerCase();
+  const bodyField = options?.bodyField ?? "riskToken";
+  let token;
+  if (typeof request.header === "function") {
+    token = request.header(headerName);
+  } else if (typeof request.get === "function") {
+    token = request.get(headerName);
+  } else if (request.headers) {
+    const raw = request.headers[headerName];
+    token = Array.isArray(raw) ? raw[0] : raw;
+  }
+  if (!token && request.body && typeof request.body === "object") {
+    const fromBody = request.body[bodyField];
+    if (typeof fromBody === "string") token = fromBody;
+  }
+  if (!token) {
+    throw new devnBotDetectorCore.BotDetectorError(
+      "MALFORMED_REQUEST",
+      `Missing risk token in header '${headerName}' or body field '${bodyField}'.`,
+      "req_guard"
+    );
+  }
+  if (options?.consume) {
+    return server.consumeRiskToken(token, options);
+  }
+  const payload = server.verifyRiskToken(token, options);
+  if (!payload) {
+    throw new devnBotDetectorCore.BotDetectorError("MALFORMED_REQUEST", "Invalid or expired risk token.", "req_guard");
+  }
+  return payload;
+}
+function createExpressBotDetector(server) {
+  return {
+    /** Route handler for POST /v1/session */
+    sessionHandler: async (req, res) => {
+      try {
+        const siteKey = String(req.header(devnBotDetectorCore.SITE_KEY_HEADER) || req.headers[devnBotDetectorCore.SITE_KEY_HEADER.toLowerCase()] || "");
+        const result = await server.createSession({
+          siteKey,
+          hostname: req.body?.hostname,
+          userAgent: req.body?.userAgent,
+          timestamp: req.body?.timestamp,
+          request: {
+            ip: req.ip,
+            userAgent: req.get?.("user-agent"),
+            origin: req.get?.("origin"),
+            host: req.get?.("host"),
+            forwardedFor: req.get?.("x-forwarded-for")
+          }
+        });
+        res.json(result);
+      } catch (err) {
+        if (err instanceof devnBotDetectorCore.BotDetectorError) {
+          res.status(err.code === "RATE_LIMITED" ? 429 : err.code === "IP_BLOCKED" ? 403 : 400).json(err.toJSON());
+          return;
+        }
+        res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "Internal error.", requestId: "req_err" } });
+      }
+    },
+    /** Route handler for POST /v1/analyze */
+    analyzeHandler: async (req, res) => {
+      try {
+        const siteKey = String(req.header(devnBotDetectorCore.SITE_KEY_HEADER) || req.headers[devnBotDetectorCore.SITE_KEY_HEADER.toLowerCase()] || "");
+        const result = await server.analyze({
+          siteKey,
+          ...req.body,
+          request: {
+            ip: req.ip,
+            userAgent: req.get?.("user-agent"),
+            origin: req.get?.("origin"),
+            host: req.get?.("host"),
+            forwardedFor: req.get?.("x-forwarded-for")
+          }
+        });
+        res.json(result);
+      } catch (err) {
+        if (err instanceof devnBotDetectorCore.BotDetectorError) {
+          res.status(err.code === "RATE_LIMITED" ? 429 : err.code === "IP_BLOCKED" ? 403 : 400).json(err.toJSON());
+          return;
+        }
+        res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "Internal error.", requestId: "req_err" } });
+      }
+    },
+    /** Middleware protecting sensitive routes with risk token verification */
+    requireRiskToken: (options) => {
+      return async (req, res, next) => {
+        try {
+          const payload = await verifyRequestRiskToken(server, req, options);
+          req.riskTokenPayload = payload;
+          next();
+        } catch (err) {
+          if (err instanceof devnBotDetectorCore.BotDetectorError) {
+            res.status(err.code === "TOKEN_ALREADY_USED" ? 409 : 403).json(err.toJSON());
+            return;
+          }
+          res.status(403).json({ error: { code: "MALFORMED_REQUEST", message: "Forbidden", requestId: "req_guard" } });
+        }
+      };
+    }
+  };
+}
+
+Object.defineProperty(exports, "API_PATHS", {
+  enumerable: true,
+  get: function () { return devnBotDetectorCore.API_PATHS; }
+});
+Object.defineProperty(exports, "BotDetectorError", {
+  enumerable: true,
+  get: function () { return devnBotDetectorCore.BotDetectorError; }
+});
+Object.defineProperty(exports, "SITE_KEY_HEADER", {
+  enumerable: true,
+  get: function () { return devnBotDetectorCore.SITE_KEY_HEADER; }
+});
+exports.ActionRiskDetector = ActionRiskDetector;
+exports.AutomationDetector = AutomationDetector;
+exports.BotDetectionServer = BotDetectionServer;
+exports.BrowserConsistencyDetector = BrowserConsistencyDetector;
+exports.DEFAULT_DETECTORS = DEFAULT_DETECTORS;
+exports.EntropyDetector = EntropyDetector;
+exports.HeadlessAdvancedDetector = HeadlessAdvancedDetector;
+exports.InteractionDetector = InteractionDetector;
+exports.MemoryRateLimiter = MemoryRateLimiter;
+exports.MemorySessionStore = MemorySessionStore;
+exports.MemorySiteResolver = MemorySiteResolver;
+exports.MemoryTokenRevocationStore = MemoryTokenRevocationStore;
+exports.RedisRateLimiter = RedisRateLimiter;
+exports.RedisSessionStore = RedisSessionStore;
+exports.RedisTokenRevocationStore = RedisTokenRevocationStore;
+exports.RiskEngine = RiskEngine;
+exports.SessionDetector = SessionDetector;
+exports.TimingDetector = TimingDetector;
+exports.TokenManager = TokenManager;
+exports.VelocityDetector = VelocityDetector;
+exports.createExpressBotDetector = createExpressBotDetector;
+exports.secureId = secureId;
+exports.verifyRequestRiskToken = verifyRequestRiskToken;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map