@arcis/node 1.6.1 → 1.6.3

package/dist/middleware/brute-force.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module @arcis/node/middleware/brute-force
+ *
+ * Brute-force protection middleware built on the bursty limiter
+ * primitive. Designed for login + password-reset endpoints where the
+ * defense isn't just "X requests per minute" but "if this IP keeps
+ * trying after the rate-limit window resets, block it for longer".
+ *
+ * Two-tier semantics:
+ *  - Steady-state: `fastPoints` consumes per `fastDuration` seconds.
+ *    Once exhausted, normal traffic gets a 429 until the window
+ *    resets.
+ *  - Brute-force: `slowPoints` failed attempts over `slowDuration`
+ *    seconds trips a `blockDuration` semi-permanent block.
+ *
+ * The middleware only consumes on `next()` by default, meaning every
+ * request counts, even successful ones. Pass `{ consumeOn: 'failure' }`
+ * plus a custom `failure` predicate to count only failed responses.
+ * The handler also exposes `req.arcisBruteForce.reward(key)` / `.delete(key)`
+ * to let the application reset counters on successful login.
+ */
+import type { Request, RequestHandler } from 'express';
+import type { IRateLimiterRes } from '../_third_party/rate-limit';
+export interface BruteForceOptions {
+    /** Points allowed in the fast window. */
+    fastPoints?: number;
+    /** Fast window length in seconds. */
+    fastDuration?: number;
+    /** Points allowed in the slow window. */
+    slowPoints?: number;
+    /** Slow window length in seconds. */
+    slowDuration?: number;
+    /** Seconds to semi-permanently block a key after slow-window exhaustion. */
+    blockDuration?: number;
+    /** Custom key resolver. Defaults to client IP. */
+    keyGenerator?: (req: Request) => string;
+    /** HTTP status to return when blocked. */
+    statusCode?: number;
+    /** Response message when blocked. */
+    message?: string;
+    /** Skip predicate. Return true to bypass the limiter for this request. */
+    skip?: (req: Request) => boolean;
+}
+export interface BruteForceController {
+    /** Reset the failure counter for a key (call after successful auth). */
+    reward(key: string, points?: number): Promise<IRateLimiterRes>;
+    /** Drop the key entirely. */
+    delete(key: string): Promise<boolean>;
+    /** Inspect the current counter without consuming. */
+    get(key: string): Promise<IRateLimiterRes | null>;
+    /** Manually trip the block (e.g. after N suspicious logins). */
+    block(key: string, secDuration: number): Promise<IRateLimiterRes>;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            arcisBruteForce?: BruteForceController;
+        }
+    }
+}
+/**
+ * Build a brute-force middleware backed by a bursty limiter. The
+ * returned function is an Express RequestHandler with a `controller`
+ * property exposing reward/delete/get/block for the application layer.
+ */
+export declare function bruteForceProtection(options?: BruteForceOptions): RequestHandler & {
+    controller: BruteForceController;
+};
+//# sourceMappingURL=brute-force.d.ts.map

package/dist/middleware/brute-force.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brute-force.d.ts","sourceRoot":"","sources":["../../src/middleware/brute-force.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/D,6BAA6B;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,qDAAqD;IACrD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAClD,gEAAgE;IAChE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACnE;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,eAAe,CAAC,EAAE,oBAAoB,CAAC;SACxC;KACF;CACF;AAaD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,GAAG;IACtF,UAAU,EAAE,oBAAoB,CAAC;CAClC,CAgFA"}