@draftlab/auth 0.0.3 → 0.0.4

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,212 @@
-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: "contact",
+   *         value: "No email or phone provided"
+   *       }
+   *     }
+   *   } 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"
+ *       }
+ *     }
+ *
+ *     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 })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+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
 /**

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
 /**

package/dist/provider/oauth2.d.ts

@@ -1,4 +1,176 @@
-import "../storage-CxKerLlc.js";
-import "../provider-tndlqCzp.js";
-import { Oauth2Config, Oauth2Provider, Oauth2Token, Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-CXHukHf2.js";
+import { Provider } from "./provider.js";
+
+//#region src/provider/oauth2.d.ts
+
+/**
+ * Configuration options for the OAuth 2.0 provider.
+ */
+interface Oauth2Config {
+  /**
+   * Provider type identifier for internal use.
+   * @internal
+   * @default "oauth2"
+   */
+  readonly type?: string;
+  /**
+   * The client ID registered with the OAuth 2.0 provider.
+   * This public identifier is used in authorization requests.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "github-app-12345"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * The client secret for authenticating with the OAuth 2.0 provider.
+   * This private credential must be kept secure and not exposed to clients.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.OAUTH_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * OAuth 2.0 endpoint URLs for the authorization and token flows.
+   */
+  readonly endpoint: {
+    /**
+     * The authorization endpoint where users are redirected for authentication.
+     *
+     * @example "https://github.com/login/oauth/authorize"
+     */
+    readonly authorization: string;
+    /**
+     * The token endpoint for exchanging authorization codes for access tokens.
+     *
+     * @example "https://github.com/login/oauth/access_token"
+     */
+    readonly token: string;
+    /**
+     * Optional JWKS endpoint for verifying ID tokens.
+     * Required only if the provider returns ID tokens that need verification.
+     *
+     * @example "https://provider.com/.well-known/jwks.json"
+     */
+    readonly jwks?: string;
+  };
+  /**
+   * OAuth 2.0 scopes to request during authorization.
+   * Scopes define the level of access being requested.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: ["user:email", "read:user", "repo"]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+  /**
+   * Whether to use PKCE (Proof Key for Code Exchange) for enhanced security.
+   * Recommended for public clients and required by some providers.
+   *
+   * @default false
+   *
+   * @example
+   * ```ts
+   * {
+   *   pkce: true // Required for Twitter/X, recommended for mobile apps
+   * }
+   * ```
+   */
+  readonly pkce?: boolean;
+  /**
+   * Additional query parameters to include in the authorization request.
+   * Useful for provider-specific parameters or customizing the auth flow.
+   *
+   * @example
+   * ```ts
+   * {
+   *   query: {
+   *     access_type: "offline",    // Request refresh token
+   *     prompt: "consent",         // Force consent screen
+   *     hd: "mycompany.com"       // Google Workspace domain
+   *   }
+   * }
+   * ```
+   */
+  readonly query?: Record<string, string>;
+}
+/**
+ * OAuth 2.0 configuration without endpoint-specific fields.
+ * Used internally for provider wrapping.
+ * @internal
+ */
+type Oauth2WrappedConfig = Omit<Oauth2Config, "endpoint" | "name">;
+/**
+ * OAuth 2.0 token response containing access tokens and metadata.
+ * Provides a structured interface for token data with lazy property access.
+ * @internal
+ */
+interface Oauth2Token {
+  /** Access token for making authenticated API requests */
+  readonly access: string;
+  /** Refresh token for obtaining new access tokens (if provided) */
+  readonly refresh: string;
+  /** Token expiration time in seconds (if provided) */
+  readonly expiry: number;
+  /** Raw token response from the provider */
+  readonly raw: Record<string, unknown>;
+}
+/**
+ * User data returned by successful OAuth 2.0 authentication.
+ */
+interface Oauth2UserData {
+  /** Token set containing access token, refresh token, and metadata */
+  readonly tokenset: Oauth2Token;
+  /** Client ID used for this authentication */
+  readonly clientID: string;
+}
+/**
+ * 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"
+ *   }
+ * })
+ * ```
+ */
+declare const Oauth2Provider: (config: Oauth2Config) => Provider<Oauth2UserData>;
+//#endregion
 export { Oauth2Config, Oauth2Provider, Oauth2Token, Oauth2UserData, Oauth2WrappedConfig };