@draftlab/auth 0.0.1

package/dist/provider/password.js

@@ -0,0 +1,366 @@
+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 * as jose from "jose";
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { TextEncoder } from "node:util";
+
+//#region src/provider/password.ts
+/**
+* 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"
+*   }
+* })
+* ```
+*/
+const PasswordProvider = (config) => {
+	const hasher = config.hasher ?? ScryptHasher();
+	/**
+	* Generates a cryptographically secure verification code.
+	*/
+	const generateCode = () => {
+		return generateUnbiasedDigits(config.length ?? 6);
+	};
+	return {
+		type: "password",
+		init(routes, ctx) {
+			/**
+			* GET /authorize - Display login form
+			*/
+			routes.get("/authorize", async (c) => ctx.forward(c, await config.login(c.request)));
+			/**
+			* POST /authorize - Process login attempt
+			*/
+			routes.post("/authorize", async (c) => {
+				const formData = await c.formData();
+				const error = async (err) => {
+					return ctx.forward(c, await config.login(c.request, formData, err));
+				};
+				const email = formData.get("email")?.toString()?.toLowerCase();
+				if (!email) return error({ type: "invalid_email" });
+				const storedHash = await Storage.get(ctx.storage, [
+					"email",
+					email,
+					"password"
+				]);
+				const password = formData.get("password")?.toString();
+				if (!(password && storedHash && await hasher.verify(password, storedHash))) return error({ type: "invalid_password" });
+				return ctx.success(c, { email }, { invalidate: async (subject) => {
+					await Storage.set(ctx.storage, [
+						"email",
+						email,
+						"subject"
+					], subject);
+				} });
+			});
+			/**
+			* GET /register - Display registration form
+			*/
+			routes.get("/register", async (c) => {
+				const state = { type: "start" };
+				await ctx.set(c, "provider", 60 * 60 * 24, state);
+				return ctx.forward(c, await config.register(c.request, state));
+			});
+			/**
+			* POST /register - Process registration steps
+			*/
+			routes.post("/register", async (c) => {
+				const formData = await c.formData();
+				const email = formData.get("email")?.toString()?.toLowerCase();
+				const action = formData.get("action")?.toString();
+				let provider = await ctx.get(c, "provider");
+				if (!provider) {
+					const state = { type: "start" };
+					await ctx.set(c, "provider", 60 * 60 * 24, state);
+					if (action === "register") provider = state;
+					else return ctx.forward(c, await config.register(c.request, state));
+				}
+				const transition = async (next, err) => {
+					await ctx.set(c, "provider", 60 * 60 * 24, next);
+					return ctx.forward(c, await config.register(c.request, next, formData, err));
+				};
+				if (action === "register" && provider.type === "start") {
+					const password = formData.get("password")?.toString();
+					const repeat = formData.get("repeat")?.toString();
+					if (!email) return transition(provider, { type: "invalid_email" });
+					if (!password) return transition(provider, { type: "invalid_password" });
+					if (password !== repeat) return transition(provider, { type: "password_mismatch" });
+					if (config.validatePassword) {
+						let validationError;
+						try {
+							if (typeof config.validatePassword === "function") validationError = await config.validatePassword(password);
+							else {
+								const result = await config.validatePassword["~standard"].validate(password);
+								if (result.issues?.length) throw new Error(result.issues.map((issue) => issue.message).join(", "));
+							}
+						} catch (error) {
+							validationError = error instanceof Error ? error.message : void 0;
+						}
+						if (validationError) return transition(provider, {
+							type: "validation_error",
+							message: validationError
+						});
+					}
+					const existingUser = await Storage.get(ctx.storage, [
+						"email",
+						email,
+						"password"
+					]);
+					if (existingUser) return transition(provider, { type: "email_taken" });
+					const code = generateCode();
+					await config.sendCode(email, code);
+					return transition({
+						type: "code",
+						code,
+						password: await hasher.hash(password),
+						email
+					});
+				}
+				if (action === "register" && provider.type === "code") {
+					const code = generateCode();
+					await config.sendCode(provider.email, code);
+					return transition({
+						type: "code",
+						code,
+						password: provider.password,
+						email: provider.email
+					});
+				}
+				if (action === "verify" && provider.type === "code") {
+					const code = formData.get("code")?.toString();
+					if (!(code && timingSafeCompare(code, provider.code))) return transition(provider, { type: "invalid_code" });
+					const existingUser = await Storage.get(ctx.storage, [
+						"email",
+						provider.email,
+						"password"
+					]);
+					if (existingUser) return transition({ type: "start" }, { type: "email_taken" });
+					await Storage.set(ctx.storage, [
+						"email",
+						provider.email,
+						"password"
+					], provider.password);
+					return ctx.success(c, { email: provider.email });
+				}
+				return transition({ type: "start" });
+			});
+			/**
+			* GET /change - Display password change form
+			*/
+			routes.get("/change", async (c) => {
+				const redirect = c.query("redirect_uri") || getRelativeUrl(c, "/authorize");
+				const state = {
+					type: "start",
+					redirect
+				};
+				await ctx.set(c, "provider", 60 * 60 * 24, state);
+				return ctx.forward(c, await config.change(c.request, state));
+			});
+			/**
+			* POST /change - Process password change steps
+			*/
+			routes.post("/change", async (c) => {
+				const formData = await c.formData();
+				const action = formData.get("action")?.toString();
+				const provider = await ctx.get(c, "provider");
+				if (!provider) throw new UnknownStateError();
+				const transition = async (next, err) => {
+					await ctx.set(c, "provider", 60 * 60 * 24, next);
+					return ctx.forward(c, await config.change(c.request, next, formData, err));
+				};
+				if (action === "code") {
+					const email = formData.get("email")?.toString()?.toLowerCase();
+					if (!email) return transition({
+						type: "start",
+						redirect: provider.redirect
+					}, { type: "invalid_email" });
+					const code = generateCode();
+					await config.sendCode(email, code);
+					return transition({
+						type: "code",
+						code,
+						email,
+						redirect: provider.redirect
+					});
+				}
+				if (action === "verify" && provider.type === "code") {
+					const code = formData.get("code")?.toString();
+					if (!(code && timingSafeCompare(code, provider.code))) return transition(provider, { type: "invalid_code" });
+					return transition({
+						type: "update",
+						email: provider.email,
+						redirect: provider.redirect
+					});
+				}
+				if (action === "update" && provider.type === "update") {
+					const existingPassword = await Storage.get(ctx.storage, [
+						"email",
+						provider.email,
+						"password"
+					]);
+					if (!existingPassword) return c.redirect(provider.redirect, 302);
+					const password = formData.get("password")?.toString();
+					const repeat = formData.get("repeat")?.toString();
+					if (!password) return transition(provider, { type: "invalid_password" });
+					if (password !== repeat) return transition(provider, { type: "password_mismatch" });
+					if (config.validatePassword) {
+						let validationError;
+						try {
+							if (typeof config.validatePassword === "function") validationError = await config.validatePassword(password);
+							else {
+								const result = await config.validatePassword["~standard"].validate(password);
+								if (result.issues?.length) throw new Error(result.issues.map((issue) => issue.message).join(", "));
+							}
+						} catch (error) {
+							validationError = error instanceof Error ? error.message : void 0;
+						}
+						if (validationError) return transition(provider, {
+							type: "validation_error",
+							message: validationError
+						});
+					}
+					await Storage.set(ctx.storage, [
+						"email",
+						provider.email,
+						"password"
+					], await hasher.hash(password));
+					const subject = await Storage.get(ctx.storage, [
+						"email",
+						provider.email,
+						"subject"
+					]);
+					if (subject) await ctx.invalidate(subject);
+					return c.redirect(provider.redirect, 302);
+				}
+				return transition({
+					type: "start",
+					redirect: provider.redirect
+				});
+			});
+		}
+	};
+};
+/**
+* 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
+*/
+const PBKDF2Hasher = (opts) => {
+	const iterations = opts?.iterations ?? 6e5;
+	return {
+		async hash(password) {
+			const encoder = new TextEncoder();
+			const passwordBytes = encoder.encode(password);
+			const salt = crypto.getRandomValues(new Uint8Array(16));
+			const keyMaterial = await crypto.subtle.importKey("raw", passwordBytes, "PBKDF2", false, ["deriveBits"]);
+			const hashBuffer = await crypto.subtle.deriveBits({
+				name: "PBKDF2",
+				hash: "SHA-256",
+				salt,
+				iterations
+			}, keyMaterial, 256);
+			const hashBase64 = jose.base64url.encode(new Uint8Array(hashBuffer));
+			const saltBase64 = jose.base64url.encode(salt);
+			return {
+				hash: hashBase64,
+				salt: saltBase64,
+				iterations
+			};
+		},
+		async verify(password, compare) {
+			const encoder = new TextEncoder();
+			const passwordBytes = encoder.encode(password);
+			const salt = jose.base64url.decode(compare.salt);
+			const keyMaterial = await crypto.subtle.importKey("raw", passwordBytes, "PBKDF2", false, ["deriveBits"]);
+			const hashBuffer = await crypto.subtle.deriveBits({
+				name: "PBKDF2",
+				hash: "SHA-256",
+				salt,
+				iterations: compare.iterations
+			}, keyMaterial, 256);
+			const hashBase64 = jose.base64url.encode(new Uint8Array(hashBuffer));
+			return timingSafeCompare(hashBase64, compare.hash);
+		}
+	};
+};
+/**
+* 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
+*/
+const ScryptHasher = (opts) => {
+	const N = opts?.N ?? 16384;
+	const r = opts?.r ?? 8;
+	const p = opts?.p ?? 1;
+	return {
+		async hash(password) {
+			const salt = randomBytes(16);
+			const keyLength = 32;
+			const derivedKey = await new Promise((resolve, reject) => {
+				scrypt(password, salt, keyLength, {
+					N,
+					r,
+					p
+				}, (err, derivedKey$1) => {
+					if (err) reject(err);
+					else resolve(derivedKey$1);
+				});
+			});
+			const hashBase64 = derivedKey.toString("base64");
+			const saltBase64 = salt.toString("base64");
+			return {
+				hash: hashBase64,
+				salt: saltBase64,
+				N,
+				r,
+				p
+			};
+		},
+		async verify(password, compare) {
+			const salt = Buffer.from(compare.salt, "base64");
+			const keyLength = 32;
+			const derivedKey = await new Promise((resolve, reject) => {
+				scrypt(password, salt, keyLength, {
+					N: compare.N,
+					r: compare.r,
+					p: compare.p
+				}, (err, derivedKey$1) => {
+					if (err) reject(err);
+					else resolve(derivedKey$1);
+				});
+			});
+			return timingSafeEqual(derivedKey, Buffer.from(compare.hash, "base64"));
+		}
+	};
+};
+
+//#endregion
+export { PBKDF2Hasher, PasswordProvider, ScryptHasher };

package/dist/provider/provider.d.ts

@@ -0,0 +1,3 @@
+import "../storage-CxKerLlc.js";
+import { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError } from "../provider-CwWMG-1l.js";
+export { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError };

package/dist/provider/provider.js

@@ -0,0 +1,44 @@
+//#region src/provider/provider.ts
+/**
+* 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)
+*   }
+* }
+* ```
+*/
+var ProviderError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ProviderError";
+	}
+};
+/**
+* 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}`)
+*   }
+* }
+* ```
+*/
+var ProviderUnknownError = class extends ProviderError {
+	constructor(message) {
+		super(message || "An unknown provider error occurred");
+		this.name = "ProviderUnknownError";
+	}
+};
+
+//#endregion
+export { ProviderError, ProviderUnknownError };

package/dist/provider-CwWMG-1l.d.ts

@@ -0,0 +1,227 @@
+import { StorageAdapter } from "./storage-CxKerLlc.js";
+import { Router } from "@draftlab/router";
+import { RouterContext } from "@draftlab/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 };