@draftlab/auth 0.0.3 → 0.1.0

package/dist/provider/password.d.ts

@@ -1,4 +1,385 @@
-import "../storage-CxKerLlc.js";
-import "../provider-tndlqCzp.js";
-import { PBKDF2Hasher, PasswordChangeError, PasswordChangeState, PasswordConfig, PasswordHasher, PasswordLoginError, PasswordProvider, PasswordRegisterError, PasswordRegisterState, PasswordUserData, ScryptHasher } from "../password-C4KLmO0O.js";
+import { Provider } from "./provider.js";
+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.
+   *
+   * @param email - The recipient's email address
+   * @param code - The verification code to send
+   * @returns Promise that resolves when email is sent
+   *
+   * @example
+   * ```ts
+   * sendCode: async (email, code) => {
+   *   await emailService.send({
+   *     to: email,
+   *     subject: 'Your verification code',
+   *     text: `Your verification code is: ${code}`
+   *   })
+   * }
+   * ```
+   */
+  sendCode: (email: string, code: string) => 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 };

package/dist/provider/password.js

@@ -1,7 +1,7 @@
-import { getRelativeUrl } from "../util-CSdHUFOo.js";
-import { UnknownStateError } from "../error-DgAKK7b2.js";
-import { generateUnbiasedDigits, timingSafeCompare } from "../random-SXMYlaVr.js";
-import { Storage } from "../storage-BEaqEPNQ.js";
+import { getRelativeUrl } from "../util.js";
+import { UnknownStateError } from "../error.js";
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.js";
+import { Storage } from "../storage/storage.js";
 import * as jose from "jose";
 import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
 import { TextEncoder } from "node:util";

package/dist/provider/provider.d.ts

@@ -1,3 +1,227 @@
-import "../storage-CxKerLlc.js";
-import { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError } from "../provider-tndlqCzp.js";
+import { StorageAdapter } from "../storage/storage.js";
+import { Router } from "@draftlab/auth-router";
+import { RouterContext } from "@draftlab/auth-router/types";
+
+//#region src/provider/provider.d.ts
+
+/**
+ * OAuth provider system for Draft Auth.
+ * Defines the interfaces and utilities for implementing authentication providers
+ * that integrate with various OAuth 2.0 services.
+ *
+ * ## Creating a Provider
+ *
+ * ```ts
+ * export const MyProvider = (config: MyConfig): Provider<MyUserData> => ({
+ *   type: "my-provider",
+ *
+ *   init(routes, ctx) {
+ *     routes.get("/authorize", async (c) => {
+ *       // Redirect to provider's auth URL
+ *       return c.redirect(authUrl)
+ *     })
+ *
+ *     routes.get("/callback", async (c) => {
+ *       // Handle callback and extract user data
+ *       const userData = await processCallback(c)
+ *       return await ctx.success(c, userData)
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * ## Using Providers
+ *
+ * ```ts
+ * export default issuer({
+ *   providers: {
+ *     github: GithubProvider({ ... }),
+ *     google: GoogleProvider({ ... })
+ *   }
+ * })
+ * ```
+ */
+/**
+ * Router instance used for provider route definitions.
+ * Providers use this to register their authorization and callback endpoints.
+ */
+type ProviderRoute = Router;
+/**
+ * Authentication provider interface that handles OAuth flows.
+ * Each provider implements authentication with a specific service (GitHub, Google, etc.).
+ *
+ * @template Properties - Type of user data returned by successful authentication
+ */
+interface Provider<Properties = Record<string, unknown>> {
+  /**
+   * Unique identifier for this provider type.
+   * Used in URLs and provider selection UI.
+   *
+   * @example "github", "google", "steam"
+   */
+  readonly type: string;
+  /**
+   * Initializes the provider by registering required routes.
+   * Called during issuer setup to configure authorization and callback endpoints.
+   *
+   * @param route - Router instance for registering provider endpoints
+   * @param options - Provider utilities and configuration
+   *
+   * @example
+   * ```ts
+   * init(routes, ctx) {
+   *   routes.get("/authorize", async (c) => {
+   *     // Redirect to OAuth provider
+   *     return c.redirect(buildAuthUrl())
+   *   })
+   *
+   *   routes.get("/callback", async (c) => {
+   *     // Process callback and return user data
+   *     const userData = await handleCallback(c)
+   *     return await ctx.success(c, userData)
+   *   })
+   * }
+   * ```
+   */
+  init: (route: ProviderRoute, options: ProviderOptions<Properties>) => void;
+}
+/**
+ * Utilities and callbacks provided to providers during initialization.
+ * Contains methods for state management, user flow completion, and storage access.
+ *
+ * @template Properties - Type of user data handled by the provider
+ */
+interface ProviderOptions<Properties> {
+  /**
+   * Name of the provider instance as configured in the issuer.
+   * Corresponds to the key used in the providers object.
+   */
+  readonly name: string;
+  /**
+   * Completes the authentication flow with user data.
+   * Called when the provider successfully authenticates a user.
+   *
+   * @param ctx - Router request context
+   * @param properties - User data extracted from the provider
+   * @param opts - Optional utilities for session management
+   * @returns Response that completes the OAuth flow
+   *
+   * @example
+   * ```ts
+   * const userData = { userId: "123", email: "user@example.com" }
+   * return await ctx.success(c, userData)
+   * ```
+   */
+  success: (ctx: RouterContext, properties: Properties, opts?: {
+    /** Function to invalidate existing user sessions */
+    readonly invalidate?: (subject: string) => Promise<void>;
+  }) => Promise<Response>;
+  /**
+   * Forwards a response through the provider context.
+   * Used for redirects and custom responses within the OAuth flow.
+   *
+   * @param ctx - Router request context
+   * @param response - Response to forward
+   * @returns Forwarded response
+   */
+  forward: (ctx: RouterContext, response: Response) => Response;
+  /**
+   * Stores a temporary value with expiration for the current session.
+   * Useful for storing OAuth state, PKCE verifiers, and other temporary data.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   * @param maxAge - TTL in seconds
+   * @param value - Value to store
+   *
+   * @example
+   * ```ts
+   * // Store OAuth state for 10 minutes
+   * await ctx.set(c, "oauth_state", 600, { state, redirectUri })
+   * ```
+   */
+  set: <T>(ctx: RouterContext, key: string, maxAge: number, value: T) => Promise<void>;
+  /**
+   * Retrieves a previously stored temporary value.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   * @returns Promise resolving to the stored value or undefined if not found/expired
+   *
+   * @example
+   * ```ts
+   * const oauthState = await ctx.get<OAuthState>(c, "oauth_state")
+   * if (!oauthState) {
+   *   throw new Error("OAuth state expired")
+   * }
+   * ```
+   */
+  get: <T>(ctx: RouterContext, key: string) => Promise<T | undefined>;
+  /**
+   * Removes a stored temporary value.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   *
+   * @example
+   * ```ts
+   * // Clean up OAuth state after use
+   * await ctx.unset(c, "oauth_state")
+   * ```
+   */
+  unset: (ctx: RouterContext, key: string) => Promise<void>;
+  /**
+   * Invalidates all sessions for a given subject (user).
+   * Forces logout across all devices and applications.
+   *
+   * @param subject - Subject identifier to invalidate
+   *
+   * @example
+   * ```ts
+   * // Force logout on password change
+   * await ctx.invalidate(userId)
+   * ```
+   */
+  invalidate: (subject: string) => Promise<void>;
+  /**
+   * Storage adapter for persistent data operations.
+   * Provides access to the configured storage backend.
+   */
+  readonly storage: StorageAdapter;
+}
+/**
+ * Base error class for provider-related errors.
+ * Extend this class to create specific provider error types.
+ *
+ * @example
+ * ```ts
+ * export class GitHubApiError extends ProviderError {
+ *   constructor(message: string, public readonly statusCode: number) {
+ *     super(message)
+ *   }
+ * }
+ * ```
+ */
+declare class ProviderError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a provider encounters an unknown or unexpected error.
+ * Used as a fallback for unhandled error conditions.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *   if (error instanceof SomeSpecificError) {
+ *     // Handle specific error
+ *   } else {
+ *     throw new ProviderUnknownError(`Unexpected error: ${error}`)
+ *   }
+ * }
+ * ```
+ */
+declare class ProviderUnknownError extends ProviderError {
+  constructor(message?: string);
+}
+//#endregion
 export { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError };