@profullstack/throttle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# @profullstack/throttle
+
+An app-wide rate limit whose answer to going over is a price, not a 429.
+
+**100 requests a minute, free. Then `402 Payment Required` with an x402 offer**,
+settled by CoinPay in USDC. It meters *every* route, so a scraper wearing a
+browser user agent is charged like any other crawler.
+
+```bash
+npm i @profullstack/throttle
+```
+
+## Why
+
+Every site in our fleet had a rate limiter in its middleware. Each one was
+hand-rolled, and each one was scoped to `/api/`.
+
+Then a headless browser in Singapore found a block explorer that had shipped
+fifteen hours earlier, and spent two days walking it: **19,000 URLs a day**, a
+fresh visitor id on every hit, a plain `Chrome/145` user agent, every page
+rendered server-side against a metered upstream API.
+
+Nothing stopped it.
+
+- It was not on a crawler list, because it declared nothing.
+- It was not rate limited, because it never touched `/api/`.
+- The analytics counted every hit as a **human visit**.
+
+The limiter we had was protecting the routes nobody was attacking. So: meter
+everything, and when a caller goes over, sell it a pass.
+
+429 is the right answer when you have nothing to sell. We do. The moment the
+allowance runs out is the best sales pitch a site will ever get, because the
+caller has just demonstrated it wants more than the free tier and is still
+holding the request open.
+
+## Use it
+
+```js
+// src/proxy.ts — Next 16 middleware
+import { createGateway } from '@profullstack/x402-gateway';
+import { createThrottle } from '@profullstack/throttle';
+
+const gateway = createGateway({
+  siteUrl: 'https://example.com',
+  coinpay: { apiKey: process.env.COINPAY_X402_KEY },
+  payTo: process.env.CRAWL_PAY_TO,
+});
+
+const throttle = createThrottle({
+  gateway,                       // over the limit → 402 with an offer
+  limit: 100,                    // the default; per caller, per minute
+  exempt: (request) => hasSession(request),
+  rules: [
+    { path: '/api/auth/', limit: 10, credential: false },
+    { path: '/health', open: true },
+  ],
+});
+
+export async function proxy(request) {
+  const answer = await throttle.handle(request);
+  if (answer) return answer;
+  return NextResponse.next();
+}
+```
+
+`handle` returns a `Response` to send, or `null` to carry on. Adapters for
+[Next](#nextjs) and [Hono](#hono) are one line on top of it.
+
+Without a `gateway` the same throttle answers `429` with `Retry-After`. That is
+the fallback, not the goal.
+
+## What a refused caller sees
+
+```
+HTTP/1.1 402 Payment Required
+ratelimit-limit: 100
+ratelimit-remaining: 0
+ratelimit-reset: 41
+```
+```json
+{
+  "x402Version": 2,
+  "accepts": [{ "scheme": "exact", "network": "base", "amount": "1000000", "…": "…" }],
+  "error": "Free allowance used: 100 requests per 60s. It resets in 41s. A pass removes the limit for 1.00 USD a day.",
+  "pass": { "price": "1.00 USD", "minutes": 1440, "buy": "https://example.com/crawl" }
+}
+```
+
+Ask for `text/html` and you get the sales page instead, which is what makes
+this survivable for a person who tripped it by accident.
+
+Pay it, and the pass comes back as the body of a `200`:
+
+```bash
+coinpay x402 pay https://example.com/crawl
+curl -H "x-crawl-pass: $PASS" https://example.com/whatever
+```
+
+A caller holding a live pass is **not metered at all**. The pass is the thing
+being sold; counting it against an allowance it bought its way out of would be
+selling the same minute twice.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `limit` | `100` | requests per window, per caller |
+| `windowSeconds` | `60` | |
+| `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 |
+| `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 |
+| `onThrottle` | — | told about every refusal; its errors are swallowed |
+
+### Rules
+
+A rule is a path pattern plus the numbers that replace the defaults for it.
+Patterns ending in `/` match by prefix, everything else exactly. The most
+specific match wins **whatever order they are written in** — the alternative is
+a config where moving two lines silently removes the brute-force limit.
+
+```js
+rules: [
+  { path: '/api/auth/', limit: 10, credential: false },  // sign-in
+  { path: '/feed/', limit: 30 },
+  { path: '/health', open: true },                       // never metered
+]
+```
+
+### Credentialed callers
+
+One host running an integration is not one browser, so a request presenting a
+credential gets a larger budget. **Both** buckets are charged: the per-address
+`ceiling` is what a caller rotating junk credentials cannot escape, since
+nothing here has authenticated any of them.
+
+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.
+
+`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
+budget.
+
+### Never metered
+
+`/robots.txt`, `/favicon.ico`, `/.well-known/`, and — when a gateway is
+supplied — its sales page and open paths, read off the gateway rather than
+restated. A paywall you cannot reach to pay is a wall.
+
+A caller we cannot identify is also within the allowance. Our own edge failing
+to hand us an address is our gap, and charging someone for it would be charging
+them for our gap.
+
+## Nextjs
+
+```js
+import { throttleProxy } from '@profullstack/throttle/next';
+export const proxy = throttleProxy({ gateway });
+export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+```
+
+Put it **after** the crawl gateway and before everything else: the gateway
+charges crawlers that declare themselves, the throttle charges the ones that do
+not, and there is no point running CORS on a request about to be refused.
+
+Runs at the edge — nothing imports `node:`, and the pass is verified with Web
+Crypto rather than a database.
+
+## Hono
+
+```js
+import { throttle } from '@profullstack/throttle/hono';
+app.use('*', throttle({ gateway }));
+```
+
+## On rotating addresses
+
+Rotating addresses defeats an address bucket. That is not a hole to be plugged,
+it is the argument the 402 makes: residential proxy bandwidth is sold by the
+gigabyte at prices that pass a dollar inside the first day of any serious
+crawl, and a rotation still fetches every page one at a time.
+
+Anyone spending more on proxies than the pass costs, in order to avoid the
+pass, has made an arithmetic mistake rather than beaten a detector. Detection
+is a race. Price is not.
+
+## Counting
+
+The default counter lives in the process, so several instances each grant their
+own allowance. That errs toward generosity, which is the right direction to be
+wrong in for a free tier. Pass a `store` to share one count across a fleet — the
+interface is a single method, so Redis or Postgres is a dozen lines:
+
+```js
+{ hit(key, windowSeconds) { return { count, resetSeconds } } }
+```
+
+## License
+
+MIT © Profullstack, LLC

package/index.d.ts

@@ -0,0 +1,93 @@
+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;
+export const ALWAYS_OPEN: string[];
+
+export interface ThrottleRule {
+  /** Prefix when it ends in `/`, exact match otherwise. */
+  path: string;
+  /** Requests per window on this rule. Inherits the default when absent. */
+  limit?: number;
+  windowSeconds?: number;
+  /** Never metered. */
+  open?: boolean;
+  /**
+   * Credentials on this rule. `false` keeps it address-bucketed however the
+   * request is authenticated — what the sign-in routes need.
+   */
+  credential?: false | { limit?: number; ceiling?: number };
+}
+
+export interface CredentialBudget {
+  /** Per credential. Default 600. */
+  limit?: number;
+  /** Per address, whatever credentials it rotates through. Default 1200. */
+  ceiling?: number;
+}
+
+export interface ThrottleEvent {
+  url: string;
+  userAgent: string | null;
+  limit: number;
+  windowSeconds: number;
+  count: number;
+  /** Whether the refusal came with something to buy. */
+  sold: boolean;
+}
+
+export interface ThrottleOptions {
+  /** Default 100. */
+  limit?: number;
+  /** Default 60. */
+  windowSeconds?: 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. */
+  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. */
+  exempt?: (request: Request) => boolean;
+  /** 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. */
+  rules?: ThrottleRule[];
+  /** Budget for callers presenting a credential. `false` to treat them as anonymous. */
+  credential?: false | CredentialBudget;
+  /** Told about every refusal. Its errors are swallowed. */
+  onThrottle?: (event: ThrottleEvent) => void | Promise<void>;
+}
+
+export interface Throttle {
+  /** A Response to send, or null to let the request through. */
+  handle: (request: Request) => Promise<Response | null>;
+  store: QuotaStore;
+  options: {
+    limit: number;
+    windowSeconds: number;
+    rules: Required<ThrottleRule>[];
+    credential: { limit: number; ceiling: number } | null;
+    openPaths: string[];
+    gateway: boolean;
+  };
+}
+
+export function createThrottle(options?: ThrottleOptions): Throttle;
+
+export function memoryStore(options?: {
+  now?: () => number;
+  sweepEvery?: number;
+}): QuotaStore & { sweep(): void; readonly size: number };
+
+export function fingerprint(value: string): string;
+export function presentedCredential(headers: Headers): string | null;
+export function addressOf(request: Request): string | null;
+export function matches(pattern: string, path: string): boolean;
+export function matchesAny(patterns: string[], path: string): boolean;
+export function compileRules(
+  rules: ThrottleRule[],
+  defaults: { limit: number; windowSeconds: number },
+): Required<ThrottleRule>[];
+export function ruleFor<T>(compiled: Required<ThrottleRule>[], path: string, defaults: T): T;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@profullstack/throttle",
+  "version": "0.1.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": [
+    "rate-limit",
+    "throttle",
+    "x402",
+    "402",
+    "payment-required",
+    "scraping",
+    "anti-scraping",
+    "crawler",
+    "nextjs",
+    "hono",
+    "middleware",
+    "coinpay",
+    "usdc"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/throttle.git"
+  },
+  "homepage": "https://github.com/profullstack/throttle#readme",
+  "bugs": {
+    "url": "https://github.com/profullstack/throttle/issues"
+  },
+  "license": "MIT",
+  "author": "Profullstack, LLC",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./next": {
+      "types": "./index.d.ts",
+      "import": "./src/next.js"
+    },
+    "./hono": {
+      "types": "./index.d.ts",
+      "import": "./src/hono.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@profullstack/x402-gateway": "^0.5.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/hono.js

@@ -0,0 +1,22 @@
+import { createThrottle } from './throttle.js';
+
+/**
+ * The throttle as Hono middleware.
+ *
+ *   import { throttle } from '@profullstack/throttle/hono';
+ *   app.use('*', throttle({ gateway }));
+ *
+ * Register it before the routes and after the crawl gateway, so a crawler that
+ * declares itself is charged by its own list rather than metered first.
+ */
+export function throttle(throttleOrOptions) {
+  const t =
+    throttleOrOptions && typeof throttleOrOptions.handle === 'function'
+      ? throttleOrOptions
+      : createThrottle(throttleOrOptions);
+  return async (c, next) => {
+    const answer = await t.handle(c.req.raw);
+    if (answer) return answer;
+    await next();
+  };
+}

package/src/identify.js

@@ -0,0 +1,57 @@
+/**
+ * Who a request is counted as.
+ *
+ * The address, by default. The gateway's `clientIp` is what reads it, because
+ * it already knows to take the edge's own hop rather than whatever the client
+ * put in `X-Forwarded-For` -- a header the client writes, and which a scraper
+ * will happily fill with a fresh address per request if we let it decide.
+ *
+ * ON ROTATION. Rotating addresses defeats an address bucket. That is not a
+ * hole to be plugged, it is the argument the 402 makes: residential proxy
+ * bandwidth is sold by the gigabyte, and a rotation still fetches every page
+ * one at a time. Anyone spending more on proxies than the pass costs, to avoid
+ * the pass, has made an arithmetic mistake rather than beaten a detector.
+ * Detection is a race; price is not.
+ */
+
+import { clientIp } from '@profullstack/x402-gateway';
+
+/**
+ * FNV-1a. A credential must never become a map key we might log or dump, and
+ * the counter only ever needs to know that two requests carried the same one.
+ */
+export function fingerprint(value) {
+  let hash = 0x811c9dc5;
+  const text = String(value);
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+/**
+ * The credential a request presents, unverified.
+ *
+ * Unverified on purpose: this layer decides how much budget a caller gets, and
+ * the route handler is what actually authenticates. Any auth scheme counts,
+ * not just Bearer -- the CoinPay wallet extension signs with
+ * `Authorization: Wallet <id>:<sig>:<ts>`, and matching Bearer alone dropped a
+ * bulk payout into the anonymous per-address bucket, which it exhausted in
+ * seconds.
+ */
+export function presentedCredential(headers) {
+  const authorization = headers.get('authorization');
+  if (authorization) {
+    const match = /^(\S+)\s+(\S+)/.exec(authorization.trim());
+    if (match) return match[2];
+  }
+  const apiKey = headers.get('x-api-key')?.trim();
+  return apiKey ? apiKey : null;
+}
+
+/** The address bucket for a request, or null when the edge gave us nothing. */
+export function addressOf(request) {
+  const ip = clientIp(request);
+  return ip ? String(ip) : null;
+}

package/src/index.js

@@ -0,0 +1,12 @@
+export { createThrottle } from './throttle.js';
+export { memoryStore } from './store.js';
+export { addressOf, fingerprint, presentedCredential } from './identify.js';
+export {
+  ALWAYS_OPEN,
+  DEFAULT_LIMIT,
+  DEFAULT_WINDOW_SECONDS,
+  compileRules,
+  matches,
+  matchesAny,
+  ruleFor,
+} from './rules.js';

package/src/next.js

@@ -0,0 +1,29 @@
+import { createThrottle } from './throttle.js';
+
+/**
+ * The throttle for Next.js, in `proxy.ts` (Next 16) or `middleware.ts`.
+ *
+ *   import { throttleProxy } from '@profullstack/throttle/next';
+ *   export const proxy = throttleProxy({ gateway });
+ *
+ * Returning `undefined` means "carry on", which is what the throttle's null
+ * becomes. Most apps already have a proxy doing CORS and security headers, so
+ * compose instead:
+ *
+ *   const answer = await throttle.handle(request);
+ *   if (answer) return answer;
+ *
+ * Put it after the crawl gateway and before everything else. The gateway
+ * charges crawlers that declare themselves; the throttle charges the ones that
+ * do not, and there is no point running CORS on a request about to be refused.
+ *
+ * Runs at the edge: nothing here imports node:, and the pass is verified with
+ * Web Crypto rather than a database.
+ */
+export function throttleProxy(throttleOrOptions) {
+  const throttle =
+    throttleOrOptions && typeof throttleOrOptions.handle === 'function'
+      ? throttleOrOptions
+      : createThrottle(throttleOrOptions);
+  return async (request) => (await throttle.handle(request)) ?? undefined;
+}

package/src/rules.js

@@ -0,0 +1,82 @@
+/**
+ * Which allowance applies to a request.
+ *
+ * A site does not have one rate limit, it has a few. Signing in has to be
+ * tighter than reading, because ten guesses a minute is a brute-force budget
+ * and a hundred is a giveaway. A server-to-server integration has to be looser
+ * than a browser, because one host legitimately sends a burst that would look
+ * like abuse from a person. Everything else -- every page, every feed, every
+ * lookup -- shares one default, and that default is the whole point of this
+ * package: it meters routes nobody thought to protect, which is where the
+ * scrapers actually are.
+ */
+
+/** The house default: a hundred requests a minute, per caller, everywhere. */
+export const DEFAULT_LIMIT = 100;
+export const DEFAULT_WINDOW_SECONDS = 60;
+
+/**
+ * Paths that are never metered, whatever the rules say.
+ *
+ * A refused caller has to be able to read the terms and buy its way out, or
+ * the 402 is a dead end: the sales page, robots.txt and the well-known paths
+ * are how a crawler complies. The gateway already knows which those are, so
+ * when one is supplied they are read off it rather than restated here.
+ */
+export const ALWAYS_OPEN = ['/robots.txt', '/favicon.ico', '/.well-known/'];
+
+const trim = (path) => String(path ?? '').trim();
+
+/** Prefix when it ends in `/`, exact match otherwise -- the gateway's rule. */
+export function matches(pattern, path) {
+  const p = trim(pattern);
+  if (!p) return false;
+  return p.endsWith('/') ? path.startsWith(p) : path === p;
+}
+
+export function matchesAny(patterns, path) {
+  return patterns.some((p) => matches(p, path));
+}
+
+/**
+ * Normalise one rule. A rule is a path pattern plus the numbers that replace
+ * the defaults for it; anything it leaves out it inherits, so `{ path:
+ * '/api/auth/', limit: 10 }` is a complete rule.
+ */
+function normaliseRule(rule, defaults) {
+  const limit = Number(rule?.limit);
+  const windowSeconds = Number(rule?.windowSeconds);
+  return {
+    path: trim(rule?.path),
+    limit: Number.isFinite(limit) && limit >= 1 ? Math.floor(limit) : defaults.limit,
+    windowSeconds:
+      Number.isFinite(windowSeconds) && windowSeconds > 0
+        ? Math.floor(windowSeconds)
+        : defaults.windowSeconds,
+    /**
+     * A rule can opt out of metering entirely (`{ path: '/health', open: true }`),
+     * which is how an app exempts a route without having to restate the whole
+     * skip list.
+     */
+    open: Boolean(rule?.open),
+    /** Credentialed callers on this rule, if it wants different numbers. */
+    credential: rule?.credential ?? null,
+  };
+}
+
+/**
+ * Compile the rule list. Longest pattern first, so `/api/auth/` is consulted
+ * before `/api/` however the site happened to order them -- the alternative is
+ * a config where moving two lines silently removes the brute-force limit.
+ */
+export function compileRules(rules = [], defaults) {
+  return rules
+    .filter((rule) => trim(rule?.path))
+    .map((rule) => normaliseRule(rule, defaults))
+    .sort((a, b) => b.path.length - a.path.length);
+}
+
+/** The rule for a path: the most specific match, or the default allowance. */
+export function ruleFor(compiled, path, defaults) {
+  return compiled.find((rule) => matches(rule.path, path)) ?? defaults;
+}

package/src/store.js

@@ -0,0 +1,13 @@
+/**
+ * Where the counts live.
+ *
+ * The default counts in this process, which means several instances each grant
+ * their own allowance. That errs toward generosity, which is the right
+ * direction to be wrong in for a free tier -- and a site that wants one shared
+ * count across a fleet passes a store of its own. The interface is a single
+ * method, so Redis, Postgres or Cloudflare KV is a dozen lines.
+ *
+ *   { hit(key, windowSeconds): { count, resetSeconds } }
+ */
+
+export { memoryQuotaStore as memoryStore } from '@profullstack/x402-gateway';

package/src/throttle.js

@@ -0,0 +1,213 @@
+/**
+ * An app-wide rate limit whose answer to going over is a price.
+ *
+ * WHY THIS EXISTS. Every site in the fleet had a rate limiter in its
+ * middleware, each one hand-rolled, each one scoped to `/api/`. Then a
+ * headless browser in Singapore found a newly shipped block explorer and spent
+ * two days walking it: 19,000 URLs a day, one fresh visitor id per hit, a
+ * plain `Chrome/145` user agent, every page rendered server-side against a
+ * paid upstream API. Nothing stopped it. It was not on a crawler list, because
+ * it declared nothing; it was not rate limited, because it never touched
+ * `/api/`; and the analytics counted every hit as a human visit. The limiter
+ * we had protected the routes nobody was attacking.
+ *
+ * So: meter everything, and when a caller goes over, sell it a pass. 429 is
+ * the right answer when you have nothing to sell. We do. The moment the
+ * allowance runs out is the best sales pitch the site will ever get, because
+ * 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.
+ */
+
+import { quotaHeaders, spend } from '@profullstack/x402-gateway';
+import { addressOf, fingerprint, presentedCredential } from './identify.js';
+import {
+  ALWAYS_OPEN,
+  DEFAULT_LIMIT,
+  DEFAULT_WINDOW_SECONDS,
+  compileRules,
+  matchesAny,
+  ruleFor,
+} from './rules.js';
+import { memoryStore } from './store.js';
+
+/**
+ * @param {object} options
+ * @param {number} [options.limit=100]              requests per window, per caller
+ * @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
+ * @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 {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
+ * @param {(event: object) => void|Promise<void>} [options.onThrottle]  told about every refusal; its errors are swallowed
+ */
+export function createThrottle(options = {}) {
+  const defaults = {
+    path: '',
+    limit: positive(options.limit, DEFAULT_LIMIT),
+    windowSeconds: positive(options.windowSeconds, DEFAULT_WINDOW_SECONDS),
+    open: false,
+    credential: null,
+  };
+
+  const store = options.store?.hit ? options.store : memoryStore();
+  const rules = compileRules(options.rules, defaults);
+  const gateway = options.gateway ?? null;
+  const identify = options.identify ?? addressOf;
+  const exempt = options.exempt ?? null;
+  const onThrottle = options.onThrottle ?? null;
+
+  /**
+   * A credentialed caller gets its own, larger budget -- one host running an
+   * integration is not one browser. Both buckets are charged: the per-address
+   * ceiling is what a caller rotating junk credentials cannot escape, since
+   * 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),
+  };
+
+  /*
+   * The paths a refused caller must still be able to read. Taken off the
+   * gateway when there is one, so the sales page it points at in the 402 is
+   * never itself throttled -- a paywall you cannot reach to pay is a wall.
+   */
+  const openPaths = [
+    ...ALWAYS_OPEN,
+    ...(gateway ? [gateway.options.path, ...(gateway.options.openPaths ?? [])] : []),
+    ...(options.openPaths ?? []),
+  ];
+
+  const quotaFor = (rule) => ({
+    requests: rule.limit,
+    windowSeconds: rule.windowSeconds,
+    store,
+  });
+
+  /** 429, for a site with nothing to sell. */
+  const tooMany = (rule, usage) => {
+    const headers = {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+      'retry-after': String(usage.resetSeconds),
+      ...quotaHeaders(quotaFor(rule), usage),
+    };
+    return new Response(
+      JSON.stringify(
+        {
+          error: 'Too many requests',
+          limit: rule.limit,
+          windowSeconds: rule.windowSeconds,
+          retryAfter: usage.resetSeconds,
+        },
+        null,
+        2,
+      ),
+      { status: 429, headers },
+    );
+  };
+
+  /**
+   * What a caller over the limit is answered with. A gateway that can take
+   * money answers 402 with an offer -- or the sales page, if the caller asked
+   * for HTML, which is what makes this survivable for a person who tripped it
+   * by accident. Without one there is nothing to sell, so 429.
+   */
+  async function refuse(request, rule, usage) {
+    if (onThrottle) {
+      try {
+        await onThrottle({
+          url: request.url,
+          userAgent: request.headers.get('user-agent') ?? null,
+          limit: rule.limit,
+          windowSeconds: rule.windowSeconds,
+          count: usage.count,
+          sold: Boolean(gateway?.enabled),
+        });
+      } catch {
+        // Telling someone must never cost the caller its answer.
+      }
+    }
+    if (!gateway) return tooMany(rule, usage);
+    return gateway.sell(request, {
+      usage,
+      quota: { requests: rule.limit, windowSeconds: rule.windowSeconds },
+    });
+  }
+
+  /**
+   * The throttle. Null means "not for me, carry on".
+   */
+  async function handle(request) {
+    const path = new URL(request.url).pathname;
+
+    if (matchesAny(openPaths, path)) return null;
+    if (exempt && exempt(request)) return null;
+
+    const rule = ruleFor(rules, path, defaults);
+    if (rule.open) return null;
+
+    /*
+     * Whoever already paid is not metered. The pass is the thing being sold;
+     * charging a caller that holds one, or counting it toward an allowance it
+     * bought its way out of, is selling the same minute twice.
+     */
+    if (gateway) {
+      const token = gateway.passFrom(request);
+      if (token && (await gateway.verifyPass(token))) return null;
+    }
+
+    const key = identify(request);
+    /*
+     * A caller we cannot identify is within the allowance. Our own edge
+     * failing to hand us an address is our gap, and charging someone for it
+     * would be charging them for our gap.
+     */
+    if (!key) return null;
+
+    /*
+     * A rule can refuse to honour credentials at all (`credential: false`),
+     * and the sign-in routes must: auth endpoints stay address-bucketed
+     * whatever headers accompany them, or a brute-force attempt would bolt an
+     * Authorization header onto every guess and buy itself the integration
+     * budget.
+     */
+    const honoursCredential = Boolean(credential) && rule.credential !== false;
+    const presented = honoursCredential ? presentedCredential(request.headers) : null;
+    if (presented) {
+      const ceilingRule = { ...rule, limit: rule.credential?.ceiling ?? credential.ceiling };
+      const perKeyRule = { ...rule, limit: rule.credential?.limit ?? credential.limit };
+      const ceiling = await spend(quotaFor(ceilingRule), `ceiling:${key}`);
+      const perKey = await spend(quotaFor(perKeyRule), `cred:${fingerprint(presented)}`);
+      /*
+       * The host ceiling is what a credential-rotating caller cannot escape,
+       * so a denial there beats a healthy per-credential budget.
+       */
+      if (ceiling?.overLimit) return refuse(request, ceilingRule, ceiling);
+      if (perKey?.overLimit) return refuse(request, perKeyRule, perKey);
+      return null;
+    }
+
+    const usage = await spend(quotaFor(rule), `${rule.path || '*'}:${key}`);
+    if (usage?.overLimit) return refuse(request, rule, usage);
+    return null;
+  }
+
+  return {
+    handle,
+    /** For tests and for a site that wants to reclaim memory on demand. */
+    store,
+    options: { ...defaults, rules, credential, openPaths, gateway: Boolean(gateway) },
+  };
+}
+
+function positive(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+}