@draftlab/auth 0.0.3 → 0.1.0

package/dist/password-C4KLmO0O.d.ts

@@ -1,385 +0,0 @@
-import { Provider } from "./provider-tndlqCzp.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 "@draftauth/core/ui/password"
- * import { PasswordProvider } from "@draftauth/core/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/pkce-276Za_rZ.js

@@ -1,162 +0,0 @@
-import { base64url } from "jose";
-
-//#region src/pkce.ts
-/**
-* Performs a timing-safe comparison of two strings to prevent timing attacks.
-* This implementation is platform-agnostic, uses a constant-time algorithm,
-* and correctly handles all Unicode characters by operating on their UTF-8 byte representation.
-* It always takes a time proportional to the length of the expected string,
-* regardless of where the strings differ, making it safe for comparing sensitive values.
-*
-* @param a - The first string to compare (often the expected, secret value).
-* @param b - The second string to compare (often the user-provided value).
-* @returns True if the strings are identical, false otherwise.
-*
-* @example
-* ```ts
-* // Safe for comparing sensitive values like PKCE verifiers or tokens
-* const isValid = await timingSafeCompare(receivedVerifier, expectedChallenge);
-*
-* // Safe for password hash verification
-* const isValidPassword = timingSafeCompare(hashedInput, storedHash);
-*
-* // Returns false for different types or lengths without leaking timing info
-* timingSafeCompare("abc", 123 as any); // false
-* timingSafeCompare("abc", "abcd"); // false
-* ```
-*/
-const timingSafeCompare = (a, b) => {
-	if (typeof a !== "string" || typeof b !== "string") return false;
-	const encoder = new TextEncoder();
-	const aBytes = encoder.encode(a);
-	const bBytes = encoder.encode(b);
-	let diff = aBytes.length ^ bBytes.length;
-	for (const [i, aByte] of aBytes.entries()) diff |= aByte ^ (bBytes[i] ?? 0);
-	return diff === 0;
-};
-/**
-* Generates a cryptographically secure code verifier for PKCE.
-* The verifier is a URL-safe base64-encoded string of random bytes.
-*
-* @param length - Length of the random buffer in bytes
-* @returns Base64url-encoded verifier string
-*/
-const generateVerifier = (length) => {
-	const buffer = new Uint8Array(length);
-	crypto.getRandomValues(buffer);
-	return base64url.encode(buffer);
-};
-/**
-* Generates a code challenge from a verifier using the specified method.
-* For 'S256', applies SHA-256 hash then base64url encoding.
-* For 'plain', returns the verifier unchanged (not recommended for production).
-*
-* @param verifier - The code verifier string
-* @param method - Challenge generation method
-* @returns Promise resolving to the code challenge string
-*/
-const generateChallenge = async (verifier, method) => {
-	if (method === "plain") return verifier;
-	const encoder = new TextEncoder();
-	const data = encoder.encode(verifier);
-	const hash = await crypto.subtle.digest("SHA-256", data);
-	return base64url.encode(new Uint8Array(hash));
-};
-/**
-* Generates a complete PKCE challenge for OAuth authorization requests.
-* Creates a cryptographically secure verifier and corresponding S256 challenge.
-* Validates that the generated verifier meets standard requirements (43-128 characters).
-*
-* @param length - Length of the random buffer in bytes (32-96 range to generate 43-128 character verifier)
-* @returns Promise resolving to PKCE challenge data
-*
-* @example
-* ```ts
-* const pkce = await generatePKCE()
-*
-* // Use challenge in authorization URL
-* authUrl.searchParams.set('code_challenge', pkce.challenge)
-* authUrl.searchParams.set('code_challenge_method', pkce.method)
-*
-* // Store verifier for token exchange
-* sessionStorage.setItem('code_verifier', pkce.verifier)
-* ```
-*
-* @throws {RangeError} If length is outside valid range or generated verifier doesn't meet requirements
-*/
-const generatePKCE = async (length = 48) => {
-	if (!Number.isInteger(length) || length < 32 || length > 96) throw new RangeError("Random buffer length must be between 32 and 96 bytes (generates 43-128 character verifier)");
-	const verifier = generateVerifier(length);
-	if (verifier.length < 43 || verifier.length > 128) throw new Error("Generated verifier does not meet requirements");
-	if (!/^[A-Za-z0-9_-]+$/.test(verifier)) throw new Error("Generated verifier is not valid base64url format");
-	const challenge = await generateChallenge(verifier, "S256");
-	return {
-		verifier,
-		challenge,
-		method: "S256"
-	};
-};
-/**
-* Validates a PKCE code verifier against a previously generated challenge.
-* Uses timing-safe comparison and timing normalization to prevent timing attacks.
-* All validation paths take the same computational time regardless of input validity,
-* making it resistant to timing-based side-channel attacks.
-*
-* @param verifier - The code verifier received from the client
-* @param challenge - The code challenge stored during authorization
-* @param method - The challenge method used during generation
-* @returns Promise resolving to true if verifier matches challenge
-*
-* @example
-* ```ts
-* // During token exchange
-* const isValid = await validatePKCE(
-*   receivedVerifier,
-*   storedChallenge,
-*   'S256'
-* )
-*
-* if (!isValid) {
-*   throw new Error('Invalid PKCE verifier')
-* }
-* ```
-*/
-const validatePKCE = async (verifier, challenge, method = "S256") => {
-	const MIN_PROCESSING_TIME = 50;
-	const RANDOM_JITTER_MAX = 20;
-	const startTime = performance.now();
-	let isValid = false;
-	let hasEarlyFailure = false;
-	const normalizedVerifier = String(verifier || "");
-	const normalizedChallenge = String(challenge || "");
-	const validations = [
-		typeof verifier === "string" && typeof challenge === "string" && verifier && challenge,
-		normalizedVerifier.length >= 43 && normalizedVerifier.length <= 128,
-		normalizedChallenge.length >= 43 && normalizedChallenge.length <= 128,
-		/^[A-Za-z0-9_-]+$/.test(normalizedVerifier),
-		/^[A-Za-z0-9_-]+$/.test(normalizedChallenge)
-	];
-	hasEarlyFailure = !validations.every(Boolean);
-	const verifierToUse = hasEarlyFailure ? "dummyverifier_".repeat(6) : normalizedVerifier;
-	try {
-		const generatedChallenge = await generateChallenge(verifierToUse, method);
-		const challengeToCompare = hasEarlyFailure ? "dummychallenge_".repeat(6) : normalizedChallenge;
-		const comparisonResult = timingSafeCompare(generatedChallenge, challengeToCompare);
-		isValid = !hasEarlyFailure && comparisonResult;
-	} catch {
-		isValid = false;
-	}
-	const elapsed = performance.now() - startTime;
-	const remainingTime = Math.max(0, MIN_PROCESSING_TIME - elapsed);
-	if (remainingTime > 0 || elapsed < MIN_PROCESSING_TIME) {
-		const jitterArray = new Uint32Array(1);
-		crypto.getRandomValues(jitterArray);
-		const jitter = (jitterArray[0] ?? 0) / 4294967295 * RANDOM_JITTER_MAX;
-		const totalDelay = Math.max(remainingTime, MIN_PROCESSING_TIME - elapsed) + jitter;
-		await new Promise((resolve) => setTimeout(resolve, totalDelay));
-	}
-	return isValid;
-};
-
-//#endregion
-export { generatePKCE, validatePKCE };