@guren/server 1.0.0-rc.9 → 1.1.0

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 };