@anomira/node-sdk 0.1.9 → 0.2.2

package/README.md

@@ -2,184 +2,320 @@
 
 Drop-in API security monitoring for Node.js. Detect brute force, credential stuffing, account takeover, data scraping, path traversal, XSS, geo-velocity attacks, and more — in real time.
 
+[![npm version](https://img.shields.io/npm/v/@anomira/node-sdk)](https://www.npmjs.com/package/@anomira/node-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 ## Install
 
 ```bash
 npm install @anomira/node-sdk
+# or
+yarn add @anomira/node-sdk
+# or
+pnpm add @anomira/node-sdk
 ```
 
-## Quick Start
+**Requirements:** Node.js 18+, ESM or CommonJS.
 
-```js
-import { Anomira } from "@anomira/node-sdk";
+---
 
-const sentinel = new Anomira({
-  apiKey:    process.env.SENTINEL_API_KEY,
-  appId:     process.env.SENTINEL_APP_ID,
-  ingestUrl: process.env.SENTINEL_INGEST_URL,
-  debug:     true,
-});
+## Quick Start (5 minutes)
+
+### 1. Set your environment variables
+
+Copy these into your `.env` file. Get the values from your [Anomira dashboard](https://app.anomira.io) under **Apps → Setup**.
+
+```env
+ANOMIRA_API_KEY=ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ANOMIRA_APP_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 ```
 
+> **Never hardcode these values.** Use environment variables or a secrets manager. Run `npx @anomira/node-sdk scan .` to catch any leaks before you commit.
+
+### 2. Add the middleware — pick your framework
+
+---
+
 ## Express
 
-```js
+The middleware goes **after** `express.json()` and **after your auth middleware** so it can read the authenticated user, and **before** your routes.
+
+### How user identity is captured automatically
+
+The SDK automatically extracts the authenticated user ID from the request — no configuration required. It tries the following sources in order:
+
+| Priority | Source | Set by |
+|---|---|---|
+| 1 | `req.user.id` / `.sub` / `.userId` / `._id` / `.uid` | Passport.js, express-jwt v6, Firebase Admin, @fastify/jwt |
+| 2 | `req.auth.sub` / `.id` / `.userId` | express-jwt v7+ |
+| 3 | `req.userId` / `req.accountId` / `req.customerId` | Custom middleware |
+| 4 | `req.session.userId` / `req.session.user.id` | express-session |
+| 5 | JWT decode from `Authorization: Bearer ...` | **Automatic fallback — works even without explicit auth middleware** |
+
+Tier 5 is the safety net: if your auth middleware hasn't set `req.user` yet, the SDK decodes the JWT token in the `Authorization` header itself (without verifying the signature — it only reads the `sub` / `id` claim). This means user tracking works even if middleware registration order is incorrect.
+
+**The only requirement:** if you use a custom auth pattern not listed above, pass `getUserId`:
+
+```ts
+const anomira = new Anomira({
+  apiKey:    process.env.ANOMIRA_API_KEY!,
+  appId:     process.env.ANOMIRA_APP_ID!,
+  getUserId: (req) => (req as any).myCustomField?.userId,
+});
+```
+
+```ts
+// app.ts (TypeScript)
 import express from "express";
 import { Anomira } from "@anomira/node-sdk";
 
 const app = express();
 
-const sentinel = new Anomira({
-  apiKey:    process.env.SENTINEL_API_KEY,
-  appId:     process.env.SENTINEL_APP_ID,
-  ingestUrl: process.env.SENTINEL_INGEST_URL,
-  debug:     true,
-  captureConsole: true,   // forwards console.log/warn/error to Logs dashboard
-  service:        "my-api",
-  detect: {
-    bruteForce:    true,
-    rateAbuse:     true,
-    pathTraversal: true,
-    xss:           true,
-    scanDetection: true,
-    geoVelocity:   true,
-  },
+const anomira = new Anomira({
+  apiKey: process.env.ANOMIRA_API_KEY!,
+  appId:  process.env.ANOMIRA_APP_ID!,
+  service: "my-api",          // appears in the Logs dashboard
+  captureConsole: true,        // forwards console.log/warn/error to Logs
 });
 
 app.use(express.json());
-app.use(sentinel.express());  // auto-instruments all routes
+app.use(anomira.express());    // ← single line — instruments all routes
+
+// Your routes
+app.post("/api/auth/login", (req, res) => { /* ... */ });
+app.get("/api/users/:id",   (req, res) => { /* ... */ });
+
+// Always flush before shutdown
+process.on("SIGTERM", async () => {
+  await anomira.flush();
+  process.exit(0);
+});
 
+app.listen(3000, () => console.log("API running on :3000"));
+```
+
+**CommonJS:**
+
+```js
+// app.js
+const express = require("express");
+const { Anomira } = require("@anomira/node-sdk");
+
+const app = express();
+const anomira = new Anomira({
+  apiKey: process.env.ANOMIRA_API_KEY,
+  appId:  process.env.ANOMIRA_APP_ID,
+});
+
+app.use(express.json());
+app.use(anomira.express());
 app.listen(3000);
 ```
 
+---
+
 ## Fastify
 
-```js
+```ts
+// server.ts
 import Fastify from "fastify";
 import { Anomira } from "@anomira/node-sdk";
 
-const app = Fastify();
+const app = Fastify({ logger: true });
 
-const sentinel = new Anomira({
-  apiKey:    process.env.SENTINEL_API_KEY,
-  appId:     process.env.SENTINEL_APP_ID,
-  ingestUrl: process.env.SENTINEL_INGEST_URL,
+const anomira = new Anomira({
+  apiKey:  process.env.ANOMIRA_API_KEY!,
+  appId:   process.env.ANOMIRA_APP_ID!,
+  service: "my-api",
 });
 
-await app.register(sentinel.fastify());
+// Register BEFORE your route plugins
+await app.register(anomira.fastify());
+
+// Your routes
+app.post("/api/auth/login", async (req, reply) => { /* ... */ });
+app.get("/api/users/:id",   async (req, reply) => { /* ... */ });
 
-app.listen({ port: 3000 });
+process.on("SIGTERM", async () => {
+  await anomira.flush();
+  await app.close();
+});
+
+await app.listen({ port: 3000, host: "0.0.0.0" });
 ```
 
-## Manual Event Tracking
+---
 
-```js
-// Track a failed OTP attempt
-sentinel.track("auth.otp.failed", {
+## What the middleware captures automatically
+
+Once registered, the middleware records **every request** with zero additional code:
+
+| Signal | Description |
+|---|---|
+| HTTP method, path, status | Full request log in **API Events** |
+| Source IP + geolocation | Country, city, lat/lng |
+| Latency | `latencyMs` per request |
+| Brute force | Repeated failures on the same endpoint |
+| Rate abuse | Unusually high request rate from one IP |
+| Path traversal | `../`, `%2e%2e/`, null bytes in paths |
+| XSS | Script tags and injection payloads in bodies |
+| Scanner/bot probing | Systematic enumeration of endpoints |
+| Geo-velocity | Impossible logins from two countries within minutes |
+
+---
+
+## Manual event tracking
+
+Use these when the middleware can't infer the event on its own — e.g., application-level failures.
+
+```ts
+// Credential stuffing / failed login attempt
+await anomira.trackLogin({
+  ip:      req.ip,
+  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,
+  success: true,
+});
+
+// Failed OTP — otp_flood detection
+anomira.track("auth.otp.failed", {
   ip:     req.ip,
   userId: req.body.phone,
   meta:   { endpoint: "/api/verify-otp" },
 });
 
-// Track a login and run geo-velocity check automatically
-await sentinel.trackLogin({ ip: req.ip, userId: user.id });
+// SIM swap detection — call after any phone-based auth
+anomira.trackPhoneAuth({ ip: req.ip, userId: user.id, phone: user.phone });
+
+// Account takeover signal — e.g., password changed from new IP
+anomira.track("auth.account.takeover", {
+  ip:     req.ip,
+  userId: user.id,
+  meta:   { reason: "password_changed_new_ip" },
+});
 
-// Track phone-based auth (SIM swap detection)
-sentinel.trackPhoneAuth({ ip: req.ip, userId: user.id, phone: user.phone });
+// Webhook replay — call when you detect a replayed webhook signature
+anomira.track("webhook.replay.detected", {
+  ip:   req.ip,
+  meta: { webhookId: req.headers["x-webhook-id"] },
+});
 ```
 
-## Structured Logging
+---
 
-```js
-sentinel.log("info",  "User registered",   { userId: user.id });
-sentinel.log("warn",  "Slow DB query",      { queryMs: 1240 });
-sentinel.log("error", "Payment failed",     { reason: err.message });
+## Structured logging
+
+Replace `console.log` calls with `anomira.log` to push structured logs to the **Logs dashboard** with level, service name, and metadata.
+
+```ts
+anomira.log("info",  "User registered",    { userId: user.id, plan: "starter" });
+anomira.log("warn",  "Slow DB query",       { queryMs: 1240, table: "transactions" });
+anomira.log("error", "Payment failed",      { reason: err.message, amount: 500_00 });
+anomira.log("debug", "Cache miss",          { key: cacheKey });
 ```
 
-## Blocklist & Firewall
+Or set `captureConsole: true` in the constructor to automatically forward all `console.*` calls — no code changes needed.
 
-The SDK syncs your blocklist and firewall rules from the dashboard every 60 seconds. Check them in your own middleware:
+---
 
-```js
-if (sentinel.isBlocked(req.ip)) {
-  return res.status(403).json({ error: "Forbidden" });
-}
+## Blocklist & firewall check
 
-const match = sentinel.matchFirewallRule({
-  url:     req.url,
-  body:    req.body,
-  headers: req.headers,
-  ip:      req.ip,
+The SDK syncs your dashboard's blocked IPs and firewall rules every 60 seconds. Use these checks in a gateway middleware before your routes:
+
+```ts
+app.use((req, res, next) => {
+  // Check if IP is manually blocked in the dashboard
+  if (anomira.isBlocked(req.ip)) {
+    return res.status(403).json({ error: "Forbidden" });
+  }
+
+  // Check firewall rules (pattern-based: path, method, header, body)
+  const match = anomira.matchFirewallRule({
+    url:     req.originalUrl,
+    method:  req.method,
+    body:    req.body,
+    headers: req.headers,
+    ip:      req.ip,
+  });
+
+  if (match) {
+    if (match.rule.action === "block") {
+      return res.status(403).json({ error: "Request blocked", rule: match.rule.name });
+    }
+    // action === "flag" — let it through but the dashboard will flag it
+  }
+
+  next();
 });
-if (match?.rule.action === "block") {
-  return res.status(403).json({ error: "Blocked by firewall rule" });
-}
 ```
 
-## Shadow Endpoint Detection
+---
 
-Register your known API routes on startup so Anomira can flag any undeclared endpoint that appears in live traffic. Endpoints that receive requests but were never declared show up in the **API Surface Map** as shadow endpoints.
+## Shadow endpoint detection
 
-```js
-// Call once after your routes are registered
-await sentinel.declareEndpoints([
-  { method: "POST", path: "/api/auth/login",           auth: false },
-  { method: "POST", path: "/api/auth/register",        auth: false },
-  { method: "GET",  path: "/api/users/:id",            auth: true  },
-  { method: "GET",  path: "/api/orders",               auth: true  },
-  { method: "POST", path: "/api/orders",               auth: true  },
-  { method: "GET",  path: "/api/health",               auth: false },
+Register your known API routes once on startup. Anomira will flag any traffic to undeclared endpoints in the **API Surface** view — a leading indicator of probing and abuse.
+
+```ts
+// Call this once, after all your routes are defined
+await anomira.declareEndpoints([
+  { method: "POST", path: "/api/auth/login",       auth: false },
+  { method: "POST", path: "/api/auth/register",    auth: false },
+  { method: "POST", path: "/api/auth/forgot",      auth: false },
+  { method: "GET",  path: "/api/users/:id",        auth: true  },
+  { method: "PUT",  path: "/api/users/:id",        auth: true  },
+  { method: "GET",  path: "/api/orders",           auth: true  },
+  { method: "POST", path: "/api/orders",           auth: true  },
+  { method: "GET",  path: "/api/health",           auth: false },
 ]);
 ```
 
-Express-style `:param` segments are normalized automatically — `/users/:id` and `/users/:userId` both map to `/users/{id}` to match discovered traffic.
+Express-style `:param` segments (`/users/:id`) are normalized automatically to match real traffic. Call this after your routes are registered so all paths are included.
 
-Use `auth: false` for public endpoints. Authenticated endpoints default to `auth: true`.
+---
 
-Shadow detection from declared endpoints only activates once your org has registered at least one endpoint, so it won't produce noise on fresh deployments before you call this method.
+## Secret scanner CLI
 
-## Secret Scanner CLI
+Scan your codebase for leaked secrets, API keys, and PII before they reach production.
 
-Scan your codebase for hardcoded secrets, API keys, BVN/NIN numbers, and PII before they reach production.
-
-Uses three detection layers:
-- **secretlint** — 50+ service-specific rules (AWS, GCP, GitHub, Stripe, Slack, Twilio, SendGrid, PostgreSQL connection strings, and more)
-- **Custom patterns** — Nigerian PII (BVN/NIN), card PANs, phone numbers
-- **Entropy analysis** (`--strict`) — catches unknown high-entropy secrets with no known prefix, using Shannon entropy scoring
-
-**Run without installing:**
 ```bash
+# One-off scan (no install needed)
 npx @anomira/node-sdk scan ./src
-```
 
-**If `@anomira/node-sdk` is already installed in your project:**
-```bash
+# If the package is already installed
 npx anomira scan ./src
 ```
 
 **Options:**
+
 ```bash
 npx @anomira/node-sdk scan ./src           # scan a directory
 npx @anomira/node-sdk scan .               # scan entire project
-npx @anomira/node-sdk scan ./src --strict  # enable entropy analysis (catches unknown secrets)
-npx @anomira/node-sdk scan ./src --json    # machine-readable JSON output for CI
-npx @anomira/node-sdk scan ./src --quiet   # only print violations, no header
+npx @anomira/node-sdk scan ./src --strict  # entropy analysis (catches unknown secrets)
+npx @anomira/node-sdk scan ./src --json    # machine-readable JSON for CI
+npx @anomira/node-sdk scan ./src --quiet   # violations only, no header
 ```
 
-**What it detects:**
+**Detects:**
 
 | Category | Examples |
 |---|---|
-| Cloud credentials | AWS access keys, GCP service account keys, Azure connection strings |
-| Source control | GitHub tokens (`ghp_`), GitLab tokens (`glpat-`), NPM tokens (`npm_`) |
-| Payment | Stripe keys (`sk_live_`), Paystack keys |
-| Communication | Slack tokens (`xoxb-`), Twilio credentials, SendGrid keys |
-| Database | Connection strings with embedded passwords (`postgresql://user:pass@host`) |
-| Auth | JWT tokens, generic API keys and bearer tokens |
-| Nigerian PII | BVN/NIN (11-digit), card PANs, Nigerian phone numbers |
-| Unknown secrets | High-entropy strings assigned to secret-like variables (`--strict`) |
-
-**Add to `package.json` for CI/CD:**
+| Cloud | AWS access keys, GCP service accounts, Azure connection strings |
+| Source control | GitHub (`ghp_`), GitLab (`glpat-`), NPM (`npm_`) tokens |
+| Payment | Stripe (`sk_live_`), Paystack secret keys |
+| Communication | Slack (`xoxb-`), Twilio, SendGrid |
+| Database | Connection strings with embedded passwords |
+| Auth | JWT tokens, bearer tokens, generic API keys |
+| PII | BVN/NIN (11-digit), card PANs, Nigerian phone numbers |
+| Unknown | High-entropy strings on secret-like variable names (`--strict`) |
+
+Add to CI/CD — exits `1` if violations are found:
+
 ```json
 {
   "scripts": {
@@ -188,44 +324,75 @@ npx @anomira/node-sdk scan ./src --quiet   # only print violations, no header
 }
 ```
 
-Exit code `0` = clean. Exit code `1` = violations found — use in CI to fail the build on leaked secrets.
+---
 
-## Environment Variables
+## Graceful shutdown
 
-| Variable | Description |
-|---|---|
-| `SENTINEL_API_KEY` | Your Anomira API key |
-| `SENTINEL_APP_ID` | Your Anomira app ID |
-| `SENTINEL_INGEST_URL` | Ingest endpoint (from your dashboard) |
+Always flush the event buffer before your process exits. Unflushed events may be lost on a hard kill.
 
-## Configuration
+```ts
+process.on("SIGTERM", async () => {
+  await anomira.flush();
+  process.exit(0);
+});
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `apiKey` | `string` | — | Your Anomira API key (required) |
-| `appId` | `string` | — | Your Anomira app ID (required) |
-| `ingestUrl` | `string` | Anomira cloud | Ingest endpoint URL |
-| `debug` | `boolean` | `false` | Log SDK activity to console |
-| `captureConsole` | `boolean` | `false` | Forward `console.*` calls to the Logs dashboard |
-| `service` | `string` | `"app"` | Service name tag for logs |
-| `detect.bruteForce` | `boolean` | `true` | Detect brute force login attempts |
-| `detect.rateAbuse` | `boolean` | `true` | Detect rate limit abuse |
-| `detect.pathTraversal` | `boolean` | `true` | Detect path traversal attempts |
-| `detect.xss` | `boolean` | `true` | Detect XSS in request bodies |
-| `detect.scanDetection` | `boolean` | `true` | Detect scanner/bot probing |
-| `detect.geoVelocity` | `boolean` | `true` | Detect impossible travel between logins |
+// For Fastify with lifecycle hooks:
+app.addHook("onClose", async () => {
+  await anomira.flush();
+});
+```
 
-## Graceful Shutdown
+---
 
-Always flush pending events before your process exits:
+## Environment variables reference
 
-```js
-process.on("SIGTERM", async () => {
-  await sentinel.flush();
-  process.exit(0);
-});
+| Variable | Required | Description |
+|---|---|---|
+| `ANOMIRA_API_KEY` | ✅ | Your API key — from dashboard under **Apps → Setup** |
+| `ANOMIRA_APP_ID` | ✅ | Your app ID — from dashboard under **Apps → Setup** |
+
+---
+
+## Configuration reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | API key (required) |
+| `appId` | `string` | — | App ID (required) |
+| `debug` | `boolean` | `false` | Log SDK activity to console |
+| `service` | `string` | `"app"` | Service name tag on all log entries |
+| `captureConsole` | `boolean` | `false` | Forward `console.*` to Logs dashboard |
+| `detect.bruteForce` | `boolean` | `true` | Brute force detection on auth endpoints |
+| `detect.rateAbuse` | `boolean` | `true` | High-rate abuse from single IP |
+| `detect.pathTraversal` | `boolean` | `true` | Path traversal payloads in URLs |
+| `detect.xss` | `boolean` | `true` | XSS payloads in request bodies |
+| `detect.scanDetection` | `boolean` | `true` | Endpoint scanner / bot probing |
+| `detect.geoVelocity` | `boolean` | `true` | Impossible travel between logins |
+
+---
+
+## Troubleshooting
+
+**No events showing in the dashboard?**
+1. Set `debug: true` in the constructor — the SDK will log every event it sends to the console.
+2. Check that `ANOMIRA_API_KEY` and `ANOMIRA_APP_ID` are set in your process environment (`console.log(process.env.ANOMIRA_API_KEY)`).
+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"`.
+
+**`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:
+```ts
+await Promise.race([
+  anomira.flush(),
+  new Promise((resolve) => setTimeout(resolve, 3000)),
+]);
 ```
 
+---
+
 ## License
 
 MIT