@anomira/node-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,973 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var async_hooks = require('async_hooks');
+
+// src/client.ts
+
+// src/buffer.ts
+var EventBuffer = class {
+  constructor(opts) {
+    this.queue = [];
+    this.timer = null;
+    this.flushing = false;
+    this.opts = opts;
+    this.startTimer();
+    this.registerShutdownHook();
+  }
+  // ─── Public API ────────────────────────────────────────────────────────────
+  push(event) {
+    this.queue.push(event);
+    this.log(`[buffer] +1 event \u2192 ${this.queue.length} queued (${event.name})`);
+    if (this.queue.length >= this.opts.maxBatchSize) {
+      this.log("[buffer] batch size reached \u2014 flushing immediately");
+      void this.flush();
+    }
+  }
+  async flush() {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+    const batch = this.queue.splice(0, this.opts.maxBatchSize);
+    this.log(`[buffer] flushing ${batch.length} events`);
+    try {
+      await this.sendWithRetry(batch);
+    } catch (err) {
+      this.warn(`[buffer] dropped ${batch.length} events after max retries:`, err);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /** Call on graceful shutdown to flush remaining events synchronously. */
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+    this.log("[buffer] shutdown complete");
+  }
+  // ─── Internals ─────────────────────────────────────────────────────────────
+  startTimer() {
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.opts.flushIntervalMs);
+    if (this.timer.unref) this.timer.unref();
+  }
+  registerShutdownHook() {
+    const current = process.getMaxListeners();
+    process.setMaxListeners(current + 3);
+    const handler = () => {
+      void this.shutdown();
+    };
+    process.once("SIGTERM", handler);
+    process.once("SIGINT", handler);
+    process.once("beforeExit", handler);
+  }
+  async sendWithRetry(events, attempt = 1) {
+    const { appId, apiKey, ingestUrl, maxRetries } = this.opts;
+    const payload = { appId, events };
+    try {
+      const res = await fetch(ingestUrl, {
+        method: "POST",
+        redirect: "manual",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `@sentinelapi/node-sdk/0.1.0`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(8e3)
+      });
+      if (res.ok) {
+        this.log(`[buffer] \u2705 sent ${events.length} events (attempt ${attempt})`);
+        return;
+      }
+      if (res.status >= 300 && res.status < 400) {
+        this.warn(`[buffer] \u274C Wrong ingest URL \u2014 got redirect to ${res.headers.get("location")}. Check SENTINEL_INGEST_URL.`);
+        return;
+      }
+      if (res.status === 401) {
+        this.warn("[buffer] \u274C Invalid API key \u2014 check your SENTINEL_API_KEY environment variable");
+        return;
+      }
+      if (res.status === 403) {
+        this.warn("[buffer] \u274C App not found \u2014 check your SENTINEL_APP_ID environment variable");
+        return;
+      }
+      if (res.status >= 400 && res.status < 500) {
+        this.warn(`[buffer] \u26A0\uFE0F  ingest rejected ${res.status} \u2014 dropping batch`);
+        return;
+      }
+      throw new Error(`Ingest HTTP ${res.status}`);
+    } catch (err) {
+      if (attempt >= maxRetries) throw err;
+      const delayMs = Math.min(1e3 * 2 ** (attempt - 1), 16e3);
+      this.log(`[buffer] retry ${attempt}/${maxRetries} in ${delayMs}ms`);
+      await sleep(delayMs);
+      return this.sendWithRetry(events, attempt + 1);
+    }
+  }
+  log(...args) {
+    if (this.opts.debug) console.log("[SentinelAPI]", ...args);
+  }
+  warn(...args) {
+    console.warn("[SentinelAPI]", ...args);
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/geo-velocity.ts
+var lastSeen = /* @__PURE__ */ new Map();
+var geoCache = /* @__PURE__ */ new Map();
+var MAX_SPEED_KMH = 900;
+var PRIVATE_RANGES = [
+  /^10\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^127\./,
+  /^::1$/,
+  /^0\.0\.0\.0$/,
+  /^fc00:/i,
+  /^fe80:/i
+];
+function isPrivateIp(ip) {
+  return PRIVATE_RANGES.some((r) => r.test(ip));
+}
+async function lookupGeo(ip, lookupUrl) {
+  if (!ip || isPrivateIp(ip)) return null;
+  const cached = geoCache.get(ip);
+  if (cached && cached.expiresAt > Date.now()) return cached.point;
+  const url = lookupUrl ? `${lookupUrl}?ip=${encodeURIComponent(ip)}` : null;
+  if (!url) return null;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(2e3) });
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (data.lat == null || data.lng == null) return null;
+    const point = {
+      ip,
+      lat: data.lat,
+      lng: data.lng,
+      country: data.country,
+      city: data.city
+    };
+    geoCache.set(ip, { point, expiresAt: Date.now() + 36e5 });
+    return point;
+  } catch {
+    return null;
+  }
+}
+function haversineKm(lat1, lng1, lat2, lng2) {
+  const R = 6371;
+  const dLat = toRad(lat2 - lat1);
+  const dLng = toRad(lng2 - lng1);
+  const a = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
+  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+function toRad(deg) {
+  return deg * Math.PI / 180;
+}
+async function checkGeoVelocity(userId, ip, tsMs, lookupUrl) {
+  const geo = await lookupGeo(ip, lookupUrl);
+  if (!geo) return null;
+  const currentPoint = { ...geo, tsMs };
+  const prev = lastSeen.get(userId);
+  lastSeen.set(userId, currentPoint);
+  if (lastSeen.size > 1e4) {
+    const cutoff = Date.now() - 864e5;
+    for (const [key, val] of lastSeen) {
+      if (val.tsMs < cutoff) lastSeen.delete(key);
+    }
+  }
+  if (!prev) return null;
+  if (prev.ip === ip) return null;
+  const distanceKm = haversineKm(prev.lat, prev.lng, currentPoint.lat, currentPoint.lng);
+  const hours = Math.max((tsMs - prev.tsMs) / 36e5, 1e-3);
+  const speedKmH = distanceKm / hours;
+  if (speedKmH < MAX_SPEED_KMH) return null;
+  return {
+    isImpossible: true,
+    distanceKm: Math.round(distanceKm),
+    speedKmH: Math.round(speedKmH),
+    from: prev,
+    to: currentPoint
+  };
+}
+
+// src/sensitive.ts
+var PATTERNS = [
+  {
+    // "password: abc123", "pwd=secret", or standalone "password123"
+    type: "password",
+    label: "Password / Secret",
+    regex: /\bpassword\w*|\b(?:passwd|pwd|pass|secret|credentials?)\s*[:=]\s*\S+/i
+  },
+  {
+    // Nigerian BVN / NIN — exactly 11 digits, not a phone number (phones start with 0)
+    type: "bvn",
+    label: "BVN / NIN",
+    regex: /\b[1-9]\d{10}\b/
+  },
+  {
+    // JWT — three base64url segments separated by dots
+    type: "jwt",
+    label: "JWT Token",
+    regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/
+  },
+  {
+    // API keys: sk_live_*, pk_live_*, or key/token/bearer label with long value
+    type: "api_key",
+    label: "API Key / Token",
+    regex: /\b(?:sk|pk|rk)[-_](?:live|test|prod|secret)[-_][A-Za-z0-9]{16,}|\b(?:token|bearer|access_token|api_key)\s*[:=]\s*[A-Za-z0-9_./-]{20,}/i
+  },
+  {
+    // Card PANs: Visa (4), Mastercard (51-55), Amex (34/37), Discover (6011/65)
+    type: "card_pan",
+    label: "Card PAN",
+    regex: /\b(?:4[0-9]{15}|5[1-5][0-9]{14}|3[47][0-9]{13}|6(?:011|5[0-9]{2})[0-9]{12})\b/
+  },
+  {
+    // Nigerian phone numbers: 080x, 081x, 070x, 090x, 091x — or with +234 prefix
+    type: "ng_phone",
+    label: "Phone Number",
+    regex: /\b(?:\+?234|0)(?:7[0-9]|8[0-1]|9[0-1])\d{8}\b/
+  },
+  {
+    // Email address appearing alongside other content — possible credential combo
+    // e.g. "john@test.com password123"
+    type: "email_credential",
+    label: "Email in Log",
+    regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/
+  }
+];
+function scanForLeaks(message) {
+  const found = [];
+  for (const p of PATTERNS) {
+    p.regex.lastIndex = 0;
+    if (p.regex.test(message)) {
+      found.push({ type: p.type, label: p.label });
+    }
+  }
+  return found;
+}
+
+// src/types.ts
+var EventName = {
+  // Auth
+  LOGIN_SUCCESS: "auth.login.success",
+  LOGIN_FAILED: "auth.login.failed",
+  LOGOUT: "auth.logout",
+  OTP_FAILED: "auth.otp.failed",
+  OTP_SUCCESS: "auth.otp.success",
+  BVN_LOOKUP: "auth.bvn.lookup",
+  NIN_LOOKUP: "auth.nin.lookup",
+  // NIN enumeration detection
+  GEO_VELOCITY: "auth.login.geo_velocity",
+  CREDENTIAL_STUFF: "auth.credential.stuffing",
+  SIM_SWAP: "auth.sim_swap.suspected",
+  // SIM swap fraud signal
+  PHONE_AUTH: "auth.phone.verified",
+  // Phone-based auth (OTP/2FA via phone)
+  // HTTP layer (auto-detected by middleware)
+  REQUEST: "http.request",
+  // every request — feeds the Events dashboard
+  RATE_LIMIT: "http.ratelimit.exceeded",
+  XSS_DETECTED: "http.xss.detected",
+  PATH_TRAVERSAL: "http.path.traversal",
+  SCAN_DETECTED: "http.scan.detected",
+  IDOR_ATTEMPT: "user.idor.attempt",
+  SQL_ERROR: "db.sql.error",
+  // Firewall (emitted when a custom request filtering rule fires)
+  FIREWALL_BLOCK: "http.firewall.block",
+  FIREWALL_FLAG: "http.firewall.flag"
+};
+
+// src/client.ts
+var requestContext = new async_hooks.AsyncLocalStorage();
+var DEFAULT_INGEST_URL = "https://ingest.anomira.io/v1/events";
+var DEFAULT_BATCH_SIZE = 100;
+var DEFAULT_FLUSH_MS = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var SentinelClient = class {
+  constructor(config) {
+    this.logBuffer = [];
+    this.logFlushTimer = null;
+    this.blocklistTimer = null;
+    this.firewallTimer = null;
+    /** In-process cache of blocked IPs — refreshed every 60 s from the ingest server. */
+    this.blockedIpCache = /* @__PURE__ */ new Set();
+    /** In-process cache of firewall rules with pre-compiled regex — refreshed every 60 s. */
+    this.compiledRules = [];
+    // Saved originals — used by SDK internals so patched console doesn't recurse
+    this._origLog = console.log.bind(console);
+    this._origWarn = console.warn.bind(console);
+    this._origError = console.error.bind(console);
+    if (!config.apiKey) throw new Error("[SentinelAPI] apiKey is required");
+    if (!config.appId) throw new Error("[SentinelAPI] appId is required");
+    this.config = {
+      apiKey: config.apiKey,
+      appId: config.appId,
+      ingestUrl: config.ingestUrl ?? DEFAULT_INGEST_URL,
+      geoLookupUrl: config.geoLookupUrl ?? "",
+      maxBatchSize: config.maxBatchSize ?? DEFAULT_BATCH_SIZE,
+      flushIntervalMs: config.flushIntervalMs ?? DEFAULT_FLUSH_MS,
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      debug: config.debug ?? false,
+      captureConsole: config.captureConsole ?? false,
+      service: config.service ?? "app",
+      getUserId: config.getUserId ?? defaultGetUserId,
+      getIp: config.getIp ?? defaultGetIp,
+      detect: {
+        bruteForce: config.detect?.bruteForce ?? true,
+        rateAbuse: config.detect?.rateAbuse ?? true,
+        pathTraversal: config.detect?.pathTraversal ?? true,
+        xss: config.detect?.xss ?? true,
+        scanDetection: config.detect?.scanDetection ?? true,
+        geoVelocity: config.detect?.geoVelocity ?? true
+      }
+    };
+    this.buffer = new EventBuffer({
+      appId: this.config.appId,
+      apiKey: this.config.apiKey,
+      ingestUrl: this.config.ingestUrl,
+      maxBatchSize: this.config.maxBatchSize,
+      flushIntervalMs: this.config.flushIntervalMs,
+      maxRetries: this.config.maxRetries,
+      debug: this.config.debug
+    });
+    void this.#validateCredentials();
+    void this.#refreshBlocklist();
+    this.blocklistTimer = setInterval(() => {
+      void this.#refreshBlocklist();
+    }, 6e4);
+    if (this.blocklistTimer.unref) this.blocklistTimer.unref();
+    void this.#refreshFirewallRules();
+    this.firewallTimer = setInterval(() => {
+      void this.#refreshFirewallRules();
+    }, 6e4);
+    if (this.firewallTimer.unref) this.firewallTimer.unref();
+    this.logFlushTimer = setInterval(() => {
+      void this.#flushLogs();
+    }, 1e4);
+    if (this.logFlushTimer.unref) this.logFlushTimer.unref();
+    if (this.config.captureConsole) this.#interceptConsole();
+  }
+  #interceptConsole() {
+    const map = [
+      ["debug", "debug"],
+      ["log", "info"],
+      ["info", "info"],
+      ["warn", "warn"],
+      ["error", "error"]
+    ];
+    for (const [method, level] of map) {
+      const original = console[method].bind(console);
+      console[method] = (...args) => {
+        original(...args);
+        const first = args[0];
+        if (typeof first === "string" && first.startsWith("[SentinelAPI]")) return;
+        const message = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+        const ctx = requestContext.getStore();
+        this.log(level, message, {
+          service: this.config.service,
+          ...ctx ? { endpoint: ctx.endpoint, method: ctx.method, ip: ctx.ip } : {}
+        });
+      };
+    }
+  }
+  async #refreshBlocklist() {
+    const syncUrl = this.config.ingestUrl.replace(/\/v1\/events$/, "/v1/blocked-ips/sync");
+    try {
+      const res = await fetch(syncUrl, {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "User-Agent": `@anomira/node-sdk/0.1.0`
+        },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) return;
+      const data = await res.json();
+      this.blockedIpCache = new Set(data.ips ?? []);
+      if (this.config.debug && this.blockedIpCache.size > 0) {
+        this._origLog(`[SentinelAPI] blocklist refreshed \u2014 ${this.blockedIpCache.size} blocked IPs`);
+      }
+    } catch {
+    }
+  }
+  async #refreshFirewallRules() {
+    const syncUrl = this.config.ingestUrl.replace(/\/v1\/events$/, "/v1/firewall-rules/sync");
+    try {
+      const res = await fetch(syncUrl, {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "User-Agent": `@anomira/node-sdk/0.1.0`
+        },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) return;
+      const data = await res.json();
+      this.compiledRules = (data.rules ?? []).map((rule) => ({
+        rule,
+        re: rule.operator === "regex" ? (() => {
+          try {
+            return new RegExp(rule.value, "i");
+          } catch {
+            return void 0;
+          }
+        })() : void 0
+      }));
+      if (this.config.debug && this.compiledRules.length > 0) {
+        this._origLog(`[SentinelAPI] firewall rules refreshed \u2014 ${this.compiledRules.length} active rules`);
+      }
+    } catch {
+    }
+  }
+  /** Evaluate all cached firewall rules against the current request.
+   *  Returns the first matching rule, or null if none match. */
+  #matchFirewallRule(req) {
+    for (const { rule, re } of this.compiledRules) {
+      let target;
+      switch (rule.field) {
+        case "url":
+          target = req.url;
+          break;
+        case "body":
+          target = typeof req.body === "string" ? req.body : JSON.stringify(req.body ?? "");
+          break;
+        case "header":
+          target = req.headers[(rule.headerName ?? "").toLowerCase()] ?? "";
+          break;
+        case "user_agent":
+          target = req.headers["user-agent"] ?? "";
+          break;
+        case "ip":
+          target = req.ip;
+          break;
+        default:
+          continue;
+      }
+      const matched = rule.operator === "regex" ? re?.test(target) ?? false : rule.operator === "contains" ? target.includes(rule.value) : rule.operator === "equals" ? target === rule.value : rule.operator === "starts_with" ? target.startsWith(rule.value) : rule.operator === "ends_with" ? target.endsWith(rule.value) : false;
+      if (matched) return { rule };
+    }
+    return null;
+  }
+  async #flushLogs() {
+    if (this.logBuffer.length === 0) return;
+    const batch = this.logBuffer.splice(0, 500);
+    const logsUrl = this.config.ingestUrl.replace(/\/v1\/events$/, "/v1/logs");
+    try {
+      const res = await fetch(logsUrl, {
+        method: "POST",
+        redirect: "manual",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `@anomira/node-sdk/0.1.0`
+        },
+        body: JSON.stringify({ appId: this.config.appId, logs: batch }),
+        signal: AbortSignal.timeout(8e3)
+      });
+      if (this.config.debug) {
+        this._origLog(`[SentinelAPI] [logs] \u2705 sent ${batch.length} log entries (${res.status})`);
+      }
+    } catch {
+      this.logBuffer.unshift(...batch);
+    }
+  }
+  async #validateCredentials() {
+    const pingUrl = this.config.ingestUrl.replace(/\/v1\/events$/, "/v1/ping") + `?appId=${encodeURIComponent(this.config.appId)}`;
+    try {
+      const res = await fetch(pingUrl, {
+        method: "GET",
+        redirect: "manual",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "User-Agent": `@anomira/node-sdk/0.1.0`
+        },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (res.status >= 300 && res.status < 400) {
+        this._origWarn(`[SentinelAPI] \u274C Wrong ingest URL \u2014 got redirect to ${res.headers.get("location")}. Check SENTINEL_INGEST_URL.`);
+        return;
+      }
+      if (res.ok) {
+        this._origLog(`[SentinelAPI] \u2705 Connected (appId: ${this.config.appId.slice(0, 8)}\u2026)`);
+        return;
+      }
+      if (res.status === 401) {
+        this._origWarn("[SentinelAPI] \u274C Invalid API key \u2014 check your SENTINEL_API_KEY");
+        return;
+      }
+      if (res.status === 403) {
+        this._origWarn("[SentinelAPI] \u274C App not found or appId mismatch \u2014 check your SENTINEL_APP_ID");
+        return;
+      }
+      this._origWarn(`[SentinelAPI] \u26A0\uFE0F  Ingest returned HTTP ${res.status} \u2014 check your configuration`);
+    } catch {
+      this._origWarn("[SentinelAPI] \u26A0\uFE0F  Could not reach ingest endpoint \u2014 check SENTINEL_INGEST_URL (current: " + this.config.ingestUrl + ")");
+    }
+  }
+  // ─── Public API ────────────────────────────────────────────────────────────
+  /**
+   * Track a custom security event.
+   *
+   * ```ts
+   * // Track a failed OTP attempt
+   * sentinel.track(EventName.OTP_FAILED, {
+   *   ip:     req.ip,
+   *   userId: req.body.phone,
+   *   meta:   { endpoint: "/api/verify-otp", attempts: 3 },
+   * });
+   * ```
+   */
+  /** Returns true if the IP is in the current blocked list. Synchronous — no network call. */
+  isBlocked(ip) {
+    return this.blockedIpCache.has(ip);
+  }
+  /** Evaluate firewall rules against a request. Returns the matched rule or null. Synchronous. */
+  matchFirewallRule(req) {
+    return this.#matchFirewallRule(req);
+  }
+  track(eventName, data) {
+    const event = {
+      name: eventName,
+      ts: Date.now(),
+      ip: data.ip,
+      userId: data.userId,
+      meta: data.meta
+    };
+    this.buffer.push(event);
+  }
+  /**
+   * Track a successful login AND run geo-velocity check.
+   * If impossible travel is detected, automatically fires an additional
+   * `auth.login.geo_velocity` event with full context.
+   *
+   * ```ts
+   * await sentinel.trackLogin({
+   *   ip:     req.ip,
+   *   userId: user.id,
+   * });
+   * ```
+   */
+  async trackLogin(data) {
+    const tsMs = Date.now();
+    this.track(EventName.LOGIN_SUCCESS, { ...data, meta: { ...data.meta } });
+    if (!this.config.detect.geoVelocity) return;
+    try {
+      const result = await checkGeoVelocity(data.userId, data.ip, tsMs, this.config.geoLookupUrl || void 0);
+      if (!result) return;
+      this.track(EventName.GEO_VELOCITY, {
+        ip: data.ip,
+        userId: data.userId,
+        meta: {
+          distanceKm: result.distanceKm,
+          speedKmH: result.speedKmH,
+          fromIp: result.from.ip,
+          fromCity: result.from.city,
+          fromCountry: result.from.country,
+          toCity: result.to.city,
+          toCountry: result.to.country,
+          minutesDiff: Math.round((result.to.tsMs - result.from.tsMs) / 6e4),
+          ...data.meta
+        }
+      });
+    } catch {
+    }
+  }
+  /**
+   * Track phone-based authentication (OTP via SMS, WhatsApp, or call).
+   * The ingest service uses this to detect SIM swap patterns:
+   * if the same userId authenticates via phone but then appears on a new
+   * device/IP shortly after, it's flagged as a suspected SIM swap.
+   *
+   * ```ts
+   * await sentinel.trackPhoneAuth({
+   *   ip:     req.ip,
+   *   userId: user.id,
+   *   phone:  user.phoneNumber,
+   * });
+   * ```
+   */
+  trackPhoneAuth(data) {
+    this.track(EventName.PHONE_AUTH, {
+      ip: data.ip,
+      userId: data.userId,
+      meta: { phone: data.phone, ...data.meta }
+    });
+  }
+  /**
+   * Send a structured log entry to the SentinelAPI Logs dashboard.
+   *
+   * ```ts
+   * sentinel.log("info",  "User registered",         { userId: user.id });
+   * sentinel.log("warn",  "Slow DB query detected",  { queryMs: 1240 });
+   * sentinel.log("error", "Payment failed",           { reason: err.message });
+   * ```
+   */
+  log(level, message, meta) {
+    const { service, ...rest } = meta ?? {};
+    const leaks = scanForLeaks(message);
+    if (leaks.length > 0) {
+      rest["sensitiveLeaks"] = leaks.map((l) => l.type);
+      if (this.config.debug) {
+        this._origWarn(
+          `[SentinelAPI] \u26A0\uFE0F  Sensitive data in log (${leaks.map((l) => l.label).join(", ")}): "${message.slice(0, 60)}\u2026"`
+        );
+      }
+    }
+    this.logBuffer.push({ level, service: service ?? this.config.service, message, meta: rest, ts: Date.now() });
+    if (this.config.debug && leaks.length === 0) {
+      this._origLog(`[SentinelAPI] log:${level} ${message}`);
+    }
+    if (this.logBuffer.length >= 50) void this.#flushLogs();
+  }
+  /**
+   * Flush all pending events immediately.
+   * Useful before a graceful shutdown outside of the process lifecycle hooks.
+   */
+  async flush() {
+    await Promise.all([this.buffer.flush(), this.#flushLogs()]);
+  }
+  /**
+   * Express middleware — auto-instruments all routes.
+   *
+   * ```ts
+   * app.use(sentinel.express());
+   * ```
+   */
+  express() {
+    return createExpressMiddleware(this);
+  }
+  /**
+   * Fastify plugin — auto-instruments all routes.
+   *
+   * ```ts
+   * await app.register(sentinel.fastify());
+   * ```
+   */
+  fastify() {
+    return createFastifyPlugin(this);
+  }
+};
+function defaultGetUserId(req) {
+  const r = req;
+  const user = r["user"];
+  if (!user) return void 0;
+  return user["id"] ?? user["userId"] ?? user["sub"] ?? user["_id"];
+}
+function normalizeIp(raw) {
+  if (raw === "::1") return "127.0.0.1";
+  if (raw === "::ffff:127.0.0.1") return "127.0.0.1";
+  if (raw.startsWith("::ffff:")) return raw.slice(7);
+  return raw;
+}
+function defaultGetIp(req) {
+  const r = req;
+  const fwd = r["headers"];
+  const xff = fwd?.["x-forwarded-for"];
+  if (xff) {
+    const first = Array.isArray(xff) ? xff[0] : xff.split(",")[0];
+    if (first) return normalizeIp(first.trim());
+  }
+  const xri = fwd?.["x-real-ip"];
+  if (typeof xri === "string") return normalizeIp(xri.trim());
+  const socket = r["socket"];
+  return normalizeIp(socket?.remoteAddress ?? "0.0.0.0");
+}
+function createExpressMiddleware(client) {
+  return async function sentinelMiddleware(req, res, next) {
+    const startMs = Date.now();
+    const ip = client.config.getIp(req);
+    if (client.isBlocked(ip)) {
+      const res_ = res;
+      if (typeof res_["status"] === "function") {
+        res_["status"](403);
+      } else {
+        res_["statusCode"] = 403;
+      }
+      if (typeof res_["end"] === "function") res_["end"]('{"error":"Forbidden"}');
+      return;
+    }
+    const userId = client.config.getUserId(req);
+    const method = req["method"]?.toUpperCase() ?? "GET";
+    const url = req["originalUrl"] ?? req["url"] ?? "/";
+    const headers = req["headers"];
+    const ua = headers?.["user-agent"] ?? "";
+    const fwMatch = client.matchFirewallRule({ url, body: req["body"], headers: headers ?? {}, ip });
+    if (fwMatch) {
+      client.track("http.firewall." + fwMatch.rule.action, {
+        ip,
+        userId,
+        meta: { url, method, ruleId: fwMatch.rule.id, attackType: fwMatch.rule.attackType }
+      });
+      if (fwMatch.rule.action === "block") {
+        const res_ = res;
+        if (typeof res_["status"] === "function") res_["status"](403);
+        else res_["statusCode"] = 403;
+        if (typeof res_["end"] === "function") res_["end"]('{"error":"Blocked by firewall rule"}');
+        return;
+      }
+    }
+    if (client.config.detect.pathTraversal && (url.includes("../") || url.includes("..%2F"))) {
+      client.track(EventName.PATH_TRAVERSAL, { ip, userId, meta: { url, method } });
+    }
+    if (client.config.detect.xss && ["POST", "PUT", "PATCH"].includes(method)) {
+      const body = JSON.stringify(req["body"]);
+      if (/<script|javascript:|on\w+=/i.test(body)) {
+        client.track(EventName.XSS_DETECTED, { ip, userId, meta: { url, method } });
+      }
+    }
+    const onFinish = () => {
+      const status = res["statusCode"] ?? 0;
+      const latencyMs = Date.now() - startMs;
+      const getHeader = res["getHeader"];
+      const bytes = typeof getHeader === "function" ? parseInt(getHeader.call(res, "content-length") ?? "0", 10) || 0 : 0;
+      client.track(EventName.REQUEST, {
+        ip,
+        userId,
+        meta: { method, endpoint: url, status, latencyMs, userAgent: ua, bytes }
+      });
+      if (client.config.detect.rateAbuse && status === 429) {
+        client.track(EventName.RATE_LIMIT, { ip, userId, meta: { url, method, statusCode: status } });
+      }
+      if (client.config.detect.bruteForce && status === 401) {
+        if (/\/(login|signin|auth|token|session)/i.test(url)) {
+          client.track(EventName.LOGIN_FAILED, { ip, userId, meta: { url, method, statusCode: status } });
+        }
+      }
+      if (client.config.detect.scanDetection && status === 404) {
+        const looksLikeScanner = !ua || /curl|wget|python|go-http|nuclei|sqlmap|nikto/i.test(ua);
+        if (looksLikeScanner) {
+          client.track(EventName.SCAN_DETECTED, { ip, userId, meta: { url, method, userAgent: ua } });
+        }
+      }
+      cleanup();
+    };
+    const cleanup = () => {
+      res.off?.("finish", onFinish);
+    };
+    res.on?.("finish", onFinish);
+    requestContext.run({ endpoint: url, method, ip }, next);
+  };
+}
+function createFastifyPlugin(client) {
+  return async function sentinelFastifyPlugin(fastify) {
+    fastify.addHook("onRequest", (req, reply) => {
+      const ip = client.config.getIp(req);
+      if (client.isBlocked(ip)) {
+        const rep = reply;
+        if (typeof rep["code"] === "function") {
+          const chained = rep["code"](403);
+          if (chained && typeof chained["send"] === "function") {
+            chained["send"]({ error: "Forbidden" });
+          }
+        }
+        return;
+      }
+      const url = req["url"] ?? "/";
+      const method = req["method"]?.toUpperCase() ?? "GET";
+      const userId = client.config.getUserId(req);
+      if (client.config.detect.pathTraversal && (url.includes("../") || url.includes("..%2F"))) {
+        client.track(EventName.PATH_TRAVERSAL, { ip, userId, meta: { url, method } });
+      }
+    });
+    fastify.addHook("preHandler", (req, reply) => {
+      const ip = client.config.getIp(req);
+      const url = req["url"] ?? "/";
+      const method = req["method"]?.toUpperCase() ?? "GET";
+      const userId = client.config.getUserId(req);
+      const headers = req["headers"];
+      const fwMatch = client.matchFirewallRule({ url, body: req["body"], headers: headers ?? {}, ip });
+      if (fwMatch) {
+        client.track("http.firewall." + fwMatch.rule.action, {
+          ip,
+          userId,
+          meta: { url, method, ruleId: fwMatch.rule.id, attackType: fwMatch.rule.attackType }
+        });
+        if (fwMatch.rule.action === "block") {
+          const rep = reply;
+          if (typeof rep["code"] === "function") {
+            const chained = rep["code"](403);
+            if (chained && typeof chained["send"] === "function") {
+              chained["send"]({ error: "Blocked by firewall rule" });
+            }
+          }
+          return;
+        }
+      }
+      if (client.config.detect.xss && ["POST", "PUT", "PATCH"].includes(method)) {
+        const body = JSON.stringify(req["body"]);
+        if (/<script|javascript:|on\w+=/i.test(body)) {
+          client.track(EventName.XSS_DETECTED, { ip, userId, meta: { url, method } });
+        }
+      }
+    });
+    fastify.addHook("onResponse", (req, reply) => {
+      const ip = client.config.getIp(req);
+      const url = req["url"] ?? "/";
+      const method = req["method"]?.toUpperCase() ?? "GET";
+      const userId = client.config.getUserId(req);
+      const status = reply["statusCode"] ?? 0;
+      const headers = req["headers"];
+      const ua = headers?.["user-agent"] ?? "";
+      const latencyMs = reply["elapsedTime"] ?? 0;
+      client.track(EventName.REQUEST, {
+        ip,
+        userId,
+        meta: { method, endpoint: url, status, latencyMs: Math.round(latencyMs), userAgent: ua, bytes: 0 }
+      });
+      if (client.config.detect.rateAbuse && status === 429) {
+        client.track(EventName.RATE_LIMIT, { ip, userId, meta: { url, method, statusCode: status } });
+      }
+      if (client.config.detect.bruteForce && status === 401 && /\/(login|signin|auth|token)/i.test(url)) {
+        client.track(EventName.LOGIN_FAILED, { ip, userId, meta: { url, method, statusCode: status } });
+      }
+      if (client.config.detect.scanDetection && status === 404) {
+        if (!ua || /curl|wget|python|go-http|nuclei|sqlmap|nikto/i.test(ua)) {
+          client.track(EventName.SCAN_DETECTED, { ip, userId, meta: { url, method, userAgent: ua } });
+        }
+      }
+      if (client.config.detect.bruteForce && status === 200 && /\/(login|signin|auth|token)/i.test(url)) {
+        if (userId) {
+          void client.trackLogin({ ip, userId, meta: { url, method } });
+        }
+      }
+    });
+  };
+}
+
+// src/middleware/express.ts
+function createExpressMiddleware2(client) {
+  return function sentinelMiddleware(req, res, next) {
+    const ip = client.config.getIp(req);
+    const userId = client.config.getUserId(req);
+    const { method, originalUrl: url } = req;
+    if (client.config.detect.pathTraversal && (url.includes("../") || url.includes("..%2F"))) {
+      client.track(EventName.PATH_TRAVERSAL, {
+        ip,
+        userId,
+        meta: { url, method }
+      });
+    }
+    if (client.config.detect.xss && ["POST", "PUT", "PATCH"].includes(method)) {
+      try {
+        const body = JSON.stringify(req.body);
+        if (/<script|javascript:|on\w+=/i.test(body)) {
+          client.track(EventName.XSS_DETECTED, {
+            ip,
+            userId,
+            meta: { url, method }
+          });
+        }
+      } catch {
+      }
+    }
+    const onFinish = () => {
+      res.off("finish", onFinish);
+      const { statusCode } = res;
+      if (client.config.detect.rateAbuse && statusCode === 429) {
+        client.track(EventName.RATE_LIMIT, {
+          ip,
+          userId,
+          meta: { url, method, statusCode }
+        });
+      }
+      if (client.config.detect.bruteForce && statusCode === 401) {
+        if (/\/(login|signin|auth|token|session)/i.test(url)) {
+          client.track(EventName.LOGIN_FAILED, {
+            ip,
+            userId,
+            meta: { url, method, statusCode }
+          });
+        }
+      }
+      if (client.config.detect.scanDetection && statusCode === 404) {
+        const ua = req.headers["user-agent"] ?? "";
+        if (!ua || /curl|wget|python|go-http|nuclei|sqlmap|nikto/i.test(ua)) {
+          client.track(EventName.SCAN_DETECTED, {
+            ip,
+            userId,
+            meta: { url, method, userAgent: ua }
+          });
+        }
+      }
+      if (client.config.detect.geoVelocity && statusCode === 200 && /\/(login|signin|auth|token)/i.test(url) && method === "POST") {
+        const resolvedUserId = client.config.getUserId(req);
+        if (resolvedUserId) {
+          void client.trackLogin({ ip, userId: resolvedUserId, meta: { url } });
+        }
+      }
+    };
+    res.on("finish", onFinish);
+    next();
+  };
+}
+
+// src/middleware/fastify.ts
+function createFastifyPlugin2(client) {
+  return async function sentinelPlugin(fastify) {
+    fastify.addHook("onRequest", async (req, _reply) => {
+      const ip = client.config.getIp(req);
+      const userId = client.config.getUserId(req);
+      const url = req.url;
+      const method = req.method.toUpperCase();
+      if (client.config.detect.pathTraversal && (url.includes("../") || url.includes("..%2F"))) {
+        client.track(EventName.PATH_TRAVERSAL, { ip, userId, meta: { url, method } });
+      }
+    });
+    fastify.addHook("preHandler", async (req, _reply) => {
+      const ip = client.config.getIp(req);
+      const userId = client.config.getUserId(req);
+      const url = req.url;
+      const method = req.method.toUpperCase();
+      if (client.config.detect.xss && ["POST", "PUT", "PATCH"].includes(method)) {
+        try {
+          const body = JSON.stringify(req.body);
+          if (/<script|javascript:|on\w+=/i.test(body)) {
+            client.track(EventName.XSS_DETECTED, { ip, userId, meta: { url, method } });
+          }
+        } catch {
+        }
+      }
+    });
+    fastify.addHook("onResponse", async (req, reply) => {
+      const ip = client.config.getIp(req);
+      const userId = client.config.getUserId(req);
+      const url = req.url;
+      const method = req.method.toUpperCase();
+      const statusCode = reply.statusCode;
+      if (client.config.detect.rateAbuse && statusCode === 429) {
+        client.track(EventName.RATE_LIMIT, { ip, userId, meta: { url, method, statusCode } });
+      }
+      if (client.config.detect.bruteForce && statusCode === 401) {
+        if (/\/(login|signin|auth|token|session)/i.test(url)) {
+          client.track(EventName.LOGIN_FAILED, { ip, userId, meta: { url, method, statusCode } });
+        }
+      }
+      if (client.config.detect.scanDetection && statusCode === 404) {
+        const ua = req.headers["user-agent"] ?? "";
+        if (!ua || /curl|wget|python|go-http|nuclei|sqlmap|nikto/i.test(ua)) {
+          client.track(EventName.SCAN_DETECTED, { ip, userId, meta: { url, method, userAgent: ua } });
+        }
+      }
+      if (client.config.detect.geoVelocity && statusCode === 200 && method === "POST" && /\/(login|signin|auth|token)/i.test(url)) {
+        const resolvedUserId = client.config.getUserId(req);
+        if (resolvedUserId) {
+          void client.trackLogin({ ip, userId: resolvedUserId, meta: { url } });
+        }
+      }
+    });
+  };
+}
+
+exports.EventName = EventName;
+exports.SentinelAPI = SentinelClient;
+exports.createExpressMiddleware = createExpressMiddleware2;
+exports.createFastifyPlugin = createFastifyPlugin2;
+exports.default = SentinelClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map