@anomira/node-sdk 0.2.3 → 0.2.5

package/README.md

@@ -168,41 +168,70 @@ Once registered, the middleware records **every request** with zero additional c
 
 Use these when the middleware can't infer the event on its own — e.g., application-level failures.
 
+### Getting the real client IP
+
+> **Important — do not use `req.ip` for the `ip` field.**
+>
+> Behind a reverse proxy (Nginx, AWS ALB, Cloudflare — which every production app uses), `req.ip` in Express without `trust proxy` configured returns `127.0.0.1` — the proxy's address, not the user's. This breaks geo-detection, IP blocking, and attack correlation.
+>
+> Always use `anomira.getClientIp(req)` instead. It reads `X-Forwarded-For`, `CF-Connecting-IP`, `X-Real-IP`, and other forwarded headers in the correct priority order automatically.
+
+```ts
+// ✅ Correct — works behind Nginx, Cloudflare, AWS ALB, any reverse proxy
+const ip = anomira.getClientIp(req);
+
+// ❌ Wrong behind a proxy — returns 127.0.0.1 unless trust proxy is configured
+const ip = req.ip;
+```
+
+If you use `anomira.express()` or `anomira.fastify()` middleware and call `track()` **inside a request handler**, you can omit the `ip` field entirely — the SDK reads it from the active request context automatically.
+
+```ts
+// ✅ Also correct — IP is resolved from middleware context, no need to pass it
+anomira.track("auth.otp.failed", { userId: req.body.phone });
+```
+
+### Examples
+
 ```ts
 // Credential stuffing / failed login attempt
 await anomira.trackLogin({
-  ip:      req.ip,
+  ip:      anomira.getClientIp(req),
   userId:  req.body.email,     // email or user ID
   success: false,              // false = failed attempt
 });
 
 // Successful login (enables geo-velocity tracking)
 await anomira.trackLogin({
-  ip:     req.ip,
-  userId: user.id,
+  ip:      anomira.getClientIp(req),
+  userId:  user.id,
   success: true,
 });
 
 // Failed OTP — otp_flood detection
 anomira.track("auth.otp.failed", {
-  ip:     req.ip,
+  ip:     anomira.getClientIp(req),
   userId: req.body.phone,
   meta:   { endpoint: "/api/verify-otp" },
 });
 
 // SIM swap detection — call after any phone-based auth
-anomira.trackPhoneAuth({ ip: req.ip, userId: user.id, phone: user.phone });
+anomira.trackPhoneAuth({
+  ip:     anomira.getClientIp(req),
+  userId: user.id,
+  phone:  user.phone,
+});
 
 // Account takeover signal — e.g., password changed from new IP
 anomira.track("auth.account.takeover", {
-  ip:     req.ip,
+  ip:     anomira.getClientIp(req),
   userId: user.id,
   meta:   { reason: "password_changed_new_ip" },
 });
 
 // Webhook replay — call when you detect a replayed webhook signature
 anomira.track("webhook.replay.detected", {
-  ip:   req.ip,
+  ip:   anomira.getClientIp(req),
   meta: { webhookId: req.headers["x-webhook-id"] },
 });
 ```
@@ -230,8 +259,10 @@ The SDK syncs your dashboard's blocked IPs and firewall rules every 60 seconds.
 
 ```ts
 app.use((req, res, next) => {
+  const ip = anomira.getClientIp(req);  // always use this, not req.ip
+
   // Check if IP is manually blocked in the dashboard
-  if (anomira.isBlocked(req.ip)) {
+  if (anomira.isBlocked(ip)) {
     return res.status(403).json({ error: "Forbidden" });
   }
 
@@ -241,7 +272,7 @@ app.use((req, res, next) => {
     method:  req.method,
     body:    req.body,
     headers: req.headers,
-    ip:      req.ip,
+    ip,
   });
 
   if (match) {
@@ -379,8 +410,8 @@ app.addHook("onClose", async () => {
 3. Confirm the middleware is registered **before** your routes and **after** body parsers.
 4. Make sure you're not blocking outbound HTTPS traffic to `api.anomira.io`.
 
-**TypeScript errors on `req.ip`?**
-Express types sometimes don't include `ip` directly. Use `(req as express.Request).ip ?? req.socket.remoteAddress ?? "0.0.0.0"`.
+**TypeScript errors on IP extraction?**
+Use `anomira.getClientIp(req)` — it handles all proxy headers and TypeScript types correctly. Do not use `req.ip` or `req.socket.remoteAddress` directly in production; both return the proxy address behind Nginx.
 
 **`flush()` taking too long on shutdown?**
 The flush waits for in-flight HTTP requests to complete. If your process needs to exit fast, you can add a timeout:

package/dist/index.cjs

@@ -404,7 +404,13 @@ var EventName = {
   SQL_ERROR: "db.sql.error",
   // Firewall (emitted when a custom request filtering rule fires)
   FIREWALL_BLOCK: "http.firewall.block",
-  FIREWALL_FLAG: "http.firewall.flag"
+  FIREWALL_FLAG: "http.firewall.flag",
+  FIREWALL_RATE_LIMIT: "http.firewall.rate_limit",
+  FIREWALL_REDIRECT_HONEYPOT: "http.firewall.redirect_honeypot",
+  FIREWALL_TAG: "http.firewall.tag",
+  FIREWALL_MONITOR: "http.firewall.monitor",
+  FIREWALL_CHALLENGE: "http.firewall.challenge",
+  FIREWALL_TEMP_BLOCK: "http.firewall.temporary_block"
 };
 
 // src/agent-detection.ts
@@ -521,6 +527,9 @@ var KNOWN_BOT_UA = [
   [/^Ruby$/i, "Ruby"]
 ];
 var AXIOS_ACCEPT = "application/json, text/plain, */*";
+function isBrowserUa(ua) {
+  return /Mozilla\/5\.0/.test(ua) && /(?:Chrome|Firefox|Safari|OPR|Edg(?:e|HTML)?|Trident)\/[\d.]+/.test(ua);
+}
 function computeBrowserFingerprint(headers, ua) {
   const signals = [];
   let score = 0;
@@ -537,10 +546,15 @@ function computeBrowserFingerprint(headers, ua) {
   }
   const accept = str(headers["accept"]);
   if (!isDefiniteBot && accept === AXIOS_ACCEPT) {
-    isDefiniteBot = true;
-    knownClient = "axios";
-    score = 100;
-    signals.push("known_accept:axios");
+    if (!isBrowserUa(ua)) {
+      isDefiniteBot = true;
+      knownClient = "axios";
+      score = 100;
+      signals.push("known_accept:axios");
+    } else {
+      score += 15;
+      signals.push("browser_axios_accept");
+    }
   }
   if (isDefiniteBot) return { score, signals, isDefiniteBot, knownClient };
   const hasSecFetchSite = "sec-fetch-site" in headers;
@@ -1147,6 +1161,108 @@ 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 SENSITIVE_FIELDS = {
+  identity: [
+    "first_name",
+    "last_name",
+    "full_name",
+    "name",
+    "bvn",
+    "nin",
+    "ssn",
+    "national_id",
+    "tin",
+    "passport",
+    "passport_number",
+    "drivers_license",
+    "license_number",
+    "voter_id",
+    "dob",
+    "date_of_birth",
+    "birth_date",
+    "birthdate",
+    "gender",
+    "marital_status",
+    "nationality"
+  ],
+  contact: [
+    "email",
+    "phone",
+    "phone_number",
+    "mobile",
+    "mobile_number",
+    "address",
+    "street",
+    "city",
+    "state",
+    "postal_code",
+    "zip"
+  ],
+  financial: [
+    "card_number",
+    "credit_card",
+    "debit_card",
+    "cvv",
+    "account_number",
+    "bank_account",
+    "routing_number",
+    "sort_code",
+    "iban",
+    "swift",
+    "wallet_id"
+  ],
+  authentication: [
+    "password",
+    "pin",
+    "otp",
+    "secret",
+    "private_key",
+    "api_key",
+    "access_token",
+    "refresh_token",
+    "jwt",
+    "bearer_token",
+    "security_answer",
+    "mother_maiden_name"
+  ],
+  biometric: [
+    "fingerprint",
+    "face_id",
+    "iris",
+    "voiceprint",
+    "biometric"
+  ],
+  health: [
+    "medical_record",
+    "diagnosis",
+    "blood_group",
+    "insurance_id"
+  ],
+  fintech: [
+    "kyc_id",
+    "customer_id",
+    "beneficiary_account",
+    "transaction_pin",
+    "wallet_balance",
+    "bank_verification_number",
+    "virtual_account",
+    "monnify_account",
+    "paystack_customer",
+    "flutterwave_customer"
+  ]
+};
+var FIELD_CATEGORY_MAP = /* @__PURE__ */ new Map();
+for (const [cat, fields] of Object.entries(SENSITIVE_FIELDS)) {
+  for (const f of fields) FIELD_CATEGORY_MAP.set(f, cat);
+}
+var VALUE_PATTERNS = [
+  { name: "email", category: "contact", re: /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/ },
+  { name: "bvn_nin", category: "identity", re: /^\d{11}$/ },
+  { name: "card_number", category: "financial", re: /^\d{13,19}$/ },
+  { name: "phone_ng", category: "contact", re: /^(?:\+234|0)[789][01]\d{8}$/ },
+  { name: "jwt", category: "authentication", re: /^eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\./ },
+  { name: "iban", category: "financial", re: /^[A-Z]{2}\d{2}[A-Z0-9]{4,30}$/ }
+];
 var AnomiraClient = class {
   constructor(config) {
     this.logBuffer = [];
@@ -1479,13 +1595,35 @@ var AnomiraClient = class {
     }
   }
   // ─── Public API ────────────────────────────────────────────────────────────
+  /**
+   * Extract the real client IP from a request object, reading forwarded headers
+   * in the correct priority order (Cloudflare → XFF → X-Real-IP → socket).
+   *
+   * Use this instead of `req.ip` when tracking events manually. `req.ip` in
+   * Express without `trust proxy` set returns the proxy's address (127.0.0.1
+   * behind Nginx), which breaks geo-detection and IP blocking.
+   *
+   * ```ts
+   * // ✅ Correct — reads X-Forwarded-For / CF-Connecting-IP automatically
+   * sentinel.track(EventName.OTP_FAILED, {
+   *   ip:     sentinel.getClientIp(req),
+   *   userId: req.body.phone,
+   *   meta:   { endpoint: "/api/verify-otp" },
+   * });
+   *
+   * // ❌ Wrong behind a proxy — req.ip is 127.0.0.1 without trust proxy configured
+   * sentinel.track(EventName.OTP_FAILED, { ip: req.ip, ... });
+   * ```
+   */
+  getClientIp(req) {
+    return this.config.getIp(req);
+  }
   /**
    * Track a custom security event.
    *
    * ```ts
-   * // Track a failed OTP attempt
    * sentinel.track(EventName.OTP_FAILED, {
-   *   ip:     req.ip,
+   *   ip:     sentinel.getClientIp(req),   // use getClientIp, not req.ip
    *   userId: req.body.phone,
    *   meta:   { endpoint: "/api/verify-otp", attempts: 3 },
    * });
@@ -1558,6 +1696,11 @@ var AnomiraClient = class {
     if (this.disabled) return;
     const ctx = requestContext.getStore();
     const resolvedIp = data.ip && data.ip !== "0.0.0.0" && data.ip !== "" ? data.ip : ctx?.ip ?? "0.0.0.0";
+    if (this.config.debug && data.ip && isPrivateIp2(data.ip)) {
+      this._origWarn(
+        `[Anomira] Warning: track() received a private/loopback IP "${data.ip}" for event "${eventName}". Behind a reverse proxy, req.ip is the proxy's address \u2014 use sentinel.getClientIp(req) instead.`
+      );
+    }
     const resolvedMeta = ctx?.endpoint && !data.meta?.["endpoint"] ? { endpoint: ctx.endpoint, method: ctx.method, ...data.meta } : data.meta;
     const event = {
       name: eventName,
@@ -1798,6 +1941,9 @@ function normalizeIp(raw) {
   if (raw.startsWith("::ffff:")) return raw.slice(7);
   return raw;
 }
+function isPrivateIp2(ip) {
+  return ip === "127.0.0.1" || ip === "::1" || ip === "0.0.0.0" || ip.startsWith("10.") || ip.startsWith("192.168.") || /^172\.(1[6-9]|2\d|3[01])\./.test(ip);
+}
 function defaultGetIp(req) {
   const r = req;
   const fwd = r["headers"];
@@ -1898,6 +2044,27 @@ function createExpressMiddleware(client) {
     const fingerprint = computeBrowserFingerprint(headers ?? {}, ua);
     const h2settings = extractHttp2Settings(req);
     const upstreamTls = extractUpstreamTls(headers ?? {});
+    const cookieHeader = headers?.["cookie"];
+    const cookieToken = cookieHeader ? cookieHeader.split(";").map((c) => c.trim()).find((c) => c.startsWith("anomira_fp="))?.slice("anomira_fp=".length) ?? "" : "";
+    const browserFpRaw = cookieToken || headers?.["x-anomira-fp"] || "";
+    let browserFp = null;
+    if (browserFpRaw) {
+      try {
+        const raw = JSON.parse(Buffer.from(browserFpRaw, "base64").toString("utf8"));
+        if (typeof raw["v"] === "number" && typeof raw["fp"] === "string") {
+          browserFp = {
+            fp: raw["fp"],
+            bot: raw["bot"] ?? 0,
+            sigs: (raw["sigs"] ?? []).join(","),
+            uid: typeof raw["uid"] === "string" && raw["uid"] ? raw["uid"] : void 0,
+            pst: raw["frm"]?.pst,
+            ttf: raw["frm"]?.ttf,
+            tts: raw["frm"]?.tts
+          };
+        }
+      } catch {
+      }
+    }
     if (client["canaryTokenCache"] && client["canaryTokenCache"].size > 0) {
       const authHeader = (typeof headers?.["authorization"] === "string" ? headers["authorization"] : "") ?? "";
       if (authHeader.startsWith("Bearer ")) {
@@ -1992,11 +2159,39 @@ function createExpressMiddleware(client) {
         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"}');
+      const res_ = res;
+      const setStatus = (code) => {
+        if (typeof res_["status"] === "function") res_["status"](code);
+        else res_["statusCode"] = code;
+      };
+      const sendBody = (body) => {
+        if (typeof res_["end"] === "function") res_["end"](body);
+      };
+      const setHeader = (k, v) => {
+        if (typeof res_["setHeader"] === "function") res_["setHeader"](k, v);
+      };
+      const action = fwMatch.rule.action;
+      if (action === "block" || action === "temporary_block") {
+        setStatus(403);
+        sendBody('{"error":"Blocked by firewall rule"}');
+        return;
+      }
+      if (action === "rate_limit") {
+        setStatus(429);
+        setHeader("Retry-After", "60");
+        sendBody('{"error":"Rate limit exceeded","retryAfter":60}');
+        return;
+      }
+      if (action === "redirect_honeypot") {
+        const target = fwMatch.rule.redirectTarget ?? "/.env";
+        setStatus(302);
+        setHeader("Location", target);
+        sendBody("");
+        return;
+      }
+      if (action === "challenge") {
+        setStatus(403);
+        sendBody('{"error":"Request challenge required"}');
         return;
       }
     }
@@ -2010,7 +2205,7 @@ function createExpressMiddleware(client) {
       }
     }
     const onFinish = () => {
-      const lateUserId = client.config.getUserId(req);
+      const lateUserId = client.config.getUserId(req) || browserFp?.uid || "";
       if (!userIdWarnFired && userIdCheckCount < 20) {
         userIdCheckCount++;
         if (!lateUserId) userIdMissCount++;
@@ -2025,6 +2220,30 @@ function createExpressMiddleware(client) {
       const latencyMs = Date.now() - startMs;
       const getHeader = res["getHeader"];
       const bytes = typeof getHeader === "function" ? parseInt(getHeader.call(res, "content-length") ?? "0", 10) || 0 : 0;
+      const rawBody = req["body"];
+      const piiFields = [];
+      const piiPatterns = [];
+      const piiCatSet = /* @__PURE__ */ new Set();
+      if (rawBody != null && typeof rawBody === "object" && !Array.isArray(rawBody)) {
+        const body = rawBody;
+        for (const key of Object.keys(body)) {
+          const cat = FIELD_CATEGORY_MAP.get(key.toLowerCase());
+          if (cat) {
+            piiFields.push(key.toLowerCase());
+            piiCatSet.add(cat);
+          }
+        }
+        for (const val of Object.values(body)) {
+          if (typeof val !== "string" || val.length > 200) continue;
+          for (const { name, category, re } of VALUE_PATTERNS) {
+            if (!piiPatterns.includes(name) && re.test(val)) {
+              piiPatterns.push(name);
+              piiCatSet.add(category);
+            }
+          }
+        }
+      }
+      const piiCategories = piiCatSet.size > 0 ? [...piiCatSet] : void 0;
       client.track(EventName.REQUEST, {
         ip,
         userId: lateUserId,
@@ -2035,9 +2254,20 @@ function createExpressMiddleware(client) {
           latencyMs,
           userAgent: ua,
           bytes,
+          ...piiFields.length > 0 ? { piiFields } : {},
+          ...piiPatterns.length > 0 ? { piiPatterns } : {},
+          ...piiCategories ? { piiCategories } : {},
           _fp: fingerprint.score,
           _fpSig: fingerprint.signals.join(","),
           ...fingerprint.knownClient ? { _fpClient: fingerprint.knownClient } : {},
+          ...browserFp ? {
+            _bfp: browserFp.fp,
+            _bbot: browserFp.bot,
+            _bsigs: browserFp.sigs,
+            ...browserFp.pst !== void 0 ? { _bpaste: browserFp.pst } : {},
+            ...browserFp.ttf !== void 0 && browserFp.ttf >= 0 ? { _bttf: browserFp.ttf } : {},
+            ...browserFp.tts !== void 0 && browserFp.tts >= 0 ? { _btts: browserFp.tts } : {}
+          } : {},
           ...h2settings ? {
             _h2Window: h2settings.initialWindowSize,
             _h2HdrTable: h2settings.headerTableSize,
@@ -2165,14 +2395,32 @@ function createFastifyPlugin(client) {
           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" });
-            }
-          }
+        const rep = reply;
+        const replyCode = (code) => typeof rep["code"] === "function" ? rep["code"](code) : rep;
+        const replyHeader = (k, v) => {
+          if (typeof rep["header"] === "function") rep["header"](k, v);
+        };
+        const replySend = (chained, body) => {
+          if (chained && typeof chained["send"] === "function") chained["send"](body);
+        };
+        const action = fwMatch.rule.action;
+        if (action === "block" || action === "temporary_block") {
+          replySend(replyCode(403), { error: "Blocked by firewall rule" });
+          return;
+        }
+        if (action === "rate_limit") {
+          replyHeader("Retry-After", "60");
+          replySend(replyCode(429), { error: "Rate limit exceeded", retryAfter: 60 });
+          return;
+        }
+        if (action === "redirect_honeypot") {
+          const target = fwMatch.rule.redirectTarget ?? "/.env";
+          replyHeader("Location", target);
+          replySend(replyCode(302), "");
+          return;
+        }
+        if (action === "challenge") {
+          replySend(replyCode(403), { error: "Request challenge required" });
           return;
         }
       }
@@ -2187,11 +2435,11 @@ function createFastifyPlugin(client) {
       const ip = client.config.getIp(req);
       const url = req["url"] ?? "/";
       const method = req["method"]?.toUpperCase() ?? "GET";
-      const userId = client.config.getUserId(req);
+      const serverUserId = client.config.getUserId(req);
       const status = reply["statusCode"] ?? 0;
       if (!userIdWarnFired && userIdCheckCount < 20) {
         userIdCheckCount++;
-        if (!userId) userIdMissCount++;
+        if (!serverUserId) userIdMissCount++;
         if (userIdCheckCount === 20 && userIdMissCount >= 18) {
           userIdWarnFired = true;
           console.warn(
@@ -2206,6 +2454,28 @@ function createFastifyPlugin(client) {
       const fingerprint = computeBrowserFingerprint(headers ?? {}, ua);
       const h2settings = extractHttp2Settings(req);
       const upstreamTls = extractUpstreamTls(headers ?? {});
+      const cookieHdrF = headers?.["cookie"];
+      const cookieTokF = cookieHdrF ? cookieHdrF.split(";").map((c) => c.trim()).find((c) => c.startsWith("anomira_fp="))?.slice("anomira_fp=".length) ?? "" : "";
+      const bfpRawF = cookieTokF || headers?.["x-anomira-fp"] || "";
+      let browserFpF = null;
+      if (bfpRawF) {
+        try {
+          const raw = JSON.parse(Buffer.from(bfpRawF, "base64").toString("utf8"));
+          if (typeof raw["v"] === "number" && typeof raw["fp"] === "string") {
+            browserFpF = {
+              fp: raw["fp"],
+              bot: raw["bot"] ?? 0,
+              sigs: (raw["sigs"] ?? []).join(","),
+              uid: typeof raw["uid"] === "string" && raw["uid"] ? raw["uid"] : void 0,
+              pst: raw["frm"]?.pst,
+              ttf: raw["frm"]?.ttf,
+              tts: raw["frm"]?.tts
+            };
+          }
+        } catch {
+        }
+      }
+      const userId = serverUserId || browserFpF?.uid || "";
       client.track(EventName.REQUEST, {
         ip,
         userId,
@@ -2219,6 +2489,14 @@ function createFastifyPlugin(client) {
           _fp: fingerprint.score,
           _fpSig: fingerprint.signals.join(","),
           ...fingerprint.knownClient ? { _fpClient: fingerprint.knownClient } : {},
+          ...browserFpF ? {
+            _bfp: browserFpF.fp,
+            _bbot: browserFpF.bot,
+            _bsigs: browserFpF.sigs,
+            ...browserFpF.pst !== void 0 ? { _bpaste: browserFpF.pst } : {},
+            ...browserFpF.ttf !== void 0 && browserFpF.ttf >= 0 ? { _bttf: browserFpF.ttf } : {},
+            ...browserFpF.tts !== void 0 && browserFpF.tts >= 0 ? { _btts: browserFpF.tts } : {}
+          } : {},
           ...h2settings ? {
             _h2Window: h2settings.initialWindowSize,
             _h2HdrTable: h2settings.headerTableSize,