@anomira/node-sdk 0.2.3 → 0.2.4

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

@@ -521,6 +521,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 +540,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 +1155,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 +1589,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 +1690,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 +1935,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"];
@@ -2025,6 +2165,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,6 +2199,9 @@ 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 } : {},