@draftlab/auth 0.0.3 → 0.0.4

package/dist/provider/oauth2.js

@@ -1,7 +1,155 @@
-import "../util-CSdHUFOo.js";
-import "../error-DgAKK7b2.js";
-import "../pkce-276Za_rZ.js";
-import "../random-SXMYlaVr.js";
-import { Oauth2Provider } from "../oauth2-B7-6Z7Lc.js";
+import { getRelativeUrl } from "../util.js";
+import { OauthError } from "../error.js";
+import { generatePKCE } from "../pkce.js";
+import { generateSecureToken, timingSafeCompare } from "../random.js";
 
+//#region src/provider/oauth2.ts
+/**
+* Creates an OAuth 2.0 authentication provider.
+* Implements the Authorization Code Grant flow with optional PKCE support.
+*
+* @param config - OAuth 2.0 provider configuration
+* @returns Provider instance implementing OAuth 2.0 authentication
+*
+* @example
+* ```ts
+* // GitHub provider with basic configuration
+* const githubProvider = Oauth2Provider({
+*   clientID: process.env.GITHUB_CLIENT_ID,
+*   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+*   endpoint: {
+*     authorization: "https://github.com/login/oauth/authorize",
+*     token: "https://github.com/login/oauth/access_token"
+*   },
+*   scopes: ["user:email", "read:user"]
+* })
+*
+* // Provider with PKCE and custom parameters
+* const customProvider = Oauth2Provider({
+*   clientID: "my-client-id",
+*   clientSecret: "my-client-secret",
+*   endpoint: {
+*     authorization: "https://provider.com/oauth/authorize",
+*     token: "https://provider.com/oauth/token",
+*     jwks: "https://provider.com/.well-known/jwks.json"
+*   },
+*   scopes: ["read", "write"],
+*   pkce: true,
+*   query: {
+*     prompt: "consent",
+*     access_type: "offline"
+*   }
+* })
+* ```
+*/
+const Oauth2Provider = (config) => {
+	const authQuery = config.query || {};
+	/**
+	* Handles the OAuth 2.0 callback logic for both GET and POST requests.
+	* Exchanges the authorization code for tokens and processes the response.
+	*/
+	const handleCallbackLogic = async (c, ctx, provider, code) => {
+		if (!(provider && code)) return c.redirect(getRelativeUrl(c, "./authorize"));
+		const tokenRequestBody = new URLSearchParams({
+			client_id: config.clientID,
+			client_secret: config.clientSecret,
+			code,
+			grant_type: "authorization_code",
+			redirect_uri: provider.redirect,
+			...provider.codeVerifier ? { code_verifier: provider.codeVerifier } : {}
+		});
+		try {
+			const response = await fetch(config.endpoint.token, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/x-www-form-urlencoded",
+					Accept: "application/json"
+				},
+				body: tokenRequestBody.toString()
+			});
+			if (!response.ok) throw new Error(`Token request failed with status ${response.status}`);
+			const tokenData = await response.json();
+			if (tokenData.error) throw new OauthError(tokenData.error, tokenData.error_description || "");
+			return await ctx.success(c, {
+				clientID: config.clientID,
+				tokenset: {
+					get access() {
+						return tokenData.access_token;
+					},
+					get refresh() {
+						return tokenData.refresh_token || "";
+					},
+					get expiry() {
+						return tokenData.expires_in || 0;
+					},
+					get raw() {
+						return tokenData;
+					}
+				}
+			});
+		} catch (error) {
+			if (error instanceof OauthError) throw error;
+			throw new OauthError("server_error", `Token exchange failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	};
+	return {
+		type: config.type || "oauth2",
+		init(routes, ctx) {
+			/**
+			* Initiates OAuth 2.0 authorization flow.
+			* Redirects user to the provider's authorization endpoint with proper parameters.
+			*/
+			routes.get("/authorize", async (c) => {
+				const state = generateSecureToken();
+				const pkce = config.pkce ? await generatePKCE() : void 0;
+				await ctx.set(c, "provider", 60 * 10, {
+					state,
+					redirect: getRelativeUrl(c, "./callback"),
+					codeVerifier: pkce?.verifier
+				});
+				const authorizationUrl = new URL(config.endpoint.authorization);
+				authorizationUrl.searchParams.set("client_id", config.clientID);
+				authorizationUrl.searchParams.set("redirect_uri", getRelativeUrl(c, "./callback"));
+				authorizationUrl.searchParams.set("response_type", "code");
+				authorizationUrl.searchParams.set("state", state);
+				authorizationUrl.searchParams.set("scope", config.scopes.join(" "));
+				if (pkce) {
+					authorizationUrl.searchParams.set("code_challenge", pkce.challenge);
+					authorizationUrl.searchParams.set("code_challenge_method", pkce.method);
+				}
+				for (const [key, value] of Object.entries(authQuery)) authorizationUrl.searchParams.set(key, value);
+				return c.redirect(authorizationUrl.toString());
+			});
+			/**
+			* Handles OAuth 2.0 callback via query parameters (GET request).
+			* Standard OAuth 2.0 callback method for most providers.
+			*/
+			routes.get("/callback", async (c) => {
+				const provider = await ctx.get(c, "provider");
+				const code = c.query("code");
+				const state = c.query("state");
+				const error = c.query("error");
+				if (error) throw new OauthError(error, c.query("error_description") || "");
+				if (!(provider && code) || provider.state && !timingSafeCompare(state || "", provider.state)) return c.redirect(getRelativeUrl(c, "./authorize"));
+				return await handleCallbackLogic(c, ctx, provider, code);
+			});
+			/**
+			* Handles OAuth 2.0 callback via form data (POST request).
+			* Alternative callback method supported by some providers.
+			*/
+			routes.post("/callback", async (c) => {
+				const provider = await ctx.get(c, "provider");
+				const formData = await c.formData();
+				const code = formData.get("code")?.toString();
+				const state = formData.get("state")?.toString();
+				const error = formData.get("error")?.toString();
+				if (error) throw new OauthError(error, formData.get("error_description")?.toString() || "");
+				if (!(provider && code) || provider.state && !timingSafeCompare(state || "", provider.state)) return c.redirect(getRelativeUrl(c, "./authorize"));
+				return await handleCallbackLogic(c, ctx, provider, code);
+			});
+		}
+	};
+};
+
+//#endregion
 export { Oauth2Provider };

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 "@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/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";