@better-auth/core 1.7.0-beta.1 → 1.7.0-beta.10

package/src/oauth2/oauth-provider.ts

@@ -1,5 +1,59 @@
+import type { JWTVerifyGetKey } from "jose";
 import type { Awaitable, LiteralString } from "../types";
 
+/**
+ * id_token verification config for a social provider.
+ *
+ * Declares how a client-submitted id_token is verified. The shared verifier
+ * (`verifyProviderIdToken`) consumes this instead of each provider implementing its own
+ * boolean check, so verification is centralized and fail-closed: a provider without a config
+ * cannot accept a forged token by omission.
+ */
+export type OAuthIdTokenConfig =
+	| {
+			/**
+			 * JWKS resolver used to verify the JWS signature. Accepts a jose
+			 * `createRemoteJWKSet` resolver or a key-resolving function
+			 * `(protectedHeader) => key`.
+			 */
+			jwks: JWTVerifyGetKey;
+			/** Expected `iss`. Omit for providers whose issuer varies per tenant. */
+			issuer?: (string | string[]) | undefined;
+			/** Expected `aud`, usually the client ID. */
+			audience: string | string[];
+			/** Permitted JWS algorithms. Defaults to the token's `alg` header. */
+			algorithms?: string[] | undefined;
+			/** Maximum token age passed to jose (e.g. `"1h"`). */
+			maxTokenAge?: string | undefined;
+			/**
+			 * How the `nonce` claim is compared to the expected nonce.
+			 * - `"exact"` (default): strict equality.
+			 * - `"exact-or-sha256"`: matches the raw nonce or its SHA-256 hex digest (Apple).
+			 */
+			nonceComparison?: ("exact" | "exact-or-sha256") | undefined;
+			/**
+			 * Accept non-JWS (opaque) tokens without signature verification. Identity is then
+			 * resolved by getUserInfo from the access token via the provider userinfo endpoint,
+			 * which validates it (e.g. Facebook Graph access tokens).
+			 */
+			allowOpaqueToken?: boolean | undefined;
+			/**
+			 * Provider-specific claim check applied after the signature, issuer,
+			 * audience, max-age, and nonce checks pass. Return `false` to reject the
+			 * token. Used to enforce constraints the standard checks cannot express,
+			 * e.g. Google's hosted-domain (`hd`) restriction. Omitted by providers
+			 * that have no extra claim requirement.
+			 */
+			verifyClaims?: ((claims: Record<string, unknown>) => boolean) | undefined;
+	  }
+	| {
+			/**
+			 * Custom verifier for providers that cannot verify against a local JWKS, such as a
+			 * remote verification endpoint (e.g. LINE).
+			 */
+			verify: (token: string, nonce?: string) => Promise<boolean>;
+	  };
+
 export interface OAuth2Tokens {
 	tokenType?: string | undefined;
 	accessToken?: string | undefined;
@@ -23,11 +77,34 @@ export type OAuth2UserInfo = {
 	emailVerified: boolean;
 };
 
+/**
+ * Request metadata available to provider refresh hooks.
+ *
+ * The refresh flow may be triggered by endpoints such as `getAccessToken` or
+ * `refreshToken`; this context gives provider hooks access to the triggering
+ * request without exposing the full endpoint implementation surface.
+ */
+export interface OAuthRefreshContext {
+	headers?: Headers | undefined;
+	request?: Request | undefined;
+}
+
 export interface OAuthProvider<
 	T extends Record<string, any> = Record<string, any>,
 	O extends Record<string, any> = Partial<ProviderOptions>,
 > {
 	id: LiteralString;
+	/**
+	 * Optional path under the resolved per-request `baseURL` where this
+	 * provider's OAuth callback handler is mounted. Providers that use the
+	 * shared `/callback/<id>` route can omit this.
+	 *
+	 * Custom paths must start with `/`.
+	 *
+	 * Endpoints compose `redirectURI = ctx.context.baseURL + callbackPath` per
+	 * request, so the provider must not hardcode an origin or `baseURL` here.
+	 */
+	callbackPath?: string | undefined;
 	createAuthorizationURL: (data: {
 		state: string;
 		codeVerifier: string;
@@ -35,6 +112,19 @@ export interface OAuthProvider<
 		redirectURI: string;
 		display?: string | undefined;
 		loginHint?: string | undefined;
+		/**
+		 * OIDC nonce generated by the redirect initiator and persisted in OAuth
+		 * state. Providers that set `requiresIdTokenNonce` must forward this to
+		 * the authorization URL as the `nonce` parameter.
+		 */
+		idTokenNonce?: string | undefined;
+		/**
+		 * Extra query parameters to append to the authorization URL.
+		 * Providers forward these to the shared `createAuthorizationURL` helper,
+		 * which drops any keys present in `RESERVED_AUTHORIZATION_PARAMS`
+		 * before applying them.
+		 */
+		additionalParams?: Record<string, string> | undefined;
 	}) => Awaitable<URL>;
 	name: string;
 	validateAuthorizationCode: (data: {
@@ -45,6 +135,12 @@ export interface OAuthProvider<
 	}) => Promise<OAuth2Tokens | null>;
 	getUserInfo: (
 		token: OAuth2Tokens & {
+			/**
+			 * OIDC nonce recovered from OAuth state. Providers that required an
+			 * ID-token nonce must pass this to `verifyProviderIdToken` before
+			 * trusting ID-token claims.
+			 */
+			expectedIdTokenNonce?: string | undefined;
 			/**
 			 * The user object from the provider
 			 * This is only available for some providers like Apple
@@ -64,27 +160,38 @@ export interface OAuthProvider<
 		data: T;
 	} | null>;
 	/**
-	 * Custom function to refresh a token
+	 * Custom function to refresh a token.
+	 *
+	 * Receives request metadata from the endpoint that triggered the refresh.
+	 * Providers that don't need request-scoped data can ignore the second
+	 * argument.
 	 */
 	refreshAccessToken?:
-		| ((refreshToken: string) => Promise<OAuth2Tokens>)
+		| ((
+				refreshToken: string,
+				ctx?: OAuthRefreshContext,
+		  ) => Promise<OAuth2Tokens>)
 		| undefined;
 	revokeToken?: ((token: string) => Promise<void>) | undefined;
 	/**
-	 * Verify the id token
-	 * @param token - The id token
-	 * @param nonce - The nonce
-	 * @returns True if the id token is valid, false otherwise
+	 * Declarative id_token verification config consumed by the shared
+	 * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
+	 * verify method, which keeps verification centralized and fail-closed.
 	 */
-	verifyIdToken?:
-		| ((token: string, nonce?: string) => Promise<boolean>)
-		| undefined;
+	idToken?: OAuthIdTokenConfig | undefined;
 	/**
 	 * The expected issuer identifier for this provider (RFC 9207).
 	 * When set, the callback handler validates the `iss` query parameter
 	 * against this value to prevent authorization server mix-up attacks.
 	 */
 	issuer?: string | undefined;
+	/**
+	 * Require shared OAuth redirect routes to bind ID-token verification to an
+	 * authorization request nonce. When true, routes generate `idTokenNonce`,
+	 * pass it to `createAuthorizationURL`, persist it in state, and provide it
+	 * back to `getUserInfo` as `expectedIdTokenNonce`.
+	 */
+	requiresIdTokenNonce?: boolean | undefined;
 	/**
 	 * Disable implicit sign up for new users. When set to true for the provider,
 	 * sign-in need to be called with with requestSignUp as true to create new users.
@@ -94,6 +201,17 @@ export interface OAuthProvider<
 	 * Disable sign up for new users.
 	 */
 	disableSignUp?: boolean | undefined;
+	/**
+	 * Accept callbacks that arrive without a `state` parameter. When true,
+	 * the shared OAuth callback handler restarts the flow server-side with
+	 * fresh `state` and PKCE instead of rejecting the request. Intended for
+	 * providers that initiate OAuth without RP-side flow kickoff (e.g.
+	 * Clever). Leave unset for any provider that always initiates from the
+	 * RP.
+	 *
+	 * @default false
+	 */
+	allowIdpInitiated?: boolean | undefined;
 	/**
 	 * Options for the provider
 	 */
@@ -104,9 +222,10 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 	/**
 	 * The client ID of your application.
 	 *
-	 * This is usually a string but can be any type depending on the provider.
+	 * Some providers accept multiple platform client IDs. The first entry is the
+	 * primary client ID used for token endpoint client authentication.
 	 */
-	clientId?: unknown | undefined;
+	clientId?: LiteralString | string[] | undefined;
 	/**
 	 * The client secret of your application
 	 */
@@ -225,4 +344,27 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 	 * @default false
 	 */
 	overrideUserInfoOnSignIn?: boolean | undefined;
+	/**
+	 * Require this provider's email to be verified before a session is created.
+	 *
+	 * When the provider reports the email as unverified, the user and account are
+	 * still created/linked, but no session is issued: the OAuth callback redirects
+	 * with `?error=email_not_verified` and id-token sign-in returns a `403`
+	 * `EMAIL_NOT_VERIFIED`. A verification email is (re)sent per the
+	 * `emailVerification` settings (`sendOnSignUp` / `sendOnSignIn`).
+	 *
+	 * The gate checks the local user's verification state, not the provider's
+	 * claim on each request: a user already verified through another method (or a
+	 * prior verified sign-in) keeps access even if the provider later reports the
+	 * email as unverified.
+	 *
+	 * This is opt-in per provider and is independent of
+	 * `emailAndPassword.requireEmailVerification`; enabling that does not gate
+	 * social sign-in. Only enable it for providers that report a trustworthy
+	 * `email_verified` signal: several providers always report the email as
+	 * unverified, which would block every sign-in.
+	 *
+	 * @default false
+	 */
+	requireEmailVerification?: boolean | undefined;
 };

package/src/oauth2/refresh-access-token.ts

@@ -1,99 +1,105 @@
-import { base64 } from "@better-auth/utils/base64";
-import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
-import type { ClientAssertionConfig } from "./client-assertion";
-import { resolveAssertionParams } from "./client-assertion";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import { fetchRefusingRedirects } from "./reject-redirects";
+import type {
+	TokenEndpointAuth,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth";
+import { parseScopeField } from "./utils";
+
+interface RefreshAccessTokenRequestInput {
+	refreshToken: string;
+	options: AwaitableFunction<Partial<ProviderOptions>>;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	tokenEndpoint?: string | undefined;
+	extraParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface RefreshAccessTokenRequestBaseInput {
+	refreshToken: string;
+	options: ProviderOptions;
+	extraParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface RefreshAccessTokenInput extends RefreshAccessTokenRequestInput {
+	options: Partial<ProviderOptions>;
+	tokenEndpoint: string;
+}
+
+/**
+ * Body keys owned by the refresh-token flow or unsafe to copy from caller input.
+ */
+const BLOCKED_REFRESH_TOKEN_PARAMS = [
+	"grant_type",
+	"refresh_token",
+	"__proto__",
+	"constructor",
+	"prototype",
+] as const;
+
+const BLOCKED_REFRESH_TOKEN_PARAMS_SET: ReadonlySet<string> = new Set(
+	BLOCKED_REFRESH_TOKEN_PARAMS,
+);
 
 export async function refreshAccessTokenRequest({
 	refreshToken,
 	options,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	tokenEndpoint,
 	extraParams,
 	resource,
-}: {
-	refreshToken: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	/** Token endpoint URL. Used as the JWT `aud` claim when signing assertions. */
-	tokenEndpoint?: string | undefined;
-	extraParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: RefreshAccessTokenRequestInput) {
 	options = typeof options === "function" ? await options() : options;
-
-	if (authentication === "private_key_jwt") {
-		if (!clientAssertion) {
-			throw new Error(
-				"private_key_jwt authentication requires a clientAssertion configuration",
-			);
-		}
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
-		const assertionParams = await resolveAssertionParams({
-			clientAssertion,
-			clientId: primaryClientId,
-			tokenEndpoint,
-		});
-		extraParams = { ...extraParams, ...assertionParams };
-	}
-
-	return createRefreshAccessTokenRequest({
+	const request = buildRefreshAccessTokenRequest({
 		refreshToken,
 		options,
-		authentication,
 		extraParams,
 		resource,
 	});
+
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "refresh_token",
+		tokenEndpointAuth,
+		authentication,
+	});
+
+	return request;
 }
 
-/**
- * @deprecated use async'd refreshAccessTokenRequest instead
- */
-export function createRefreshAccessTokenRequest({
+function applyRefreshExtraParams(
+	body: URLSearchParams,
+	extraParams: Record<string, string> | undefined,
+) {
+	if (!extraParams) return;
+	for (const [key, value] of Object.entries(extraParams)) {
+		if (BLOCKED_REFRESH_TOKEN_PARAMS_SET.has(key)) continue;
+		body.set(key, value);
+	}
+}
+
+function buildRefreshAccessTokenRequest({
 	refreshToken,
 	options,
-	authentication,
 	extraParams,
 	resource,
-}: {
-	refreshToken: string;
-	options: ProviderOptions;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	extraParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: RefreshAccessTokenRequestBaseInput) {
 	const body = new URLSearchParams();
-	const headers: Record<string, any> = {
+	const headers: Record<string, string> = {
 		"content-type": "application/x-www-form-urlencoded",
 		accept: "application/json",
 	};
 
 	body.set("grant_type", "refresh_token");
 	body.set("refresh_token", refreshToken);
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
-	if (authentication === "basic") {
-		if (primaryClientId) {
-			headers["authorization"] =
-				"Basic " +
-				base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`);
-		} else {
-			headers["authorization"] =
-				"Basic " + base64.encode(`:${options.clientSecret ?? ""}`);
-		}
-	} else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) {
-			body.set("client_secret", options.clientSecret);
-		}
-	}
-
 	if (resource) {
 		if (typeof resource === "string") {
 			body.append("resource", resource);
@@ -104,9 +110,7 @@ export function createRefreshAccessTokenRequest({
 		}
 	}
 	if (extraParams) {
-		for (const [key, value] of Object.entries(extraParams)) {
-			body.set(key, value);
-		}
+		applyRefreshExtraParams(body, extraParams);
 	}
 
 	return {
@@ -120,32 +124,27 @@ export async function refreshAccessToken({
 	options,
 	tokenEndpoint,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	extraParams,
-}: {
-	refreshToken: string;
-	options: Partial<ProviderOptions>;
-	tokenEndpoint: string;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	extraParams?: Record<string, string> | undefined;
-}): Promise<OAuth2Tokens> {
+	resource,
+}: RefreshAccessTokenInput): Promise<OAuth2Tokens> {
 	const { body, headers } = await refreshAccessTokenRequest({
 		refreshToken,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		extraParams,
+		resource,
 	});
 
-	const { data, error } = await betterFetch<{
+	const { data, error } = await fetchRefusingRedirects<{
 		access_token: string;
 		refresh_token?: string | undefined;
 		expires_in?: number | undefined;
 		refresh_token_expires_in?: number | undefined;
 		token_type?: string | undefined;
-		scope?: string | undefined;
+		scope?: unknown;
 		id_token?: string | undefined;
 	}>(tokenEndpoint, {
 		method: "POST",
@@ -159,7 +158,7 @@ export async function refreshAccessToken({
 		accessToken: data.access_token,
 		refreshToken: data.refresh_token,
 		tokenType: data.token_type,
-		scopes: data.scope?.split(" "),
+		scopes: parseScopeField(data.scope),
 		idToken: data.id_token,
 	};
 

package/src/oauth2/reject-redirects.ts

@@ -0,0 +1,75 @@
+// cspell:ignore workerd
+import type { BetterFetchOption } from "@better-fetch/fetch";
+import { betterFetch } from "@better-fetch/fetch";
+import { BetterAuthError } from "../error";
+
+const httpRedirectStatuses = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * Whether a response from a `redirect: "manual"` fetch is a redirect.
+ *
+ * Node/undici exposes the real 3xx status. Spec-compliant runtimes (Cloudflare
+ * Workers, Deno, browsers) return an opaque-redirect filtered response with
+ * status 0 and type `"opaqueredirect"`, so the status alone is not enough.
+ */
+function isRedirectResponse(response: Response): boolean {
+	return (
+		response.type === "opaqueredirect" ||
+		httpRedirectStatuses.has(response.status)
+	);
+}
+
+function redirectRefused(endpoint: string): BetterAuthError {
+	return new BetterAuthError(
+		`The OAuth endpoint "${endpoint}" returned an HTTP redirect. Server-side OAuth fetches refuse redirects to prevent SSRF; configure the final endpoint URL.`,
+	);
+}
+
+/**
+ * Fetch option that refuses HTTP redirects portably.
+ *
+ * Cloudflare Workers (workerd) rejects `redirect: "error"`, so manual mode is
+ * used and the resolved response is checked with {@link assertResponseNotRedirect}
+ * (or, for betterFetch, with {@link fetchRefusingRedirects}).
+ */
+export const noFollowRedirect = { redirect: "manual" } as const;
+
+/**
+ * Throw when a native-`fetch` response (e.g. jose's JWKS loader) resolved to a
+ * redirect, so an attacker-influenced endpoint cannot bounce a server-side
+ * request to an internal address.
+ */
+export function assertResponseNotRedirect(
+	endpoint: string,
+	response: Response,
+): void {
+	if (isRedirectResponse(response)) throw redirectRefused(endpoint);
+}
+
+/**
+ * betterFetch that refuses HTTP redirects on a server-side OAuth fetch.
+ *
+ * Returns the betterFetch result and throws if the endpoint redirected, on both
+ * undici (real 3xx status) and spec-compliant runtimes (opaque redirect, where
+ * the error status is 0). The redirect is never followed on any runtime.
+ */
+export async function fetchRefusingRedirects<T>(
+	url: string,
+	options?: BetterFetchOption,
+) {
+	let redirected = false;
+	const onError = options?.onError;
+	const result = await betterFetch<T>(url, {
+		...options,
+		...noFollowRedirect,
+		async onError(context) {
+			if (isRedirectResponse(context.response)) redirected = true;
+			await onError?.(context);
+		},
+	}).catch((error) => {
+		if (redirected) throw redirectRefused(url);
+		throw error;
+	});
+	if (redirected) throw redirectRefused(url);
+	return result;
+}