@rapidrest/service-core 1.5.0 → 1.7.0

package/dist/types/RateLimiter.d.ts

@@ -0,0 +1,87 @@
+import type { HttpRequest } from "./http/index.js";
+/**
+ * The event type recorded via `@rapidrest/core`'s `EventUtils.record()` when a rate limit is exceeded (either
+ * the per-identifier or the per-source-IP layer - see `layer` on the event). A brute-force/abuse signal
+ * covering every rate-limited route from one call site, rather than instrumenting each caller's individual
+ * failure branches.
+ */
+export declare const RATELIMIT_EXCEEDED_EVENT = "ratelimit.exceeded";
+/**
+ * Configuration options for the source-IP counter layered alongside the primary, identifier-keyed one. An
+ * identifier (username/email/etc.) alone can't catch an attacker who rotates identifiers against a single
+ * source, and is itself something an attacker and a victim can share (e.g. a common username) - keying a
+ * second, independent counter on the caller's IP address closes that gap without weakening the existing
+ * per-identifier throttle. Deliberately more permissive by default than the per-identifier limit, since a
+ * single IP can legitimately represent many users behind NAT/a corporate proxy.
+ */
+export interface IPRateLimiterConfig {
+    /** Set to `false` to disable the per-IP counter. Default is `true`. */
+    enabled?: boolean;
+    /** The maximum number of attempts allowed from a single IP within `windowSeconds`. Default is `100`. */
+    maxAttempts?: number;
+    /** The length of the window, in seconds, that `maxAttempts` applies to. Default is `300` (5 minutes). */
+    windowSeconds?: number;
+}
+/**
+ * Configuration options for `RateLimiter`, read from the `rateLimit` path of the application configuration.
+ */
+export interface RateLimiterConfig {
+    /** Set to `false` to disable rate limiting entirely. Default is `true`. */
+    enabled?: boolean;
+    /** The maximum number of attempts allowed within `windowSeconds` before being rejected. Default is `5`. */
+    maxAttempts?: number;
+    /** The length of the sliding window, in seconds, that `maxAttempts` applies to. Default is `300` (5 minutes). */
+    windowSeconds?: number;
+    /** Configuration for the additional, independent per-source-IP counter. */
+    ip?: IPRateLimiterConfig;
+}
+/**
+ * A simple attempt-count rate limiter used to defend expensive or guessable endpoints (credential
+ * verification, one-time-code redemption, enumeration-prone lookups, etc.) against brute-force/abuse
+ * attacks. Backed by Redis when a `cache` connection is configured (so the count is shared across server
+ * instances), and falls back to an in-process in-memory counter otherwise.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RateLimiter {
+    protected config: RateLimiterConfig;
+    protected trustedProxies: string[];
+    private connMgr?;
+    /** In-memory fallback store, used both when no `cache` connection is configured and when the connected
+     * Redis server is too old to support `INCREX` (see `redisIncrexUnsupported` below). */
+    private readonly memoryStore;
+    protected logger: any;
+    /** Set once `incrementRedis()` learns the connected server rejects `INCREX` as unknown (`INCREX` is a
+     * Redis 8.8+ command - not yet supported by Redis Software, Redis Cloud, or any Redis-protocol-compatible
+     * server that hasn't caught up, e.g. Memurai on Windows) - subsequent calls skip straight to the in-memory
+     * fallback instead of paying for (and logging) a failed round trip on every single request. This does mean
+     * the per-identifier/per-IP counters stop being atomic across multiple server instances sharing one Redis
+     * for as long as this process runs, which is a real, deliberate degradation - see the class doc comment -
+     * but a working, non-atomic rate limiter is better than every rate-limited request 500ing.
+     */
+    private redisIncrexUnsupported;
+    private get cacheClient();
+    /**
+     * Records an attempt for the given identifier and throws once it has exceeded the configured
+     * `maxAttempts` within `windowSeconds`. A no-op when rate limiting is disabled via config.
+     *
+     * When `req` is supplied, an independent, more permissive counter keyed on the caller's source IP is
+     * also checked and incremented (see `IPRateLimiterConfig`) - this catches an attacker who rotates
+     * identifiers against a single source, which the identifier-keyed counter alone cannot.
+     * @param identifier A value that scopes the counter to a particular caller/target (e.g. a claimed username
+     * or email). Callers should be aware that an identifier alone can be shared by an attacker and a victim
+     * (e.g. a username), so this limits attempts against that identifier globally rather than per-source.
+     * @param req The source HTTP request, used to derive the caller's IP for the additional per-IP counter.
+     * Omit to check only the identifier-keyed counter (e.g. when no request is available).
+     */
+    checkAndIncrement(identifier: string, req?: HttpRequest): Promise<void>;
+    /**
+     * Increments the counter for `key` and throws once it exceeds `maxAttempts` within `windowSeconds`.
+     * Shared by the identifier-keyed and IP-keyed counters in `checkAndIncrement()` - the two are otherwise
+     * entirely independent (different keys, different limits), this just avoids duplicating the
+     * increment-then-compare logic between them.
+     */
+    private enforceLimit;
+    private incrementRedis;
+    private incrementMemory;
+}

package/dist/types/decorators/RouteDecorators.d.ts

@@ -135,6 +135,16 @@ export declare function Protect(acl?: PartialACL): (target: any, propertyKey?: s
  * @param name THe name of the query parameter whose value will be injected.
  */
 export declare function Query(name?: string | undefined): (target: any, propertyKey: string, index: number) => void;
+/**
+ * Indicates that the endpoint should have rate limiting applied for all incoming requests. This can be applied
+ * at the endpoint function level or the route class level. When applying at the class level, all defined
+ * endpoints in the class will have rate limiting applied.
+ *
+ * When performing rate limiting, the method and path of the request (without the query portion) is used as the identifier
+ * when calling `RateLimiter.checkAndIncrement()` such that a `GET /path/to/my/route` request has the effect of calling
+ * `RateLimiter.checkAndIncrement('GET /path/to/my/route', req)` directly.
+ */
+export declare function RateLimit(): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
 /**
  * Injects the HTTP request object as the value of the decorated argument.
  */

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ export * from "./NetUtils.js";
 export * from "./NotificationUtils.js";
 export * from "./ObjectFactory.js";
 export * from "./OpenApiSpec.js";
+export * from "./RateLimiter.js";
 export * from "./Server.js";
 export * from "./Types.js";
 export * from "./auth/index.js";

package/dist/types/routes/RouteUtils.d.ts

@@ -1,4 +1,5 @@
 import type { RequestHandler } from "../http/types.js";
+import { RateLimiter } from "../RateLimiter.js";
 /**
  * Provides a set of utilities for converting Route classes to HTTP middleware.
  *
@@ -9,12 +10,18 @@ export declare class RouteUtils {
     private apiSpec;
     private authMiddleware?;
     private logger?;
+    protected rateLimiter?: RateLimiter;
     protected trustedRoles: string[];
     /**
      * Creates a middleware function that checks if the user has elevated privileges and if not
      * throws the `AUTH_REQUIRES_ELEVATION` error.
      */
     checkElevation(lastStart?: number): RequestHandler;
+    /**
+     * Creates a middleware function that performs rate limiting on the request where the identifier
+     * used to identify the resource is the request `<method> <path>`.
+     */
+    checkRateLimiter(): RequestHandler;
     /**
      * Creates a middleware function that verifies the incoming request is from a valid user with at least
      * one of the specified roles.

package/dist/types/security/ACLUtils.d.ts

@@ -153,17 +153,41 @@ export declare class ACLUtils {
      */
     saveACLs(acls: AccessControlList[]): Promise<void>;
     /**
-     * Retrieves the most specific record in the provided ACL associated with the provided user: an exact
-     * uid/anonymous match beats a role match, which beats a wildcard (`.*`/`*`) match — regardless of where
+     * Retrieves the most specific record in the provided ACL associated with the provided user. An exact
+     * uid/anonymous match beats a role match, which beats a wildcard (`.*`/`*`) match, regardless of where
      * each record sits in `acl.records`. Without this, a wildcard grant authored before a specific record
-     * (a natural authoring order) would silently shadow that more specific record. Only falls back to the
-     * parent ACL when nothing in this ACL's own records matches at all.
+     * (a natural authoring order) would silently shadow that more specific record. If no record can be found
+     * in the ACL provided, searches each parent for a matching record.
+     *
+     * The depth of the search can be limited by setting the `options.maxDepth` option to a non-negative value. A value
+     * of `0` only searches the provided ACL, a value of `1` searches the provided ACL and its direct parent, a value of
+     * `2` searches the ACL, it's parent and grand-parent, and so on. A value of `-1` (the default) means no limit;
+     * the entire parent chain is searched.
+     *
+     * Since records support regex patterns, it is also possible to cap the match quality (**specificity**) via the
+     * `options.specificity` option. This is a ceiling, not an exact requirement: setting `options.specificity` to
+     * `exact` only matches the user's UID exactly. A value of `role` matches the UID or a user's role (preferring
+     * the UID match). A value of `wildcard` matches the UID, role, or any regex pattern (e.g. `.*` or `user*`),
+     * preferring the most specific of those that match.
+     *
+     * The default options are:
+     * ```ts
+     * {
+     *   maxDepth: -1 // no limit,
+     *   specificity: "wildcard"
+     * }
+     * ```
      *
      * @param acl The access control list that will be searched.
      * @param user The user to find a record for.
+     * @param options The set of options to consider
      * @returns The ACL record associated with the given user if found, otherwise `undefined`.
      */
-    getRecord(acl: AccessControlList, user: JWTUser | undefined): ACLRecord | null;
+    getRecord(acl: AccessControlList, user: JWTUser | undefined, options?: {
+        specificity?: "exact" | "role" | "wildcard";
+        maxDepth?: number;
+        curDepth?: number;
+    }): ACLRecord | null;
     /**
      * Attempts to retrieve the parent access control list for the given ACL object.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rapidrest/service-core",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "description": "Provides all core functionality for RapidREST based backend services.",
     "repository": "https://github.com/rapidrest/service-core.git",
     "author": "RapidREST <rapidrests@gmail.com>",
@@ -21,10 +21,10 @@
         "test": "vitest run",
         "test:prod": "yarn lint && vitest run --coverage",
         "test:watch": "vitest",
-        "release": "tsx scripts/release.ts"
+        "release": "rapidrest release"
     },
     "dependencies": {
-        "axios": "^1.19.0",
+        "axios": "^1.20.0",
         "dayjs": "^1.11.23",
         "deepmerge": "^4.3.1",
         "node-schedule": "^2.1.1",
@@ -58,30 +58,31 @@
         }
     },
     "devDependencies": {
-        "@rapidrest/core": "^5.1.0",
-        "@simplewebauthn/server": "^13.3.2",
-        "@swc/core": "^1.16.1",
+        "@rapidrest/cli": "^1.0.1",
+        "@rapidrest/core": "^5.2.0",
+        "@simplewebauthn/server": "^14.0.1",
+        "@swc/core": "^1.16.2",
         "@types/better-sqlite3": "^9.6.0",
-        "@types/bun": "^1.4.0",
-        "@types/node": "^26.2.0",
+        "@types/bun": "^1.4.2",
+        "@types/node": "^26.5.0",
         "@types/node-schedule": "^2.1.8",
         "@types/rimraf": "^4.0.5",
-        "@types/semver": "^7",
+        "@types/semver": "^7.8.0",
         "@types/speakeasy": "^2.0.10",
         "@types/uuid": "^11.0.0",
         "@types/ws": "^8.18.1",
-        "@typescript-eslint/eslint-plugin": "^8.67.0",
-        "@typescript-eslint/parser": "^8.67.0",
-        "@vitest/coverage-v8": "^4.1.11",
+        "@typescript-eslint/eslint-plugin": "^8.70.0",
+        "@typescript-eslint/parser": "^8.70.0",
+        "@vitest/coverage-v8": "^5.0.0",
         "autocannon": "^8.0.0",
-        "better-sqlite3": "^12.0.0",
-        "eslint": "^10.9.0",
+        "better-sqlite3": "^13.0.3",
+        "eslint": "^10.10.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-import": "^2.32.0",
-        "eslint-plugin-jsdoc": "^64.2.1",
-        "globals": "^17.11.0",
+        "eslint-plugin-jsdoc": "^64.3.6",
+        "globals": "^17.12.0",
         "lodash-es": "^4.18.1",
-        "mongodb": "^7.5.0",
+        "mongodb": "^7.6.0",
         "mongodb-memory-server": "^11.2.0",
         "nconf": "^0.13.0",
         "nock": "^14.0.17",
@@ -93,14 +94,15 @@
         "rimraf": "^6.1.3",
         "semver": "^7.8.5",
         "ts-node": "^10.9.2",
-        "tsx": "^4.23.12",
+        "tsx": "^4.23.13",
         "typedoc": "^0.28.20",
-        "typedoc-plugin-markdown": "^4.12.0",
-        "typeorm": "^1.1.0",
+        "typedoc-plugin-markdown": "^4.13.0",
+        "typeorm": "^1.1.1",
         "typescript": "^6.0.3",
-        "unplugin-swc": "^1.5.11",
+        "unplugin-swc": "^1.6.0",
         "uuid": "^14.0.2",
-        "vitest": "^4.1.11",
+        "vite": "^8.2.2",
+        "vitest": "^5.0.0",
         "winston": "^3.19.0",
         "ws": "^8.21.3"
     },