@draftlab/auth 0.0.1

package/dist/pkce-276Za_rZ.js

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

package/dist/pkce.d.ts

@@ -0,0 +1,72 @@
+//#region src/pkce.d.ts
+/**
+ * PKCE (Proof Key for Code Exchange) implementation for OAuth security.
+ * Provides protection against authorization code interception attacks by using
+ * dynamically generated code verifiers and challenges.
+ */
+/**
+ * PKCE challenge methods supported by the implementation.
+ */
+type PKCEMethod = "S256" | "plain";
+/**
+ * Complete PKCE challenge data containing verifier, challenge, and method.
+ */
+interface PKCEChallenge {
+  /** The code verifier to be sent to the token endpoint */
+  readonly verifier: string;
+  /** The code challenge to be sent to the authorization endpoint */
+  readonly challenge: string;
+  /** The challenge method used */
+  readonly method: "S256";
+}
+/**
+ * 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
+ */
+declare const generatePKCE: (length?: number) => Promise<PKCEChallenge>;
+/**
+ * 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')
+ * }
+ * ```
+ */
+declare const validatePKCE: (verifier: string, challenge: string, method?: PKCEMethod) => Promise<boolean>;
+//#endregion
+export { generatePKCE, validatePKCE };

package/dist/pkce.js

@@ -0,0 +1,3 @@
+import { generatePKCE, validatePKCE } from "./pkce-276Za_rZ.js";
+
+export { generatePKCE, validatePKCE };

package/dist/provider/code.d.ts

@@ -0,0 +1,4 @@
+import "../storage-CxKerLlc.js";
+import "../provider-CwWMG-1l.js";
+import { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData } from "../code-l_uvMR1j.js";
+export { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData };

package/dist/provider/code.js

@@ -0,0 +1,145 @@
+import { generateUnbiasedDigits, timingSafeCompare } from "../random-SXMYlaVr.js";
+
+//#region src/provider/code.ts
+/**
+* Creates a PIN code authentication provider.
+* Implements a flexible claim-based authentication flow with PIN verification.
+*
+* @template Claims - Type of claims to collect (email, phone, username, etc.)
+* @param config - PIN code provider configuration
+* @returns Provider instance implementing PIN code authentication
+*
+* @example
+* ```ts
+* // Email-based PIN authentication
+* const emailCodeProvider = CodeProvider<{ email: string }>({
+*   length: 6,
+*   request: async (req, state, form, error) => {
+*     if (state.type === 'start') {
+*       return new Response(renderEmailForm(form?.get('email'), error))
+*     } else {
+*       return new Response(renderPinForm(state.claims.email, error, state.resend))
+*     }
+*   },
+*   sendCode: async (claims, code) => {
+*     if (!claims.email || !isValidEmail(claims.email)) {
+*       return {
+*         type: "invalid_claim",
+*         key: "email",
+*         value: "Invalid email address"
+*       }
+*     }
+*
+*     await emailService.send(claims.email, `Your verification code: ${code}`)
+*   }
+* })
+*
+* // Multi-channel PIN authentication (email or phone)
+* const flexibleCodeProvider = CodeProvider<{ email?: string; phone?: string }>({
+*   length: 4,
+*   request: async (req, state, form, error) => {
+*     if (state.type === 'start') {
+*       return new Response(renderContactForm(form, error))
+*     } else {
+*       const contact = state.claims.email || state.claims.phone
+*       return new Response(renderPinForm(contact, error))
+*     }
+*   },
+*   sendCode: async (claims, code) => {
+*     if (claims.email) {
+*       await emailService.send(claims.email, `PIN: ${code}`)
+*     } else if (claims.phone) {
+*       await smsService.send(claims.phone, `PIN: ${code}`)
+*     } else {
+*       return {
+*         type: "invalid_claim",
+*         key: "contact",
+*         value: "Provide either email or phone number"
+*       }
+*     }
+*   }
+* })
+*
+* // Usage in issuer
+* export default issuer({
+*   providers: {
+*     email: emailCodeProvider,
+*     flexible: flexibleCodeProvider
+*   },
+*   success: async (ctx, value) => {
+*     if (value.provider === "code") {
+*       const email = value.claims.email
+*       const phone = value.claims.phone
+*
+*       // Look up or create user based on verified claims
+*       const userId = await findOrCreateUser({ email, phone })
+*
+*       return ctx.subject("user", { userId, email, phone })
+*     }
+*   }
+* })
+* ```
+*/
+const CodeProvider = (config) => {
+	const codeLength = config.length || 6;
+	/**
+	* Generates a cryptographically secure PIN code.
+	*/
+	const generateCode = () => {
+		return generateUnbiasedDigits(codeLength);
+	};
+	return {
+		type: "code",
+		init(routes, ctx) {
+			/**
+			* Transitions between authentication states and renders the appropriate UI.
+			*/
+			const transition = async (c, nextState, formData, error) => {
+				await ctx.set(c, "provider", 60 * 60 * 24, nextState);
+				const response = await config.request(c.request, nextState, formData, error);
+				return ctx.forward(c, response);
+			};
+			/**
+			* GET /authorize - Display initial claim collection form
+			*/
+			routes.get("/authorize", (c) => {
+				return transition(c, { type: "start" });
+			});
+			/**
+			* POST /authorize - Handle form submissions and state transitions
+			*/
+			routes.post("/authorize", async (c) => {
+				const formData = await c.formData();
+				const currentState = await ctx.get(c, "provider");
+				const action = formData.get("action")?.toString();
+				if (action === "request" || action === "resend") {
+					const code = generateCode();
+					const formEntries = Object.fromEntries(formData);
+					const { action: _,...claims } = formEntries;
+					const sendError = await config.sendCode(claims, code);
+					if (sendError) return transition(c, { type: "start" }, formData, sendError);
+					return transition(c, {
+						type: "code",
+						resend: action === "resend",
+						claims,
+						code
+					}, formData);
+				}
+				if (action === "verify" && currentState?.type === "code") {
+					const enteredCode = formData.get("code")?.toString();
+					if (!(currentState.code && enteredCode && timingSafeCompare(currentState.code, enteredCode))) return transition(c, {
+						...currentState,
+						resend: false
+					}, formData, { type: "invalid_code" });
+					await ctx.unset(c, "provider");
+					const successResponse = await ctx.success(c, { claims: currentState.claims });
+					return ctx.forward(c, successResponse);
+				}
+				return transition(c, { type: "start" }, formData);
+			});
+		}
+	};
+};
+
+//#endregion
+export { CodeProvider };

package/dist/provider/facebook.d.ts

@@ -0,0 +1,137 @@
+import "../storage-CxKerLlc.js";
+import { Provider } from "../provider-CwWMG-1l.js";
+import { Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-DtKwtl8p.js";
+
+//#region src/provider/facebook.d.ts
+
+/**
+ * Configuration options for Facebook OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with Facebook-specific documentation.
+ */
+interface FacebookConfig extends Oauth2WrappedConfig {
+  /**
+   * Facebook App ID from your Facebook App Dashboard.
+   * This is the public identifier for your Facebook application.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "1234567890123456"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * Facebook App Secret from your Facebook App Dashboard.
+   * Keep this secure and never expose it to client-side code.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.FACEBOOK_APP_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * Facebook permissions to request during login.
+   * Determines what data your app can access from the user's Facebook account.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: [
+   *     "email",           // User's email address
+   *     "public_profile",  // Basic profile info
+   *     "user_friends",    // User's friends list
+   *     "user_posts"       // User's timeline posts
+   *   ]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+  /**
+   * Additional query parameters for Facebook OAuth authorization.
+   * Useful for Facebook-specific options like response type or display mode.
+   *
+   * @example
+   * ```ts
+   * {
+   *   query: {
+   *     display: "popup",           // Show login in popup
+   *     auth_type: "rerequest",     // Force permission re-request
+   *     state: "custom-state"       // Custom state parameter
+   *   }
+   * }
+   * ```
+   */
+  readonly query?: Record<string, string>;
+}
+/**
+ * Creates a Facebook OAuth 2.0 authentication provider.
+ * Use this when you need access tokens to call Facebook Graph API on behalf of the user.
+ *
+ * @param config - Facebook OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Facebook
+ *
+ * @example
+ * ```ts
+ * // Basic Facebook authentication
+ * const basicFacebook = FacebookProvider({
+ *   clientID: process.env.FACEBOOK_APP_ID,
+ *   clientSecret: process.env.FACEBOOK_APP_SECRET,
+ *   scopes: ["email", "public_profile"]
+ * })
+ *
+ * // Facebook with extended permissions
+ * const extendedFacebook = FacebookProvider({
+ *   clientID: process.env.FACEBOOK_APP_ID,
+ *   clientSecret: process.env.FACEBOOK_APP_SECRET,
+ *   scopes: [
+ *     "email",
+ *     "public_profile",
+ *     "user_friends",
+ *     "user_posts",
+ *     "user_photos"
+ *   ],
+ *   query: {
+ *     display: "popup",
+ *     auth_type: "rerequest" // Force permission approval
+ *   }
+ * })
+ *
+ * // Using the access token for Graph API calls
+ * export default issuer({
+ *   providers: { facebook: extendedFacebook },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "facebook") {
+ *       const token = value.tokenset.access
+ *
+ *       // Get user profile with custom fields
+ *       const profileRes = await fetch(
+ *         `https://graph.facebook.com/me?fields=id,name,email,picture.width(200),friends&access_token=${token}`
+ *       )
+ *       const profile = await profileRes.json()
+ *
+ *       // Get user's posts (if permission granted)
+ *       const postsRes = await fetch(
+ *         `https://graph.facebook.com/me/posts?access_token=${token}`
+ *       )
+ *       const posts = await postsRes.json()
+ *
+ *       return ctx.subject("user", {
+ *         facebookId: profile.id,
+ *         name: profile.name,
+ *         email: profile.email,
+ *         picture: profile.picture?.data?.url,
+ *         friendsCount: profile.friends?.summary?.total_count || 0,
+ *         postsCount: posts.data?.length || 0
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const FacebookProvider: (config: FacebookConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { FacebookConfig, FacebookProvider };

package/dist/provider/facebook.js

@@ -0,0 +1,85 @@
+import "../util-CSdHUFOo.js";
+import "../error-DgAKK7b2.js";
+import "../pkce-276Za_rZ.js";
+import "../random-SXMYlaVr.js";
+import { Oauth2Provider } from "../oauth2-B7-6Z7Lc.js";
+
+//#region src/provider/facebook.ts
+/**
+* Creates a Facebook OAuth 2.0 authentication provider.
+* Use this when you need access tokens to call Facebook Graph API on behalf of the user.
+*
+* @param config - Facebook OAuth 2.0 configuration
+* @returns OAuth 2.0 provider configured for Facebook
+*
+* @example
+* ```ts
+* // Basic Facebook authentication
+* const basicFacebook = FacebookProvider({
+*   clientID: process.env.FACEBOOK_APP_ID,
+*   clientSecret: process.env.FACEBOOK_APP_SECRET,
+*   scopes: ["email", "public_profile"]
+* })
+*
+* // Facebook with extended permissions
+* const extendedFacebook = FacebookProvider({
+*   clientID: process.env.FACEBOOK_APP_ID,
+*   clientSecret: process.env.FACEBOOK_APP_SECRET,
+*   scopes: [
+*     "email",
+*     "public_profile",
+*     "user_friends",
+*     "user_posts",
+*     "user_photos"
+*   ],
+*   query: {
+*     display: "popup",
+*     auth_type: "rerequest" // Force permission approval
+*   }
+* })
+*
+* // Using the access token for Graph API calls
+* export default issuer({
+*   providers: { facebook: extendedFacebook },
+*   success: async (ctx, value) => {
+*     if (value.provider === "facebook") {
+*       const token = value.tokenset.access
+*
+*       // Get user profile with custom fields
+*       const profileRes = await fetch(
+*         `https://graph.facebook.com/me?fields=id,name,email,picture.width(200),friends&access_token=${token}`
+*       )
+*       const profile = await profileRes.json()
+*
+*       // Get user's posts (if permission granted)
+*       const postsRes = await fetch(
+*         `https://graph.facebook.com/me/posts?access_token=${token}`
+*       )
+*       const posts = await postsRes.json()
+*
+*       return ctx.subject("user", {
+*         facebookId: profile.id,
+*         name: profile.name,
+*         email: profile.email,
+*         picture: profile.picture?.data?.url,
+*         friendsCount: profile.friends?.summary?.total_count || 0,
+*         postsCount: posts.data?.length || 0
+*       })
+*     }
+*   }
+* })
+* ```
+*/
+const FacebookProvider = (config) => {
+	return Oauth2Provider({
+		...config,
+		type: "facebook",
+		endpoint: {
+			authorization: "https://www.facebook.com/v18.0/dialog/oauth",
+			token: "https://graph.facebook.com/v18.0/oauth/access_token"
+		}
+	});
+};
+
+//#endregion
+export { FacebookProvider };