@vsaas/loopback 12.1.0 → 12.2.0

package/docs/rate-limiting.md

@@ -0,0 +1,879 @@
+# Rate limiting
+
+LoopBack provides a framework-level rate limiter for remote methods, authentication flows, and application-specific operations. Policy, subject selection, and storage are separate, so applications can reuse the same enforcement engine without coupling it to HTTP, a `User` model, or a particular database.
+
+This guide covers general rate limiting. Authentication-specific buckets are described in [Two-factor authentication](./two-factor-authentication.md#authentication-rate-limiting).
+
+## Initialization
+
+Configure every provider, store, subject keyring, programmatic rule, named policy, and resolver before initialization:
+
+```js
+app.set('rateLimit', {
+  limits: {
+    maxBatchEntries: 1000,
+    maxCostPerConsume: 100000,
+  },
+  subjectKeyrings: {
+    default: {
+      currentKeyId: '2026-01',
+      keys: {
+        '2026-01': process.env.RATE_LIMIT_SUBJECT_KEY,
+      },
+    },
+  },
+  stores: {
+    primary: {
+      provider: 'persisted-model',
+      model: 'RateLimitState',
+      namespace: 'example-api-production',
+    },
+  },
+});
+
+// Define programmatic rules and register custom providers or resolvers here.
+await app.initializeRateLimiting();
+```
+
+Call `initializeRateLimiting()` after models and datasources have been attached and before the application starts accepting traffic. Initialization validates the complete configuration, probes the stores, freezes the registry, and installs the remote-method hooks.
+
+If any concrete `User` model uses `twoFactor` or `authenticationRateLimit`, call `initializeAuthenticationSecurity()` instead. That initializer also initializes general rate limiting and must own the startup sequence:
+
+```js
+await app.initializeAuthenticationSecurity();
+```
+
+Both initializers support promises and Node-style callbacks and are idempotent. A configured authentication flow remains unavailable until initialization succeeds; it does not silently fall back to unprotected behavior.
+
+## Mental model: what does one rule do?
+
+A rate-limit rule creates counters. For every operation, it answers four questions:
+
+1. **What is being limited?** The `bucket` identifies the action, for example `report-generation` or `file-upload`.
+2. **Who owns the counter?** The `subject` identifies the caller or resource whose quota is consumed, for example one user, tenant, API key, device, source address, or the application as a whole.
+3. **What is the quota?** The `limit` defines the capacity and time window.
+4. **How much does this operation consume?** The `cost` is normally `1`, but it can represent rows, bytes, recipients, jobs, or any other whole-number unit.
+
+For example, the following rule means “each API key can consume 100 units from the `report-generation` bucket every minute”:
+
+```text
+bucket: report-generation
+subject: API key "key-42"
+limit: 100
+window: 60 seconds
+cost of the current operation: 5
+```
+
+After that operation, the counter for `key-42` has consumed 5 of its 100 units. Another API key gets a different counter. The same API key using a different bucket also gets a different counter.
+
+The complete persisted counter identity is derived from:
+
+```text
+namespace
++ scope
++ subjectType
++ HMAC(canonicalValue)
++ bucket
++ policyId
++ policyVersion
++ subject key ID
+```
+
+This is why the labels in the subject descriptor must remain stable after deployment. Changing one of them starts addressing a different counter.
+
+## Application configuration
+
+The `rateLimit` application setting has three main sections.
+
+### Safety limits
+
+`limits.maxBatchEntries` and `limits.maxCostPerConsume` protect the limiter itself from unexpectedly large inputs. They do **not** define how many operations a user is allowed to perform. User-facing quotas belong in a rule's `limit`.
+
+| Option                     |  Default | Description                                                                                                                                                   |
+| -------------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `limits.maxBatchEntries`   |   `1000` | Maximum number of entries accepted by one `consumeBatch()` call. Must be a positive safe integer. Validation happens before subject and policy resolvers run. |
+| `limits.maxCostPerConsume` | `100000` | Maximum cost of one resolved consumption. Must be a positive safe integer.                                                                                    |
+
+#### Example: `maxBatchEntries`
+
+```js
+limits: {
+  maxBatchEntries: 500,
+}
+```
+
+With this configuration:
+
+- a call to `consumeBatch()` with 500 entries is accepted for evaluation;
+- a call with 501 entries fails immediately with `RATE_LIMIT_CONFIGURATION_INVALID`;
+- the failure happens before `subject`, `limit`, or `cost` resolvers run;
+- it does not matter whether those 501 entries would eventually belong to the same subject or different subjects.
+
+An “entry” is one element of the array passed to `consumeBatch()`. It is not the number of database rows inside the entry and it is not the entry's cost.
+
+Choose this value from the largest batch your public or internal API legitimately accepts. If an endpoint permits at most 200 work items, a value such as 250 leaves operational margin without allowing unbounded resolver work.
+
+#### Example: `maxCostPerConsume`
+
+```js
+limits: {
+  maxCostPerConsume: 10_000,
+}
+```
+
+Suppose a rule uses the number of validated rows as its cost:
+
+```js
+cost: (context) => context.rows.length;
+```
+
+With this configuration:
+
+- an operation containing 2,000 rows resolves to `cost: 2000` and can be evaluated normally;
+- an operation containing 10,001 rows fails with `RATE_LIMIT_CONFIGURATION_INVALID`;
+- the failure means “the caller asked the limiter to process an unsafe cost”, not “the subject exhausted its quota”; therefore it is not a `429 RATE_LIMITED` response.
+
+For `consumeBatch()`, the limit is checked again after entries for the same counter are grouped. If two entries for the same subject cost 6,000 each, their atomic group costs 12,000 and is rejected. Two entries for different subjects may each cost 6,000 because each becomes a separate atomic consumption.
+
+Set `maxCostPerConsume` to the largest legitimate atomic consumption. If larger work is valid, either increase the safety bound deliberately or split the work into separately meaningful subjects or operations. Do not raise it merely to hide input-validation problems.
+
+### Subject keyrings
+
+Raw subject values are never persisted. The limiter derives a stable HMAC-SHA-256 identifier using a named subject keyring:
+
+```js
+subjectKeyrings: {
+  default: {
+    currentKeyId: '2026-01',
+    keys: {
+      '2025-06': process.env.RATE_LIMIT_SUBJECT_KEY_OLD,
+      '2026-01': process.env.RATE_LIMIT_SUBJECT_KEY,
+    },
+  },
+}
+```
+
+| Option         | Required | Description                                                       |
+| -------------- | -------- | ----------------------------------------------------------------- |
+| `currentKeyId` | Yes      | ID used for new state. It must reference an entry in `keys`.      |
+| `keys.<keyId>` | Yes      | A `Buffer` or base64-encoded secret containing at least 32 bytes. |
+
+Keyring, key, store, rule, namespace, scope, subject type, bucket, policy ID, and policy-version identifiers must use only letters, digits, `.`, `_`, and `-`, with a maximum length of 128 characters. Subject values may be strings or buffers from 1 to 4096 bytes.
+
+Use a different secret for each environment. Do not use identifiers, passwords, API keys, IP addresses, or other subject values as HMAC keys.
+
+### Stores
+
+The built-in durable store uses a LoopBack `PersistedModel`:
+
+```js
+stores: {
+  primary: {
+    provider: 'persisted-model',
+    model: 'RateLimitState',
+    namespace: 'example-api-production',
+    maxRetries: 20,
+  },
+}
+```
+
+| Option        | Default | Description                                                                                                                                                                      |
+| ------------- | ------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`    |       — | Store-provider name. The built-in provider is `persisted-model`.                                                                                                                 |
+| `model`       |       — | Model name used by the persisted-model provider. It should be a private `RateLimitState` model attached to a durable datasource.                                                 |
+| `namespace`   |       — | Isolates state belonging to an application or deployment. It is required by static remote policies and authentication rate limiting. Use a stable, unique value per environment. |
+| `allowMemory` | `false` | Explicitly allows the resolved model to use the built-in memory connector. Intended for tests and single-instance development; memory state is private to each process and does not survive restarts or share counters between instances. |
+| `maxRetries`  |    `20` | Maximum compare-and-swap retry count for concurrent state changes.                                                                                                               |
+
+At startup, the persisted-model provider verifies deterministic string-ID
+round-tripping, duplicate-ID enforcement, two concurrent conditional updates,
+a stale update, and cleanup. Initialization fails if exactly one concurrent
+CAS does not win or if the connector's duplicate-key error cannot be
+recognized. This runtime probe protects every deployment; it does not replace
+the connector contract suite.
+
+MongoDB deployments can run the real multi-store contract before adopting a
+connector or connector upgrade:
+
+```sh
+MONGODB_RATE_LIMIT_TEST_URL=mongodb://127.0.0.1:27017/loopback-rate-limit-contract \
+  pnpm --filter @vsaas/loopback test:run -- test/rate-limit-persistence.mongodb.test.js
+```
+
+The contract starts two store instances, exercises concurrent creates and CAS,
+and confirms that one deterministic string ID owns the resulting state. Add an
+equivalent real-database contract before documenting another connector as
+supported. Memory-backed stores are never selected implicitly; they always
+require explicit opt-in through `allowMemory`.
+
+`RateLimitState` is security state. Keep it private, do not expose it through REST, and use a datasource shared by all application instances. There is no automatic production memory fallback.
+
+Redis is optional and therefore is not bundled with the framework. Install
+[`@vsaas/loopback-component-rate-limit-redis`](https://github.com/vsaas/loopback-monorepo/tree/main/loopback-component-rate-limit-redis)
+only in applications that need it. The package is a LoopBack component: it is loaded from
+`component-config.json`, owns a Redis connection pool, and registers the `redis` provider before
+rate-limit initialization.
+
+```json
+{
+  "@vsaas/loopback-component-rate-limit-redis": {
+    "redis": {
+      "url": "${REDIS_URL}"
+    },
+    "pool": {
+      "minimum": 1,
+      "maximum": 10,
+      "acquireTimeout": 5000
+    },
+    "keyPrefix": "example-api:rate-limit:"
+  }
+}
+```
+
+Select it like any other store:
+
+```js
+stores: {
+  primary: {
+    provider: 'redis',
+    namespace: 'example-api-production',
+  },
+}
+```
+
+The Redis package uses isolated pooled connections for standalone Redis or
+slot-primary routing with per-primary serialization for Redis Cluster.
+`WATCH` and `MULTI/EXEC` provide atomic updates, while Redis `TIME` supplies
+the authoritative clock. It preserves TTL, revision checks, `operationId`
+deduplication, and fail-closed recovery of uncertain writes. Connection,
+pool, and Cluster settings live exclusively in `component-config.json`;
+supplying them inside a store definition fails configuration on purpose so a
+single owner controls connection lifecycle. Store definitions may override
+only `keyPrefix`, `maxRetries`, and `maxStateBytes`. See the package's dedicated
+manual for every connection, Cluster, pool, store, security, health, shutdown,
+and test option.
+
+The existing generic provider API remains available for other storage implementations:
+
+```js
+app.registerRateLimitProvider('custom-store', (options) => createCustomStore(options));
+```
+
+A custom store must implement:
+
+```text
+initialize()
+healthCheck()
+inspect(input)
+consume(input)
+reset(input)
+delete(input)
+```
+
+TypeScript consumers and optional store packages can import the shared store
+contract from `@vsaas/loopback/rate-limit`:
+
+```ts
+import type {
+  RateLimitStore,
+  RateLimitInspection,
+  RateLimitConsumption,
+  RateLimitReset,
+  RateLimitDelete,
+  RateLimitDecision,
+} from '@vsaas/loopback/rate-limit';
+```
+
+Mutating operations must preserve the framework's `operationId` idempotency and revision/compare-and-swap guarantees. An ambiguous write outcome must fail closed instead of being retried as a new operation.
+
+## Programmatic rules
+
+Define a rule before initialization:
+
+```js
+app.rateLimiter.defineRule({
+  id: 'report-generation-by-api-key',
+  algorithm: 'fixed-window',
+  store: 'primary',
+  subjectKeyring: 'default',
+  bucket: 'report-generation',
+  phase: 'domain',
+  order: 0,
+  onStoreError: 'deny',
+
+  subject: (context) => ({
+    namespace: 'example-api-production',
+    scope: 'reporting',
+    subjectType: 'api-key',
+    canonicalValue: context.apiKeyId,
+  }),
+
+  limit: (context) => ({
+    limit: context.plan.unitsPerMinute,
+    windowMs: 60_000,
+    blockDurationMs: 60_000,
+    stateTtlMs: 120_000,
+    revision: context.plan.revision,
+  }),
+
+  cost: (context) => context.reportCount,
+});
+```
+
+The names `report-generation`, `reporting`, and `api-key` are examples chosen by this application. The framework does not contain a built-in reporting or API-key model.
+
+After initialization, the application supplies the context expected by the three resolvers:
+
+```js
+const decision = await app.rateLimiter.consume('report-generation-by-api-key', {
+  apiKeyId: 'key-42',
+  reportCount: 5,
+  plan: {
+    unitsPerMinute: 100,
+    revision: 'standard-plan-v1',
+  },
+});
+```
+
+For this call:
+
+- `subject()` selects the counter belonging to API key `key-42`;
+- `limit()` assigns that counter a capacity of 100 units for 60 seconds;
+- `cost()` consumes 5 units;
+- `consume()` returns the resulting decision without throwing merely because it is denied.
+
+### Rule options
+
+| Option               |  Default | Description                                                                                                                               |
+| -------------------- | -------: | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                 |        — | Unique rule identifier.                                                                                                                   |
+| `algorithm`          |        — | Currently only `fixed-window` is supported for registered programmatic rules.                                                             |
+| `store`              |        — | Name of a registered store.                                                                                                               |
+| `subjectKeyring`     |        — | Keyring used to HMAC the subject.                                                                                                         |
+| `bucket`             |        — | Logical counter bucket.                                                                                                                   |
+| `phase`              | `domain` | Composition phase: `early`, `resolved`, or `domain`.                                                                                      |
+| `order`              |      `0` | Integer ordering within a phase.                                                                                                          |
+| `shortCircuitOnDeny` |  `false` | Stops evaluation after this rule denies. Leave it disabled when all applicable decisions or audit records are needed.                     |
+| `onStoreError`       |        — | Required: `deny` or `allow`.                                                                                                              |
+| `subject(context)`   |        — | Synchronous or asynchronous resolver returning the subject descriptor.                                                                    |
+| `limit`              |        — | Static limit object or synchronous/asynchronous resolver. Returning `null` disables the rule for that context without touching the store. |
+| `cost`               |      `1` | Positive integer or resolver. It cannot exceed `limits.maxCostPerConsume`.                                                                |
+
+`onStoreError: 'allow'` converts a store failure into an allowed decision. Reserve it for explicitly best-effort, non-security use cases. Authentication rate limiting always fails closed.
+
+### `phase` and `order`: ordering several rules
+
+`phase` and `order` determine the order in which **rules** are evaluated when an integration composes several rules for one operation. They do not order incoming requests, give priority to one customer, change a quota, or control database execution order.
+
+Rules are sorted by:
+
+1. `phase`: `early`, then `resolved`, then `domain`;
+2. `order`: lower integers first within the same phase;
+3. original array order when both values are equal.
+
+The three phase names are framework-defined ordering slots:
+
+| Phase      | Runs | Intended use                                                                                                                                                             |
+| ---------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `early`    | 1st  | Coarse limits that can be derived from information available immediately, such as a global endpoint budget or a trusted request source.                                  |
+| `resolved` | 2nd  | Limits that use an identity already resolved by the integration, such as an authenticated principal, tenant, or API key. Static remote-method policies use this default. |
+| `domain`   | 3rd  | Limits based on application or resource context, such as a project, document, subscription plan, or job. Programmatic rules use this default.                            |
+
+The framework only enforces this ordering. It does not verify that an `early` rule really uses request-level data or that a `domain` rule uses a domain object. Treat the phase names as shared conventions so integrations compose predictably.
+
+Example:
+
+```js
+[
+  { ruleId: 'endpoint-global', phase: 'early', order: 0 },
+  { ruleId: 'source-volume', phase: 'early', order: 10 },
+  { ruleId: 'account-quota', phase: 'resolved', order: 0 },
+  { ruleId: 'project-quota', phase: 'domain', order: 0 },
+];
+```
+
+The execution order is exactly the order shown. `order: 10` does not mean “ten requests later”; it only places `source-volume` after rules with a lower order in the `early` phase.
+
+Ordering matters most when `shortCircuitOnDeny` is `true`: after that rule denies, later rules are not evaluated or consumed. With the default `false`, all applicable rules are evaluated in order and the final operation is denied if **any** rule denies. A later allow never erases an earlier denial.
+
+For a single call to a registered rule through `inspect()`, `consume()`, `enforce()`, or `consumeBatch()`, there is only one rule, so its `phase` and `order` have no observable effect. They become relevant when the resolved rule is composed with others, especially through remote-method resolvers and the lower-level `consumeAll()` API.
+
+### Subject descriptor
+
+The `subject` resolver returns:
+
+| Field            | Who defines its value? | Description                                                                        |
+| ---------------- | ---------------------- | ---------------------------------------------------------------------------------- |
+| `namespace`      | Application            | Application or deployment boundary.                                                |
+| `scope`          | Application            | Stable label that groups a family of subjects or counters.                         |
+| `subjectType`    | Application            | Stable label describing the kind of value contained in `canonicalValue`.           |
+| `canonicalValue` | Application            | Raw string or buffer that identifies the subject. It is HMACed before persistence. |
+
+`scope` and `subjectType` are **not predefined enums**. LoopBack does not obtain them from models, dependency injection, HTTP, authentication, or a business hierarchy. The application chooses them. The only framework restriction is their format: 1 to 128 characters using letters, digits, `.`, `_`, or `-`.
+
+This keeps the implementation generic. Examples of valid application-defined subjects are:
+
+| Use case                    | `scope`       | `subjectType` | `canonicalValue`             |
+| --------------------------- | ------------- | ------------- | ---------------------------- |
+| One quota per account       | `billing`     | `account`     | `String(account.id)`         |
+| One quota per API key       | `public-api`  | `api-key`     | `String(apiKey.id)`          |
+| One quota per import source | `imports`     | `source`      | normalized source ID         |
+| One quota per device        | `telemetry`   | `device`      | `String(device.id)`          |
+| One global counter          | `maintenance` | `global`      | a stable value such as `all` |
+
+These words are illustrative, not reserved. An application could use `workspace`, `organization`, `queue`, or another vocabulary that matches its domain.
+
+Think of the fields this way:
+
+- `scope` answers “in which part of the application does this identity live?”;
+- `subjectType` answers “what kind of identity is this?”;
+- `canonicalValue` answers “which exact identity is it?”;
+- `bucket` answers “which action is being counted for that identity?”.
+
+For example, these are different counters even though their raw value is the same:
+
+```js
+{ scope: "billing", subjectType: "account", canonicalValue: "42" }
+{ scope: "public-api", subjectType: "api-key", canonicalValue: "42" }
+```
+
+Use stable IDs rather than display names or mutable attributes. Normalize equivalent values before returning them—for example, lowercase a case-insensitive email or use a canonical textual representation for an address. The framework HMACs the final value but does not canonicalize business data for you.
+
+State identity also includes the subject key ID, bucket, policy ID, and policy version. Changing any identity component creates or addresses an independent counter, so renaming `scope` or `subjectType` is a state migration rather than a cosmetic refactor.
+
+### Limit object
+
+Programmatic duration values are in **milliseconds**.
+
+| Option            |                              Default | Description                                                                         |
+| ----------------- | -----------------------------------: | ----------------------------------------------------------------------------------- |
+| `limit`           |                                    — | Positive integer capacity for the fixed window.                                     |
+| `windowMs`        |                                    — | Positive window duration in milliseconds.                                           |
+| `blockDurationMs` |                           `windowMs` | How long subsequent attempts remain blocked after capacity is exhausted.            |
+| `stateTtlMs`      | `2 × max(windowMs, blockDurationMs)` | Persistence TTL. It must cover both durations and cannot exceed 365 days.           |
+| `revision`        |                                    — | Required non-empty policy revision. Change it whenever the policy semantics change. |
+
+`limit` can be either one fixed object for every subject or a resolver function.
+
+#### Fixed limit
+
+Use a fixed object when every subject receives the same quota:
+
+```js
+limit: {
+  limit: 100,
+  windowMs: 60_000,
+  blockDurationMs: 60_000,
+  stateTtlMs: 120_000,
+  revision: "1",
+}
+```
+
+This means:
+
+- each counter has 100 units per 60-second fixed window;
+- an operation consumes the rule's resolved `cost`;
+- the operation that brings consumption to exactly 100 is allowed;
+- the next operation is denied while the counter is blocked;
+- when either the fixed window or the active block expires, the state resets and a new window can start with zero consumption.
+
+The quota is measured in **cost units**, not automatically in HTTP requests. With the default `cost: 1`, 100 units means 100 operations. With `cost: context.rows.length`, it means 100 rows across any number of operations.
+
+The framework snapshots a fixed limit when `defineRule()` is called. Mutating the original JavaScript object later does not change the registered rule. Restart and re-register the rule with a new `revision` to deploy a policy change.
+
+#### Dynamic limit
+
+Use a resolver when the quota depends on runtime context:
+
+```js
+limit: async (context) => {
+  const plan = await findPlan(context.accountId);
+
+  if (!plan.rateLimitEnabled) return null;
+
+  return {
+    limit: plan.unitsPerHour,
+    windowMs: 60 * 60 * 1000,
+    blockDurationMs: 5 * 60 * 1000,
+    stateTtlMs: 2 * 60 * 60 * 1000,
+    revision: String(plan.rateLimitRevision),
+  };
+};
+```
+
+The resolver may be synchronous or asynchronous. It receives the same read-only context passed to `inspect()`, `consume()`, `enforce()`, or each batch entry.
+
+Returning `null` means “this rule does not apply to this context”:
+
+- no store is read or mutated;
+- the `subject` and `cost` resolvers are not called;
+- the public decision contains `applied: false` and `allowed: true`;
+- no counter is created.
+
+This is useful for an unlimited plan or a feature that is disabled for a particular context. It is not the same as returning an extremely large limit.
+
+#### What each field controls
+
+`limit` is the total capacity of one fixed window. It must be a positive integer.
+
+`windowMs` is the length of the fixed window. A window begins when the first applicable consumption creates fresh state; it is not aligned automatically to wall-clock boundaries such as the beginning of a minute.
+
+`blockDurationMs` is the requested block duration once capacity has been filled or an operation exceeds the remaining capacity. It defaults to `windowMs`.
+
+```text
+limit = 10
+windowMs = 60 seconds
+blockDurationMs = 15 seconds
+```
+
+The tenth unit is allowed and starts the block for following operations. After the 15-second block expires, the fixed-window state resets and a new window can start.
+
+Fixed-window state also resets when the original window expires. Therefore the effective wait ends at the earlier of the block expiry and the window expiry. A `blockDurationMs` longer than `windowMs` does not extend the block beyond that window. If the application needs escalating or independent lockout periods for failures, use a `failure-lockout` policy through a remote resolver or the authentication adapter rather than a registered fixed-window rule.
+
+If the counter has 8 of 10 units consumed and the next operation costs 3:
+
+- the operation is denied in full;
+- the counter does not partially accept 2 units;
+- the block begins;
+- the caller must retry the whole operation after the block expires.
+
+`stateTtlMs` controls how long persisted counter state remains eligible for cleanup. It is not the quota window and it is not the client retry delay. It must be at least as long as both `windowMs` and `blockDurationMs`. When omitted, it defaults to twice the longer of those durations, capped at 365 days.
+
+`revision` identifies the semantics of a dynamic policy. Use a stable string such as a configuration version, subscription-policy version, or explicit deployment revision:
+
+```js
+revision: 'free-plan-v3';
+```
+
+Change it whenever `limit`, `windowMs`, `blockDurationMs`, or `stateTtlMs` changes. A new revision addresses new policy state. Reusing the same rule ID and revision with different values is treated as a configuration error because different application instances could otherwise enforce incompatible policies against the same counter.
+
+The revision identifies policy semantics across the entire rule, not only within one subject. If two plans return different limits, they must also return revisions that distinguish those policies:
+
+```js
+// Good: different semantics have different revisions.
+{ limit: 100, revision: "free-v2", /* ... */ }
+{ limit: 10_000, revision: "pro-v4", /* ... */ }
+
+// Invalid: the same rule and revision resolve to two different limits.
+{ limit: 100, revision: "1", /* ... */ }
+{ limit: 10_000, revision: "1", /* ... */ }
+```
+
+Changing a revision starts addressing different policy state, so active consumption from the previous revision does not carry over automatically. Coordinate revision changes as quota migrations, especially across multiple application instances.
+
+The policy resolver may determine a quota from one object while the counter belongs to another. For example, an account's subscription plan can supply the limit while `subject()` returns an API-key ID, creating one counter per key under the account's plan. The framework deliberately does not prescribe how policies are inherited or who owns the counter.
+
+### Operations
+
+```js
+const preview = await app.rateLimiter.inspect('report-generation-by-api-key', context);
+const decision = await app.rateLimiter.consume('report-generation-by-api-key', context);
+await app.rateLimiter.enforce('report-generation-by-api-key', context);
+```
+
+| Operation      | Behavior                                                                                                                                                 |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inspect`      | Reads a decision without consuming capacity. Do not use it as an authorization check followed by a later consume; another request can race between them. |
+| `consume`      | Atomically consumes capacity and returns a decision.                                                                                                     |
+| `enforce`      | Consumes capacity and throws `RATE_LIMITED` when denied.                                                                                                 |
+| `consumeBatch` | Resolves and consumes a set of entries, grouping compatible entries for the same state into one atomic cost.                                             |
+
+A decision includes `ruleId`, `applied`, `allowed`, `blockedUntilMs`, and `revision`. A rule whose limit resolver returns `null` produces `applied: false`.
+
+Choose the operation from the behavior the caller needs:
+
+- use `inspect()` for diagnostics, status pages, or a non-binding preview—not to reserve quota;
+- use `consume()` when the caller wants to handle an allowed or denied decision itself;
+- use `enforce()` when denial should immediately become a `RATE_LIMITED` error;
+- use `consumeBatch()` when one input contains several independently addressable work items.
+
+Consumption happens before the protected business operation. If the business operation later fails, the limiter does not refund the cost automatically. Automatic refunds would permit retry races and ambiguous double spending. Design cost around accepted attempts, or implement a separate, explicitly idempotent compensation workflow if the domain genuinely requires refunds.
+
+#### Administrative operations
+
+The limiter also exposes non-consuming helpers on `app.rateLimit.limiter` for support interventions and diagnostics:
+
+| Operation                            | Behavior                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `reset(rule, expectedRevision)`      | Clears one subject's persisted state when the stored revision still matches. Returns an outcome of `reset`, `not-found`, or `preserved-newer-state` when a concurrent consumption already created newer state. |
+| `delete(rules)`                      | Removes persisted state for the given resolved rules across their stores.                                                       |
+| `inspectAll(rules)`                  | Reads decisions for several rules without consuming capacity, composing them in `phase`/`order` order.                          |
+| `subjectIdentity(rule)`              | Returns the stable internal identity string derived from the subject and bucket; useful when correlating logs with store state. |
+
+These operations follow the same compare-and-swap guarantees as consumption. `reset()` never overwrites state created after the caller read it, so it cannot accidentally clear a block that a newer policy version established.
+
+### Batch consumption
+
+`consumeBatch()` runs one registered rule for many input entries:
+
+```js
+const decisions = await app.rateLimiter.consumeBatch(
+  'report-generation-by-api-key',
+  validatedJobs.map((job) => ({
+    entryId: job.id,
+    context: {
+      apiKeyId: job.apiKeyId,
+      reportCount: job.reports.length,
+      plan: job.plan,
+    },
+  })),
+);
+```
+
+Each array element has two fields:
+
+| Field     | Purpose                                                                                                                                                                                                      |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `entryId` | Unique correlation ID from 1 to 256 characters. It appears in the returned decision so the caller can match output to input. It does **not** define the rate-limit subject and is not part of counter state. |
+| `context` | Arbitrary application data passed to the rule's `subject`, `limit`, and `cost` resolvers.                                                                                                                    |
+
+The limiter processes a batch in these steps:
+
+1. It verifies that the input is an array, does not exceed `maxBatchEntries`, and contains unique valid `entryId` values.
+2. It calls the rule's `limit` resolver for every entry. An entry returning `null` becomes `applied: false` and does not touch the store.
+3. It resolves the subject and cost of every applicable entry.
+4. It groups entries that address the same counter and use the same policy.
+5. It adds the costs inside each group and performs one atomic consumption for that group.
+6. It returns one decision per input entry, in the original input order.
+
+#### Worked example
+
+Assume the rule identifies its subject with `context.accountId`, uses `context.units` as cost, and allows 10 units:
+
+```js
+[
+  { entryId: 'job-1', context: { accountId: 'A', units: 3 } },
+  { entryId: 'job-2', context: { accountId: 'A', units: 2 } },
+  { entryId: 'job-3', context: { accountId: 'B', units: 4 } },
+];
+```
+
+The limiter creates two atomic groups:
+
+```text
+account A: job-1 + job-2 = cost 5
+account B: job-3         = cost 4
+```
+
+If account A already consumed 7 of 10 units, its remaining capacity is 3. The grouped cost of 5 is denied in full; neither `job-1` nor `job-2` receives a partial allowance. If account B has enough capacity, `job-3` is still allowed.
+
+The result remains aligned with the input:
+
+```js
+[
+  { entryId: 'job-1', applied: true, allowed: false /* ... */ },
+  { entryId: 'job-2', applied: true, allowed: false /* ... */ },
+  { entryId: 'job-3', applied: true, allowed: true /* ... */ },
+];
+```
+
+Entries grouped into the same atomic consumption receive the same rate-limit decision. `consumeBatch()` returns denied decisions; it does not throw `RATE_LIMITED` merely because one group is denied. The caller must inspect every decision and decide which allowed work to continue.
+
+#### Important batch guarantees and limits
+
+- **Atomic per counter:** all cost grouped for one counter is accepted or denied together.
+- **No transaction across counters:** different subjects are consumed independently. A denial or later business failure for one subject does not roll back another subject's quota.
+- **Errors do not imply zero consumption:** groups are consumed independently and may run concurrently. If one store operation fails and the batch promise rejects, another group may already have consumed quota.
+- **Stable output:** returned decisions have the same order as the input entries.
+- **Policy consistency:** entries for the same counter must resolve the same policy fingerprint. Incompatible policies in one batch are rejected as a configuration error.
+- **Grouped safety bound:** the summed cost of one group cannot exceed `maxCostPerConsume`.
+- **No automatic refund:** a later failure while processing an allowed entry does not restore quota.
+
+Validate and deduplicate the complete application payload **before** calling `consumeBatch()`. Derive cost from trusted, validated data rather than a count supplied by the client. For example, use `validatedRows.length`, not `request.body.declaredRowCount`.
+
+## Remote-method policies
+
+Remote methods can reference a named static policy:
+
+```js
+app.set('rateLimitPolicies', {
+  publicSearch: {
+    policyId: 'public-search',
+    policyVersion: '2',
+    algorithm: 'fixed-window',
+    maxAttempts: 30,
+    observationWindow: 60,
+    blockDuration: 120,
+    stateTtl: 300,
+  },
+});
+```
+
+Unlike programmatic rules, durations in `rateLimitPolicies` are in **seconds**.
+
+### Fixed-window policy
+
+| Option              |     Default | Description                                                                                   |
+| ------------------- | ----------: | --------------------------------------------------------------------------------------------- |
+| `policyId`          | Policy name | Stable state-policy identifier.                                                               |
+| `policyVersion`     |           — | Required revision. Change it with any semantic policy change.                                 |
+| `algorithm`         |           — | `fixed-window`.                                                                               |
+| `maxAttempts`       |           — | Positive capacity per observation window.                                                     |
+| `observationWindow` |           — | Window length in seconds.                                                                     |
+| `blockDuration`     |           — | Block duration in seconds.                                                                    |
+| `stateTtl`          |           — | State TTL in seconds. It must cover the window and block duration and cannot exceed 365 days. |
+
+### Failure-lockout policy
+
+Failure lockout is available to custom remote resolvers and authentication-specific controls:
+
+| Option              |         Default | Description                                                                  |
+| ------------------- | --------------: | ---------------------------------------------------------------------------- |
+| `policyId`          |     Policy name | Stable state-policy identifier.                                              |
+| `policyVersion`     |               — | Required revision.                                                           |
+| `algorithm`         |               — | `failure-lockout`.                                                           |
+| `maxFailedAttempts` |               — | Failures allowed in the observation window.                                  |
+| `observationWindow` |               — | Failure observation window in seconds.                                       |
+| `blockDuration`     |               — | Initial block duration in seconds.                                           |
+| `strategy`          |         `fixed` | `fixed` or `exponential`.                                                    |
+| `multiplier`        |             `2` | Backoff multiplier for the exponential strategy.                             |
+| `maxBlockDuration`  | `blockDuration` | Maximum block duration in seconds.                                           |
+| `backoffResetAfter` |               — | Successful or quiet period after which the backoff level resets, in seconds. |
+| `stateTtl`          |               — | State TTL in seconds. It must cover all relevant windows and maximum blocks. |
+
+`multiplier` accepts values from 1 to 100. Escalation is computed as
+`blockDuration × multiplier^(level − 1)`, capped at 30 doublings and at
+`maxBlockDuration`, so extreme configurations cannot overflow block durations.
+
+### Static remote-method metadata
+
+Attach a policy in the model JSON or through `remoteMethod()` metadata:
+
+```json
+{
+  "rateLimit": {
+    "policy": "publicSearch",
+    "store": "primary",
+    "subjectKeyring": "default",
+    "bucket": "PublicSearch.find",
+    "cost": 1,
+    "onStoreError": "deny",
+    "phase": "resolved",
+    "order": 0,
+    "shortCircuitOnDeny": false
+  }
+}
+```
+
+| Option               |        Default | Description                            |
+| -------------------- | -------------: | -------------------------------------- |
+| `policy`             |              — | Name in `rateLimitPolicies`.           |
+| `store`              |              — | Registered store name.                 |
+| `subjectKeyring`     |      `default` | Subject keyring.                       |
+| `bucket`             | `Model.method` | Counter bucket.                        |
+| `cost`               |            `1` | Positive consumption cost.             |
+| `onStoreError`       |         `deny` | `deny` or `allow`.                     |
+| `phase`              |     `resolved` | Composition phase.                     |
+| `order`              |            `0` | Integer ordering within the phase.     |
+| `shortCircuitOnDeny` |        `false` | Whether this denial stops later rules. |
+
+A static remote policy is **global per endpoint**. Its subject is the resolved `Model.method`, not the caller's IP address, user, tenant, or access token. This is appropriate for a global endpoint budget. Use a resolver when the policy must distinguish callers.
+
+### Remote resolver
+
+A remote resolver returns one or more fully resolved rules. Normalize the policy through the public helper so validation and fingerprinting stay consistent:
+
+```js
+const loopback = require('@vsaas/loopback');
+
+const policy = loopback.rateLimit.normalizeFixedWindowPolicy({
+  policyId: 'public-search-source',
+  policyVersion: '1',
+  maxAttempts: 30,
+  observationWindowMs: 60_000,
+  blockDurationMs: 120_000,
+  stateTtlMs: 300_000,
+});
+
+app.registerRateLimitResolver('publicSearchBySource', async (context) => {
+  const source = context.source;
+  if (!source) return null;
+
+  return {
+    ruleId: 'public-search-source',
+    store: 'primary',
+    subjectKeyring: 'default',
+    bucket: 'PublicSearch.find',
+    subject: {
+      namespace: 'example-api-production',
+      scope: 'remote-method',
+      subjectType: 'source',
+      canonicalValue: source,
+    },
+    policy,
+    cost: 1,
+    onStoreError: 'deny',
+    phase: 'early',
+    order: 0,
+    shortCircuitOnDeny: false,
+  };
+});
+```
+
+Reference it from remote metadata with `"resolver": "publicSearchBySource"`. The resolver context contains `app`, `model`, `methodName`, `args`, `request`, `accessToken`, and `source`. It may return `null`, one resolved rule, or a list of resolved rules.
+
+By default, `source` is the request IP address. A model can supply its own
+signal by defining a static `getRateLimitSource(request)` hook, which receives
+the request and returns any stable source identifier, or `null` to omit
+source-based rules for that call. This mirrors how authentication rate limiting
+resolves its source through `resolveAuthenticationRateLimitSource`.
+
+Resolver policy helpers use **milliseconds**, because they produce the programmatic normalized policy contract. Named `rateLimitPolicies` remain in seconds.
+
+All returned rules compose in stable `phase` and `order` order. Any denial denies the request; a later allowed decision cannot overwrite an earlier denial.
+
+Static policy and resolver references are validated at startup. Static definitions are snapshotted, so mutating configuration after initialization has no effect.
+
+## Errors and HTTP behavior
+
+| Code                               | HTTP status | Meaning                                                                                                               |
+| ---------------------------------- | ----------: | --------------------------------------------------------------------------------------------------------------------- |
+| `RATE_LIMITED`                     |       `429` | The applicable policy denied the operation. Remote responses include a rounded-up `Retry-After` value when available. |
+| `RATE_LIMIT_UNAVAILABLE`           |       `503` | Required rate-limit state could not be read or updated safely.                                                        |
+| `RATE_LIMIT_CONFIGURATION_INVALID` |       `500` | Invalid configuration or policy mismatch. This should normally fail startup.                                          |
+| `RATE_LIMIT_OPERATION_AMBIGUOUS`   |       `503` | The store cannot prove whether a mutation completed.                                                                  |
+
+`RATE_LIMITED` and `RATE_LIMIT_UNAVAILABLE` remote error responses set
+`Cache-Control: no-store`, and `RATE_LIMITED` responses include a rounded-up
+`Retry-After` value when a block is active. The configuration and
+ambiguous-operation codes follow normal framework error handling; do not
+convert unavailable or ambiguous security-state errors into ordinary
+application errors.
+
+## State cleanup
+
+Expired state can be removed with:
+
+```js
+const result = await app.cleanupRateLimitStates({
+  model: 'RateLimitState',
+  now: new Date(),
+});
+```
+
+The helper deletes records whose `expiresAt` is older than `now`. Schedule it as a recurring maintenance job. Cleanup does not replace datasource TTL indexes where the connector supports them, but it provides a connector-independent fallback.
+
+## Key rotation
+
+Rotate a subject keyring without resetting or duplicating live counters:
+
+1. Add the new key while retaining the old key.
+2. Change `currentKeyId` to the new key.
+3. Deploy the configuration everywhere.
+4. Keep the old key for at least the longest `stateTtl`, plus cleanup and deployment margin.
+5. Run cleanup and verify that no unexpired state references the old key.
+6. Remove the old key.
+
+The limiter checks live candidates across retained keys. If multiple live states make the active counter ambiguous, it fails closed. Removing an old key too early can bypass an existing block by making its state unreachable.
+
+## Production checklist
+
+- Use a private, durable `RateLimitState` model shared by every instance.
+- Give each deployment a stable, unique namespace.
+- Keep HMAC keys outside source control and use at least 32 random bytes.
+- Initialize before listening and treat initialization failure as a deployment failure.
+- Use `onStoreError: 'deny'` for abuse prevention, authentication, authorization, and resource protection.
+- Derive batch cost from validated, deduplicated input.
+- Increment policy revisions whenever semantics change.
+- Monitor `429`, unavailable-state errors, ambiguous operations, store latency, and cleanup lag.
+- Test capacity boundaries, block expiry, concurrent consumption, store failure, policy changes, key rotation, and multi-instance behavior.