@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/rate-limit.cjs

@@ -0,0 +1,354 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugins/rate-limit/index.ts
+var rate_limit_exports = {};
+__export(rate_limit_exports, {
+  normalizeAccountIdentifier: () => normalizeAccountIdentifier,
+  normalizeIp: () => normalizeIp,
+  rateLimit: () => rateLimit
+});
+module.exports = __toCommonJS(rate_limit_exports);
+
+// src/core/errors.ts
+var FortressError = class extends Error {
+  code;
+  statusCode;
+  retryAfter;
+  details;
+  /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+  oauthError;
+  /** Human-readable description for the OAuth `error_description` field. */
+  oauthDescription;
+  /** Optional URI for the OAuth `error_uri` field (§5.2). */
+  oauthErrorUri;
+  constructor(code, message, statusCode, options) {
+    super(message, { cause: options?.cause });
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryAfter = options?.retryAfter;
+    this.details = options?.details;
+    this.oauthError = options?.oauthError;
+    this.oauthDescription = options?.oauthDescription;
+    this.oauthErrorUri = options?.oauthErrorUri;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...this.details !== void 0 && { details: this.details }
+    };
+  }
+};
+var Errors = {
+  unauthorized: (message = "Unauthorized") => new FortressError("UNAUTHORIZED", message, 401),
+  tokenReuse: () => new FortressError("TOKEN_REUSE", "Token reuse detected", 401),
+  sessionIdleTimeout: () => new FortressError("SESSION_IDLE_TIMEOUT", "Session idle timeout exceeded", 401),
+  sessionAbsoluteTimeout: () => new FortressError("SESSION_ABSOLUTE_TIMEOUT", "Session absolute timeout exceeded", 401),
+  forbidden: (message = "Forbidden") => new FortressError("FORBIDDEN", message, 403),
+  badRequest: (message = "Bad request") => new FortressError("BAD_REQUEST", message, 400),
+  notFound: (message = "Not found") => new FortressError("NOT_FOUND", message, 404),
+  conflict: (message = "Conflict", options) => new FortressError("CONFLICT", message, 409, options),
+  unprocessable: (message = "Unprocessable entity", options) => new FortressError("UNPROCESSABLE_ENTITY", message, 422, options),
+  rateLimited: (retryAfter) => new FortressError("RATE_LIMITED", "Too many requests", 429, { retryAfter }),
+  database: (message = "Database error", cause) => new FortressError("DATABASE_ERROR", message, 500, { cause }),
+  serviceUnavailable: (message = "Service unavailable", options) => new FortressError("SERVICE_UNAVAILABLE", message, 503, options),
+  validationError: (issues) => new FortressError("VALIDATION_ERROR", "Validation failed", 422, { details: issues }),
+  /**
+   * RFC 6749 §5.2 / §4.1.2.1 OAuth error.
+   *
+   * The HTTP error mapper detects `oauthError` and emits the OAuth-spec
+   * JSON body `{ error, error_description, error_uri? }` instead of the
+   * default fortress `{ code, message }` shape, so strict OAuth clients
+   * (Moodle, openid-client, Spring Security, etc.) can switch behaviour
+   * on the machine-readable `error` field.
+   *
+   * Status is inferred from the OAuth code per the spec table:
+   * - `invalid_client` → 401
+   * - everything else → 400
+   */
+  oauth: (error, description, options) => {
+    const status = options?.status ?? (error === "invalid_client" ? 401 : 400);
+    const code = status === 401 ? "UNAUTHORIZED" : "BAD_REQUEST";
+    return new FortressError(code, description ?? error, status, {
+      oauthError: error,
+      oauthDescription: description,
+      oauthErrorUri: options?.errorUri,
+      cause: options?.cause
+    });
+  },
+  /**
+   * Reconstruct a {@link FortressError} from a JSON error body emitted by
+   * `errorToResponse`. Used by the in-process `fortress.call.*` client to
+   * convert non-2xx responses into typed throws that mirror what a direct
+   * service-method call would produce.
+   *
+   * Maps by HTTP status when the body doesn't carry a recognizable
+   * `{ code, message }` payload, so network errors and opaque upstream
+   * failures still become structured `FortressError`s.
+   */
+  fromHttpResponse: (status, body) => {
+    const payload = body && typeof body === "object" ? body : {};
+    const message = typeof payload.message === "string" ? payload.message : `HTTP ${status}`;
+    const code = typeof payload.code === "string" && isFortressErrorCode(payload.code) ? payload.code : statusToErrorCode(status);
+    return new FortressError(code, message, status, { details: payload.details });
+  }
+};
+function isFortressErrorCode(code) {
+  return code === "UNAUTHORIZED" || code === "TOKEN_REUSE" || code === "SESSION_IDLE_TIMEOUT" || code === "SESSION_ABSOLUTE_TIMEOUT" || code === "FORBIDDEN" || code === "BAD_REQUEST" || code === "NOT_FOUND" || code === "CONFLICT" || code === "UNPROCESSABLE_ENTITY" || code === "RATE_LIMITED" || code === "DATABASE_ERROR" || code === "VALIDATION_ERROR" || code === "SERVICE_UNAVAILABLE";
+}
+function statusToErrorCode(status) {
+  if (status === 401)
+    return "UNAUTHORIZED";
+  if (status === 403)
+    return "FORBIDDEN";
+  if (status === 404)
+    return "NOT_FOUND";
+  if (status === 409)
+    return "CONFLICT";
+  if (status === 422)
+    return "UNPROCESSABLE_ENTITY";
+  if (status === 429)
+    return "RATE_LIMITED";
+  if (status === 503)
+    return "SERVICE_UNAVAILABLE";
+  if (status >= 500)
+    return "DATABASE_ERROR";
+  return "BAD_REQUEST";
+}
+
+// src/plugins/rate-limit/memory-store.ts
+function createMemoryStore() {
+  const store = /* @__PURE__ */ new Map();
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, record] of store) {
+      const timestamps = record.timestamps.filter((timestamp) => now - timestamp < record.maxWindowMs);
+      if (timestamps.length === 0)
+        store.delete(key);
+      else
+        store.set(key, { ...record, timestamps });
+    }
+  }, 6e4);
+  if (typeof cleanupInterval === "object" && "unref" in cleanupInterval)
+    cleanupInterval.unref();
+  return {
+    async increment(key, windowMs) {
+      const now = Date.now();
+      const existing = store.get(key);
+      const maxWindowMs = Math.max(existing?.maxWindowMs ?? 0, windowMs);
+      const retained = (existing?.timestamps ?? []).filter((timestamp) => timestamp > now - maxWindowMs);
+      retained.push(now);
+      store.set(key, { timestamps: retained, maxWindowMs, lastWindowMs: windowMs });
+      const active = retained.filter((timestamp) => timestamp > now - windowMs);
+      return { count: active.length, resetAt: active[0] + windowMs };
+    },
+    async get(key) {
+      const record = store.get(key);
+      if (!record)
+        return null;
+      const now = Date.now();
+      const active = record.timestamps.filter((timestamp) => timestamp > now - record.lastWindowMs);
+      if (active.length === 0)
+        return null;
+      return {
+        count: active.length,
+        resetAt: active[0] + record.lastWindowMs
+      };
+    }
+  };
+}
+
+// src/plugins/rate-limit/index.ts
+var DEFAULT_LOGIN = { maxPerIp: 10, maxPerAccount: 5, windowSeconds: 900 };
+var DEFAULT_REGISTER = { maxPerIp: 3, windowSeconds: 3600 };
+var DEFAULT_REFRESH = { maxPerIp: 60, maxPerUser: 60, windowSeconds: 60 };
+var DEFAULT_OAUTH_TOKEN = { maxPerIp: 60, windowSeconds: 60 };
+var DEFAULT_API_KEY_ISSUE = { maxPerIp: 10, maxPerUser: 10, windowSeconds: 3600 };
+function normalizeIp(ip) {
+  if (!ip)
+    return "unknown";
+  if (ip.startsWith("::ffff:"))
+    return ip.slice(7);
+  if (ip.includes(":"))
+    return ip.split(":").slice(0, 4).join(":");
+  return ip;
+}
+function normalizeAccountIdentifier(identifier) {
+  return identifier.trim().normalize("NFC").toLowerCase();
+}
+function ipFromRequest(request) {
+  const xff = request.headers.get("x-forwarded-for");
+  if (xff)
+    return xff.split(",")[0].trim();
+  return request.headers.get("x-real-ip") ?? "";
+}
+async function runRule(store, ruleName, rule, keys) {
+  const windowMs = rule.windowSeconds * 1e3;
+  const prefix = rule.keyPrefix ?? ruleName;
+  if (rule.maxPerIp != null) {
+    const ip = normalizeIp(keys.ip);
+    const res = await store.increment(`${prefix}:ip:${ip}`, windowMs);
+    if (res.count > rule.maxPerIp) {
+      const retryAfter = Math.max(Math.ceil((res.resetAt - Date.now()) / 1e3), 1);
+      throw Errors.rateLimited(retryAfter);
+    }
+  }
+  if (rule.maxPerUser != null && keys.userId != null) {
+    const res = await store.increment(`${prefix}:user:${keys.userId}`, windowMs);
+    if (res.count > rule.maxPerUser) {
+      const retryAfter = Math.max(Math.ceil((res.resetAt - Date.now()) / 1e3), 1);
+      throw Errors.rateLimited(retryAfter);
+    }
+  }
+}
+function isDisabled(block) {
+  return !!block && "disabled" in block && block.disabled === true;
+}
+function rateLimit(config = {}) {
+  const store = config.store ?? createMemoryStore();
+  const loginCfg = isDisabled(config.login) ? void 0 : { ...DEFAULT_LOGIN, ...config.login };
+  const registerCfg = isDisabled(config.register) ? void 0 : { ...DEFAULT_REGISTER, ...config.register };
+  const refreshCfg = config.refresh ? { ...DEFAULT_REFRESH, ...config.refresh } : void 0;
+  const oauthTokenCfg = config.oauthToken ? { ...DEFAULT_OAUTH_TOKEN, ...config.oauthToken } : void 0;
+  const apiKeyIssueCfg = config.apiKeyIssue ? { ...DEFAULT_API_KEY_ISSUE, ...config.apiKeyIssue } : void 0;
+  const rules = { ...config.rules };
+  if (loginCfg) {
+    rules.login = { maxPerIp: loginCfg.maxPerIp, windowSeconds: loginCfg.windowSeconds };
+    if (loginCfg.maxPerAccount != null) {
+      rules["login:account"] = {
+        maxPerUser: loginCfg.maxPerAccount,
+        windowSeconds: loginCfg.windowSeconds,
+        keyPrefix: "login:account"
+      };
+    }
+  }
+  if (registerCfg)
+    rules.register = { maxPerIp: registerCfg.maxPerIp, windowSeconds: registerCfg.windowSeconds };
+  if (refreshCfg) {
+    rules.refresh = {
+      maxPerIp: refreshCfg.maxPerIp,
+      maxPerUser: refreshCfg.maxPerUser,
+      windowSeconds: refreshCfg.windowSeconds
+    };
+  }
+  if (oauthTokenCfg)
+    rules.oauthToken = { maxPerIp: oauthTokenCfg.maxPerIp, windowSeconds: oauthTokenCfg.windowSeconds };
+  if (apiKeyIssueCfg) {
+    rules.apiKeyIssue = {
+      maxPerIp: apiKeyIssueCfg.maxPerIp,
+      maxPerUser: apiKeyIssueCfg.maxPerUser,
+      windowSeconds: apiKeyIssueCfg.windowSeconds
+    };
+  }
+  async function check(ruleName, keys) {
+    const rule = rules[ruleName];
+    if (!rule)
+      throw new Error(`rate-limit: unknown rule '${ruleName}' \u2014 declare it in config.rules or add the matching endpoint config block`);
+    await runRule(store, ruleName, rule, keys);
+  }
+  const middleware = [];
+  const bindBuiltin = (ruleName, match, methodFilter, position) => {
+    middleware.push({
+      path: match,
+      position,
+      handler: async (_ctx, request, next) => {
+        const req = request.request;
+        if (!(req instanceof Request))
+          throw Errors.badRequest("PluginRequestContext.request is required");
+        if (methodFilter && !methodFilter.includes(req.method)) {
+          await next();
+          return;
+        }
+        const { fortressUserId: userId } = request;
+        await check(ruleName, { ip: ipFromRequest(req), userId });
+        await next();
+      }
+    });
+  };
+  if (oauthTokenCfg)
+    bindBuiltin("oauthToken", "/oauth/token", ["POST"], "before-auth");
+  if (apiKeyIssueCfg)
+    bindBuiltin("apiKeyIssue", "/api-key/keys", ["POST"], "after-auth");
+  for (const binding of config.paths ?? []) {
+    const inlineRule = typeof binding.rule === "object" ? binding.rule : null;
+    const ruleName = typeof binding.rule === "string" ? binding.rule : `path:${binding.match}`;
+    if (inlineRule)
+      rules[ruleName] = inlineRule;
+    else if (!rules[ruleName])
+      throw new Error(`rate-limit: unknown rule reference '${binding.rule}' in paths config`);
+    const position = binding.position ?? "before-auth";
+    const methodFilter = binding.methods?.map((m) => m.toUpperCase());
+    middleware.push({
+      path: binding.match,
+      position,
+      handler: async (_ctx, request, next) => {
+        const req = request.request;
+        if (!(req instanceof Request))
+          throw Errors.badRequest("PluginRequestContext.request is required");
+        if (methodFilter && !methodFilter.includes(req.method)) {
+          await next();
+          return;
+        }
+        const { fortressUserId: userId } = request;
+        await check(ruleName, { ip: ipFromRequest(req), userId });
+        await next();
+      }
+    });
+  }
+  return {
+    name: "rate-limit",
+    ...middleware.length > 0 ? { middleware } : {},
+    hooks: {
+      async beforeLogin(ctx) {
+        if (!loginCfg)
+          return;
+        const ip = ctx.meta?.ipAddress;
+        const email = ctx.email;
+        if (loginCfg.maxPerIp != null)
+          await check("login", { ip });
+        if (loginCfg.maxPerAccount != null)
+          await check("login:account", { userId: normalizeAccountIdentifier(email) });
+      },
+      async beforeRegister(ctx) {
+        if (!registerCfg)
+          return;
+        await check("register", { ip: ctx.meta?.ipAddress });
+      },
+      async beforeTokenRefresh(ctx) {
+        if (!refreshCfg)
+          return;
+        const ip = ctx.meta?.ipAddress;
+        await check("refresh", { ip });
+      }
+    },
+    methods: (_ctx) => ({
+      check,
+      /** Read-only view of the resolved rule registry (debug / introspection). */
+      listRules: () => Object.keys(rules)
+    })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  normalizeAccountIdentifier,
+  normalizeIp,
+  rateLimit
+});

package/dist/plugins/rate-limit.d.cts

@@ -0,0 +1,140 @@
+import { F as FortressPlugin } from '../config-GtlVt6ZD.cjs';
+import '../index-CxEkfCA0.cjs';
+import '../jwt.cjs';
+import '../types-et0R8tsC.cjs';
+import '../auth-service-BcyQ2PuZ.cjs';
+
+interface RateLimitStore {
+    /** Increment the counter for a key within a sliding window. Returns current count and reset time. */
+    increment: (key: string, windowMs: number) => Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Get the current counter for the most recently used window. */
+    get: (key: string) => Promise<{
+        count: number;
+        resetAt: number;
+    } | null>;
+}
+
+/**
+ * Sliding-window rate limiting plugin for fortress.
+ *
+ * Protects built-in Fortress auth endpoints (`login`, `register`, `refresh`,
+ * plus OAuth token issuance and API-key creation when those plugins are
+ * mounted) and exposes a `check()` method + per-framework middleware
+ * wrappers so consumers can rate-limit any of their own routes.
+ *
+ * Ships with an in-memory store; bring-your-own store via the
+ * {@link RateLimitStore} interface for distributed deployments (Redis, etc).
+ *
+ * @module
+ */
+
+/**
+ * A single rate-limit rule. At least one of `maxPerIp` / `maxPerUser` must be
+ * set; if neither is set the rule is a no-op. Keys are checked independently
+ * and the first to exceed short-circuits with a `rateLimited` error.
+ */
+interface RateLimitRule {
+    /** Max requests per client IP in the window. */
+    maxPerIp?: number;
+    /** Max requests per authenticated user in the window. Ignored if the check has no userId. */
+    maxPerUser?: number;
+    /** Sliding window length in seconds. */
+    windowSeconds: number;
+    /** Optional key-namespace override. Defaults to the rule name. */
+    keyPrefix?: string;
+}
+/** Rate-limit config block for login (per-account adds an email-scoped key). */
+interface LoginRateLimit {
+    maxPerIp?: number;
+    maxPerAccount?: number;
+    windowSeconds?: number;
+}
+interface SimpleRateLimit {
+    maxPerIp?: number;
+    maxPerUser?: number;
+    windowSeconds?: number;
+}
+/** Sentinel passed to the `login` / `register` blocks to opt out of the always-on defaults. */
+interface DisabledBlock {
+    disabled: true;
+}
+interface RateLimitConfig {
+    /**
+     * Limit for `POST /auth/login`. **Always on with defaults** when the plugin
+     * is registered — pass `{ disabled: true }` to turn it off. This is a gate
+     * plugin; leaving the default protects against silent loss of auth DoS
+     * protection on upgrade.
+     */
+    login?: LoginRateLimit | DisabledBlock;
+    /**
+     * Limit for `POST /auth/register`. Same default-on / explicit-disable
+     * behavior as `login` — both are security-critical gates.
+     */
+    register?: {
+        maxPerIp?: number;
+        windowSeconds?: number;
+    } | DisabledBlock;
+    /** Limit for `POST /auth/refresh` (runs in `beforeTokenRefresh` hook). */
+    refresh?: SimpleRateLimit;
+    /** Limit for OAuth `POST /oauth/token` (IP-scoped; client_id lives in the form body). */
+    oauthToken?: {
+        maxPerIp?: number;
+        windowSeconds?: number;
+    };
+    /** Limit for API-key issuance `POST /api-key/keys` (requires authenticated user). */
+    apiKeyIssue?: SimpleRateLimit;
+    /**
+     * Named rules referenced by `methods.check(name, keys)` and the
+     * per-framework middleware wrappers. Use these for your own app routes
+     * or for Fortress endpoints that don't have a dedicated config block
+     * (magic-link, 2FA verify, email verification — these are methods-only,
+     * so wire the limiter in your own handler).
+     */
+    rules?: Record<string, RateLimitRule>;
+    /**
+     * Extra path-based bindings for any route served by `fortress.handleRequest`.
+     * Each entry binds a named rule (or inline rule) to a path glob.
+     */
+    paths?: PathBinding[];
+    /** Custom store for rate-limit counters. Default: in-memory sliding window. */
+    store?: RateLimitStore;
+}
+/**
+ * Declarative rate-limit binding for a Fortress-dispatched path. Only fires
+ * for routes that flow through `fortress.handleRequest`.
+ *
+ * **When to use `paths` vs the framework wrappers**:
+ * - Framework wrappers (`honoRateLimit` / `expressRateLimit` /
+ *   `svelteKitRateLimit`) — use when you have a middleware layer around your
+ *   routes. Mount on any path, Fortress-owned or user-owned.
+ * - `paths` — use in serverless / framework-less deployments that call
+ *   `fortress.handleRequest` directly, or when you prefer declarative config
+ *   co-located with the rest of the rate-limit setup.
+ *
+ * Both target the same store. **Don't stack both on the same path** — each
+ * match increments the counter, so double-wrapping halves the effective
+ * limit.
+ */
+interface PathBinding {
+    /** Path glob (supports `*` and `:param`). */
+    match: string;
+    /** HTTP methods to restrict to (uppercase). Omit to match all methods. */
+    methods?: string[];
+    /** Pipeline phase. `after-auth` required when keying per user. Default: `before-auth`. */
+    position?: 'before-auth' | 'after-auth';
+    /** Named rule key in `config.rules`, or an inline rule. */
+    rule: string | RateLimitRule;
+}
+/**
+ * Normalize an IPv6 address to its /64 prefix to prevent bypass via address rotation.
+ * IPv4 addresses are returned as-is.
+ */
+declare function normalizeIp(ip: string | undefined | null): string;
+/** Canonical key for account-scoped login limits. */
+declare function normalizeAccountIdentifier(identifier: string): string;
+declare function rateLimit(config?: RateLimitConfig): FortressPlugin;
+
+export { type DisabledBlock, type LoginRateLimit, type PathBinding, type RateLimitConfig, type RateLimitRule, type RateLimitStore, type SimpleRateLimit, normalizeAccountIdentifier, normalizeIp, rateLimit };

package/dist/plugins/rate-limit.d.ts

@@ -0,0 +1,140 @@
+import { F as FortressPlugin } from '../config-B2366s_G.js';
+import '../index-CxEkfCA0.js';
+import '../jwt.js';
+import '../types-et0R8tsC.js';
+import '../auth-service-BkzZkWfH.js';
+
+interface RateLimitStore {
+    /** Increment the counter for a key within a sliding window. Returns current count and reset time. */
+    increment: (key: string, windowMs: number) => Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Get the current counter for the most recently used window. */
+    get: (key: string) => Promise<{
+        count: number;
+        resetAt: number;
+    } | null>;
+}
+
+/**
+ * Sliding-window rate limiting plugin for fortress.
+ *
+ * Protects built-in Fortress auth endpoints (`login`, `register`, `refresh`,
+ * plus OAuth token issuance and API-key creation when those plugins are
+ * mounted) and exposes a `check()` method + per-framework middleware
+ * wrappers so consumers can rate-limit any of their own routes.
+ *
+ * Ships with an in-memory store; bring-your-own store via the
+ * {@link RateLimitStore} interface for distributed deployments (Redis, etc).
+ *
+ * @module
+ */
+
+/**
+ * A single rate-limit rule. At least one of `maxPerIp` / `maxPerUser` must be
+ * set; if neither is set the rule is a no-op. Keys are checked independently
+ * and the first to exceed short-circuits with a `rateLimited` error.
+ */
+interface RateLimitRule {
+    /** Max requests per client IP in the window. */
+    maxPerIp?: number;
+    /** Max requests per authenticated user in the window. Ignored if the check has no userId. */
+    maxPerUser?: number;
+    /** Sliding window length in seconds. */
+    windowSeconds: number;
+    /** Optional key-namespace override. Defaults to the rule name. */
+    keyPrefix?: string;
+}
+/** Rate-limit config block for login (per-account adds an email-scoped key). */
+interface LoginRateLimit {
+    maxPerIp?: number;
+    maxPerAccount?: number;
+    windowSeconds?: number;
+}
+interface SimpleRateLimit {
+    maxPerIp?: number;
+    maxPerUser?: number;
+    windowSeconds?: number;
+}
+/** Sentinel passed to the `login` / `register` blocks to opt out of the always-on defaults. */
+interface DisabledBlock {
+    disabled: true;
+}
+interface RateLimitConfig {
+    /**
+     * Limit for `POST /auth/login`. **Always on with defaults** when the plugin
+     * is registered — pass `{ disabled: true }` to turn it off. This is a gate
+     * plugin; leaving the default protects against silent loss of auth DoS
+     * protection on upgrade.
+     */
+    login?: LoginRateLimit | DisabledBlock;
+    /**
+     * Limit for `POST /auth/register`. Same default-on / explicit-disable
+     * behavior as `login` — both are security-critical gates.
+     */
+    register?: {
+        maxPerIp?: number;
+        windowSeconds?: number;
+    } | DisabledBlock;
+    /** Limit for `POST /auth/refresh` (runs in `beforeTokenRefresh` hook). */
+    refresh?: SimpleRateLimit;
+    /** Limit for OAuth `POST /oauth/token` (IP-scoped; client_id lives in the form body). */
+    oauthToken?: {
+        maxPerIp?: number;
+        windowSeconds?: number;
+    };
+    /** Limit for API-key issuance `POST /api-key/keys` (requires authenticated user). */
+    apiKeyIssue?: SimpleRateLimit;
+    /**
+     * Named rules referenced by `methods.check(name, keys)` and the
+     * per-framework middleware wrappers. Use these for your own app routes
+     * or for Fortress endpoints that don't have a dedicated config block
+     * (magic-link, 2FA verify, email verification — these are methods-only,
+     * so wire the limiter in your own handler).
+     */
+    rules?: Record<string, RateLimitRule>;
+    /**
+     * Extra path-based bindings for any route served by `fortress.handleRequest`.
+     * Each entry binds a named rule (or inline rule) to a path glob.
+     */
+    paths?: PathBinding[];
+    /** Custom store for rate-limit counters. Default: in-memory sliding window. */
+    store?: RateLimitStore;
+}
+/**
+ * Declarative rate-limit binding for a Fortress-dispatched path. Only fires
+ * for routes that flow through `fortress.handleRequest`.
+ *
+ * **When to use `paths` vs the framework wrappers**:
+ * - Framework wrappers (`honoRateLimit` / `expressRateLimit` /
+ *   `svelteKitRateLimit`) — use when you have a middleware layer around your
+ *   routes. Mount on any path, Fortress-owned or user-owned.
+ * - `paths` — use in serverless / framework-less deployments that call
+ *   `fortress.handleRequest` directly, or when you prefer declarative config
+ *   co-located with the rest of the rate-limit setup.
+ *
+ * Both target the same store. **Don't stack both on the same path** — each
+ * match increments the counter, so double-wrapping halves the effective
+ * limit.
+ */
+interface PathBinding {
+    /** Path glob (supports `*` and `:param`). */
+    match: string;
+    /** HTTP methods to restrict to (uppercase). Omit to match all methods. */
+    methods?: string[];
+    /** Pipeline phase. `after-auth` required when keying per user. Default: `before-auth`. */
+    position?: 'before-auth' | 'after-auth';
+    /** Named rule key in `config.rules`, or an inline rule. */
+    rule: string | RateLimitRule;
+}
+/**
+ * Normalize an IPv6 address to its /64 prefix to prevent bypass via address rotation.
+ * IPv4 addresses are returned as-is.
+ */
+declare function normalizeIp(ip: string | undefined | null): string;
+/** Canonical key for account-scoped login limits. */
+declare function normalizeAccountIdentifier(identifier: string): string;
+declare function rateLimit(config?: RateLimitConfig): FortressPlugin;
+
+export { type DisabledBlock, type LoginRateLimit, type PathBinding, type RateLimitConfig, type RateLimitRule, type RateLimitStore, type SimpleRateLimit, normalizeAccountIdentifier, normalizeIp, rateLimit };