@better-auth/sso 1.4.7-beta.2 → 1.4.7-beta.4

package/src/oidc/discovery.ts

@@ -0,0 +1,355 @@
+/**
+ * OIDC Discovery Pipeline
+ *
+ * Implements OIDC discovery document fetching, validation, and hydration.
+ * This module is used both at provider registration time (to persist validated config)
+ * and at runtime (to hydrate legacy providers that are missing metadata).
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+
+import { betterFetch } from "@better-fetch/fetch";
+import type {
+	DiscoverOIDCConfigParams,
+	HydratedOIDCConfig,
+	OIDCDiscoveryDocument,
+} from "./types";
+import { DiscoveryError, REQUIRED_DISCOVERY_FIELDS } from "./types";
+
+/** Default timeout for discovery requests (10 seconds) */
+const DEFAULT_DISCOVERY_TIMEOUT = 10000;
+
+/**
+ * Main entry point: Discover and hydrate OIDC configuration from an issuer.
+ *
+ * This function:
+ * 1. Computes the discovery URL from the issuer
+ * 2. Validates the discovery URL (stub for now)
+ * 3. Fetches the discovery document
+ * 4. Validates the discovery document (issuer match + required fields)
+ * 5. Normalizes URLs (stub for now)
+ * 6. Selects token endpoint auth method
+ * 7. Merges with existing config (existing values take precedence)
+ *
+ * @param params - Discovery parameters
+ * @returns Hydrated OIDC configuration ready for persistence
+ * @throws DiscoveryError on any failure
+ */
+export async function discoverOIDCConfig(
+	params: DiscoverOIDCConfigParams,
+): Promise<HydratedOIDCConfig> {
+	const {
+		issuer,
+		existingConfig,
+		timeout = DEFAULT_DISCOVERY_TIMEOUT,
+	} = params;
+
+	const discoveryUrl =
+		params.discoveryEndpoint ||
+		existingConfig?.discoveryEndpoint ||
+		computeDiscoveryUrl(issuer);
+
+	validateDiscoveryUrl(discoveryUrl);
+
+	const discoveryDoc = await fetchDiscoveryDocument(discoveryUrl, timeout);
+
+	validateDiscoveryDocument(discoveryDoc, issuer);
+
+	const normalizedDoc = normalizeDiscoveryUrls(discoveryDoc, issuer);
+
+	const tokenEndpointAuth = selectTokenEndpointAuthMethod(
+		normalizedDoc,
+		existingConfig?.tokenEndpointAuthentication,
+	);
+
+	const hydratedConfig: HydratedOIDCConfig = {
+		issuer: existingConfig?.issuer ?? normalizedDoc.issuer,
+		discoveryEndpoint: existingConfig?.discoveryEndpoint ?? discoveryUrl,
+		authorizationEndpoint:
+			existingConfig?.authorizationEndpoint ??
+			normalizedDoc.authorization_endpoint,
+		tokenEndpoint:
+			existingConfig?.tokenEndpoint ?? normalizedDoc.token_endpoint,
+		jwksEndpoint: existingConfig?.jwksEndpoint ?? normalizedDoc.jwks_uri,
+		userInfoEndpoint:
+			existingConfig?.userInfoEndpoint ?? normalizedDoc.userinfo_endpoint,
+		tokenEndpointAuthentication:
+			existingConfig?.tokenEndpointAuthentication ?? tokenEndpointAuth,
+		scopesSupported:
+			existingConfig?.scopesSupported ?? normalizedDoc.scopes_supported,
+	};
+
+	return hydratedConfig;
+}
+
+/**
+ * Compute the discovery URL from an issuer URL.
+ *
+ * Per OIDC Discovery spec, the discovery document is located at:
+ * <issuer>/.well-known/openid-configuration
+ *
+ * Handles trailing slashes correctly.
+ */
+export function computeDiscoveryUrl(issuer: string): string {
+	const baseUrl = issuer.endsWith("/") ? issuer.slice(0, -1) : issuer;
+	return `${baseUrl}/.well-known/openid-configuration`;
+}
+
+/**
+ * Validate a discovery URL before fetching.
+ *
+ * @param url - The discovery URL to validate
+ * @throws DiscoveryError if URL is invalid
+ */
+export function validateDiscoveryUrl(url: string): void {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+			throw new DiscoveryError(
+				"discovery_invalid_url",
+				`Discovery URL must use HTTP or HTTPS protocol: ${url}`,
+				{ url, protocol: parsed.protocol },
+			);
+		}
+	} catch (error) {
+		if (error instanceof DiscoveryError) {
+			throw error;
+		}
+		throw new DiscoveryError(
+			"discovery_invalid_url",
+			`Invalid discovery URL: ${url}`,
+			{ url },
+			{ cause: error },
+		);
+	}
+}
+
+/**
+ * Fetch the OIDC discovery document from the IdP.
+ *
+ * @param url - The discovery endpoint URL
+ * @param timeout - Request timeout in milliseconds
+ * @returns The parsed discovery document
+ * @throws DiscoveryError on network errors, timeouts, or invalid responses
+ */
+export async function fetchDiscoveryDocument(
+	url: string,
+	timeout: number = DEFAULT_DISCOVERY_TIMEOUT,
+): Promise<OIDCDiscoveryDocument> {
+	try {
+		const response = await betterFetch<OIDCDiscoveryDocument>(url, {
+			method: "GET",
+			timeout,
+		});
+
+		if (response.error) {
+			const { status } = response.error;
+
+			if (status === 404) {
+				throw new DiscoveryError(
+					"discovery_not_found",
+					"Discovery endpoint not found",
+					{
+						url,
+						status,
+					},
+				);
+			}
+
+			if (status === 408) {
+				throw new DiscoveryError(
+					"discovery_timeout",
+					"Discovery request timed out",
+					{
+						url,
+						timeout,
+					},
+				);
+			}
+
+			throw new DiscoveryError(
+				"discovery_unexpected_error",
+				`Unexpected discovery error: ${response.error.statusText}`,
+				{ url, ...response.error },
+			);
+		}
+
+		if (!response.data) {
+			throw new DiscoveryError(
+				"discovery_invalid_json",
+				"Discovery endpoint returned an empty response",
+				{ url },
+			);
+		}
+
+		const data = response.data as OIDCDiscoveryDocument | string;
+		if (typeof data === "string") {
+			throw new DiscoveryError(
+				"discovery_invalid_json",
+				"Discovery endpoint returned invalid JSON",
+				{ url, bodyPreview: data.slice(0, 200) },
+			);
+		}
+
+		return data;
+	} catch (error) {
+		if (error instanceof DiscoveryError) {
+			throw error;
+		}
+
+		// betterFetch throws AbortError on timeout (not returned as response.error)
+		// Check error.name since message varies by runtime
+		if (error instanceof Error && error.name === "AbortError") {
+			throw new DiscoveryError(
+				"discovery_timeout",
+				"Discovery request timed out",
+				{
+					url,
+					timeout,
+				},
+			);
+		}
+
+		throw new DiscoveryError(
+			"discovery_unexpected_error",
+			`Unexpected error during discovery: ${error instanceof Error ? error.message : String(error)}`,
+			{ url },
+			{ cause: error },
+		);
+	}
+}
+
+/**
+ * Validate a discovery document.
+ *
+ * Checks:
+ * 1. All required fields are present
+ * 2. Issuer matches the configured issuer (case-sensitive, exact match)
+ *
+ * Invariant: If this function returns without throwing, the document is safe
+ * to use for hydrating OIDC config (required fields present, issuer matches
+ * configured value, basic structural sanity verified).
+ *
+ * @param doc - The discovery document to validate
+ * @param configuredIssuer - The expected issuer value
+ * @throws DiscoveryError if validation fails
+ */
+export function validateDiscoveryDocument(
+	doc: OIDCDiscoveryDocument,
+	configuredIssuer: string,
+): void {
+	const missingFields: string[] = [];
+
+	for (const field of REQUIRED_DISCOVERY_FIELDS) {
+		if (!doc[field]) {
+			missingFields.push(field);
+		}
+	}
+
+	if (missingFields.length > 0) {
+		throw new DiscoveryError(
+			"discovery_incomplete",
+			`Discovery document is missing required fields: ${missingFields.join(", ")}`,
+			{ missingFields },
+		);
+	}
+
+	const discoveredIssuer = doc.issuer.endsWith("/")
+		? doc.issuer.slice(0, -1)
+		: doc.issuer;
+	const expectedIssuer = configuredIssuer.endsWith("/")
+		? configuredIssuer.slice(0, -1)
+		: configuredIssuer;
+
+	if (discoveredIssuer !== expectedIssuer) {
+		throw new DiscoveryError(
+			"issuer_mismatch",
+			`Discovered issuer "${doc.issuer}" does not match configured issuer "${configuredIssuer}"`,
+			{
+				discovered: doc.issuer,
+				configured: configuredIssuer,
+			},
+		);
+	}
+}
+
+/**
+ * Normalize URLs in the discovery document.
+ *
+ * @param doc - The discovery document
+ * @param _issuerBase - The base issuer URL
+ * @returns The normalized discovery document
+ */
+export function normalizeDiscoveryUrls(
+	doc: OIDCDiscoveryDocument,
+	_issuerBase: string,
+): OIDCDiscoveryDocument {
+	return doc;
+}
+
+/**
+ * Normalize a single URL endpoint.
+ *
+ * @param endpoint - The endpoint URL to normalize
+ * @param _issuerBase - The base issuer URL
+ * @returns The normalized endpoint URL
+ */
+export function normalizeUrl(endpoint: string, _issuerBase: string): string {
+	return endpoint;
+}
+
+/**
+ * Select the token endpoint authentication method.
+ *
+ * @param doc - The discovery document
+ * @param existing - Existing authentication method from config
+ * @returns The selected authentication method
+ */
+export function selectTokenEndpointAuthMethod(
+	doc: OIDCDiscoveryDocument,
+	existing?: "client_secret_basic" | "client_secret_post",
+): "client_secret_basic" | "client_secret_post" {
+	if (existing) {
+		return existing;
+	}
+
+	const supported = doc.token_endpoint_auth_methods_supported;
+
+	if (!supported || supported.length === 0) {
+		return "client_secret_basic";
+	}
+
+	if (supported.includes("client_secret_basic")) {
+		return "client_secret_basic";
+	}
+
+	if (supported.includes("client_secret_post")) {
+		return "client_secret_post";
+	}
+
+	return "client_secret_basic";
+}
+
+/**
+ * Check if a provider configuration needs runtime discovery.
+ *
+ * Returns true if we need discovery at runtime to complete the token exchange
+ * and validation. Specifically checks for:
+ * - `tokenEndpoint` - required for exchanging authorization code for tokens
+ * - `jwksEndpoint` - required for validating ID token signatures
+ *
+ * Note: `authorizationEndpoint` is handled separately in the sign-in flow,
+ * so it's not checked here.
+ *
+ * @param config - Partial OIDC config from the provider
+ * @returns true if runtime discovery should be performed
+ */
+export function needsRuntimeDiscovery(
+	config: Partial<HydratedOIDCConfig> | undefined,
+): boolean {
+	if (!config) {
+		return true;
+	}
+
+	return !config.tokenEndpoint || !config.jwksEndpoint;
+}

package/src/oidc/errors.ts

@@ -0,0 +1,86 @@
+/**
+ * OIDC Discovery Error Mapping
+ *
+ * Maps DiscoveryError codes to appropriate APIError responses.
+ * Used at the boundary between the discovery pipeline and HTTP handlers.
+ */
+
+import { APIError } from "better-auth/api";
+import type { DiscoveryError } from "./types";
+
+/**
+ * Maps a DiscoveryError to an appropriate APIError for HTTP responses.
+ *
+ * Error code mapping:
+ * - discovery_invalid_url       → 400 BAD_REQUEST
+ * - discovery_not_found         → 400 BAD_REQUEST
+ * - discovery_invalid_json      → 400 BAD_REQUEST
+ * - discovery_incomplete        → 400 BAD_REQUEST
+ * - issuer_mismatch             → 400 BAD_REQUEST
+ * - unsupported_token_auth_method → 400 BAD_REQUEST
+ * - discovery_timeout           → 502 BAD_GATEWAY
+ * - discovery_unexpected_error  → 502 BAD_GATEWAY
+ *
+ * @param error - The DiscoveryError to map
+ * @returns An APIError with appropriate status and message
+ */
+export function mapDiscoveryErrorToAPIError(error: DiscoveryError): APIError {
+	switch (error.code) {
+		case "discovery_timeout":
+			return new APIError("BAD_GATEWAY", {
+				message: `OIDC discovery timed out: ${error.message}`,
+				code: error.code,
+			});
+
+		case "discovery_unexpected_error":
+			return new APIError("BAD_GATEWAY", {
+				message: `OIDC discovery failed: ${error.message}`,
+				code: error.code,
+			});
+
+		case "discovery_not_found":
+			return new APIError("BAD_REQUEST", {
+				message: `OIDC discovery endpoint not found. The issuer may not support OIDC discovery, or the URL is incorrect. ${error.message}`,
+				code: error.code,
+			});
+
+		case "discovery_invalid_url":
+			return new APIError("BAD_REQUEST", {
+				message: `Invalid OIDC discovery URL: ${error.message}`,
+				code: error.code,
+			});
+
+		case "discovery_invalid_json":
+			return new APIError("BAD_REQUEST", {
+				message: `OIDC discovery returned invalid data: ${error.message}`,
+				code: error.code,
+			});
+
+		case "discovery_incomplete":
+			return new APIError("BAD_REQUEST", {
+				message: `OIDC discovery document is missing required fields: ${error.message}`,
+				code: error.code,
+			});
+
+		case "issuer_mismatch":
+			return new APIError("BAD_REQUEST", {
+				message: `OIDC issuer mismatch: ${error.message}`,
+				code: error.code,
+			});
+
+		case "unsupported_token_auth_method":
+			return new APIError("BAD_REQUEST", {
+				message: `Incompatible OIDC provider: ${error.message}`,
+				code: error.code,
+			});
+
+		default: {
+			// Exhaustive check - TypeScript will error if we miss a case
+			const _exhaustiveCheck: never = error.code;
+			return new APIError("INTERNAL_SERVER_ERROR", {
+				message: `Unexpected discovery error: ${error.message}`,
+				code: "discovery_unexpected_error",
+			});
+		}
+	}
+}

package/src/oidc/index.ts

@@ -0,0 +1,31 @@
+/**
+ * OIDC Discovery Module
+ *
+ * This module provides OIDC discovery document fetching, validation, and hydration.
+ * It is used both at provider registration time (to persist validated config)
+ * and at runtime (to hydrate legacy providers that are missing metadata).
+ */
+
+export {
+	computeDiscoveryUrl,
+	discoverOIDCConfig,
+	fetchDiscoveryDocument,
+	needsRuntimeDiscovery,
+	normalizeDiscoveryUrls,
+	normalizeUrl,
+	selectTokenEndpointAuthMethod,
+	validateDiscoveryDocument,
+	validateDiscoveryUrl,
+} from "./discovery";
+
+export { mapDiscoveryErrorToAPIError } from "./errors";
+
+export {
+	type DiscoverOIDCConfigParams,
+	DiscoveryError,
+	type DiscoveryErrorCode,
+	type HydratedOIDCConfig,
+	type OIDCDiscoveryDocument,
+	REQUIRED_DISCOVERY_FIELDS,
+	type RequiredDiscoveryField,
+} from "./types";

package/src/oidc/types.ts

@@ -0,0 +1,210 @@
+/**
+ * OIDC Discovery Types
+ *
+ * Types for the OIDC discovery document and hydrated configuration.
+ * Based on OpenID Connect Discovery 1.0 specification.
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+
+/**
+ * Raw OIDC Discovery Document as returned by the IdP's
+ * .well-known/openid-configuration endpoint.
+ *
+ * Required fields for Better Auth's OIDC support:
+ * - issuer
+ * - authorization_endpoint
+ * - token_endpoint
+ * - jwks_uri (required for ID token validation)
+ *
+ */
+export interface OIDCDiscoveryDocument {
+	/** REQUIRED. URL using the https scheme that the OP asserts as its Issuer Identifier. */
+	issuer: string;
+
+	/** REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint. */
+	authorization_endpoint: string;
+
+	/**
+	 * REQUIRED (spec says "unless only implicit flow is used").
+	 * URL of the OP's OAuth 2.0 Token Endpoint.
+	 * We only support authorization code flow.
+	 */
+	token_endpoint: string;
+
+	/** REQUIRED. URL of the OP's JSON Web Key Set document for ID token validation. */
+	jwks_uri: string;
+
+	/** RECOMMENDED. URL of the OP's UserInfo Endpoint. */
+	userinfo_endpoint?: string;
+
+	/**
+	 * OPTIONAL. JSON array containing a list of Client Authentication methods
+	 * supported by this Token Endpoint.
+	 * Default: ["client_secret_basic"]
+	 */
+	token_endpoint_auth_methods_supported?: string[];
+
+	/** OPTIONAL. JSON array containing a list of the OAuth 2.0 scope values that this server supports. */
+	scopes_supported?: string[];
+
+	/** OPTIONAL. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports. */
+	response_types_supported?: string[];
+
+	/** OPTIONAL. JSON array containing a list of the Subject Identifier types that this OP supports. */
+	subject_types_supported?: string[];
+
+	/** OPTIONAL. JSON array containing a list of the JWS signing algorithms supported by the OP. */
+	id_token_signing_alg_values_supported?: string[];
+
+	/** OPTIONAL. JSON array containing a list of the claim names that the OP may supply values for. */
+	claims_supported?: string[];
+
+	/** OPTIONAL. URL of a page containing human-readable information about the OP. */
+	service_documentation?: string;
+
+	/** OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter. */
+	claims_parameter_supported?: boolean;
+
+	/** OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter. */
+	request_parameter_supported?: boolean;
+
+	/** OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter. */
+	request_uri_parameter_supported?: boolean;
+
+	/** OPTIONAL. Boolean value specifying whether the OP requires any request_uri values to be pre-registered. */
+	require_request_uri_registration?: boolean;
+
+	/** OPTIONAL. URL of the OP's end session endpoint. */
+	end_session_endpoint?: string;
+
+	/** OPTIONAL. URL of the OP's revocation endpoint. */
+	revocation_endpoint?: string;
+
+	/** OPTIONAL. URL of the OP's introspection endpoint. */
+	introspection_endpoint?: string;
+
+	/** OPTIONAL. JSON array of PKCE code challenge methods supported (e.g., "S256", "plain"). */
+	code_challenge_methods_supported?: string[];
+
+	/** Allow additional fields from the discovery document */
+	[key: string]: unknown;
+}
+
+/**
+ * Error codes for OIDC discovery operations.
+ */
+export type DiscoveryErrorCode =
+	/** Request to discovery endpoint timed out */
+	| "discovery_timeout"
+	/** Discovery endpoint returned 404 or similar */
+	| "discovery_not_found"
+	/** Discovery endpoint returned invalid JSON */
+	| "discovery_invalid_json"
+	/** Discovery URL is invalid or malformed */
+	| "discovery_invalid_url"
+	/** Discovery document issuer doesn't match configured issuer */
+	| "issuer_mismatch"
+	/** Discovery document is missing required fields */
+	| "discovery_incomplete"
+	/** IdP only advertises token auth methods that Better Auth doesn't currently support */
+	| "unsupported_token_auth_method"
+	/** Catch-all for unexpected errors */
+	| "discovery_unexpected_error";
+
+/**
+ * Custom error class for OIDC discovery failures.
+ * Can be caught and mapped to APIError at the edge.
+ */
+export class DiscoveryError extends Error {
+	public readonly code: DiscoveryErrorCode;
+	public readonly details?: Record<string, unknown>;
+
+	constructor(
+		code: DiscoveryErrorCode,
+		message: string,
+		details?: Record<string, unknown>,
+		options?: { cause?: unknown },
+	) {
+		super(message, options);
+		this.name = "DiscoveryError";
+		this.code = code;
+		this.details = details;
+
+		// Maintains proper stack trace for where the error was thrown
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, DiscoveryError);
+		}
+	}
+}
+
+/**
+ * Hydrated OIDC configuration after discovery.
+ * This is the normalized shape that gets persisted to the database
+ * or merged into provider config at runtime.
+ *
+ * Field names are camelCase to match Better Auth conventions.
+ */
+export interface HydratedOIDCConfig {
+	/** The issuer URL (validated to match configured issuer) */
+	issuer: string;
+
+	/** The discovery endpoint URL */
+	discoveryEndpoint: string;
+
+	/** URL of the authorization endpoint */
+	authorizationEndpoint: string;
+
+	/** URL of the token endpoint */
+	tokenEndpoint: string;
+
+	/** URL of the JWKS endpoint */
+	jwksEndpoint: string;
+
+	/** URL of the userinfo endpoint (optional) */
+	userInfoEndpoint?: string;
+
+	/** Token endpoint authentication method */
+	tokenEndpointAuthentication?: "client_secret_basic" | "client_secret_post";
+
+	/** Scopes supported by the IdP */
+	scopesSupported?: string[];
+}
+
+/**
+ * Parameters for the discoverOIDCConfig function.
+ */
+export interface DiscoverOIDCConfigParams {
+	/** The issuer URL to discover configuration from */
+	issuer: string;
+
+	/**
+	 * Optional existing configuration.
+	 * Values provided here will override discovered values.
+	 */
+	existingConfig?: Partial<HydratedOIDCConfig>;
+
+	/**
+	 * Optional custom discovery endpoint URL.
+	 * If not provided, defaults to <issuer>/.well-known/openid-configuration
+	 */
+	discoveryEndpoint?: string;
+
+	/**
+	 * Optional timeout in milliseconds for the discovery request.
+	 * @default 10000 (10 seconds)
+	 */
+	timeout?: number;
+}
+
+/**
+ * Required fields that must be present in a valid discovery document.
+ */
+export const REQUIRED_DISCOVERY_FIELDS = [
+	"issuer",
+	"authorization_endpoint",
+	"token_endpoint",
+	"jwks_uri",
+] as const;
+
+export type RequiredDiscoveryField = (typeof REQUIRED_DISCOVERY_FIELDS)[number];