@anomira/node-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+import { Request, Response, NextFunction } from 'express';
+import { FastifyPluginAsync } from 'fastify';
+
+interface SentinelConfig {
+    /** SDK API key — get this from the SentinelAPI dashboard */
+    apiKey: string;
+    /** Your app ID from the SentinelAPI dashboard */
+    appId: string;
+    /**
+     * Ingest endpoint URL.
+     * @default "https://ingest.anomira.io/v1/events"
+     */
+    ingestUrl?: string;
+    /**
+     * Geo-lookup endpoint URL for client-side geo-velocity checks.
+     * Should point to your SentinelAPI ingest service geo endpoint.
+     * If not provided, client-side geo-velocity is skipped (server-side still runs).
+     * @example "https://ingest.anomira.io/v1/geo"
+     */
+    geoLookupUrl?: string;
+    /**
+     * Max events to buffer before forcing a flush.
+     * @default 100
+     */
+    maxBatchSize?: number;
+    /**
+     * Max milliseconds to hold events before flushing.
+     * @default 5000
+     */
+    flushIntervalMs?: number;
+    /**
+     * Max retry attempts on ingest failure.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * If true, log SDK activity to console (useful during integration).
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * If true, automatically intercept console.log/info/warn/error/debug
+     * and forward them to the SentinelAPI Logs dashboard.
+     * Existing console output is preserved — logs still print to your terminal.
+     * @default false
+     */
+    captureConsole?: boolean;
+    /**
+     * Service name tag applied to all captured console logs.
+     * @default "app"
+     */
+    service?: string;
+    /**
+     * Auto-detection features to enable in the middleware.
+     * All default to true.
+     */
+    detect?: {
+        /** Flag repeated login failures from the same IP as brute_force */
+        bruteForce?: boolean;
+        /** Flag 429 responses as rate_abuse */
+        rateAbuse?: boolean;
+        /** Flag path traversal patterns in the URL */
+        pathTraversal?: boolean;
+        /** Flag XSS patterns in request body */
+        xss?: boolean;
+        /** Flag suspicious scan patterns (many 404s) */
+        scanDetection?: boolean;
+        /** Detect impossible travel between login events */
+        geoVelocity?: boolean;
+    };
+    /**
+     * Custom function to extract userId from the request.
+     * Default: reads req.user?.id || req.user?.userId || req.user?.sub
+     */
+    getUserId?: (req: unknown) => string | undefined;
+    /**
+     * Custom function to extract the client IP from the request.
+     * Default: reads X-Forwarded-For → X-Real-IP → socket.remoteAddress
+     */
+    getIp?: (req: unknown) => string;
+}
+interface SdkEvent {
+    name: string;
+    ts: number;
+    ip: string;
+    userId?: string;
+    meta?: Record<string, unknown>;
+}
+interface IngestPayload {
+    appId: string;
+    events: SdkEvent[];
+}
+declare const EventName: {
+    readonly LOGIN_SUCCESS: "auth.login.success";
+    readonly LOGIN_FAILED: "auth.login.failed";
+    readonly LOGOUT: "auth.logout";
+    readonly OTP_FAILED: "auth.otp.failed";
+    readonly OTP_SUCCESS: "auth.otp.success";
+    readonly BVN_LOOKUP: "auth.bvn.lookup";
+    readonly NIN_LOOKUP: "auth.nin.lookup";
+    readonly GEO_VELOCITY: "auth.login.geo_velocity";
+    readonly CREDENTIAL_STUFF: "auth.credential.stuffing";
+    readonly SIM_SWAP: "auth.sim_swap.suspected";
+    readonly PHONE_AUTH: "auth.phone.verified";
+    readonly REQUEST: "http.request";
+    readonly RATE_LIMIT: "http.ratelimit.exceeded";
+    readonly XSS_DETECTED: "http.xss.detected";
+    readonly PATH_TRAVERSAL: "http.path.traversal";
+    readonly SCAN_DETECTED: "http.scan.detected";
+    readonly IDOR_ATTEMPT: "user.idor.attempt";
+    readonly SQL_ERROR: "db.sql.error";
+    readonly FIREWALL_BLOCK: "http.firewall.block";
+    readonly FIREWALL_FLAG: "http.firewall.flag";
+};
+type EventNameValue = typeof EventName[keyof typeof EventName];
+type FirewallField = "url" | "body" | "header" | "user_agent" | "ip";
+type FirewallOperator = "contains" | "equals" | "starts_with" | "ends_with" | "regex";
+type FirewallAction = "block" | "flag";
+interface FirewallRule {
+    id: string;
+    field: FirewallField;
+    headerName?: string | null;
+    operator: FirewallOperator;
+    value: string;
+    action: FirewallAction;
+    attackType: string;
+}
+
+/**
+ * SentinelClient — the core SDK object.
+ *
+ * Instantiate once and reuse across your application:
+ *
+ * ```ts
+ * import { SentinelAPI } from "@anomira/node-sdk";
+ *
+ * export const sentinel = new SentinelAPI({
+ *   apiKey: process.env.SENTINEL_API_KEY!,
+ *   appId:  process.env.SENTINEL_APP_ID!,
+ * });
+ * ```
+ */
+declare class SentinelClient {
+    #private;
+    readonly config: Required<Omit<SentinelConfig, "getUserId" | "getIp" | "detect">> & {
+        getUserId: NonNullable<SentinelConfig["getUserId"]>;
+        getIp: NonNullable<SentinelConfig["getIp"]>;
+        detect: Required<NonNullable<SentinelConfig["detect"]>>;
+        captureConsole: boolean;
+        service: string;
+    };
+    private readonly buffer;
+    private readonly logBuffer;
+    private logFlushTimer;
+    private blocklistTimer;
+    private firewallTimer;
+    /** In-process cache of blocked IPs — refreshed every 60 s from the ingest server. */
+    private blockedIpCache;
+    /** In-process cache of firewall rules with pre-compiled regex — refreshed every 60 s. */
+    private compiledRules;
+    private readonly _origLog;
+    private readonly _origWarn;
+    private readonly _origError;
+    constructor(config: SentinelConfig);
+    /**
+     * 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: string): boolean;
+    /** Evaluate firewall rules against a request. Returns the matched rule or null. Synchronous. */
+    matchFirewallRule(req: {
+        url: string;
+        body: unknown;
+        headers: Record<string, string | undefined>;
+        ip: string;
+    }): {
+        rule: FirewallRule;
+    } | null;
+    track(eventName: string, data: {
+        ip: string;
+        userId?: string;
+        meta?: Record<string, unknown>;
+    }): void;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    trackLogin(data: {
+        ip: string;
+        userId: string;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * 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: {
+        ip: string;
+        userId: string;
+        phone: string;
+        meta?: Record<string, unknown>;
+    }): void;
+    /**
+     * 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: "debug" | "info" | "warn" | "error" | "fatal", message: string, meta?: Record<string, unknown> & {
+        service?: string;
+    }): void;
+    /**
+     * Flush all pending events immediately.
+     * Useful before a graceful shutdown outside of the process lifecycle hooks.
+     */
+    flush(): Promise<void>;
+    /**
+     * Express middleware — auto-instruments all routes.
+     *
+     * ```ts
+     * app.use(sentinel.express());
+     * ```
+     */
+    express(): (req: Record<string, unknown>, res: Record<string, unknown>, next: () => void) => Promise<void>;
+    /**
+     * Fastify plugin — auto-instruments all routes.
+     *
+     * ```ts
+     * await app.register(sentinel.fastify());
+     * ```
+     */
+    fastify(): (fastify: {
+        addHook: (event: string, fn: (req: Record<string, unknown>, reply: Record<string, unknown>) => void) => void;
+    }) => Promise<void>;
+}
+
+/**
+ * Typed Express middleware — exported separately for projects that want
+ * to import the middleware type explicitly.
+ *
+ * Most users will use `sentinel.express()` instead of importing this directly.
+ */
+
+/**
+ * Returns fully-typed Express middleware.
+ *
+ * ```ts
+ * import express from "express";
+ * import { SentinelAPI } from "@sentinelapi/node-sdk";
+ *
+ * const app = express();
+ * const sentinel = new SentinelAPI({ apiKey: "...", appId: "..." });
+ *
+ * app.use(sentinel.express());          // auto-instrument all routes
+ *
+ * // Or import the typed version directly:
+ * import { createExpressMiddleware } from "@sentinelapi/node-sdk/middleware/express";
+ * app.use(createExpressMiddleware(sentinel));
+ * ```
+ */
+declare function createExpressMiddleware(client: SentinelClient): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Typed Fastify plugin — exported separately for projects that want
+ * to import the plugin type explicitly.
+ *
+ * Most users will use `sentinel.fastify()` instead of importing this directly.
+ */
+
+/**
+ * Returns a Fastify plugin for auto-instrumentation.
+ *
+ * ```ts
+ * import Fastify from "fastify";
+ * import { SentinelAPI } from "@sentinelapi/node-sdk";
+ *
+ * const app = Fastify();
+ * const sentinel = new SentinelAPI({ apiKey: "...", appId: "..." });
+ *
+ * await app.register(sentinel.fastify());
+ * ```
+ */
+declare function createFastifyPlugin(client: SentinelClient): FastifyPluginAsync;
+
+export { EventName, type EventNameValue, type IngestPayload, type SdkEvent, SentinelClient as SentinelAPI, type SentinelConfig, createExpressMiddleware, createFastifyPlugin, SentinelClient as default };