@veloxts/auth 0.3.4 → 0.3.6

package/dist/plugin.js

@@ -16,7 +16,7 @@ export const AUTH_VERSION = packageJson.version ?? '0.0.0-unknown';
 // Auth Plugin
 // ============================================================================
 /**
- * Creates the VeloxTS auth plugin
+ * Creates the VeloxTS auth plugin (succinct API)
  *
  * This plugin provides:
  * - JWT token management (access + refresh tokens)
@@ -26,9 +26,9 @@ export const AUTH_VERSION = packageJson.version ?? '0.0.0-unknown';
  *
  * @example
  * ```typescript
- * import { createAuthPlugin } from '@veloxts/auth';
+ * import { authPlugin } from '@veloxts/auth';
  *
- * const authPlugin = createAuthPlugin({
+ * const auth = authPlugin({
  *   jwt: {
  *     secret: process.env.JWT_SECRET!,
  *     accessTokenExpiry: '15m',
@@ -44,7 +44,7 @@ export const AUTH_VERSION = packageJson.version ?? '0.0.0-unknown';
  * });
  *
  * // Register with VeloxApp
- * app.register(authPlugin);
+ * await app.register(auth);
  *
  * // Use in procedures
  * const { middleware, requireAuth } = app.auth.middleware;
@@ -54,11 +54,12 @@ export const AUTH_VERSION = packageJson.version ?? '0.0.0-unknown';
  *   .query(async ({ ctx }) => ctx.user);
  * ```
  */
-export function createAuthPlugin(options) {
+export function authPlugin(options) {
     return {
         name: '@veloxts/auth',
         version: AUTH_VERSION,
-        dependencies: ['@veloxts/core'],
+        // No explicit dependencies - works with any Fastify instance
+        // The plugin decorates Fastify with auth functionality
         async register(server, _opts) {
             const config = { ...options, ..._opts };
             const { debug = false } = config;
@@ -157,17 +158,35 @@ export function createAuthPlugin(options) {
         },
     };
 }
+/**
+ * Creates the VeloxTS auth plugin
+ *
+ * @deprecated Use `authPlugin()` instead. Will be removed in v0.9.
+ */
+export const createAuthPlugin = authPlugin;
 /**
  * Default auth plugin with minimal configuration
- * Requires JWT_SECRET environment variable
+ *
+ * Uses environment variables for configuration:
+ * - `JWT_SECRET` (required): Secret for signing JWT tokens
+ *
+ * @throws {Error} If JWT_SECRET environment variable is not set
+ *
+ * @example
+ * ```typescript
+ * import { defaultAuthPlugin } from '@veloxts/auth';
+ *
+ * // Requires JWT_SECRET environment variable
+ * await app.register(defaultAuthPlugin());
+ * ```
  */
-export function authPlugin() {
+export function defaultAuthPlugin() {
     const secret = process.env.JWT_SECRET;
     if (!secret) {
         throw new Error('JWT_SECRET environment variable is required for auth plugin. ' +
             'Set it to a secure random string of at least 32 characters.');
     }
-    return createAuthPlugin({
+    return authPlugin({
         jwt: { secret },
     });
 }

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Authentication-specific rate limiting
+ *
+ * Provides specialized rate limiters for authentication endpoints with:
+ * - Per-email+IP tracking (prevents brute force on specific accounts)
+ * - Account lockout detection
+ * - Separate limits for login, register, and password reset
+ * - Progressive backoff support
+ *
+ * @module auth/rate-limit
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { MiddlewareFunction } from '@veloxts/router';
+/**
+ * Configuration for auth rate limiting
+ */
+export interface AuthRateLimitConfig {
+    /**
+     * Maximum attempts before lockout
+     * @default 5
+     */
+    maxAttempts?: number;
+    /**
+     * Window duration in milliseconds
+     * @default 900000 (15 minutes)
+     */
+    windowMs?: number;
+    /**
+     * Lockout duration in milliseconds after max attempts exceeded
+     * @default 900000 (15 minutes)
+     */
+    lockoutDurationMs?: number;
+    /**
+     * Custom key generator for rate limiting
+     * Default uses IP + identifier (email)
+     */
+    keyGenerator?: (ctx: BaseContext, identifier?: string) => string;
+    /**
+     * Error message when rate limited
+     * @default 'Too many attempts. Please try again later.'
+     */
+    message?: string;
+    /**
+     * Enable progressive backoff (double lockout on repeated violations)
+     * @default false
+     */
+    progressiveBackoff?: boolean;
+}
+/**
+ * Configuration for the auth rate limiter factory
+ */
+export interface AuthRateLimiterConfig {
+    /**
+     * Rate limit for login attempts
+     * @default { maxAttempts: 5, windowMs: 900000 }
+     */
+    login?: AuthRateLimitConfig;
+    /**
+     * Rate limit for registration attempts
+     * @default { maxAttempts: 3, windowMs: 3600000 }
+     */
+    register?: AuthRateLimitConfig;
+    /**
+     * Rate limit for password reset requests
+     * @default { maxAttempts: 3, windowMs: 3600000 }
+     */
+    passwordReset?: AuthRateLimitConfig;
+    /**
+     * Rate limit for token refresh
+     * @default { maxAttempts: 10, windowMs: 60000 }
+     */
+    refresh?: AuthRateLimitConfig;
+}
+/**
+ * Stop cleanup interval (for testing)
+ */
+export declare function stopAuthRateLimitCleanup(): void;
+/**
+ * Clear all rate limit entries (for testing)
+ */
+export declare function clearAuthRateLimitStore(): void;
+/**
+ * Creates an authentication rate limiter
+ *
+ * This factory returns rate limit middlewares configured for different
+ * auth operations with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const authRateLimiter = createAuthRateLimiter({
+ *   login: { maxAttempts: 5, windowMs: 15 * 60 * 1000 },
+ *   register: { maxAttempts: 3, windowMs: 60 * 60 * 1000 },
+ * });
+ *
+ * // Apply to procedures
+ * const login = procedure()
+ *   .use(authRateLimiter.login(ctx => ctx.input.email))
+ *   .mutation(loginHandler);
+ *
+ * const register = procedure()
+ *   .use(authRateLimiter.register())
+ *   .mutation(registerHandler);
+ * ```
+ */
+export declare function createAuthRateLimiter(config?: AuthRateLimiterConfig): {
+    /**
+     * Rate limiter for login attempts
+     *
+     * @param identifierFn - Function to extract identifier (email) from context
+     *
+     * @example
+     * ```typescript
+     * login: procedure()
+     *   .use(authRateLimiter.login((ctx) => (ctx.input as { email: string }).email))
+     *   .input(LoginSchema)
+     *   .mutation(handler)
+     * ```
+     */
+    login: <TInput, TContext extends BaseContext, TOutput>(identifierFn?: (ctx: TContext & {
+        input?: unknown;
+    }) => string) => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for registration attempts
+     * Uses IP-only by default (no identifier needed)
+     */
+    register: <TInput, TContext extends BaseContext, TOutput>() => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for password reset requests
+     *
+     * @param identifierFn - Optional function to extract identifier (email)
+     */
+    passwordReset: <TInput, TContext extends BaseContext, TOutput>(identifierFn?: (ctx: TContext & {
+        input?: unknown;
+    }) => string) => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for token refresh
+     */
+    refresh: <TInput, TContext extends BaseContext, TOutput>() => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Record a failed attempt (call after authentication fails)
+     *
+     * This allows tracking failures even when rate limit hasn't been hit,
+     * enabling account lockout after X failed passwords.
+     *
+     * @param key - Rate limit key (usually IP:email or IP)
+     * @param operation - Operation type for key namespacing
+     */
+    recordFailure: (key: string, operation: "login" | "register" | "password-reset") => void;
+    /**
+     * Reset rate limit for a key (call after successful auth)
+     */
+    resetLimit: (key: string, operation: "login" | "register" | "password-reset") => void;
+    /**
+     * Check if a key is currently locked out
+     */
+    isLockedOut: (key: string, operation: "login" | "register" | "password-reset") => boolean;
+    /**
+     * Get remaining attempts for a key
+     */
+    getRemainingAttempts: (key: string, operation: "login" | "register" | "password-reset" | "refresh") => number;
+};
+/**
+ * Pre-configured auth rate limiter with sensible defaults
+ *
+ * @example
+ * ```typescript
+ * import { authRateLimiter } from '@veloxts/auth';
+ *
+ * const login = procedure()
+ *   .use(authRateLimiter.login((ctx) => ctx.input.email))
+ *   .mutation(handler);
+ * ```
+ */
+export declare const authRateLimiter: {
+    /**
+     * Rate limiter for login attempts
+     *
+     * @param identifierFn - Function to extract identifier (email) from context
+     *
+     * @example
+     * ```typescript
+     * login: procedure()
+     *   .use(authRateLimiter.login((ctx) => (ctx.input as { email: string }).email))
+     *   .input(LoginSchema)
+     *   .mutation(handler)
+     * ```
+     */
+    login: <TInput, TContext extends BaseContext, TOutput>(identifierFn?: (ctx: TContext & {
+        input?: unknown;
+    }) => string) => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for registration attempts
+     * Uses IP-only by default (no identifier needed)
+     */
+    register: <TInput, TContext extends BaseContext, TOutput>() => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for password reset requests
+     *
+     * @param identifierFn - Optional function to extract identifier (email)
+     */
+    passwordReset: <TInput, TContext extends BaseContext, TOutput>(identifierFn?: (ctx: TContext & {
+        input?: unknown;
+    }) => string) => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Rate limiter for token refresh
+     */
+    refresh: <TInput, TContext extends BaseContext, TOutput>() => MiddlewareFunction<TInput, TContext, TContext, TOutput>;
+    /**
+     * Record a failed attempt (call after authentication fails)
+     *
+     * This allows tracking failures even when rate limit hasn't been hit,
+     * enabling account lockout after X failed passwords.
+     *
+     * @param key - Rate limit key (usually IP:email or IP)
+     * @param operation - Operation type for key namespacing
+     */
+    recordFailure: (key: string, operation: "login" | "register" | "password-reset") => void;
+    /**
+     * Reset rate limit for a key (call after successful auth)
+     */
+    resetLimit: (key: string, operation: "login" | "register" | "password-reset") => void;
+    /**
+     * Check if a key is currently locked out
+     */
+    isLockedOut: (key: string, operation: "login" | "register" | "password-reset") => boolean;
+    /**
+     * Get remaining attempts for a key
+     */
+    getRemainingAttempts: (key: string, operation: "login" | "register" | "password-reset" | "refresh") => number;
+};
+//# sourceMappingURL=rate-limit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.js

@@ -0,0 +1,352 @@
+/**
+ * Authentication-specific rate limiting
+ *
+ * Provides specialized rate limiters for authentication endpoints with:
+ * - Per-email+IP tracking (prevents brute force on specific accounts)
+ * - Account lockout detection
+ * - Separate limits for login, register, and password reset
+ * - Progressive backoff support
+ *
+ * @module auth/rate-limit
+ */
+import { AuthError } from './types.js';
+// ============================================================================
+// Rate Limit Store
+// ============================================================================
+/**
+ * In-memory rate limit store
+ *
+ * PRODUCTION NOTE: Replace with Redis for horizontal scaling:
+ * ```typescript
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ *
+ * // Store entry as JSON with TTL
+ * await redis.setex(`ratelimit:${key}`, ttlSeconds, JSON.stringify(entry));
+ *
+ * // Get entry
+ * const data = await redis.get(`ratelimit:${key}`);
+ * const entry = data ? JSON.parse(data) : null;
+ * ```
+ */
+const authRateLimitStore = new Map();
+/**
+ * Cleanup interval reference
+ */
+let cleanupInterval = null;
+/**
+ * Start periodic cleanup of expired entries
+ */
+function startCleanup() {
+    if (cleanupInterval)
+        return;
+    cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [key, entry] of authRateLimitStore.entries()) {
+            // Remove if both window and lockout have expired
+            const windowExpired = entry.windowResetAt <= now;
+            const lockoutExpired = !entry.lockoutUntil || entry.lockoutUntil <= now;
+            if (windowExpired && lockoutExpired) {
+                authRateLimitStore.delete(key);
+            }
+        }
+    }, 60000); // Run every minute
+}
+/**
+ * Stop cleanup interval (for testing)
+ */
+export function stopAuthRateLimitCleanup() {
+    if (cleanupInterval) {
+        clearInterval(cleanupInterval);
+        cleanupInterval = null;
+    }
+}
+/**
+ * Clear all rate limit entries (for testing)
+ */
+export function clearAuthRateLimitStore() {
+    authRateLimitStore.clear();
+}
+// Start cleanup on module load
+startCleanup();
+// ============================================================================
+// Auth Rate Limiter
+// ============================================================================
+/**
+ * Creates an authentication rate limiter
+ *
+ * This factory returns rate limit middlewares configured for different
+ * auth operations with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const authRateLimiter = createAuthRateLimiter({
+ *   login: { maxAttempts: 5, windowMs: 15 * 60 * 1000 },
+ *   register: { maxAttempts: 3, windowMs: 60 * 60 * 1000 },
+ * });
+ *
+ * // Apply to procedures
+ * const login = procedure()
+ *   .use(authRateLimiter.login(ctx => ctx.input.email))
+ *   .mutation(loginHandler);
+ *
+ * const register = procedure()
+ *   .use(authRateLimiter.register())
+ *   .mutation(registerHandler);
+ * ```
+ */
+export function createAuthRateLimiter(config = {}) {
+    // Default configurations
+    const loginConfig = {
+        maxAttempts: config.login?.maxAttempts ?? 5,
+        windowMs: config.login?.windowMs ?? 15 * 60 * 1000, // 15 minutes
+        lockoutDurationMs: config.login?.lockoutDurationMs ?? 15 * 60 * 1000,
+        keyGenerator: config.login?.keyGenerator ?? defaultKeyGenerator,
+        message: config.login?.message ?? 'Too many login attempts. Please try again later.',
+        progressiveBackoff: config.login?.progressiveBackoff ?? true,
+    };
+    const registerConfig = {
+        maxAttempts: config.register?.maxAttempts ?? 3,
+        windowMs: config.register?.windowMs ?? 60 * 60 * 1000, // 1 hour
+        lockoutDurationMs: config.register?.lockoutDurationMs ?? 60 * 60 * 1000,
+        keyGenerator: config.register?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
+        message: config.register?.message ?? 'Too many registration attempts. Please try again later.',
+        progressiveBackoff: config.register?.progressiveBackoff ?? false,
+    };
+    const passwordResetConfig = {
+        maxAttempts: config.passwordReset?.maxAttempts ?? 3,
+        windowMs: config.passwordReset?.windowMs ?? 60 * 60 * 1000, // 1 hour
+        lockoutDurationMs: config.passwordReset?.lockoutDurationMs ?? 60 * 60 * 1000,
+        keyGenerator: config.passwordReset?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
+        message: config.passwordReset?.message ?? 'Too many password reset attempts. Please try again later.',
+        progressiveBackoff: config.passwordReset?.progressiveBackoff ?? false,
+    };
+    const refreshConfig = {
+        maxAttempts: config.refresh?.maxAttempts ?? 10,
+        windowMs: config.refresh?.windowMs ?? 60 * 1000, // 1 minute
+        lockoutDurationMs: config.refresh?.lockoutDurationMs ?? 60 * 1000,
+        keyGenerator: config.refresh?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
+        message: config.refresh?.message ?? 'Too many token refresh attempts. Please try again later.',
+        progressiveBackoff: config.refresh?.progressiveBackoff ?? false,
+    };
+    return {
+        /**
+         * Rate limiter for login attempts
+         *
+         * @param identifierFn - Function to extract identifier (email) from context
+         *
+         * @example
+         * ```typescript
+         * login: procedure()
+         *   .use(authRateLimiter.login((ctx) => (ctx.input as { email: string }).email))
+         *   .input(LoginSchema)
+         *   .mutation(handler)
+         * ```
+         */
+        login: (identifierFn) => {
+            return createRateLimitMiddleware(loginConfig, 'login', identifierFn);
+        },
+        /**
+         * Rate limiter for registration attempts
+         * Uses IP-only by default (no identifier needed)
+         */
+        register: () => {
+            return createRateLimitMiddleware(registerConfig, 'register');
+        },
+        /**
+         * Rate limiter for password reset requests
+         *
+         * @param identifierFn - Optional function to extract identifier (email)
+         */
+        passwordReset: (identifierFn) => {
+            return createRateLimitMiddleware(passwordResetConfig, 'password-reset', identifierFn);
+        },
+        /**
+         * Rate limiter for token refresh
+         */
+        refresh: () => {
+            return createRateLimitMiddleware(refreshConfig, 'refresh');
+        },
+        /**
+         * Record a failed attempt (call after authentication fails)
+         *
+         * This allows tracking failures even when rate limit hasn't been hit,
+         * enabling account lockout after X failed passwords.
+         *
+         * @param key - Rate limit key (usually IP:email or IP)
+         * @param operation - Operation type for key namespacing
+         */
+        recordFailure: (key, operation) => {
+            const fullKey = `auth:${operation}:${key}`;
+            const config = operation === 'login'
+                ? loginConfig
+                : operation === 'register'
+                    ? registerConfig
+                    : passwordResetConfig;
+            const now = Date.now();
+            const entry = authRateLimitStore.get(fullKey);
+            if (!entry || entry.windowResetAt <= now) {
+                // Start new window
+                authRateLimitStore.set(fullKey, {
+                    attempts: 1,
+                    windowResetAt: now + config.windowMs,
+                    lockoutUntil: null,
+                    lockoutCount: entry?.lockoutCount ?? 0,
+                });
+            }
+            else {
+                // Increment in current window
+                entry.attempts++;
+                // Check if lockout should trigger
+                if (entry.attempts >= config.maxAttempts) {
+                    const lockoutMultiplier = config.progressiveBackoff ? 2 ** entry.lockoutCount : 1;
+                    entry.lockoutUntil = now + config.lockoutDurationMs * lockoutMultiplier;
+                    entry.lockoutCount++;
+                }
+            }
+        },
+        /**
+         * Reset rate limit for a key (call after successful auth)
+         */
+        resetLimit: (key, operation) => {
+            const fullKey = `auth:${operation}:${key}`;
+            authRateLimitStore.delete(fullKey);
+        },
+        /**
+         * Check if a key is currently locked out
+         */
+        isLockedOut: (key, operation) => {
+            const fullKey = `auth:${operation}:${key}`;
+            const entry = authRateLimitStore.get(fullKey);
+            if (!entry || !entry.lockoutUntil)
+                return false;
+            if (entry.lockoutUntil <= Date.now()) {
+                // Lockout expired
+                return false;
+            }
+            return true;
+        },
+        /**
+         * Get remaining attempts for a key
+         */
+        getRemainingAttempts: (key, operation) => {
+            const fullKey = `auth:${operation}:${key}`;
+            const config = operation === 'login'
+                ? loginConfig
+                : operation === 'register'
+                    ? registerConfig
+                    : operation === 'refresh'
+                        ? refreshConfig
+                        : passwordResetConfig;
+            const entry = authRateLimitStore.get(fullKey);
+            if (!entry || entry.windowResetAt <= Date.now()) {
+                return config.maxAttempts;
+            }
+            return Math.max(0, config.maxAttempts - entry.attempts);
+        },
+    };
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Default key generator combining IP and identifier
+ */
+function defaultKeyGenerator(ctx, identifier) {
+    const ip = ctx.request.ip ?? 'unknown';
+    return identifier ? `${ip}:${identifier.toLowerCase()}` : ip;
+}
+/**
+ * Creates the actual rate limit middleware
+ */
+function createRateLimitMiddleware(config, operation, identifierFn) {
+    return async ({ ctx, input, next }) => {
+        const now = Date.now();
+        // Generate rate limit key
+        const identifier = identifierFn ? identifierFn({ ...ctx, input }) : undefined;
+        const baseKey = config.keyGenerator(ctx, identifier);
+        const key = `auth:${operation}:${baseKey}`;
+        // Get or create entry
+        let entry = authRateLimitStore.get(key);
+        // Check if currently locked out
+        if (entry?.lockoutUntil && entry.lockoutUntil > now) {
+            const retryAfter = Math.ceil((entry.lockoutUntil - now) / 1000);
+            // Set headers
+            ctx.reply.header('X-RateLimit-Limit', String(config.maxAttempts));
+            ctx.reply.header('X-RateLimit-Remaining', '0');
+            ctx.reply.header('X-RateLimit-Reset', String(Math.ceil(entry.lockoutUntil / 1000)));
+            ctx.reply.header('Retry-After', String(retryAfter));
+            throw new AuthError(`${config.message} Try again in ${formatDuration(retryAfter * 1000)}.`, 429, 'RATE_LIMIT_EXCEEDED');
+        }
+        // Clean up expired window
+        if (entry && entry.windowResetAt <= now) {
+            // Preserve lockout count for progressive backoff
+            const lockoutCount = entry.lockoutCount;
+            entry = {
+                attempts: 0,
+                windowResetAt: now + config.windowMs,
+                lockoutUntil: null,
+                lockoutCount,
+            };
+            authRateLimitStore.set(key, entry);
+        }
+        // Initialize if no entry
+        if (!entry) {
+            entry = {
+                attempts: 0,
+                windowResetAt: now + config.windowMs,
+                lockoutUntil: null,
+                lockoutCount: 0,
+            };
+            authRateLimitStore.set(key, entry);
+        }
+        // Increment attempt count
+        entry.attempts++;
+        // Set rate limit headers
+        const remaining = Math.max(0, config.maxAttempts - entry.attempts);
+        ctx.reply.header('X-RateLimit-Limit', String(config.maxAttempts));
+        ctx.reply.header('X-RateLimit-Remaining', String(remaining));
+        ctx.reply.header('X-RateLimit-Reset', String(Math.ceil(entry.windowResetAt / 1000)));
+        // Check if limit exceeded
+        if (entry.attempts > config.maxAttempts) {
+            // Apply lockout
+            const lockoutMultiplier = config.progressiveBackoff ? 2 ** entry.lockoutCount : 1;
+            entry.lockoutUntil = now + config.lockoutDurationMs * lockoutMultiplier;
+            entry.lockoutCount++;
+            const retryAfter = Math.ceil((entry.lockoutUntil - now) / 1000);
+            ctx.reply.header('Retry-After', String(retryAfter));
+            throw new AuthError(`${config.message} Try again in ${formatDuration(retryAfter * 1000)}.`, 429, 'RATE_LIMIT_EXCEEDED');
+        }
+        return next();
+    };
+}
+/**
+ * Format duration in human-readable form
+ */
+function formatDuration(ms) {
+    const seconds = Math.ceil(ms / 1000);
+    if (seconds < 60)
+        return `${seconds} second${seconds !== 1 ? 's' : ''}`;
+    const minutes = Math.ceil(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} minute${minutes !== 1 ? 's' : ''}`;
+    const hours = Math.ceil(minutes / 60);
+    return `${hours} hour${hours !== 1 ? 's' : ''}`;
+}
+// ============================================================================
+// Convenience Export
+// ============================================================================
+/**
+ * Pre-configured auth rate limiter with sensible defaults
+ *
+ * @example
+ * ```typescript
+ * import { authRateLimiter } from '@veloxts/auth';
+ *
+ * const login = procedure()
+ *   .use(authRateLimiter.login((ctx) => ctx.input.email))
+ *   .mutation(handler);
+ * ```
+ */
+export const authRateLimiter = createAuthRateLimiter();
+//# sourceMappingURL=rate-limit.js.map