@profullstack/throttle 0.3.4 → 0.4.0

package/README.md

@@ -70,6 +70,20 @@ export async function proxy(request) {
 Without a `gateway` the same throttle answers `429` with `Retry-After`. That is
 the fallback, not the goal.
 
+## Headroom: only offenders are refused
+
+Since 0.4.0 every number a site configures is multiplied by `headroom` (default
+5): the default allowance, every rule, the credential budget and ceiling, and
+the subresource bucket. Write the limits as "what a normal reader uses"; the
+throttle refuses only a caller five times past that. People were being refused
+for ordinary heavy use when the limits had no room above typical consumption.
+
+Brute-force guards keep the number as written. A rule is a guard when it is
+marked `guard: true`, marked `credential: false` (the sign-in pattern), or its
+path looks like auth (`/auth/`, `/login`, `/signup`, `*-password`, `/reset`,
+`/otp`, `/verify-*`, `/oauth/`, `2fa`/`mfa`). So `{ path: '/api/auth/', limit: 10,
+credential: false }` stays 10 a minute while `/feed/` at 30 becomes 150.
+
 ## What a refused caller sees
 
 ```
@@ -105,7 +119,8 @@ selling the same minute twice.
 
 | Option | Default | |
 |---|---|---|
-| `limit` | `100` | requests per window, per caller |
+| `limit` | `100` | requests per window, per caller, before `headroom` |
+| `headroom` | `5` | multiplier on every limit except brute-force guards; `1` uses the numbers as written |
 | `windowSeconds` | `60` | |
 | `gateway` | — | an `@profullstack/x402-gateway`; makes over-limit a 402 |
 | `rules` | `[]` | per-path allowances; most specific match wins |

package/index.d.ts

@@ -3,6 +3,8 @@ import type { Gateway, QuotaStore } from '@profullstack/x402-gateway';
 /** The house default: a hundred requests a minute, per caller, everywhere. */
 export const DEFAULT_LIMIT: 100;
 export const DEFAULT_WINDOW_SECONDS: 60;
+/** Every limit is multiplied by this unless the rule is a brute-force guard. */
+export const DEFAULT_HEADROOM: 5;
 export const ALWAYS_OPEN: string[];
 
 export interface ThrottleRule {
@@ -18,6 +20,11 @@ export interface ThrottleRule {
    * request is authenticated — what the sign-in routes need.
    */
   credential?: false | { limit?: number; ceiling?: number };
+  /**
+   * A brute-force guard: its numbers are used as written, never multiplied by
+   * headroom. Implied by `credential: false` and by auth-looking paths.
+   */
+  guard?: boolean;
 }
 
 export interface CredentialBudget {
@@ -38,10 +45,15 @@ export interface ThrottleEvent {
 }
 
 export interface ThrottleOptions {
-  /** Default 100. */
+  /** Default 100, before headroom. */
   limit?: number;
   /** Default 60. */
   windowSeconds?: number;
+  /**
+   * Multiplier on every limit (default, rules, credential budget, subresources)
+   * except brute-force guards. Default 5; pass 1 to use the numbers as written.
+   */
+  headroom?: number;
   /** Over-limit is answered 402 with this gateway's offer instead of 429. */
   gateway?: Gateway | null;
   /** Shared counter. Default: one per process, so each instance grants its own. */
@@ -79,6 +91,7 @@ export interface Throttle {
   options: {
     limit: number;
     windowSeconds: number;
+    headroom: number;
     rules: Required<ThrottleRule>[];
     credential: { limit: number; ceiling: number } | null;
     subresources: { limit: number } | null;
@@ -106,3 +119,7 @@ export function compileRules(
   defaults: { limit: number; windowSeconds: number },
 ): Required<ThrottleRule>[];
 export function ruleFor<T>(compiled: Required<ThrottleRule>[], path: string, defaults: T): T;
+/** Whether a compiled rule is a brute-force guard (never scaled by headroom). */
+export function isGuard(rule: { path: string; credential?: unknown; guard?: boolean }): boolean;
+/** A compiled rule with its limits multiplied by `headroom`, unless it is a guard. */
+export function withHeadroom<T extends { path: string; limit: number }>(rule: T, headroom: number): T;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@profullstack/throttle",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
-  "description": "An app-wide rate limit whose answer to going over is a price, not a 429. 100 requests a minute free, then x402 Payment Required with an offer, settled by CoinPay. Meters every route, so a scraper wearing a browser user agent is charged like any other crawler.",
+  "description": "An app-wide rate limit whose answer to going over is a price, not a 429. 100 requests a minute free (times 5 headroom), then x402 Payment Required with an offer, settled by CoinPay. Meters every route, so a scraper wearing a browser user agent is charged like any other crawler.",
   "keywords": [
     "rate-limit",
     "throttle",
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@profullstack/x402-gateway": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0"
+    "@profullstack/x402-gateway": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0"
   },
   "scripts": {
     "test": "node --test"

package/src/index.js

@@ -3,10 +3,13 @@ export { memoryStore } from './store.js';
 export { addressOf, fingerprint, presentedCredential } from './identify.js';
 export {
   ALWAYS_OPEN,
+  DEFAULT_HEADROOM,
   DEFAULT_LIMIT,
   DEFAULT_WINDOW_SECONDS,
   compileRules,
   matches,
   matchesAny,
+  isGuard,
   ruleFor,
+  withHeadroom,
 } from './rules.js';

package/src/rules.js

@@ -15,6 +15,23 @@
 export const DEFAULT_LIMIT = 100;
 export const DEFAULT_WINDOW_SECONDS = 60;
 
+/**
+ * How far above the configured numbers a caller may go before it is refused.
+ * Every limit a site writes down is multiplied by this, so the numbers in a
+ * config read as "what a normal reader uses" and the throttle only catches
+ * callers far past that. On 2026-10-28 people complained that ordinary heavy
+ * use was being refused; the limits had been sized to typical consumption
+ * with no room above it. Brute-force guards (see `isGuard`) are never scaled.
+ */
+export const DEFAULT_HEADROOM = 5;
+
+/**
+ * Paths whose limit is a brute-force budget, not a reading allowance. Ten
+ * guesses a minute at a password is the point of the rule; five times that is
+ * a giveaway, so these keep the number the site wrote.
+ */
+const GUARD_PATH = /(^|[/_-])(auth|oauth|log-?in|sign-?in|sign-?up|register|password|passwd|reset|otp|verify|magic|2fa|mfa|totp)([/_.-]|$)/i;
+
 /**
  * Paths that are never metered, whatever the rules say.
  *
@@ -61,9 +78,33 @@ function normaliseRule(rule, defaults) {
     open: Boolean(rule?.open),
     /** Credentialed callers on this rule, if it wants different numbers. */
     credential: rule?.credential ?? null,
+    /** A brute-force guard: its numbers are never multiplied by headroom. */
+    guard: Boolean(rule?.guard),
   };
 }
 
+/**
+ * Whether a compiled rule is a brute-force guard: marked `guard: true`, marked
+ * `credential: false` (the documented sign-in pattern), or on an auth-looking
+ * path.
+ */
+export function isGuard(rule) {
+  return Boolean(rule.guard) || rule.credential === false || GUARD_PATH.test(rule.path);
+}
+
+/** A rule with its limits multiplied by `headroom`, unless it is a guard. */
+export function withHeadroom(rule, headroom) {
+  if (headroom === 1 || isGuard(rule)) return rule;
+  const credential = rule.credential && typeof rule.credential === 'object'
+    ? {
+        ...rule.credential,
+        ...(rule.credential.limit ? { limit: Math.floor(rule.credential.limit * headroom) } : {}),
+        ...(rule.credential.ceiling ? { ceiling: Math.floor(rule.credential.ceiling * headroom) } : {}),
+      }
+    : rule.credential;
+  return { ...rule, limit: Math.floor(rule.limit * headroom), credential };
+}
+
 /**
  * Compile the rule list. Longest pattern first, so `/api/auth/` is consulted
  * before `/api/` however the site happened to order them -- the alternative is

package/src/throttle.js

@@ -17,25 +17,30 @@
  * the caller has just demonstrated it wants more than the free tier and is
  * still holding the request open.
  *
- * A hundred requests a minute is the default. A person reading a site produces
- * a few dozen; a scraper produces that in a second.
+ * A hundred requests a minute is the default, and every number is then
+ * multiplied by `headroom` (5): a heavy reader is never refused, only a
+ * caller five times past what the site considers normal. A person reading a
+ * site produces a few dozen; a scraper produces that in a second.
  */
 
 import { quotaHeaders, spend } from '@profullstack/x402-gateway';
 import { addressOf, fingerprint, presentedCredential } from './identify.js';
 import {
   ALWAYS_OPEN,
+  DEFAULT_HEADROOM,
   DEFAULT_LIMIT,
   DEFAULT_WINDOW_SECONDS,
   compileRules,
   matchesAny,
   ruleFor,
+  withHeadroom,
 } from './rules.js';
 import { memoryStore } from './store.js';
 
 /**
  * @param {object} options
- * @param {number} [options.limit=100]              requests per window, per caller
+ * @param {number} [options.limit=100]              requests per window, per caller, before headroom
+ * @param {number} [options.headroom=5]             multiplier on every limit except brute-force guards; 1 to use the numbers as written
  * @param {number} [options.windowSeconds=60]
  * @param {object} [options.gateway]                a @profullstack/x402-gateway; over-limit is answered 402 with its offer
  * @param {object} [options.store]                  shared counter; default is per-process
@@ -49,16 +54,24 @@ import { memoryStore } from './store.js';
  * @param {(event: object) => void|Promise<void>} [options.onThrottle]  told about every refusal; its errors are swallowed
  */
 export function createThrottle(options = {}) {
-  const defaults = {
+  const headroom = positiveReal(options.headroom, DEFAULT_HEADROOM);
+  const scale = (n) => Math.floor(n * headroom);
+
+  /*
+   * Rules inherit the unscaled default and are scaled once afterwards, so a
+   * rule that leaves out its limit is not multiplied twice.
+   */
+  const base = {
     path: '',
     limit: positive(options.limit, DEFAULT_LIMIT),
     windowSeconds: positive(options.windowSeconds, DEFAULT_WINDOW_SECONDS),
     open: false,
     credential: null,
   };
+  const defaults = { ...base, limit: scale(base.limit) };
 
   const store = options.store?.hit ? options.store : memoryStore();
-  const rules = compileRules(options.rules, defaults);
+  const rules = compileRules(options.rules, base).map((rule) => withHeadroom(rule, headroom));
   const gateway = options.gateway ?? null;
   const identify = options.identify ?? addressOf;
   /*
@@ -79,8 +92,8 @@ export function createThrottle(options = {}) {
    * this layer has not authenticated any of them.
    */
   const credential = options.credential === false ? null : {
-    limit: positive(options.credential?.limit, 600),
-    ceiling: positive(options.credential?.ceiling, 1200),
+    limit: scale(positive(options.credential?.limit, 600)),
+    ceiling: scale(positive(options.credential?.ceiling, 1200)),
   };
 
   /*
@@ -104,7 +117,7 @@ export function createThrottle(options = {}) {
    * buys itself a bigger bucket, not an unmetered site.
    */
   const subresources = options.subresources === false ? null : {
-    limit: positive(options.subresources?.limit, 1000),
+    limit: scale(positive(options.subresources?.limit, 1000)),
   };
 
   const quotaFor = (rule) => ({
@@ -246,7 +259,7 @@ export function createThrottle(options = {}) {
     handle,
     /** For tests and for a site that wants to reclaim memory on demand. */
     store,
-    options: { ...defaults, rules, credential, subresources, openPaths, gateway: Boolean(gateway) },
+    options: { ...defaults, headroom, rules, credential, subresources, openPaths, gateway: Boolean(gateway) },
   };
 }
 
@@ -261,6 +274,11 @@ export function isSubresource(request) {
   return SUBRESOURCE.has(request.headers.get('sec-fetch-dest') ?? '');
 }
 
+function positiveReal(value, fallback) {
+  const n = Number(value);
+  return value !== undefined && value !== null && Number.isFinite(n) && n >= 1 ? n : fallback;
+}
+
 function positive(value, fallback) {
   const n = Number(value);
   return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;