@guren/server 1.0.0-rc.25 → 1.0.0-rc.26

package/dist/chunk-UY3AZSYL.js

@@ -0,0 +1,14 @@
+// src/redis/client.ts
+import Redis from "ioredis";
+function createRedisClient(options = {}) {
+  const { url, ...redisOptions } = options;
+  if (url) {
+    return new Redis(url, redisOptions);
+  }
+  return new Redis(redisOptions);
+}
+
+export {
+  Redis,
+  createRedisClient
+};

package/dist/client-CKXJLsTe.d.ts

@@ -0,0 +1,232 @@
+import { Context, MiddlewareHandler } from 'hono';
+import Redis, { RedisOptions } from 'ioredis';
+
+/**
+ * Rate limit entry stored in the backing store.
+ */
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Store interface for rate limit data.
+ * Implement this for Redis or database-backed storage.
+ */
+interface RateLimitStore {
+    /**
+     * Get the current rate limit entry for a key.
+     */
+    get(key: string): Promise<RateLimitEntry | null>;
+    /**
+     * Increment the count for a key and return the new entry.
+     * If the key doesn't exist, create it with count=1.
+     */
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    /**
+     * Reset the count for a key.
+     */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Base class for in-memory rate limit stores with automatic cleanup.
+ */
+declare abstract class BaseMemoryStore implements RateLimitStore {
+    protected cleanupInterval?: ReturnType<typeof setInterval>;
+    constructor(cleanupIntervalMs?: number);
+    abstract get(key: string): Promise<RateLimitEntry | null>;
+    abstract increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    abstract reset(key: string): Promise<void>;
+    abstract cleanup(): void;
+    abstract clear(): void;
+    abstract get size(): number;
+    destroy(): void;
+}
+/**
+ * In-memory rate limit store.
+ * Suitable for single-process development, not for production clusters.
+ */
+declare class MemoryRateLimitStore extends BaseMemoryStore {
+    private entries;
+    get(key: string): Promise<RateLimitEntry | null>;
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    reset(key: string): Promise<void>;
+    cleanup(): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Configuration options for rate limiting.
+ */
+interface RateLimitOptions {
+    /**
+     * Maximum number of requests allowed in the time window.
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Time window in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Function to extract the rate limit key from the request.
+     * Defaults to using the client IP address.
+     */
+    keyGenerator?: (ctx: Context) => string | Promise<string>;
+    /**
+     * Rate limit store implementation.
+     * Defaults to in-memory store.
+     */
+    store?: RateLimitStore;
+    /**
+     * Whether to skip rate limiting for certain requests.
+     */
+    skip?: (ctx: Context) => boolean | Promise<boolean>;
+    /**
+     * Custom handler when rate limit is exceeded.
+     */
+    onRateLimited?: (ctx: Context, retryAfter: number) => Response | Promise<Response>;
+    /**
+     * Whether to add rate limit headers to all responses.
+     * @default true
+     */
+    headers?: boolean;
+    /**
+     * Custom message when rate limit is exceeded.
+     * @default 'Too many requests, please try again later.'
+     */
+    message?: string;
+    /**
+     * HTTP status code when rate limit is exceeded.
+     * @default 429
+     */
+    statusCode?: number;
+    /**
+     * Prefix for rate limit keys.
+     * @default 'rl:'
+     */
+    keyPrefix?: string;
+    /**
+     * Trust reverse-proxy headers for client IP resolution, checked in order:
+     * `CF-Connecting-IP`, `True-Client-IP`, `X-Real-IP`, then the first entry
+     * of `X-Forwarded-For`. Falls back to `server.requestIP()` when none are set.
+     *
+     * Enable ONLY when every request passes through a proxy that sets or strips
+     * these headers — on direct deployments clients can spoof them to bypass
+     * per-client limits. Ignored when a custom `keyGenerator` is supplied.
+     * @default false
+     */
+    trustProxy?: boolean;
+}
+/**
+ * Create a rate limiting middleware.
+ *
+ * @example
+ * ```ts
+ * // Basic usage - 100 requests per minute per IP
+ * app.use('*', createRateLimitMiddleware())
+ *
+ * // Stricter limit for login endpoint
+ * router.post('/login', [AuthController, 'login'],
+ *   createRateLimitMiddleware({
+ *     limit: 5,
+ *     windowMs: 15 * 60 * 1000, // 15 minutes
+ *   })
+ * )
+ *
+ * // Custom key based on authenticated user
+ * app.use('/api/*', createRateLimitMiddleware({
+ *   limit: 1000,
+ *   windowMs: 60 * 60 * 1000, // 1 hour
+ *   keyGenerator: async (ctx) => {
+ *     const user = await ctx.get('user')
+ *     return user?.id?.toString() ?? defaultKeyGenerator(ctx)
+ *   },
+ * }))
+ * ```
+ */
+declare function createRateLimitMiddleware(options?: RateLimitOptions): MiddlewareHandler;
+/**
+ * Rate limit result information.
+ */
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: Date;
+    isLimited: boolean;
+}
+/**
+ * Get rate limit information for a key without incrementing.
+ *
+ * @example
+ * ```ts
+ * const info = await getRateLimitInfo('user:123', store, { limit: 100 })
+ * console.log(`${info.remaining} requests remaining`)
+ * ```
+ */
+declare function getRateLimitInfo(key: string, store: RateLimitStore, options?: {
+    limit: number;
+    keyPrefix?: string;
+}): Promise<RateLimitInfo>;
+/**
+ * Reset rate limit for a specific key.
+ *
+ * @example
+ * ```ts
+ * // Reset rate limit after successful captcha
+ * await resetRateLimit(clientIp, store)
+ * ```
+ */
+declare function resetRateLimit(key: string, store: RateLimitStore, options?: {
+    keyPrefix?: string;
+}): Promise<void>;
+/**
+ * Sliding window rate limit store.
+ * More accurate than fixed window but uses more memory.
+ */
+declare class SlidingWindowRateLimitStore extends BaseMemoryStore {
+    private requests;
+    get(key: string): Promise<RateLimitEntry | null>;
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    reset(key: string): Promise<void>;
+    cleanup(): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Options for creating a Redis client.
+ */
+interface RedisClientOptions extends RedisOptions {
+    /**
+     * Redis connection URL (e.g., 'redis://localhost:6379').
+     * If provided, overrides host/port/password.
+     */
+    url?: string;
+    /**
+     * Key prefix for all operations.
+     * @default ''
+     */
+    keyPrefix?: string;
+}
+/**
+ * Create a Redis client with the given options.
+ *
+ * @example
+ * ```ts
+ * // Using URL
+ * const redis = createRedisClient({ url: 'redis://localhost:6379' })
+ *
+ * // Using host/port
+ * const redis = createRedisClient({ host: 'localhost', port: 6379 })
+ *
+ * // With key prefix
+ * const redis = createRedisClient({
+ *   url: process.env.REDIS_URL,
+ *   keyPrefix: 'myapp:',
+ * })
+ * ```
+ */
+declare function createRedisClient(options?: RedisClientOptions): Redis;
+
+export { MemoryRateLimitStore as M, type RateLimitStore as R, SlidingWindowRateLimitStore as S, type RateLimitEntry as a, type RedisClientOptions as b, createRedisClient as c, type RateLimitInfo as d, type RateLimitOptions as e, createRateLimitMiddleware as f, getRateLimitInfo as g, resetRateLimit as r };

package/dist/email-verification-CAeArjui.d.ts

@@ -0,0 +1,327 @@
+import { A as Authenticatable, U as UserProvider } from './api-token-BSSCLlFW.js';
+
+/**
+ * Hash a token using SHA-256 or SHA-512.
+ */
+declare function hashToken(token: string, algorithm?: 'sha256' | 'sha512'): string;
+/**
+ * Generate a secure random token.
+ */
+declare function generateToken(length?: number): string;
+/**
+ * Generate a random ID (16 bytes = 32 hex chars).
+ */
+declare function generateId(): string;
+/**
+ * Securely compare two hex strings using timing-safe comparison.
+ */
+declare function secureCompare(a: string, b: string): boolean;
+/**
+ * Securely compare two arbitrary strings using timing-safe comparison.
+ * Unlike secureCompare, this works with any string encoding (UUIDs, tokens, etc.).
+ */
+declare function secureStringCompare(a: string, b: string): boolean;
+/**
+ * Build a URL with token and optional email parameters.
+ */
+declare function buildTokenUrl(baseUrl: string, token: string, email?: string): string;
+/**
+ * Parse a URL to extract token and email parameters.
+ */
+declare function parseTokenUrl(url: string): {
+    token: string | null;
+    email: string | null;
+};
+
+/**
+ * Configuration for password reset tokens.
+ */
+interface PasswordResetConfig {
+    /** Token expiration time in milliseconds (default: 1 hour) */
+    expiresIn?: number;
+    /** Token byte length before encoding (default: 32) */
+    tokenLength?: number;
+}
+/**
+ * Storage interface for password reset tokens.
+ */
+interface PasswordResetTokenStore {
+    /** Store a token ID with associated email and expiration */
+    store(tokenId: string, email: string, expiresAt: Date): Promise<void>;
+    /** Find email by token ID, returns null if not found or expired */
+    find(tokenId: string): Promise<{
+        email: string;
+        expiresAt: Date;
+    } | null>;
+    /** Delete a token ID from storage */
+    delete(tokenId: string): Promise<void>;
+    /** Delete all tokens for an email */
+    deleteForEmail(email: string): Promise<void>;
+}
+/**
+ * In-memory token store for testing and development.
+ */
+declare class MemoryPasswordResetStore implements PasswordResetTokenStore {
+    private tokens;
+    store(tokenId: string, email: string, expiresAt: Date): Promise<void>;
+    find(tokenId: string): Promise<{
+        email: string;
+        expiresAt: Date;
+    } | null>;
+    delete(tokenId: string): Promise<void>;
+    deleteForEmail(email: string): Promise<void>;
+    /** Clear all tokens (useful for testing) */
+    clear(): void;
+}
+/**
+ * Result of creating a password reset token.
+ */
+interface PasswordResetTokenResult {
+    /** The plain-text token to send to the user (via email) */
+    token: string;
+    /** The token ID stored in the backing store */
+    tokenId: string;
+    /** When the token expires */
+    expiresAt: Date;
+}
+/**
+ * Create a password reset token for a user.
+ *
+ * @param email - The user's email address
+ * @param store - The token storage implementation
+ * @param config - Optional configuration
+ * @returns The token result containing plain token and hash
+ */
+declare function createPasswordResetToken(email: string, store: PasswordResetTokenStore, config?: PasswordResetConfig): Promise<PasswordResetTokenResult>;
+/**
+ * Verify a password reset token.
+ *
+ * @param token - The plain-text token from the reset URL
+ * @param store - The token storage implementation
+ * @param config - Optional configuration (must match createPasswordResetToken config)
+ * @returns The email if token is valid, null otherwise
+ */
+declare function verifyPasswordResetToken(token: string, store: PasswordResetTokenStore, _config?: PasswordResetConfig): Promise<string | null>;
+/**
+ * Complete a password reset by updating the user's password and invalidating the token.
+ *
+ * @param token - The plain-text token from the reset URL
+ * @param newPassword - The new password (should be validated by caller)
+ * @param store - The token storage implementation
+ * @param provider - The user provider to look up and update the user
+ * @param updatePassword - Function to update the user's password
+ * @param config - Optional configuration
+ * @returns The user if reset was successful, null if token is invalid
+ */
+declare function completePasswordReset<T extends Authenticatable>(token: string, newPassword: string, store: PasswordResetTokenStore, provider: UserProvider<T>, updatePassword: (user: T, password: string) => Promise<void>, _config?: PasswordResetConfig): Promise<T | null>;
+/**
+ * Build a password reset URL from a base URL and token.
+ */
+declare const buildPasswordResetUrl: typeof buildTokenUrl;
+/**
+ * Parse a password reset URL to extract the token and optional email.
+ */
+declare const parsePasswordResetUrl: typeof parseTokenUrl;
+
+/**
+ * Email verification token data stored in the backing store.
+ * Only the hashed token is stored for security.
+ */
+interface EmailVerificationToken {
+    email: string;
+    tokenId: string;
+    expiresAt: Date;
+    createdAt: Date;
+}
+/**
+ * Store interface for email verification tokens.
+ * Implement this to use database-backed storage.
+ */
+interface EmailVerificationTokenStore {
+    /**
+     * Store a new verification token.
+     */
+    store(token: EmailVerificationToken): Promise<void>;
+    /**
+     * Find a token by its opaque token ID.
+     */
+    findByTokenId(tokenId: string): Promise<EmailVerificationToken | null>;
+    /**
+     * Delete a token by its opaque token ID.
+     */
+    delete(tokenId: string): Promise<void>;
+    /**
+     * Delete all tokens for a given email.
+     */
+    deleteForEmail(email: string): Promise<void>;
+}
+/**
+ * In-memory store for testing purposes.
+ * Do NOT use in production - tokens will be lost on restart.
+ */
+declare class MemoryEmailVerificationStore implements EmailVerificationTokenStore {
+    private tokens;
+    store(token: EmailVerificationToken): Promise<void>;
+    findByTokenId(tokenId: string): Promise<EmailVerificationToken | null>;
+    delete(tokenId: string): Promise<void>;
+    deleteForEmail(email: string): Promise<void>;
+    /**
+     * Clear all tokens (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Get the count of stored tokens (useful for testing).
+     */
+    get size(): number;
+}
+/**
+ * Configuration options for email verification.
+ */
+interface EmailVerificationConfig {
+    /**
+     * Token expiration time in milliseconds.
+     * @default 86400000 (24 hours)
+     */
+    expiresIn?: number;
+    /**
+     * Token byte length (before hex encoding).
+     * @default 32
+     */
+    tokenLength?: number;
+}
+/**
+ * Result of creating an email verification token.
+ */
+interface EmailVerificationTokenResult {
+    /**
+     * The raw token to send to the user via email.
+     * This is NOT stored - only the hash is stored.
+     */
+    token: string;
+    /**
+     * When the token expires.
+     */
+    expiresAt: Date;
+}
+/**
+ * Create a new email verification token.
+ *
+ * @param email - The email address to verify
+ * @param store - Token store implementation
+ * @param config - Optional configuration
+ * @returns The raw token to send via email
+ *
+ * @example
+ * ```ts
+ * const { token, expiresAt } = await createEmailVerificationToken(
+ *   user.email,
+ *   verificationStore
+ * )
+ *
+ * // Send email with verification link
+ * await sendEmail({
+ *   to: user.email,
+ *   subject: 'Verify your email',
+ *   html: `<a href="${buildVerificationUrl(baseUrl, token)}">Verify Email</a>`,
+ * })
+ * ```
+ */
+declare function createEmailVerificationToken(email: string, store: EmailVerificationTokenStore, config?: EmailVerificationConfig): Promise<EmailVerificationTokenResult>;
+/**
+ * Verify an email verification token.
+ *
+ * @param token - The raw token from the verification link
+ * @param store - Token store implementation
+ * @param config - Optional configuration (not currently used, reserved for future)
+ * @returns The email address if valid, null if invalid or expired
+ *
+ * @example
+ * ```ts
+ * const email = await verifyEmailToken(token, verificationStore)
+ *
+ * if (!email) {
+ *   return ctx.json({ error: 'Invalid or expired token' }, 400)
+ * }
+ *
+ * // Mark user as verified
+ * await User.update({ email }, { emailVerifiedAt: new Date() })
+ * ```
+ */
+declare function verifyEmailToken(token: string, store: EmailVerificationTokenStore, _config?: EmailVerificationConfig): Promise<string | null>;
+/**
+ * Complete email verification by consuming the token.
+ *
+ * @param token - The raw token from the verification link
+ * @param store - Token store implementation
+ * @param markVerified - Function to mark the user as verified
+ * @returns The result of markVerified if successful, null if token invalid
+ *
+ * @example
+ * ```ts
+ * const result = await completeEmailVerification(
+ *   token,
+ *   verificationStore,
+ *   async (email) => {
+ *     await User.update({ email }, { emailVerifiedAt: new Date() })
+ *     return User.findByEmail(email)
+ *   }
+ * )
+ *
+ * if (!result) {
+ *   return ctx.json({ error: 'Invalid or expired token' }, 400)
+ * }
+ *
+ * return ctx.redirect('/dashboard')
+ * ```
+ */
+declare function completeEmailVerification<T>(token: string, store: EmailVerificationTokenStore, markVerified: (email: string) => Promise<T>): Promise<T | null>;
+/**
+ * Build a verification URL.
+ */
+declare const buildVerificationUrl: typeof buildTokenUrl;
+/**
+ * Parse a verification URL to extract token and email.
+ */
+declare const parseVerificationUrl: typeof parseTokenUrl;
+/**
+ * Check if a user's email is verified.
+ * Helper function for use with User models.
+ *
+ * @param user - User object with emailVerifiedAt field
+ * @returns true if verified, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (!isEmailVerified(user)) {
+ *   return ctx.redirect('/verify-email')
+ * }
+ * ```
+ */
+declare function isEmailVerified(user: {
+    emailVerifiedAt?: Date | null;
+} | null): boolean;
+/**
+ * Middleware factory to require verified email.
+ *
+ * @param options - Configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * router.get('/dashboard', [DashboardController, 'index'],
+ *   requireAuthenticated(),
+ *   requireVerifiedEmail({ redirectTo: '/verify-email' })
+ * )
+ * ```
+ */
+declare function requireVerifiedEmail(options?: {
+    redirectTo?: string;
+    getUser?: (ctx: unknown) => Promise<{
+        emailVerifiedAt?: Date | null;
+    } | null>;
+}): (ctx: {
+    get: (key: string) => unknown;
+    redirect: (url: string) => Response;
+}, next: () => Promise<void>) => Promise<Response | undefined>;
+
+export { type EmailVerificationTokenStore as E, MemoryEmailVerificationStore as M, type PasswordResetTokenStore as P, type EmailVerificationToken as a, type EmailVerificationConfig as b, type EmailVerificationTokenResult as c, MemoryPasswordResetStore as d, type PasswordResetConfig as e, type PasswordResetTokenResult as f, buildPasswordResetUrl as g, buildVerificationUrl as h, completeEmailVerification as i, completePasswordReset as j, createEmailVerificationToken as k, createPasswordResetToken as l, isEmailVerified as m, parseVerificationUrl as n, verifyPasswordResetToken as o, parsePasswordResetUrl as p, buildTokenUrl as q, requireVerifiedEmail as r, generateId as s, generateToken as t, hashToken as u, verifyEmailToken as v, parseTokenUrl as w, secureCompare as x, secureStringCompare as y };