@anomira/node-sdk 0.1.9 → 0.2.2

package/dist/index.d.cts

@@ -78,6 +78,43 @@ interface AnomiraConfig {
      * Default: reads X-Forwarded-For → X-Real-IP → socket.remoteAddress
      */
     getIp?: (req: unknown) => string;
+    /**
+     * Invisible security — automatic blocking from Anomira's community
+     * threat intelligence network.
+     *
+     * When enabled (the default), the SDK periodically fetches high-confidence
+     * attacker IPs from the Anomira network — IPs that have been seen attacking
+     * multiple customers — and blocks them automatically, without any manual
+     * decision required.
+     *
+     * This is the "invisible" part: your API is protected from known bad actors
+     * the moment they appear in the network, before they even reach your handlers.
+     *
+     * Set `enabled: false` to disable auto-blocking and use threat data for
+     * alerting only (the data is still fetched and logged).
+     */
+    autoBlock?: {
+        /**
+         * Whether to automatically block IPs from the community threat network.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Minimum community confidence score (0-100) to trigger an auto-block.
+         * Only IPs above this threshold are blocked automatically.
+         *
+         * @default 85
+         *
+         * Guidance:
+         *   85  (default) — confirmed malicious across multiple customers, very low false-positive risk
+         *   70             — broader coverage, slightly higher false-positive risk
+         *   95             — maximum precision, only the most confirmed threats
+         *
+         * Do not set below 60 — scores below that reflect limited data and carry
+         * meaningful false-positive risk.
+         */
+        communityThreshold?: number;
+    };
 }
 interface SdkEvent {
     name: string;
@@ -150,22 +187,41 @@ interface FirewallRule {
  */
 declare class AnomiraClient {
     #private;
-    readonly config: Required<Omit<AnomiraConfig, "getUserId" | "getIp" | "detect">> & {
+    readonly config: Required<Omit<AnomiraConfig, "getUserId" | "getIp" | "detect" | "autoBlock">> & {
         getUserId: NonNullable<AnomiraConfig["getUserId"]>;
         getIp: NonNullable<AnomiraConfig["getIp"]>;
         detect: Required<NonNullable<AnomiraConfig["detect"]>>;
         captureConsole: boolean;
         service: string;
+        autoBlock: Required<NonNullable<AnomiraConfig["autoBlock"]>>;
     };
     private readonly buffer;
     private readonly logBuffer;
     private logFlushTimer;
     private blocklistTimer;
     private firewallTimer;
+    private communityThreatTimer;
     /** True when credentials are missing — all operations become no-ops. */
     private disabled;
-    /** In-process cache of blocked IPs — refreshed every 60 s from the ingest server. */
+    /** In-process cache of manually blocked IPs — refreshed every 60 s. */
     private blockedIpCache;
+    /** In-process cache of community threat IPs with their confidence scores.
+     *  Populated from Anomira's federated threat network — IPs confirmed malicious
+     *  across multiple customers. Refreshed every 60 s. */
+    private communityThreatCache;
+    /**
+     * Set of honeypot paths to intercept. When a request matches, the SDK returns
+     * a fake response instead of forwarding to the customer's route handlers.
+     * Synced from ingest every 60 s. Keys are lowercase path strings.
+     */
+    private honeypotPaths;
+    /**
+     * Set of active canary token strings embedded in previously-served honeypot
+     * responses. When any of these appear in a request's Authorization header or
+     * body, a http.canary.triggered event is fired.
+     * Synced from ingest every 60 s (max 100 tokens, sliding 7-day window).
+     */
+    private canaryTokenCache;
     /** In-process cache of firewall rules with pre-compiled regex — refreshed every 60 s. */
     private compiledRules;
     private readonly _origLog;
@@ -184,8 +240,37 @@ declare class AnomiraClient {
      * });
      * ```
      */
-    /** Returns true if the IP is in the current blocked list. Synchronous — no network call. */
+    /**
+     * Returns true if the IP should be blocked. Synchronous — no network call.
+     *
+     * Checks two independent sources:
+     *   1. Manual blocklist  — IPs explicitly blocked by the customer or via playbooks.
+     *   2. Community threats — IPs from Anomira's federated network whose confidence
+     *                         score meets the autoBlock.communityThreshold (default 85).
+     *                         Only active when autoBlock.enabled is true (the default).
+     *
+     * If a customer sets autoBlock.enabled = false, only the manual blocklist is checked.
+     */
     isBlocked(ip: string): boolean;
+    /**
+     * Returns the block reason for an IP — useful for logging or custom responses.
+     * Returns null if the IP is not blocked.
+     */
+    blockReason(ip: string): {
+        source: "manual" | "community";
+        score?: number;
+        topAttack?: string;
+    } | null;
+    /**
+     * Fire-and-forget: report a blocked-IP attempt to the ingest server so the
+     * dashboard can show that the block is actively working.
+     * Called automatically by the Express/Fastify middleware — no manual call needed.
+     */
+    reportBlockedHit(ip: string, meta: {
+        method: string;
+        url: string;
+        userAgent: string;
+    }): void;
     /** Evaluate firewall rules against a request. Returns the matched rule or null. Synchronous. */
     matchFirewallRule(req: {
         url: string;
@@ -196,7 +281,18 @@ declare class AnomiraClient {
         rule: FirewallRule;
     } | null;
     track(eventName: string, data: {
-        ip: string;
+        /**
+         * Client IP address. Optional — when omitted or empty the SDK
+         * automatically reads it from the active request context set by the
+         * Express/Fastify middleware.  This means developers calling track()
+         * inside a request handler get the correct IP for free, with no extra
+         * configuration required.
+         *
+         * Only pass this explicitly when calling track() outside a request
+         * context (e.g. from a background job or a webhook handler that has
+         * the IP available separately).
+         */
+        ip?: string;
         userId?: string;
         meta?: Record<string, unknown>;
     }): void;
@@ -213,7 +309,7 @@ declare class AnomiraClient {
      * ```
      */
     trackLogin(data: {
-        ip: string;
+        ip?: string;
         userId: string;
         meta?: Record<string, unknown>;
     }): Promise<void>;
@@ -232,7 +328,7 @@ declare class AnomiraClient {
      * ```
      */
     trackPhoneAuth(data: {
-        ip: string;
+        ip?: string;
         userId: string;
         phone: string;
         meta?: Record<string, unknown>;

package/dist/index.d.ts

@@ -78,6 +78,43 @@ interface AnomiraConfig {
      * Default: reads X-Forwarded-For → X-Real-IP → socket.remoteAddress
      */
     getIp?: (req: unknown) => string;
+    /**
+     * Invisible security — automatic blocking from Anomira's community
+     * threat intelligence network.
+     *
+     * When enabled (the default), the SDK periodically fetches high-confidence
+     * attacker IPs from the Anomira network — IPs that have been seen attacking
+     * multiple customers — and blocks them automatically, without any manual
+     * decision required.
+     *
+     * This is the "invisible" part: your API is protected from known bad actors
+     * the moment they appear in the network, before they even reach your handlers.
+     *
+     * Set `enabled: false` to disable auto-blocking and use threat data for
+     * alerting only (the data is still fetched and logged).
+     */
+    autoBlock?: {
+        /**
+         * Whether to automatically block IPs from the community threat network.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Minimum community confidence score (0-100) to trigger an auto-block.
+         * Only IPs above this threshold are blocked automatically.
+         *
+         * @default 85
+         *
+         * Guidance:
+         *   85  (default) — confirmed malicious across multiple customers, very low false-positive risk
+         *   70             — broader coverage, slightly higher false-positive risk
+         *   95             — maximum precision, only the most confirmed threats
+         *
+         * Do not set below 60 — scores below that reflect limited data and carry
+         * meaningful false-positive risk.
+         */
+        communityThreshold?: number;
+    };
 }
 interface SdkEvent {
     name: string;
@@ -150,22 +187,41 @@ interface FirewallRule {
  */
 declare class AnomiraClient {
     #private;
-    readonly config: Required<Omit<AnomiraConfig, "getUserId" | "getIp" | "detect">> & {
+    readonly config: Required<Omit<AnomiraConfig, "getUserId" | "getIp" | "detect" | "autoBlock">> & {
         getUserId: NonNullable<AnomiraConfig["getUserId"]>;
         getIp: NonNullable<AnomiraConfig["getIp"]>;
         detect: Required<NonNullable<AnomiraConfig["detect"]>>;
         captureConsole: boolean;
         service: string;
+        autoBlock: Required<NonNullable<AnomiraConfig["autoBlock"]>>;
     };
     private readonly buffer;
     private readonly logBuffer;
     private logFlushTimer;
     private blocklistTimer;
     private firewallTimer;
+    private communityThreatTimer;
     /** True when credentials are missing — all operations become no-ops. */
     private disabled;
-    /** In-process cache of blocked IPs — refreshed every 60 s from the ingest server. */
+    /** In-process cache of manually blocked IPs — refreshed every 60 s. */
     private blockedIpCache;
+    /** In-process cache of community threat IPs with their confidence scores.
+     *  Populated from Anomira's federated threat network — IPs confirmed malicious
+     *  across multiple customers. Refreshed every 60 s. */
+    private communityThreatCache;
+    /**
+     * Set of honeypot paths to intercept. When a request matches, the SDK returns
+     * a fake response instead of forwarding to the customer's route handlers.
+     * Synced from ingest every 60 s. Keys are lowercase path strings.
+     */
+    private honeypotPaths;
+    /**
+     * Set of active canary token strings embedded in previously-served honeypot
+     * responses. When any of these appear in a request's Authorization header or
+     * body, a http.canary.triggered event is fired.
+     * Synced from ingest every 60 s (max 100 tokens, sliding 7-day window).
+     */
+    private canaryTokenCache;
     /** In-process cache of firewall rules with pre-compiled regex — refreshed every 60 s. */
     private compiledRules;
     private readonly _origLog;
@@ -184,8 +240,37 @@ declare class AnomiraClient {
      * });
      * ```
      */
-    /** Returns true if the IP is in the current blocked list. Synchronous — no network call. */
+    /**
+     * Returns true if the IP should be blocked. Synchronous — no network call.
+     *
+     * Checks two independent sources:
+     *   1. Manual blocklist  — IPs explicitly blocked by the customer or via playbooks.
+     *   2. Community threats — IPs from Anomira's federated network whose confidence
+     *                         score meets the autoBlock.communityThreshold (default 85).
+     *                         Only active when autoBlock.enabled is true (the default).
+     *
+     * If a customer sets autoBlock.enabled = false, only the manual blocklist is checked.
+     */
     isBlocked(ip: string): boolean;
+    /**
+     * Returns the block reason for an IP — useful for logging or custom responses.
+     * Returns null if the IP is not blocked.
+     */
+    blockReason(ip: string): {
+        source: "manual" | "community";
+        score?: number;
+        topAttack?: string;
+    } | null;
+    /**
+     * Fire-and-forget: report a blocked-IP attempt to the ingest server so the
+     * dashboard can show that the block is actively working.
+     * Called automatically by the Express/Fastify middleware — no manual call needed.
+     */
+    reportBlockedHit(ip: string, meta: {
+        method: string;
+        url: string;
+        userAgent: string;
+    }): void;
     /** Evaluate firewall rules against a request. Returns the matched rule or null. Synchronous. */
     matchFirewallRule(req: {
         url: string;
@@ -196,7 +281,18 @@ declare class AnomiraClient {
         rule: FirewallRule;
     } | null;
     track(eventName: string, data: {
-        ip: string;
+        /**
+         * Client IP address. Optional — when omitted or empty the SDK
+         * automatically reads it from the active request context set by the
+         * Express/Fastify middleware.  This means developers calling track()
+         * inside a request handler get the correct IP for free, with no extra
+         * configuration required.
+         *
+         * Only pass this explicitly when calling track() outside a request
+         * context (e.g. from a background job or a webhook handler that has
+         * the IP available separately).
+         */
+        ip?: string;
         userId?: string;
         meta?: Record<string, unknown>;
     }): void;
@@ -213,7 +309,7 @@ declare class AnomiraClient {
      * ```
      */
     trackLogin(data: {
-        ip: string;
+        ip?: string;
         userId: string;
         meta?: Record<string, unknown>;
     }): Promise<void>;
@@ -232,7 +328,7 @@ declare class AnomiraClient {
      * ```
      */
     trackPhoneAuth(data: {
-        ip: string;
+        ip?: string;
         userId: string;
         phone: string;
         meta?: Record<string, unknown>;