@profullstack/throttle 0.1.0 → 0.2.0

package/README.md

@@ -110,7 +110,8 @@ selling the same minute twice.
 | `gateway` | — | an `@profullstack/x402-gateway`; makes over-limit a 402 |
 | `rules` | `[]` | per-path allowances; most specific match wins |
 | `credential` | `{ limit: 600, ceiling: 1200 }` | budget for callers presenting one |
-| `exempt` | — | never metered, e.g. a signed-in session |
+| `exempt` | — | never metered, e.g. a health check |
+| `credentialFrom` | auth headers | what counts as a credential; read the session cookie too |
 | `openPaths` | — | extra paths never metered |
 | `identify` | the caller's address | what to count against |
 | `store` | per-process | supply one to share a count across a fleet |
@@ -142,6 +143,18 @@ Any auth scheme counts, not just `Bearer` — matching Bearer alone once dropped
 a signed wallet's bulk payout into the anonymous bucket, which it exhausted in
 seconds.
 
+A site whose customers arrive in a browser should count its session cookie as a
+credential, so a signed-in merchant watching a dashboard is not metered as an
+anonymous scraper:
+
+```js
+credentialFrom: (request) =>
+  sessionIdFrom(request) ?? presentedCredential(request.headers),
+```
+
+Prefer that to `exempt`. Exempting sessions outright hands an unmetered site to
+anyone willing to sign up first.
+
 `credential: false` on a rule keeps it address-bucketed however the request is
 authenticated. **The sign-in routes need this**, or a brute-force attempt bolts
 an `Authorization` header onto every guess and buys itself the integration

package/index.d.ts

@@ -48,8 +48,14 @@ export interface ThrottleOptions {
   store?: QuotaStore;
   /** What to count against. Default: the caller's address, as the edge reported it. */
   identify?: (request: Request) => string | null;
-  /** Never metered, e.g. a request carrying a signed-in session cookie. */
+  /** Never metered, e.g. a health check. */
   exempt?: (request: Request) => boolean;
+  /**
+   * What counts as a credential for the larger budget. Default: an
+   * `Authorization` or `X-API-Key` header. Supply one that also reads a
+   * session cookie so signed-in customers are not metered as anonymous.
+   */
+  credentialFrom?: (request: Request) => string | null;
   /** Extra paths never metered. The gateway's sales page is added for you. */
   openPaths?: string[];
   /** Per-path allowances. Most specific match wins, whatever order they are in. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/throttle",
-  "version": "0.1.0",
+  "version": "0.2.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.",
   "keywords": [

package/src/throttle.js

@@ -40,7 +40,8 @@ import { memoryStore } from './store.js';
  * @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
  * @param {(request: Request) => string|null} [options.identify]  what to count against; default the caller's address
- * @param {(request: Request) => boolean} [options.exempt]        never metered, e.g. a signed-in session
+ * @param {(request: Request) => boolean} [options.exempt]        never metered, e.g. a health check
+ * @param {(request: Request) => string|null} [options.credentialFrom]  what counts as a credential; default an Authorization or X-API-Key header
  * @param {string[]} [options.openPaths]            extra paths never metered
  * @param {Array} [options.rules]                   per-path allowances, most specific wins
  * @param {{limit?: number, ceiling?: number}} [options.credential]  budget for callers presenting a credential
@@ -59,6 +60,14 @@ export function createThrottle(options = {}) {
   const rules = compileRules(options.rules, defaults);
   const gateway = options.gateway ?? null;
   const identify = options.identify ?? addressOf;
+  /*
+   * What counts as a credential. The default reads the request's own auth
+   * headers, but a site whose customers arrive in a browser needs its session
+   * cookie to count too: a signed-in merchant watching a dashboard is not a
+   * scraper, and the alternative -- exempting sessions outright -- hands an
+   * unmetered site to anyone willing to sign up first.
+   */
+  const credentialFrom = options.credentialFrom ?? ((request) => presentedCredential(request.headers));
   const exempt = options.exempt ?? null;
   const onThrottle = options.onThrottle ?? null;
 
@@ -179,7 +188,7 @@ export function createThrottle(options = {}) {
      * budget.
      */
     const honoursCredential = Boolean(credential) && rule.credential !== false;
-    const presented = honoursCredential ? presentedCredential(request.headers) : null;
+    const presented = honoursCredential ? credentialFrom(request) : null;
     if (presented) {
       const ceilingRule = { ...rule, limit: rule.credential?.ceiling ?? credential.ceiling };
       const perKeyRule = { ...rule, limit: rule.credential?.limit ?? credential.limit };