/**
 * In-memory sliding window rate limiter.
 *
 * Tracks failed attempts per key (typically IP address) using a sliding
 * time window. No external dependencies — state resets on server restart.
 *
 * @module
 */
import type { Context } from 'hono';
/**
 * Default tracked-key cap: bounds worst-case memory under key-enumeration
 * attacks (an attacker rotating source IPs cannot grow the backing map
 * indefinitely between cleanup ticks). Tuned to comfortably fit real
 * traffic for a single-instance deployment while capping memory at a few
 * MB in the worst case.
 */
export declare const DEFAULT_RATE_LIMITER_MAX_KEYS = 100000;
/**
 * Configuration for a rate limiter instance.
 */
export interface RateLimiterOptions {
    /** Maximum allowed attempts within the window. */
    max_attempts: number;
    /** Sliding window duration in milliseconds. */
    window_ms: number;
    /** Interval for pruning stale entries (0 disables the timer). */
    cleanup_interval_ms: number;
    /**
     * Maximum tracked keys. When exceeded, the least-recently-used key is
     * evicted — bounds memory under key-enumeration attacks. Default:
     * `DEFAULT_RATE_LIMITER_MAX_KEYS` (100_000). Pass `null` to disable the
     * cap (falls back to an unbounded `Map` — only recommended when the key
     * set is known to be closed, e.g. a per-account limiter keyed to a
     * bounded-size account table).
     *
     * LRU trade-off: every `check` / `record` call marks the key as
     * most-recently-used, so keys under active attack stay fresh and won't
     * be evicted. A slow-burn attacker spread across many low-volume keys
     * can, however, drop out of the table and reset their budget — set
     * `max_keys` high enough to fit the expected legitimate key set and
     * this stays theoretical.
     */
    max_keys?: number | null;
}
/** Default options for per-IP login rate limiting: 5 attempts per 15 minutes. */
export declare const default_login_ip_rate_limit: RateLimiterOptions;
/** Default options for per-account login rate limiting: 10 attempts per 30 minutes. */
export declare const default_login_account_rate_limit: RateLimiterOptions;
/**
 * Default options for per-IP action-dispatcher rate limiting: 600 attempts
 * per 15 minutes. Shared by the HTTP RPC and WebSocket action dispatchers
 * (one budget per action, not per transport). Permissive — catches runaway
 * scripts and egregious oracle probes, but well above human or normal
 * automation pace. Tighten downstream for stricter deployments.
 */
export declare const default_action_ip_rate_limit: RateLimiterOptions;
/**
 * Default options for per-actor action-dispatcher rate limiting: 1200
 * attempts per 15 minutes. Shared by the HTTP RPC and WebSocket action
 * dispatchers. Permissive — sustained ~80/min is well above any human
 * admin workflow; an oracle probing 10k addresses still finishes in
 * ~2 hours, slow enough to surface in audit. Tighten downstream.
 */
export declare const default_action_account_rate_limit: RateLimiterOptions;
/**
 * Result of a rate limit check or record operation.
 */
export interface RateLimitResult {
    /** Whether the request is allowed. */
    allowed: boolean;
    /** Remaining attempts before blocking. */
    remaining: number;
    /** Seconds until the oldest active attempt expires (0 if allowed). */
    retry_after: number;
}
/**
 * In-memory sliding window rate limiter.
 *
 * Stores an array of timestamps per key. On `check`/`record`, timestamps
 * outside the window are pruned. `retry_after` reports seconds until the
 * oldest active timestamp expires.
 *
 * The backing store is an `LruMap` when `options.max_keys` is a positive
 * number (default `DEFAULT_RATE_LIMITER_MAX_KEYS`) and a plain `Map` when
 * `max_keys` is `null`. The `LruMap` path bounds memory under
 * key-enumeration attack at the cost of a slight per-op overhead and the
 * LRU trade-off described on `RateLimiterOptions.max_keys`.
 *
 * Parameters that accept `RateLimiter | null` (e.g. `ip_rate_limiter`,
 * `login_account_rate_limiter`) silently disable rate limiting when `null`
 * is passed — no checks are performed and all requests are allowed through.
 */
export declare class RateLimiter {
    #private;
    readonly options: RateLimiterOptions;
    constructor(options: RateLimiterOptions);
    /** Number of tracked keys. */
    get size(): number;
    /**
     * Check whether `key` is allowed without recording an attempt.
     *
     * Prunes timestamps that fell outside the window as a side effect (and
     * removes the key entirely when none remain), so the backing map stays
     * bounded even under read-only traffic.
     *
     * @param key - rate limit key (e.g. IP address)
     * @param now - current timestamp in ms (defaults to `Date.now()`)
     * @mutates internal map - prunes expired timestamps for `key`
     */
    check(key: string, now?: number): RateLimitResult;
    /**
     * Record a failed attempt for `key` and return the updated result.
     *
     * @param key - rate limit key (e.g. IP address)
     * @param now - current timestamp in ms (defaults to `Date.now()`)
     * @mutates internal map - appends `now` to the timestamp list for `key` (after pruning expired entries)
     */
    record(key: string, now?: number): RateLimitResult;
    /**
     * Clear all attempts for `key` (e.g. after successful login).
     *
     * @mutates internal map - removes the entry for `key`
     */
    reset(key: string): void;
    /**
     * Remove entries whose timestamps are all outside the window.
     *
     * @param now - current timestamp in ms (defaults to `Date.now()`)
     * @mutates internal map - prunes expired timestamps and deletes empty keys
     */
    cleanup(now?: number): void;
    /**
     * Stop the cleanup timer. Safe to call multiple times.
     *
     * @mutates timer - clears the cleanup `setInterval` and nulls the handle
     */
    dispose(): void;
}
/**
 * Create a `RateLimiter` with sensible defaults for per-IP login protection.
 *
 * @param options - override individual options; unset fields use `default_login_ip_rate_limit`
 */
export declare const create_rate_limiter: (options?: Partial<RateLimiterOptions>) => RateLimiter;
/**
 * Build a 429 rate-limit-exceeded JSON response with `Retry-After` header.
 *
 * @param c - Hono context
 * @param retry_after - seconds until the client should retry
 * @returns a 429 Response
 */
export declare const rate_limit_exceeded_response: (c: Context, retry_after: number) => Response;
//# sourceMappingURL=rate_limiter.d.ts.map