@draftlab/auth 0.0.3 → 0.1.0

package/dist/pkce.js

@@ -1,3 +1,162 @@
-import { generatePKCE, validatePKCE } from "./pkce-276Za_rZ.js";
+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/provider/code.d.ts

@@ -1,4 +1,228 @@
-import "../storage-CxKerLlc.js";
-import "../provider-tndlqCzp.js";
-import { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData } from "../code-DJxdFR7p.js";
+import { Provider } from "./provider.js";
+
+//#region src/provider/code.d.ts
+
+/**
+ * Configuration options for the PIN code authentication provider.
+ *
+ * @template Claims - Type of claims collected during authentication (email, phone, etc.)
+ */
+interface CodeProviderConfig<Claims extends Record<string, string> = Record<string, string>> {
+  /**
+   * The length of the generated PIN code.
+   * Common values are 4, 6, or 8 digits.
+   *
+   * @default 6
+   *
+   * @example
+   * ```ts
+   * {
+   *   length: 4 // 4-digit PIN for easier entry
+   * }
+   * ```
+   */
+  readonly length?: number;
+  /**
+   * Request handler for rendering the authentication UI.
+   * Handles both the initial claim collection and PIN code entry screens.
+   *
+   * @param req - The HTTP request object
+   * @param state - Current authentication state (start or code verification)
+   * @param form - Form data from POST requests (if any)
+   * @param error - Authentication error to display (if any)
+   * @returns Promise resolving to the authentication page response
+   *
+   * @example
+   * ```ts
+   * request: async (req, state, form, error) => {
+   *   if (state.type === 'start') {
+   *     return new Response(renderClaimForm(form, error))
+   *   } else {
+   *     return new Response(renderCodeForm(state.claims.email, error))
+   *   }
+   * }
+   * ```
+   */
+  request: (req: Request, state: CodeProviderState, form?: FormData, error?: CodeProviderError) => Promise<Response>;
+  /**
+   * Callback for sending PIN codes to users via their preferred method.
+   * Should handle delivery via email, SMS, or other communication channels.
+   *
+   * @param claims - User claims containing contact information
+   * @param code - The generated PIN code to send
+   * @returns Promise resolving to undefined on success, or error object on failure
+   *
+   * @example
+   * ```ts
+   * sendCode: async (claims, code) => {
+   *   try {
+   *     if (claims.email) {
+   *       await emailService.send({
+   *         to: claims.email,
+   *         subject: 'Your verification code',
+   *         text: `Your PIN code is: ${code}`
+   *       })
+   *     } else if (claims.phone) {
+   *       await smsService.send(claims.phone, `PIN: ${code}`)
+   *     } else {
+   *       return {
+   *         type: "invalid_claim",
+   *         key: "email",
+   *         value: "Email or phone number is required"
+   *       }
+   *     }
+   *   } catch (error) {
+   *     return {
+   *       type: "invalid_claim",
+   *       key: "delivery",
+   *       value: "Failed to send code"
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  sendCode: (claims: Claims, code: string) => Promise<CodeProviderError | undefined>;
+}
+/**
+ * Authentication flow states for the PIN code provider.
+ * The provider transitions between these states during authentication.
+ */
+type CodeProviderState = {
+  /** Initial state: user enters their claims (email, phone, etc.) */
+  readonly type: "start";
+} | {
+  /** Code verification state: user enters the PIN code */
+  readonly type: "code";
+  /** Whether this is a code resend request */
+  readonly resend?: boolean;
+  /** The generated PIN code for verification */
+  readonly code: string;
+  /** User claims collected during the start phase */
+  readonly claims: Record<string, string>;
+};
+/**
+ * Possible errors during PIN code authentication.
+ */
+type CodeProviderError = {
+  /** The entered PIN code is incorrect */
+  readonly type: "invalid_code";
+} | {
+  /** A user claim is invalid or missing */
+  readonly type: "invalid_claim";
+  /** The claim field that failed validation */
+  readonly key: string;
+  /** The invalid value or error description */
+  readonly value: string;
+};
+/**
+ * User data returned by successful PIN code authentication.
+ *
+ * @template Claims - Type of claims collected during authentication
+ */
+interface CodeUserData<Claims extends Record<string, string> = Record<string, string>> {
+  /** The verified claims collected during authentication */
+  readonly claims: Claims;
+}
+/**
+ * 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"
+ *       }
+ *     }
+ *
+ *     try {
+ *       await emailService.send(claims.email, `Your verification code: ${code}`)
+ *     } catch {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "delivery",
+ *         value: "Failed to send 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) => {
+ *     try {
+ *       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: "email",
+ *           value: "Provide either email or phone number"
+ *         }
+ *       }
+ *     } catch {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "delivery",
+ *         value: "Failed to send code"
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // 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 })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const CodeProvider: <Claims extends Record<string, string> = Record<string, string>>(config: CodeProviderConfig<Claims>) => Provider<CodeUserData<Claims>>;
+/**
+ * Type helper for CodeProvider configuration options.
+ * @internal
+ */
+type CodeProviderOptions = Parameters<typeof CodeProvider>[0];
+//#endregion
 export { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData };

package/dist/provider/code.js

@@ -1,4 +1,4 @@
-import { generateUnbiasedDigits, timingSafeCompare } from "../random-SXMYlaVr.js";
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.js";
 
 //#region src/provider/code.ts
 /**
@@ -30,7 +30,15 @@ import { generateUnbiasedDigits, timingSafeCompare } from "../random-SXMYlaVr.js
 *       }
 *     }
 *
-*     await emailService.send(claims.email, `Your verification code: ${code}`)
+*     try {
+*       await emailService.send(claims.email, `Your verification code: ${code}`)
+*     } catch {
+*       return {
+*         type: "invalid_claim",
+*         key: "delivery",
+*         value: "Failed to send code"
+*       }
+*     }
 *   }
 * })
 *
@@ -46,15 +54,23 @@ import { generateUnbiasedDigits, timingSafeCompare } from "../random-SXMYlaVr.js
 *     }
 *   },
 *   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 {
+*     try {
+*       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: "email",
+*           value: "Provide either email or phone number"
+*         }
+*       }
+*     } catch {
 *       return {
 *         type: "invalid_claim",
-*         key: "contact",
-*         value: "Provide either email or phone number"
+*         key: "delivery",
+*         value: "Failed to send code"
 *       }
 *     }
 *   }
@@ -124,18 +140,15 @@ const CodeProvider = (config) => {
 						claims,
 						code
 					}, formData);
-				}
-				if (action === "verify" && currentState?.type === "code") {
+				} else 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 await ctx.success(c, { claims: currentState.claims });
 				}
-				return transition(c, { type: "start" }, formData);
 			});
 		}
 	};

package/dist/provider/facebook.d.ts

@@ -1,6 +1,5 @@
-import "../storage-CxKerLlc.js";
-import { Provider } from "../provider-tndlqCzp.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-CXHukHf2.js";
+import { Provider } from "./provider.js";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
 
 //#region src/provider/facebook.d.ts
 

package/dist/provider/facebook.js

@@ -1,8 +1,4 @@
-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 { Oauth2Provider } from "./oauth2.js";
 
 //#region src/provider/facebook.ts
 /**

package/dist/provider/github.d.ts

@@ -1,6 +1,5 @@
-import "../storage-CxKerLlc.js";
-import { Provider } from "../provider-tndlqCzp.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-CXHukHf2.js";
+import { Provider } from "./provider.js";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
 
 //#region src/provider/github.d.ts
 

package/dist/provider/github.js

@@ -1,8 +1,4 @@
-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 { Oauth2Provider } from "./oauth2.js";
 
 //#region src/provider/github.ts
 /**

package/dist/provider/google.d.ts

@@ -1,6 +1,5 @@
-import "../storage-CxKerLlc.js";
-import { Provider } from "../provider-tndlqCzp.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-CXHukHf2.js";
+import { Provider } from "./provider.js";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
 
 //#region src/provider/google.d.ts
 

package/dist/provider/google.js

@@ -1,8 +1,4 @@
-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 { Oauth2Provider } from "./oauth2.js";
 
 //#region src/provider/google.ts
 /**