@draftlab/auth 0.15.0 → 0.16.0

package/dist/provider/password.d.mts

@@ -1,412 +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 };