@aooth/auth 0.1.33 → 0.1.34

package/dist/index.cjs

@@ -951,6 +951,190 @@ var AuthCredential = class {
 	}
 };
 //#endregion
+//#region src/rate-limit/rules.ts
+const DEFAULT_RATE_LIMIT_MESSAGE = "Too many requests. Please try again in {{delta}}.";
+const DURATION_UNITS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+/** `'5m'` / `'90s'` / `'500ms'` / `'1h'` / `'2d'` → ms. Throws on anything else. */
+function parseDurationMs(input) {
+	const m = /^(\d+)(ms|s|m|h|d)$/.exec(input.trim());
+	if (!m) throw new Error(`Invalid rate-limit window "${input}" — expected "<int><unit>" with unit ms|s|m|h|d (e.g. "5m")`);
+	return Number(m[1]) * DURATION_UNITS[m[2]];
+}
+/**
+* Humanize a ms duration for `{{window}}` / `{{delta}}` placeholders:
+* `"5 minutes"`, `"4 minutes 32 seconds"`, `"1 hour"`. Sub-second values
+* round UP to `"1 second"` — a retry hint of "0 seconds" reads as broken.
+* At most the two largest units are shown.
+*/
+function formatDurationMs(ms) {
+	const totalSeconds = Math.max(1, Math.ceil(ms / 1e3));
+	const units = [
+		["day", 86400],
+		["hour", 3600],
+		["minute", 60],
+		["second", 1]
+	];
+	const parts = [];
+	let rest = totalSeconds;
+	for (const [name, size] of units) {
+		if (parts.length === 2) break;
+		const n = Math.floor(rest / size);
+		if (n === 0) continue;
+		rest -= n * size;
+		parts.push(`${n} ${name}${n === 1 ? "" : "s"}`);
+	}
+	return parts.join(" ");
+}
+function parseRuleString(input) {
+	const pipe = input.indexOf("|");
+	const message = pipe >= 0 ? input.slice(pipe + 1).trim() : void 0;
+	const head = (pipe >= 0 ? input.slice(0, pipe) : input).trim();
+	const m = /^(\d+)\s*(?:\/|\s+per\s+)\s*(\d+(?:ms|s|m|h|d))$/i.exec(head);
+	if (!m) throw new Error(`Invalid rate-limit rule "${input}" — expected "<limit>/<window>" or "<limit> per <window>" (e.g. "6/5m", "30 per 1m"), optionally followed by " | <message>"`);
+	return {
+		limit: Number(m[1]),
+		window: parseDurationMs(m[2]),
+		...message !== void 0 && message !== "" && { message }
+	};
+}
+function assertValidRule(rule) {
+	if (!Number.isInteger(rule.limit) || rule.limit <= 0) throw new Error(`Invalid rate-limit rule: limit must be a positive integer (got ${rule.limit})`);
+	if (!Number.isFinite(rule.window) || rule.window <= 0) throw new Error(`Invalid rate-limit rule: window must be a positive ms value (got ${rule.window})`);
+}
+/** Normalize any {@link RateLimitRuleInput}. Throws on invalid grammar or non-positive values. */
+function parseRateLimitRule(input) {
+	if (typeof input !== "string" && typeof input.window === "number") {
+		assertValidRule(input);
+		return input;
+	}
+	const rule = typeof input === "string" ? parseRuleString(input) : {
+		limit: input.limit,
+		window: parseDurationMs(input.window),
+		...input.message !== void 0 && { message: input.message }
+	};
+	assertValidRule(rule);
+	return rule;
+}
+/**
+* Render a 429 message template. Placeholders: `{{limit}}` (alias `{{max}}`),
+* `{{window}}` and `{{delta}}` — both humanized via {@link formatDurationMs}.
+*/
+function renderRateLimitMessage(template, rule, retryAfterMs) {
+	return template.replaceAll("{{limit}}", String(rule.limit)).replaceAll("{{max}}", String(rule.limit)).replaceAll("{{window}}", formatDurationMs(rule.window)).replaceAll("{{delta}}", formatDurationMs(retryAfterMs));
+}
+//#endregion
+//#region src/rate-limit/store.ts
+/**
+* In-memory `RateLimitStore` — the zero-config default (single process only).
+* Lazy-evicts expired counters on access; `cleanup()` sweeps the whole map for
+* periodic compaction in long-lived processes (same pattern as
+* `DenylistStoreMemory`).
+*/
+var RateLimitStoreMemory = class {
+	entries = /* @__PURE__ */ new Map();
+	clock;
+	constructor(opts) {
+		this.clock = opts?.clock ?? require_clock.defaultClock;
+	}
+	async hit(key, ttlMs) {
+		const now = this.clock.now();
+		const entry = this.entries.get(key);
+		if (!entry || entry.expiresAt <= now) {
+			this.entries.set(key, {
+				count: 1,
+				expiresAt: now + ttlMs
+			});
+			return 1;
+		}
+		entry.count += 1;
+		return entry.count;
+	}
+	async reset(key) {
+		this.entries.delete(key);
+	}
+	/** Drop every counter — test-harness reset between cases. */
+	clear() {
+		this.entries.clear();
+	}
+	async cleanup() {
+		const now = this.clock.now();
+		let removed = 0;
+		for (const [key, entry] of this.entries) if (entry.expiresAt <= now) {
+			this.entries.delete(key);
+			removed++;
+		}
+		return removed;
+	}
+};
+//#endregion
+//#region src/rate-limit/rate-limiter.ts
+/**
+* Fixed-window rate limiter with window-aligned keys (RL.spec.md §4.2).
+*
+* For each rule the current window starts at `floor(now / window) * window`;
+* the counter key embeds that start, so a new window is automatically a new
+* key and one atomic store increment decides. All rules are hit on every
+* check (rejected requests count too — they cannot extend a fixed window).
+*/
+var RateLimiter = class {
+	store;
+	clock;
+	constructor(opts) {
+		this.store = opts?.store ?? new RateLimitStoreMemory({ clock: opts?.clock });
+		this.clock = opts?.clock ?? require_clock.defaultClock;
+	}
+	/**
+	* Evaluate `rules` for `scope` (handler/bucket id) + `subject` (caller
+	* identity). Store keys are `<scope>:<subject>:<ruleIndex>:<windowStart>`
+	* with scope/subject each URI-encoded — raw components would collide
+	* (IPv6 addresses, route paths, and custom subjects all contain `:`).
+	*
+	* When several rules are violated at once, the governing rule is the one
+	* whose window frees capacity LAST — the request only becomes allowed once
+	* every rule passes, so a shorter hint would invite guaranteed-rejected
+	* retries.
+	*/
+	async check(scope, subject, rules, opts) {
+		if (rules.length === 0) throw new Error("RateLimiter.check: at least one rule is required");
+		const parsed = rules.map((r) => parseRateLimitRule(r));
+		const now = this.clock.now();
+		const keyBase = `${encodeURIComponent(scope)}:${encodeURIComponent(subject)}`;
+		const evaluated = await Promise.all(parsed.map(async (rule, i) => {
+			const windowStart = Math.floor(now / rule.window) * rule.window;
+			const key = `${keyBase}:${i}:${windowStart}`;
+			const count = await this.store.hit(key, rule.window * 2);
+			return {
+				rule,
+				remaining: Math.max(0, rule.limit - count),
+				resetAt: windowStart + rule.window,
+				violated: count > rule.limit
+			};
+		}));
+		const violated = evaluated.filter((e) => e.violated);
+		const rejected = violated.length > 0;
+		const governing = rejected ? violated.reduce((a, b) => b.resetAt > a.resetAt ? b : a) : evaluated.reduce((a, b) => b.remaining < a.remaining ? b : a);
+		const resetAfterMs = governing.resetAt - now;
+		return {
+			allowed: !rejected,
+			limit: governing.rule.limit,
+			remaining: governing.remaining,
+			resetAt: governing.resetAt,
+			resetAfterMs,
+			policies: parsed,
+			...rejected && {
+				retryAfterMs: resetAfterMs,
+				message: renderRateLimitMessage(governing.rule.message ?? opts?.defaultMessage ?? "Too many requests. Please try again in {{delta}}.", governing.rule, resetAfterMs)
+			}
+		};
+	}
+};
+//#endregion
 //#region src/magic-link.ts
 /**
 * 32 bytes of CSPRNG entropy (256 bits) encoded as base64url — 43 chars,
@@ -965,6 +1149,13 @@ exports.AuthError = AuthError;
 exports.CredentialStoreEncapsulated = CredentialStoreEncapsulated;
 exports.CredentialStoreJwt = CredentialStoreJwt;
 exports.CredentialStoreMemory = CredentialStoreMemory;
+exports.DEFAULT_RATE_LIMIT_MESSAGE = DEFAULT_RATE_LIMIT_MESSAGE;
 exports.DenylistStoreMemory = DenylistStoreMemory;
+exports.RateLimitStoreMemory = RateLimitStoreMemory;
+exports.RateLimiter = RateLimiter;
 exports.defaultClock = require_clock.defaultClock;
+exports.formatDurationMs = formatDurationMs;
 exports.generateMagicLinkToken = generateMagicLinkToken;
+exports.parseDurationMs = parseDurationMs;
+exports.parseRateLimitRule = parseRateLimitRule;
+exports.renderRateLimitMessage = renderRateLimitMessage;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { a as CredentialState, c as RefreshConfig, i as CredentialMetadata, l as SessionEnricher, n as DenylistStore, o as EnrichedSession, r as AuthContext, s as IssueResult, t as CredentialStore, u as SessionInfo } from "./store-BG6m6oSJ.cjs";
 import { n as defaultClock, t as Clock } from "./clock-BjXa0LXb.cjs";
+import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-N9daSmHS.cjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts
@@ -414,6 +415,111 @@ declare class AuthCredential<TPayload extends object = object> {
   private respondToRefreshReuse;
 }
 //#endregion
+//#region src/rate-limit/rules.d.ts
+/**
+ * Rate-limit rule model + the compact string grammar (RL.spec.md §4.1).
+ *
+ * Input rules and normalized rules are distinct types: inputs accept the
+ * ergonomic forms (`'6/5m | message'`, `{ limit, window: '5m' }`),
+ * `parseRateLimitRule` normalizes everything to ms. Parsing happens eagerly
+ * (decoration/config time), so a bad rule string fails at boot, not per
+ * request.
+ */
+/** Normalized rule — `window` always in ms. */
+interface RateLimitRule {
+  /** Max hits per window. */
+  limit: number;
+  /** Window length, ms. */
+  window: number;
+  /** 429 message template for THIS rule (see {@link renderRateLimitMessage}). */
+  message?: string;
+}
+/**
+ * What decorators / options accept:
+ *  - `'<limit>/<window>'`            — `'6/5m'`
+ *  - `'<limit> per <window>'`        — `'6 per 5m'`
+ *  - either form + `' | <message>'`  — `'6/5m | Wait {{delta}}'`
+ *  - `{ limit, window, message? }`   — `window` in ms or `'5m'` form
+ */
+type RateLimitRuleInput = string | {
+  limit: number;
+  window: number | string;
+  message?: string;
+};
+declare const DEFAULT_RATE_LIMIT_MESSAGE = "Too many requests. Please try again in {{delta}}.";
+/** `'5m'` / `'90s'` / `'500ms'` / `'1h'` / `'2d'` → ms. Throws on anything else. */
+declare function parseDurationMs(input: string): number;
+/**
+ * Humanize a ms duration for `{{window}}` / `{{delta}}` placeholders:
+ * `"5 minutes"`, `"4 minutes 32 seconds"`, `"1 hour"`. Sub-second values
+ * round UP to `"1 second"` — a retry hint of "0 seconds" reads as broken.
+ * At most the two largest units are shown.
+ */
+declare function formatDurationMs(ms: number): string;
+/** Normalize any {@link RateLimitRuleInput}. Throws on invalid grammar or non-positive values. */
+declare function parseRateLimitRule(input: RateLimitRuleInput): RateLimitRule;
+/**
+ * Render a 429 message template. Placeholders: `{{limit}}` (alias `{{max}}`),
+ * `{{window}}` and `{{delta}}` — both humanized via {@link formatDurationMs}.
+ */
+declare function renderRateLimitMessage(template: string, rule: RateLimitRule, retryAfterMs: number): string;
+//#endregion
+//#region src/rate-limit/rate-limiter.d.ts
+interface RateLimiterOptions {
+  /** Counter storage. Default: a fresh `RateLimitStoreMemory` (single process only). */
+  store?: RateLimitStore;
+  /** Injectable time source for deterministic tests. */
+  clock?: Clock;
+}
+/** The outcome of one `check()` — everything a transport needs for headers + 429. */
+interface RateLimitDecision {
+  allowed: boolean;
+  /** Limit of the governing rule (the violated one, else the lowest-remaining one). */
+  limit: number;
+  remaining: number;
+  /** ms epoch when the governing window resets. */
+  resetAt: number;
+  /**
+   * ms until the governing window resets, measured with the limiter's own
+   * clock — transports derive the `RateLimit-Reset` header from this instead
+   * of re-subtracting `Date.now()` (which would drift under injected clocks).
+   */
+  resetAfterMs: number;
+  /** Present when `!allowed`: ms until the governing window frees capacity. */
+  retryAfterMs?: number;
+  /** Present when `!allowed`: rendered from the violated rule's message template. */
+  message?: string;
+  /** Every evaluated rule (for the `RateLimit-Policy` header). */
+  policies: RateLimitRule[];
+}
+/**
+ * Fixed-window rate limiter with window-aligned keys (RL.spec.md §4.2).
+ *
+ * For each rule the current window starts at `floor(now / window) * window`;
+ * the counter key embeds that start, so a new window is automatically a new
+ * key and one atomic store increment decides. All rules are hit on every
+ * check (rejected requests count too — they cannot extend a fixed window).
+ */
+declare class RateLimiter {
+  private readonly store;
+  private readonly clock;
+  constructor(opts?: RateLimiterOptions);
+  /**
+   * Evaluate `rules` for `scope` (handler/bucket id) + `subject` (caller
+   * identity). Store keys are `<scope>:<subject>:<ruleIndex>:<windowStart>`
+   * with scope/subject each URI-encoded — raw components would collide
+   * (IPv6 addresses, route paths, and custom subjects all contain `:`).
+   *
+   * When several rules are violated at once, the governing rule is the one
+   * whose window frees capacity LAST — the request only becomes allowed once
+   * every rule passes, so a shorter hint would invite guaranteed-rejected
+   * retries.
+   */
+  check(scope: string, subject: string, rules: RateLimitRuleInput[], opts?: {
+    defaultMessage?: string;
+  }): Promise<RateLimitDecision>;
+}
+//#endregion
 //#region src/email.d.ts
 /**
  * Discriminator for auth-related email events emitted by the workflow stack.
@@ -515,4 +621,4 @@ type BuildMagicLinkUrl = (kind: AuthEmailKind, token: string, ctx?: {
  */
 declare function generateMagicLinkToken(): string;
 //#endregion
-export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, generateMagicLinkToken };
+export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, DEFAULT_RATE_LIMIT_MESSAGE, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RateLimitDecision, type RateLimitRule, type RateLimitRuleInput, type RateLimitStore, RateLimitStoreMemory, RateLimiter, type RateLimiterOptions, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, formatDurationMs, generateMagicLinkToken, parseDurationMs, parseRateLimitRule, renderRateLimitMessage };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { a as CredentialState, c as RefreshConfig, i as CredentialMetadata, l as SessionEnricher, n as DenylistStore, o as EnrichedSession, r as AuthContext, s as IssueResult, t as CredentialStore, u as SessionInfo } from "./store-BG6m6oSJ.mjs";
 import { n as defaultClock, t as Clock } from "./clock-BjXa0LXb.mjs";
+import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-jFgby4bK.mjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts
@@ -414,6 +415,111 @@ declare class AuthCredential<TPayload extends object = object> {
   private respondToRefreshReuse;
 }
 //#endregion
+//#region src/rate-limit/rules.d.ts
+/**
+ * Rate-limit rule model + the compact string grammar (RL.spec.md §4.1).
+ *
+ * Input rules and normalized rules are distinct types: inputs accept the
+ * ergonomic forms (`'6/5m | message'`, `{ limit, window: '5m' }`),
+ * `parseRateLimitRule` normalizes everything to ms. Parsing happens eagerly
+ * (decoration/config time), so a bad rule string fails at boot, not per
+ * request.
+ */
+/** Normalized rule — `window` always in ms. */
+interface RateLimitRule {
+  /** Max hits per window. */
+  limit: number;
+  /** Window length, ms. */
+  window: number;
+  /** 429 message template for THIS rule (see {@link renderRateLimitMessage}). */
+  message?: string;
+}
+/**
+ * What decorators / options accept:
+ *  - `'<limit>/<window>'`            — `'6/5m'`
+ *  - `'<limit> per <window>'`        — `'6 per 5m'`
+ *  - either form + `' | <message>'`  — `'6/5m | Wait {{delta}}'`
+ *  - `{ limit, window, message? }`   — `window` in ms or `'5m'` form
+ */
+type RateLimitRuleInput = string | {
+  limit: number;
+  window: number | string;
+  message?: string;
+};
+declare const DEFAULT_RATE_LIMIT_MESSAGE = "Too many requests. Please try again in {{delta}}.";
+/** `'5m'` / `'90s'` / `'500ms'` / `'1h'` / `'2d'` → ms. Throws on anything else. */
+declare function parseDurationMs(input: string): number;
+/**
+ * Humanize a ms duration for `{{window}}` / `{{delta}}` placeholders:
+ * `"5 minutes"`, `"4 minutes 32 seconds"`, `"1 hour"`. Sub-second values
+ * round UP to `"1 second"` — a retry hint of "0 seconds" reads as broken.
+ * At most the two largest units are shown.
+ */
+declare function formatDurationMs(ms: number): string;
+/** Normalize any {@link RateLimitRuleInput}. Throws on invalid grammar or non-positive values. */
+declare function parseRateLimitRule(input: RateLimitRuleInput): RateLimitRule;
+/**
+ * Render a 429 message template. Placeholders: `{{limit}}` (alias `{{max}}`),
+ * `{{window}}` and `{{delta}}` — both humanized via {@link formatDurationMs}.
+ */
+declare function renderRateLimitMessage(template: string, rule: RateLimitRule, retryAfterMs: number): string;
+//#endregion
+//#region src/rate-limit/rate-limiter.d.ts
+interface RateLimiterOptions {
+  /** Counter storage. Default: a fresh `RateLimitStoreMemory` (single process only). */
+  store?: RateLimitStore;
+  /** Injectable time source for deterministic tests. */
+  clock?: Clock;
+}
+/** The outcome of one `check()` — everything a transport needs for headers + 429. */
+interface RateLimitDecision {
+  allowed: boolean;
+  /** Limit of the governing rule (the violated one, else the lowest-remaining one). */
+  limit: number;
+  remaining: number;
+  /** ms epoch when the governing window resets. */
+  resetAt: number;
+  /**
+   * ms until the governing window resets, measured with the limiter's own
+   * clock — transports derive the `RateLimit-Reset` header from this instead
+   * of re-subtracting `Date.now()` (which would drift under injected clocks).
+   */
+  resetAfterMs: number;
+  /** Present when `!allowed`: ms until the governing window frees capacity. */
+  retryAfterMs?: number;
+  /** Present when `!allowed`: rendered from the violated rule's message template. */
+  message?: string;
+  /** Every evaluated rule (for the `RateLimit-Policy` header). */
+  policies: RateLimitRule[];
+}
+/**
+ * Fixed-window rate limiter with window-aligned keys (RL.spec.md §4.2).
+ *
+ * For each rule the current window starts at `floor(now / window) * window`;
+ * the counter key embeds that start, so a new window is automatically a new
+ * key and one atomic store increment decides. All rules are hit on every
+ * check (rejected requests count too — they cannot extend a fixed window).
+ */
+declare class RateLimiter {
+  private readonly store;
+  private readonly clock;
+  constructor(opts?: RateLimiterOptions);
+  /**
+   * Evaluate `rules` for `scope` (handler/bucket id) + `subject` (caller
+   * identity). Store keys are `<scope>:<subject>:<ruleIndex>:<windowStart>`
+   * with scope/subject each URI-encoded — raw components would collide
+   * (IPv6 addresses, route paths, and custom subjects all contain `:`).
+   *
+   * When several rules are violated at once, the governing rule is the one
+   * whose window frees capacity LAST — the request only becomes allowed once
+   * every rule passes, so a shorter hint would invite guaranteed-rejected
+   * retries.
+   */
+  check(scope: string, subject: string, rules: RateLimitRuleInput[], opts?: {
+    defaultMessage?: string;
+  }): Promise<RateLimitDecision>;
+}
+//#endregion
 //#region src/email.d.ts
 /**
  * Discriminator for auth-related email events emitted by the workflow stack.
@@ -515,4 +621,4 @@ type BuildMagicLinkUrl = (kind: AuthEmailKind, token: string, ctx?: {
  */
 declare function generateMagicLinkToken(): string;
 //#endregion
-export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, generateMagicLinkToken };
+export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, DEFAULT_RATE_LIMIT_MESSAGE, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RateLimitDecision, type RateLimitRule, type RateLimitRuleInput, type RateLimitStore, RateLimitStoreMemory, RateLimiter, type RateLimiterOptions, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, formatDurationMs, generateMagicLinkToken, parseDurationMs, parseRateLimitRule, renderRateLimitMessage };

package/dist/index.mjs

@@ -950,6 +950,190 @@ var AuthCredential = class {
 	}
 };
 //#endregion
+//#region src/rate-limit/rules.ts
+const DEFAULT_RATE_LIMIT_MESSAGE = "Too many requests. Please try again in {{delta}}.";
+const DURATION_UNITS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+/** `'5m'` / `'90s'` / `'500ms'` / `'1h'` / `'2d'` → ms. Throws on anything else. */
+function parseDurationMs(input) {
+	const m = /^(\d+)(ms|s|m|h|d)$/.exec(input.trim());
+	if (!m) throw new Error(`Invalid rate-limit window "${input}" — expected "<int><unit>" with unit ms|s|m|h|d (e.g. "5m")`);
+	return Number(m[1]) * DURATION_UNITS[m[2]];
+}
+/**
+* Humanize a ms duration for `{{window}}` / `{{delta}}` placeholders:
+* `"5 minutes"`, `"4 minutes 32 seconds"`, `"1 hour"`. Sub-second values
+* round UP to `"1 second"` — a retry hint of "0 seconds" reads as broken.
+* At most the two largest units are shown.
+*/
+function formatDurationMs(ms) {
+	const totalSeconds = Math.max(1, Math.ceil(ms / 1e3));
+	const units = [
+		["day", 86400],
+		["hour", 3600],
+		["minute", 60],
+		["second", 1]
+	];
+	const parts = [];
+	let rest = totalSeconds;
+	for (const [name, size] of units) {
+		if (parts.length === 2) break;
+		const n = Math.floor(rest / size);
+		if (n === 0) continue;
+		rest -= n * size;
+		parts.push(`${n} ${name}${n === 1 ? "" : "s"}`);
+	}
+	return parts.join(" ");
+}
+function parseRuleString(input) {
+	const pipe = input.indexOf("|");
+	const message = pipe >= 0 ? input.slice(pipe + 1).trim() : void 0;
+	const head = (pipe >= 0 ? input.slice(0, pipe) : input).trim();
+	const m = /^(\d+)\s*(?:\/|\s+per\s+)\s*(\d+(?:ms|s|m|h|d))$/i.exec(head);
+	if (!m) throw new Error(`Invalid rate-limit rule "${input}" — expected "<limit>/<window>" or "<limit> per <window>" (e.g. "6/5m", "30 per 1m"), optionally followed by " | <message>"`);
+	return {
+		limit: Number(m[1]),
+		window: parseDurationMs(m[2]),
+		...message !== void 0 && message !== "" && { message }
+	};
+}
+function assertValidRule(rule) {
+	if (!Number.isInteger(rule.limit) || rule.limit <= 0) throw new Error(`Invalid rate-limit rule: limit must be a positive integer (got ${rule.limit})`);
+	if (!Number.isFinite(rule.window) || rule.window <= 0) throw new Error(`Invalid rate-limit rule: window must be a positive ms value (got ${rule.window})`);
+}
+/** Normalize any {@link RateLimitRuleInput}. Throws on invalid grammar or non-positive values. */
+function parseRateLimitRule(input) {
+	if (typeof input !== "string" && typeof input.window === "number") {
+		assertValidRule(input);
+		return input;
+	}
+	const rule = typeof input === "string" ? parseRuleString(input) : {
+		limit: input.limit,
+		window: parseDurationMs(input.window),
+		...input.message !== void 0 && { message: input.message }
+	};
+	assertValidRule(rule);
+	return rule;
+}
+/**
+* Render a 429 message template. Placeholders: `{{limit}}` (alias `{{max}}`),
+* `{{window}}` and `{{delta}}` — both humanized via {@link formatDurationMs}.
+*/
+function renderRateLimitMessage(template, rule, retryAfterMs) {
+	return template.replaceAll("{{limit}}", String(rule.limit)).replaceAll("{{max}}", String(rule.limit)).replaceAll("{{window}}", formatDurationMs(rule.window)).replaceAll("{{delta}}", formatDurationMs(retryAfterMs));
+}
+//#endregion
+//#region src/rate-limit/store.ts
+/**
+* In-memory `RateLimitStore` — the zero-config default (single process only).
+* Lazy-evicts expired counters on access; `cleanup()` sweeps the whole map for
+* periodic compaction in long-lived processes (same pattern as
+* `DenylistStoreMemory`).
+*/
+var RateLimitStoreMemory = class {
+	entries = /* @__PURE__ */ new Map();
+	clock;
+	constructor(opts) {
+		this.clock = opts?.clock ?? defaultClock;
+	}
+	async hit(key, ttlMs) {
+		const now = this.clock.now();
+		const entry = this.entries.get(key);
+		if (!entry || entry.expiresAt <= now) {
+			this.entries.set(key, {
+				count: 1,
+				expiresAt: now + ttlMs
+			});
+			return 1;
+		}
+		entry.count += 1;
+		return entry.count;
+	}
+	async reset(key) {
+		this.entries.delete(key);
+	}
+	/** Drop every counter — test-harness reset between cases. */
+	clear() {
+		this.entries.clear();
+	}
+	async cleanup() {
+		const now = this.clock.now();
+		let removed = 0;
+		for (const [key, entry] of this.entries) if (entry.expiresAt <= now) {
+			this.entries.delete(key);
+			removed++;
+		}
+		return removed;
+	}
+};
+//#endregion
+//#region src/rate-limit/rate-limiter.ts
+/**
+* Fixed-window rate limiter with window-aligned keys (RL.spec.md §4.2).
+*
+* For each rule the current window starts at `floor(now / window) * window`;
+* the counter key embeds that start, so a new window is automatically a new
+* key and one atomic store increment decides. All rules are hit on every
+* check (rejected requests count too — they cannot extend a fixed window).
+*/
+var RateLimiter = class {
+	store;
+	clock;
+	constructor(opts) {
+		this.store = opts?.store ?? new RateLimitStoreMemory({ clock: opts?.clock });
+		this.clock = opts?.clock ?? defaultClock;
+	}
+	/**
+	* Evaluate `rules` for `scope` (handler/bucket id) + `subject` (caller
+	* identity). Store keys are `<scope>:<subject>:<ruleIndex>:<windowStart>`
+	* with scope/subject each URI-encoded — raw components would collide
+	* (IPv6 addresses, route paths, and custom subjects all contain `:`).
+	*
+	* When several rules are violated at once, the governing rule is the one
+	* whose window frees capacity LAST — the request only becomes allowed once
+	* every rule passes, so a shorter hint would invite guaranteed-rejected
+	* retries.
+	*/
+	async check(scope, subject, rules, opts) {
+		if (rules.length === 0) throw new Error("RateLimiter.check: at least one rule is required");
+		const parsed = rules.map((r) => parseRateLimitRule(r));
+		const now = this.clock.now();
+		const keyBase = `${encodeURIComponent(scope)}:${encodeURIComponent(subject)}`;
+		const evaluated = await Promise.all(parsed.map(async (rule, i) => {
+			const windowStart = Math.floor(now / rule.window) * rule.window;
+			const key = `${keyBase}:${i}:${windowStart}`;
+			const count = await this.store.hit(key, rule.window * 2);
+			return {
+				rule,
+				remaining: Math.max(0, rule.limit - count),
+				resetAt: windowStart + rule.window,
+				violated: count > rule.limit
+			};
+		}));
+		const violated = evaluated.filter((e) => e.violated);
+		const rejected = violated.length > 0;
+		const governing = rejected ? violated.reduce((a, b) => b.resetAt > a.resetAt ? b : a) : evaluated.reduce((a, b) => b.remaining < a.remaining ? b : a);
+		const resetAfterMs = governing.resetAt - now;
+		return {
+			allowed: !rejected,
+			limit: governing.rule.limit,
+			remaining: governing.remaining,
+			resetAt: governing.resetAt,
+			resetAfterMs,
+			policies: parsed,
+			...rejected && {
+				retryAfterMs: resetAfterMs,
+				message: renderRateLimitMessage(governing.rule.message ?? opts?.defaultMessage ?? "Too many requests. Please try again in {{delta}}.", governing.rule, resetAfterMs)
+			}
+		};
+	}
+};
+//#endregion
 //#region src/magic-link.ts
 /**
 * 32 bytes of CSPRNG entropy (256 bits) encoded as base64url — 43 chars,
@@ -959,4 +1143,4 @@ function generateMagicLinkToken() {
 	return randomBytes(32).toString("base64url");
 }
 //#endregion
-export { AuthCredential, AuthError, CredentialStoreEncapsulated, CredentialStoreJwt, CredentialStoreMemory, DenylistStoreMemory, defaultClock, generateMagicLinkToken };
+export { AuthCredential, AuthError, CredentialStoreEncapsulated, CredentialStoreJwt, CredentialStoreMemory, DEFAULT_RATE_LIMIT_MESSAGE, DenylistStoreMemory, RateLimitStoreMemory, RateLimiter, defaultClock, formatDurationMs, generateMagicLinkToken, parseDurationMs, parseRateLimitRule, renderRateLimitMessage };

package/dist/redis.cjs

@@ -146,6 +146,36 @@ var DenylistStoreRedis = class {
 		return 0;
 	}
 };
+/**
+* Redis-backed `RateLimitStore` (RL.spec.md §4.3) — one atomic `INCR` per
+* hit, `PEXPIRE` on first increment for garbage collection.
+*
+* Correctness never depends on the TTL: the limiter embeds the window start
+* in the key, so a new window is a new key. If the process dies between
+* `incr` and `pexpire`, the TTL-less key leaks a few bytes but is never
+* counted again.
+*/
+var RateLimitStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:rl";
+	}
+	key(key) {
+		return `${this.prefix}:${key}`;
+	}
+	async hit(key, ttlMs) {
+		const k = this.key(key);
+		const count = await this.redis.incr(k);
+		if (count === 1) await this.redis.pexpire(k, ttlMs);
+		return count;
+	}
+	async reset(key) {
+		await this.redis.del(this.key(key));
+	}
+};
 //#endregion
 exports.CredentialStoreRedis = CredentialStoreRedis;
 exports.DenylistStoreRedis = DenylistStoreRedis;
+exports.RateLimitStoreRedis = RateLimitStoreRedis;

package/dist/redis.d.cts

@@ -1,22 +1,42 @@
 import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-BG6m6oSJ.cjs";
+import { t as RateLimitStore } from "./store-N9daSmHS.cjs";
 
 //#region src/redis/index.d.ts
 /**
  * Structural Redis client. Covers the exact set of commands used by
- * `CredentialStoreRedis` and `DenylistStoreRedis` — no more.
+ * `CredentialStoreRedis`, `DenylistStoreRedis`, and `RateLimitStoreRedis` —
+ * no more.
  *
- * Compatible by-shape with `ioredis`, `redis@4+`, `@redis/client`, and ad-hoc
- * test doubles. Consumers are free to wrap whatever client they ship; we
- * deliberately do not declare a peer dep on any specific package.
+ * Compatible by-shape with `ioredis` and ad-hoc test doubles. Consumers are
+ * free to wrap whatever client they ship; we deliberately do not declare a
+ * peer dep on any specific package.
+ *
+ * ALL TTLs are MILLISECONDS. That is why the interface exposes `pexpire`
+ * rather than `expire` — redis's `EXPIRE` takes seconds, and a raw client
+ * passed by shape would otherwise satisfy the type while silently setting
+ * a 1000× TTL (a 5-minute counter becomes a ~3.5-day one). With `pexpire`
+ * a seconds-based double fails to typecheck instead of misbehaving.
+ * `node-redis` (`redis@4+`) users adapt the camelCase methods, e.g.:
+ *
+ * ```ts
+ * const redisLike: RedisLike = {
+ *   set: (k, v, _px, ttlMs) => client.set(k, v, ttlMs !== undefined ? { PX: ttlMs } : {}),
+ *   get: (k) => client.get(k),
+ *   del: (...k) => client.del(k),
+ *   exists: (k) => client.exists(k),
+ *   pexpire: (k, ms) => client.pExpire(k, ms).then((ok) => (ok ? 1 : 0)),
+ *   incr: (k) => client.incr(k),
+ *   sadd: (k, ...m) => client.sAdd(k, m),
+ *   srem: (k, ...m) => client.sRem(k, m),
+ *   smembers: (k) => client.sMembers(k),
+ * }
+ * ```
  *
  * Return types are widened to the union of what real clients return:
  *   - `set` returns `'OK' | string | null` (null on conditional sets that fail)
- *   - `del` / `expire` / `exists` / `sadd` / `srem` return `number`
+ *   - `del` / `pexpire` / `exists` / `incr` / `sadd` / `srem` return `number`
  *   - `get` returns `string | null`
  *   - `smembers` returns `string[]`
- *
- * The `ttl` arg passed to `set` is in MILLISECONDS — we always call with
- * `PX`, never `EX`, so callers don't have to translate.
  */
 interface RedisLike {
   /** `SET key value [PX ms]` — accepts an optional ms TTL. */
@@ -25,7 +45,9 @@ interface RedisLike {
   del(...keys: string[]): Promise<number>;
   exists(key: string): Promise<number>;
   /** `PEXPIRE key ttlMs` — ms TTL on an existing key. */
-  expire(key: string, ttlMs: number): Promise<number>;
+  pexpire(key: string, ttlMs: number): Promise<number>;
+  /** `INCR key` — atomic increment-and-get; creates the key at 1. */
+  incr(key: string): Promise<number>;
   sadd(key: string, ...members: string[]): Promise<number>;
   srem(key: string, ...members: string[]): Promise<number>;
   smembers(key: string): Promise<string[]>;
@@ -88,5 +110,27 @@ declare class DenylistStoreRedis implements DenylistStore {
   has(jti: string): Promise<boolean>;
   cleanup(): Promise<number>;
 }
+interface RedisRateLimitStoreOptions {
+  redis: RedisLike;
+  /** Key prefix. Defaults to `aooth:rl`. Combined as `<prefix>:<limiter key>`. */
+  prefix?: string;
+}
+/**
+ * Redis-backed `RateLimitStore` (RL.spec.md §4.3) — one atomic `INCR` per
+ * hit, `PEXPIRE` on first increment for garbage collection.
+ *
+ * Correctness never depends on the TTL: the limiter embeds the window start
+ * in the key, so a new window is a new key. If the process dies between
+ * `incr` and `pexpire`, the TTL-less key leaks a few bytes but is never
+ * counted again.
+ */
+declare class RateLimitStoreRedis implements RateLimitStore {
+  private readonly redis;
+  private readonly prefix;
+  constructor(opts: RedisRateLimitStoreOptions);
+  private key;
+  hit(key: string, ttlMs: number): Promise<number>;
+  reset(key: string): Promise<void>;
+}
 //#endregion
-export { CredentialStoreRedis, DenylistStoreRedis, RedisLike };
+export { CredentialStoreRedis, DenylistStoreRedis, RateLimitStoreRedis, RedisLike };

package/dist/redis.d.mts

@@ -1,22 +1,42 @@
 import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-BG6m6oSJ.mjs";
+import { t as RateLimitStore } from "./store-jFgby4bK.mjs";
 
 //#region src/redis/index.d.ts
 /**
  * Structural Redis client. Covers the exact set of commands used by
- * `CredentialStoreRedis` and `DenylistStoreRedis` — no more.
+ * `CredentialStoreRedis`, `DenylistStoreRedis`, and `RateLimitStoreRedis` —
+ * no more.
  *
- * Compatible by-shape with `ioredis`, `redis@4+`, `@redis/client`, and ad-hoc
- * test doubles. Consumers are free to wrap whatever client they ship; we
- * deliberately do not declare a peer dep on any specific package.
+ * Compatible by-shape with `ioredis` and ad-hoc test doubles. Consumers are
+ * free to wrap whatever client they ship; we deliberately do not declare a
+ * peer dep on any specific package.
+ *
+ * ALL TTLs are MILLISECONDS. That is why the interface exposes `pexpire`
+ * rather than `expire` — redis's `EXPIRE` takes seconds, and a raw client
+ * passed by shape would otherwise satisfy the type while silently setting
+ * a 1000× TTL (a 5-minute counter becomes a ~3.5-day one). With `pexpire`
+ * a seconds-based double fails to typecheck instead of misbehaving.
+ * `node-redis` (`redis@4+`) users adapt the camelCase methods, e.g.:
+ *
+ * ```ts
+ * const redisLike: RedisLike = {
+ *   set: (k, v, _px, ttlMs) => client.set(k, v, ttlMs !== undefined ? { PX: ttlMs } : {}),
+ *   get: (k) => client.get(k),
+ *   del: (...k) => client.del(k),
+ *   exists: (k) => client.exists(k),
+ *   pexpire: (k, ms) => client.pExpire(k, ms).then((ok) => (ok ? 1 : 0)),
+ *   incr: (k) => client.incr(k),
+ *   sadd: (k, ...m) => client.sAdd(k, m),
+ *   srem: (k, ...m) => client.sRem(k, m),
+ *   smembers: (k) => client.sMembers(k),
+ * }
+ * ```
  *
  * Return types are widened to the union of what real clients return:
  *   - `set` returns `'OK' | string | null` (null on conditional sets that fail)
- *   - `del` / `expire` / `exists` / `sadd` / `srem` return `number`
+ *   - `del` / `pexpire` / `exists` / `incr` / `sadd` / `srem` return `number`
  *   - `get` returns `string | null`
  *   - `smembers` returns `string[]`
- *
- * The `ttl` arg passed to `set` is in MILLISECONDS — we always call with
- * `PX`, never `EX`, so callers don't have to translate.
  */
 interface RedisLike {
   /** `SET key value [PX ms]` — accepts an optional ms TTL. */
@@ -25,7 +45,9 @@ interface RedisLike {
   del(...keys: string[]): Promise<number>;
   exists(key: string): Promise<number>;
   /** `PEXPIRE key ttlMs` — ms TTL on an existing key. */
-  expire(key: string, ttlMs: number): Promise<number>;
+  pexpire(key: string, ttlMs: number): Promise<number>;
+  /** `INCR key` — atomic increment-and-get; creates the key at 1. */
+  incr(key: string): Promise<number>;
   sadd(key: string, ...members: string[]): Promise<number>;
   srem(key: string, ...members: string[]): Promise<number>;
   smembers(key: string): Promise<string[]>;
@@ -88,5 +110,27 @@ declare class DenylistStoreRedis implements DenylistStore {
   has(jti: string): Promise<boolean>;
   cleanup(): Promise<number>;
 }
+interface RedisRateLimitStoreOptions {
+  redis: RedisLike;
+  /** Key prefix. Defaults to `aooth:rl`. Combined as `<prefix>:<limiter key>`. */
+  prefix?: string;
+}
+/**
+ * Redis-backed `RateLimitStore` (RL.spec.md §4.3) — one atomic `INCR` per
+ * hit, `PEXPIRE` on first increment for garbage collection.
+ *
+ * Correctness never depends on the TTL: the limiter embeds the window start
+ * in the key, so a new window is a new key. If the process dies between
+ * `incr` and `pexpire`, the TTL-less key leaks a few bytes but is never
+ * counted again.
+ */
+declare class RateLimitStoreRedis implements RateLimitStore {
+  private readonly redis;
+  private readonly prefix;
+  constructor(opts: RedisRateLimitStoreOptions);
+  private key;
+  hit(key: string, ttlMs: number): Promise<number>;
+  reset(key: string): Promise<void>;
+}
 //#endregion
-export { CredentialStoreRedis, DenylistStoreRedis, RedisLike };
+export { CredentialStoreRedis, DenylistStoreRedis, RateLimitStoreRedis, RedisLike };

package/dist/redis.mjs

@@ -145,5 +145,34 @@ var DenylistStoreRedis = class {
 		return 0;
 	}
 };
+/**
+* Redis-backed `RateLimitStore` (RL.spec.md §4.3) — one atomic `INCR` per
+* hit, `PEXPIRE` on first increment for garbage collection.
+*
+* Correctness never depends on the TTL: the limiter embeds the window start
+* in the key, so a new window is a new key. If the process dies between
+* `incr` and `pexpire`, the TTL-less key leaks a few bytes but is never
+* counted again.
+*/
+var RateLimitStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:rl";
+	}
+	key(key) {
+		return `${this.prefix}:${key}`;
+	}
+	async hit(key, ttlMs) {
+		const k = this.key(key);
+		const count = await this.redis.incr(k);
+		if (count === 1) await this.redis.pexpire(k, ttlMs);
+		return count;
+	}
+	async reset(key) {
+		await this.redis.del(this.key(key));
+	}
+};
 //#endregion
-export { CredentialStoreRedis, DenylistStoreRedis };
+export { CredentialStoreRedis, DenylistStoreRedis, RateLimitStoreRedis };

package/dist/store-N9daSmHS.d.cts

@@ -0,0 +1,39 @@
+import { t as Clock } from "./clock-BjXa0LXb.cjs";
+
+//#region src/rate-limit/store.d.ts
+/**
+ * Storage contract for the fixed-window limiter (RL.spec.md §4.3).
+ *
+ * The limiter embeds the window start in the key, so a new window is a new
+ * key and correctness never depends on the TTL — the TTL only garbage-collects
+ * dead counters.
+ */
+interface RateLimitStore {
+  /**
+   * Atomically increment `key`, setting `ttlMs` expiry when the key is
+   * created; returns the new count.
+   */
+  hit(key: string, ttlMs: number): Promise<number>;
+  /** Optional: drop a counter (tests / admin unblock). */
+  reset?(key: string): Promise<void>;
+}
+/**
+ * In-memory `RateLimitStore` — the zero-config default (single process only).
+ * Lazy-evicts expired counters on access; `cleanup()` sweeps the whole map for
+ * periodic compaction in long-lived processes (same pattern as
+ * `DenylistStoreMemory`).
+ */
+declare class RateLimitStoreMemory implements RateLimitStore {
+  private readonly entries;
+  private readonly clock;
+  constructor(opts?: {
+    clock?: Clock;
+  });
+  hit(key: string, ttlMs: number): Promise<number>;
+  reset(key: string): Promise<void>;
+  /** Drop every counter — test-harness reset between cases. */
+  clear(): void;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { RateLimitStoreMemory as n, RateLimitStore as t };

package/dist/store-jFgby4bK.d.mts

@@ -0,0 +1,39 @@
+import { t as Clock } from "./clock-BjXa0LXb.mjs";
+
+//#region src/rate-limit/store.d.ts
+/**
+ * Storage contract for the fixed-window limiter (RL.spec.md §4.3).
+ *
+ * The limiter embeds the window start in the key, so a new window is a new
+ * key and correctness never depends on the TTL — the TTL only garbage-collects
+ * dead counters.
+ */
+interface RateLimitStore {
+  /**
+   * Atomically increment `key`, setting `ttlMs` expiry when the key is
+   * created; returns the new count.
+   */
+  hit(key: string, ttlMs: number): Promise<number>;
+  /** Optional: drop a counter (tests / admin unblock). */
+  reset?(key: string): Promise<void>;
+}
+/**
+ * In-memory `RateLimitStore` — the zero-config default (single process only).
+ * Lazy-evicts expired counters on access; `cleanup()` sweeps the whole map for
+ * periodic compaction in long-lived processes (same pattern as
+ * `DenylistStoreMemory`).
+ */
+declare class RateLimitStoreMemory implements RateLimitStore {
+  private readonly entries;
+  private readonly clock;
+  constructor(opts?: {
+    clock?: Clock;
+  });
+  hit(key: string, ttlMs: number): Promise<number>;
+  reset(key: string): Promise<void>;
+  /** Drop every counter — test-harness reset between cases. */
+  clear(): void;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { RateLimitStoreMemory as n, RateLimitStore as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/auth",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "Auth method layer for aoothjs (sessions, tokens, password reset, MFA primitives)",
   "keywords": [
     "aoothjs",
@@ -104,7 +104,7 @@
   },
   "dependencies": {
     "jose": "^6.2.3",
-    "@aooth/user": "0.1.33"
+    "@aooth/user": "0.1.34"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.78",