@draftlab/auth 0.15.1 → 0.16.0

package/dist/provider/password.d.mts

@@ -1,384 +0,0 @@
-import { Provider } from "./provider.mjs";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-
-//#region src/provider/password.d.ts
-/**
- * Password-based authentication provider for Draft Auth.
- * Supports user registration, login, and password changes with email verification.
- *
- * ## Quick Setup
- *
- * ```ts
- * import { PasswordUI } from "@draftlab/auth/ui/password"
- * import { PasswordProvider } from "@draftlab/auth/provider/password"
- *
- * export default issuer({
- *   providers: {
- *     password: PasswordProvider(
- *       PasswordUI({
- *         copy: {
- *           error_email_taken: "This email is already taken."
- *         },
- *         sendCode: async (email, code) => {
- *           await sendEmail(email, `Your verification code: ${code}`)
- *         }
- *       })
- *     )
- *   }
- * })
- * ```
- *
- * ## Custom UI Implementation
- *
- * For full control over the user interface, implement the handlers directly:
- *
- * ```ts
- * PasswordProvider({
- *   login: async (req, form, error) => {
- *     return new Response(renderLoginPage(form, error))
- *   },
- *   register: async (req, state, form, error) => {
- *     return new Response(renderRegisterPage(state, form, error))
- *   },
- *   change: async (req, state, form, error) => {
- *     return new Response(renderChangePage(state, form, error))
- *   },
- *   sendCode: async (email, code) => {
- *     await yourEmailService.send(email, code)
- *   }
- * })
- * ```
- *
- * ## Features
- *
- * - **Email verification**: Secure registration with email confirmation codes
- * - **Password hashing**: Built-in Scrypt and PBKDF2 support with secure defaults
- * - **Password validation**: Configurable password strength requirements
- * - **Password reset**: Secure password change flow with email verification
- * - **Session management**: Automatic invalidation on password changes
- *
- * @packageDocumentation
- */
-/**
- * Password hashing interface for secure password storage.
- * Implement this interface to use custom password hashing algorithms.
- *
- * @template T - The hash storage format (usually an object with hash, salt, and params)
- * @internal
- */
-interface PasswordHasher<T> {
-  /**
-       * Hashes a plaintext password for secure storage.
-       *
-       * @param password - The plaintext password to hash
-       * @returns Promise resolving to the hash data structure
-       */
-  hash(password: string): Promise<T>;
-  /**
-       * Verifies a plaintext password against a stored hash.
-       *
-       * @param password - The plaintext password to verify
-       * @param compare - The stored hash data to compare against
-       * @returns Promise resolving to true if password matches
-       */
-  verify(password: string, compare: T): Promise<boolean>;
-}
-/**
- * Configuration for the password authentication provider.
- */
-interface PasswordConfig {
-  /**
-       * Length of verification codes sent to users.
-       * @internal
-       * @default 6
-       */
-  readonly length?: number;
-  /**
-       * Password hashing implementation to use.
-       * @internal
-       * @default ScryptHasher()
-       */
-  readonly hasher?: PasswordHasher<unknown>;
-  /**
-       * Request handler for rendering the login screen.
-       * Receives the request, optional form data, and any login errors.
-       *
-       * @param req - The HTTP request object
-       * @param form - Form data from POST requests (if any)
-       * @param error - Login error to display (if any)
-       * @returns Promise resolving to the login page response
-       *
-       * @example
-       * ```ts
-       * login: async (req, form, error) => {
-       *   const html = renderLoginPage({
-       *     email: form?.get('email'),
-       *     error: error?.type
-       *   })
-       *   return new Response(html, {
-       *     headers: { 'Content-Type': 'text/html' }
-       *   })
-       * }
-       * ```
-       */
-  login: (req: Request, form?: FormData, error?: PasswordLoginError) => Promise<Response>;
-  /**
-       * Request handler for rendering the registration screen.
-       * Handles both initial registration form and email verification.
-       *
-       * @param req - The HTTP request object
-       * @param state - Current registration state (start or code verification)
-       * @param form - Form data from POST requests (if any)
-       * @param error - Registration error to display (if any)
-       * @returns Promise resolving to the registration page response
-       *
-       * @example
-       * ```ts
-       * register: async (req, state, form, error) => {
-       *   if (state.type === 'start') {
-       *     return new Response(renderRegistrationForm(error))
-       *   } else {
-       *     return new Response(renderCodeVerification(state.email, error))
-       *   }
-       * }
-       * ```
-       */
-  register: (req: Request, state: PasswordRegisterState, form?: FormData, error?: PasswordRegisterError) => Promise<Response>;
-  /**
-       * Request handler for rendering the password change screen.
-       * Handles email entry, code verification, and password update steps.
-       *
-       * @param req - The HTTP request object
-       * @param state - Current password change state
-       * @param form - Form data from POST requests (if any)
-       * @param error - Password change error to display (if any)
-       * @returns Promise resolving to the password change page response
-       *
-       * @example
-       * ```ts
-       * change: async (req, state, form, error) => {
-       *   switch (state.type) {
-       *     case 'start':
-       *       return new Response(renderEmailForm(error))
-       *     case 'code':
-       *       return new Response(renderCodeForm(state.email, error))
-       *     case 'update':
-       *       return new Response(renderPasswordForm(error))
-       *   }
-       * }
-       * ```
-       */
-  change: (req: Request, state: PasswordChangeState, form?: FormData, error?: PasswordChangeError) => Promise<Response>;
-  /**
-       * Callback for sending verification codes to users via email.
-       * Implement this to integrate with your email service provider.
-       *
-       * The context parameter indicates why the code is being sent:
-       * - "register": User is registering for the first time
-       * - "register:resend": User requested to resend registration code
-       * - "reset": User is resetting their password
-       * - "reset:resend": User requested to resend password reset code
-       *
-       * @param email - The recipient's email address
-       * @param code - The verification code to send
-       * @param context - The context of why the code is being sent
-       * @returns Promise that resolves when email is sent
-       *
-       * @example
-       * ```ts
-       * sendCode: async (email, code, context) => {
-       *   const templates = {
-       *     "register": {
-       *       subject: "Welcome! Verify your email",
-       *       body: `Welcome! Your verification code is: ${code}`
-       *     },
-       *     "register:resend": {
-       *       subject: "Your verification code (resent)",
-       *       body: `Here's your code again: ${code}`
-       *     },
-       *     "reset": {
-       *       subject: "Reset your password",
-       *       body: `Your password reset code is: ${code}`
-       *     },
-       *     "reset:resend": {
-       *       subject: "Password reset code (resent)",
-       *       body: `Here's your reset code again: ${code}`
-       *     }
-       *   }
-       *
-       *   const template = templates[context]
-       *   await emailService.send({
-       *     to: email,
-       *     subject: template.subject,
-       *     text: template.body
-       *   })
-       * }
-       * ```
-       */
-  sendCode: (email: string, code: string, context: "register" | "register:resend" | "reset" | "reset:resend") => Promise<void>;
-  /**
-       * Optional password validation function or schema.
-       * Can be either a validation function or a standard-schema validator.
-       *
-       * @param password - The password to validate
-       * @returns Error message if invalid, undefined if valid
-       *
-       * @example
-       * ```ts
-       * // Function-based validation
-       * validatePassword: (password) => {
-       *   if (password.length < 8) return "Password must be at least 8 characters"
-       *   if (!/[A-Z]/.test(password)) return "Password must contain uppercase letter"
-       *   return undefined
-       * }
-       *
-       * // Schema-based validation
-       * validatePassword: pipe(
-       *   string(),
-       *   minLength(8, "Password must be at least 8 characters"),
-       *   regex(/[A-Z]/, "Password must contain uppercase letter")
-       * )
-       * ```
-       */
-  readonly validatePassword?: StandardSchemaV1 | ((password: string) => Promise<string | undefined> | string | undefined);
-}
-/**
- * Registration flow states that determine which UI to show.
- * The registration process moves through these states sequentially.
- */
-type PasswordRegisterState = {
-  /** Initial state: user enters email and password */readonly type: "start";
-} | {
-  /** Code verification state: user enters emailed verification code */readonly type: "code"; /** The verification code sent to the user */
-  readonly code: string; /** The user's email address */
-  readonly email: string; /** The hashed password (ready for storage) */
-  readonly password: unknown;
-};
-/**
- * Possible errors during user registration.
- */
-type PasswordRegisterError = {
-  /** The verification code entered is incorrect */readonly type: "invalid_code";
-} | {
-  /** The email address is already registered */readonly type: "email_taken";
-} | {
-  /** The email address format is invalid */readonly type: "invalid_email";
-} | {
-  /** The password does not meet requirements */readonly type: "invalid_password";
-} | {
-  /** Password and confirmation password don't match */readonly type: "password_mismatch";
-} | {
-  /** Custom validation error from validatePassword callback */readonly type: "validation_error";
-  readonly message?: string;
-};
-/**
- * Password change flow states that determine which UI to show.
- */
-type PasswordChangeState = {
-  /** Initial state: user enters their email address */readonly type: "start"; /** URL to redirect to after successful password change */
-  readonly redirect: string;
-} | {
-  /** Code verification state: user enters emailed verification code */readonly type: "code"; /** The verification code sent to the user */
-  readonly code: string; /** The user's email address */
-  readonly email: string; /** URL to redirect to after completion */
-  readonly redirect: string;
-} | {
-  /** Password update state: user enters new password */readonly type: "update"; /** URL to redirect to after completion */
-  readonly redirect: string; /** The verified email address */
-  readonly email: string;
-};
-/**
- * Possible errors during password changes.
- */
-type PasswordChangeError = {
-  /** The email address format is invalid */readonly type: "invalid_email";
-} | {
-  /** The verification code entered is incorrect */readonly type: "invalid_code";
-} | {
-  /** The new password does not meet requirements */readonly type: "invalid_password";
-} | {
-  /** New password and confirmation don't match */readonly type: "password_mismatch";
-} | {
-  /** Custom validation error from validatePassword callback */readonly type: "validation_error";
-  readonly message: string;
-};
-/**
- * Possible errors during login attempts.
- */
-type PasswordLoginError = {
-  /** The email address format is invalid */readonly type: "invalid_email";
-} | {
-  /** The password is incorrect or email not found */readonly type: "invalid_password";
-};
-/**
- * User data returned by successful password authentication.
- */
-interface PasswordUserData {
-  /** The authenticated user's email address */
-  readonly email: string;
-}
-/**
- * Creates a password authentication provider with email verification.
- * Implements secure registration, login, and password change flows.
- *
- * @param config - Provider configuration including UI handlers and email service
- * @returns Provider instance implementing password authentication
- *
- * @example
- * ```ts
- * const provider = PasswordProvider({
- *   login: async (req, form, error) => {
- *     return new Response(renderLogin(form, error))
- *   },
- *   register: async (req, state, form, error) => {
- *     return new Response(renderRegister(state, form, error))
- *   },
- *   change: async (req, state, form, error) => {
- *     return new Response(renderChange(state, form, error))
- *   },
- *   sendCode: async (email, code) => {
- *     await emailService.send(email, `Code: ${code}`)
- *   },
- *   validatePassword: (pwd) => {
- *     return pwd.length >= 8 ? undefined : "Too short"
- *   }
- * })
- * ```
- */
-declare const PasswordProvider: (config: PasswordConfig) => Provider<PasswordUserData>;
-/**
- * PBKDF2 password hasher with configurable iterations.
- * Good choice for compatibility but slower than Scrypt.
- *
- * @param opts - Configuration options
- * @returns Password hasher using PBKDF2 algorithm
- * @internal
- */
-declare const PBKDF2Hasher: (opts?: {
-  iterations?: number;
-}) => PasswordHasher<{
-  hash: string;
-  salt: string;
-  iterations: number;
-}>;
-/**
- * Scrypt password hasher with secure defaults.
- * Recommended choice for new applications due to memory-hard properties.
- *
- * @param opts - Scrypt parameters (N, r, p)
- * @returns Password hasher using Scrypt algorithm
- * @internal
- */
-declare const ScryptHasher: (opts?: {
-  N?: number;
-  r?: number;
-  p?: number;
-}) => PasswordHasher<{
-  hash: string;
-  salt: string;
-  N: number;
-  r: number;
-  p: number;
-}>;
-//#endregion
-export { PBKDF2Hasher, PasswordChangeError, PasswordChangeState, PasswordConfig, PasswordHasher, PasswordLoginError, PasswordProvider, PasswordRegisterError, PasswordRegisterState, PasswordUserData, ScryptHasher };