@better-auth/core 1.7.0-beta.3 → 1.7.0-beta.5

package/src/oauth2/token-endpoint-auth.ts

@@ -0,0 +1,221 @@
+import { encodeBasicCredentials } from "./basic-credentials";
+import type {
+	ClientAssertionGetter,
+	ClientAssertionGrantType,
+} from "./client-assertion";
+import { resolveClientAssertionParams } from "./client-assertion";
+import { getPrimaryClientId } from "./utils";
+
+export type TokenEndpointAuth =
+	| {
+			method: "none";
+	  }
+	| {
+			method: "client_secret_basic";
+	  }
+	| {
+			method: "client_secret_post";
+	  }
+	| {
+			method: "private_key_jwt";
+			getClientAssertion: ClientAssertionGetter;
+	  };
+
+export type TokenEndpointAuthMethod = TokenEndpointAuth["method"];
+
+export type TokenEndpointSecretAuthentication = "basic" | "post";
+
+export interface TokenEndpointClientOptions {
+	clientId?: string | string[] | undefined;
+	clientSecret?: string | undefined;
+}
+
+export interface ApplyTokenEndpointAuthInput {
+	body: URLSearchParams;
+	headers: Record<string, string>;
+	options: TokenEndpointClientOptions;
+	tokenEndpoint: string;
+	grantType: ClientAssertionGrantType;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+}
+
+function getDefaultTokenEndpointAuth(
+	options: TokenEndpointClientOptions,
+	authentication?: TokenEndpointSecretAuthentication,
+): TokenEndpointAuth {
+	if (authentication === "basic") {
+		return { method: "client_secret_basic" };
+	}
+	if (options.clientSecret) {
+		return { method: "client_secret_post" };
+	}
+	return { method: "none" };
+}
+
+function assertNoClientSecret(
+	method: "none" | "private_key_jwt",
+	options: TokenEndpointClientOptions,
+	body: URLSearchParams,
+) {
+	if (options.clientSecret || body.has("client_secret")) {
+		throw new Error(
+			`${method} token endpoint authentication cannot be combined with clientSecret`,
+		);
+	}
+}
+
+function setClientId(body: URLSearchParams, clientId: string | undefined) {
+	if (clientId) {
+		body.set("client_id", clientId);
+	}
+}
+
+function assertClientSecretConfigured(
+	method: "client_secret_basic" | "client_secret_post",
+	options: TokenEndpointClientOptions,
+): asserts options is TokenEndpointClientOptions & { clientSecret: string } {
+	if (!options.clientSecret) {
+		throw new Error(
+			`${method} token endpoint authentication requires clientSecret`,
+		);
+	}
+}
+
+function assertClientIdConfigured(
+	method: TokenEndpointAuthMethod,
+	clientId: string | undefined,
+): asserts clientId is string {
+	if (!clientId) {
+		throw new Error(
+			`${method} token endpoint authentication requires clientId`,
+		);
+	}
+}
+
+function setClientSecretPostAuth({
+	body,
+	options,
+	clientId,
+	requireClientSecret,
+}: {
+	body: URLSearchParams;
+	options: TokenEndpointClientOptions;
+	clientId: string | undefined;
+	requireClientSecret?: boolean | undefined;
+}) {
+	if (requireClientSecret) {
+		assertClientSecretConfigured("client_secret_post", options);
+	}
+	if (options.clientSecret) {
+		assertClientIdConfigured("client_secret_post", clientId);
+		setClientId(body, clientId);
+		body.set("client_secret", options.clientSecret);
+	}
+}
+
+function setClientSecretBasicAuth({
+	headers,
+	options,
+	clientId,
+	body,
+}: {
+	headers: Record<string, string>;
+	options: TokenEndpointClientOptions;
+	clientId: string | undefined;
+	body: URLSearchParams;
+}) {
+	if (body.has("client_secret")) {
+		throw new Error(
+			"client_secret_basic token endpoint authentication cannot be combined with client_secret body parameters",
+		);
+	}
+	assertClientSecretConfigured("client_secret_basic", options);
+	assertClientIdConfigured("client_secret_basic", clientId);
+	headers.authorization = encodeBasicCredentials(
+		clientId,
+		options.clientSecret,
+	);
+}
+
+function assertCompleteManualClientAssertion(body: URLSearchParams) {
+	if (body.has("client_assertion") !== body.has("client_assertion_type")) {
+		throw new Error(
+			"client_assertion and client_assertion_type must both be provided",
+		);
+	}
+}
+
+export async function applyTokenEndpointAuth({
+	body,
+	headers,
+	options,
+	tokenEndpoint,
+	grantType,
+	tokenEndpointAuth,
+	authentication,
+}: ApplyTokenEndpointAuthInput) {
+	assertCompleteManualClientAssertion(body);
+
+	const clientId = getPrimaryClientId(options.clientId);
+	if (body.has("client_assertion")) {
+		if (tokenEndpointAuth) {
+			throw new Error(
+				"client_assertion body parameters cannot be combined with tokenEndpointAuth",
+			);
+		}
+		assertNoClientSecret("private_key_jwt", options, body);
+		setClientId(body, clientId);
+		return;
+	}
+
+	const auth =
+		tokenEndpointAuth ?? getDefaultTokenEndpointAuth(options, authentication);
+
+	if (auth.method === "private_key_jwt") {
+		assertNoClientSecret(auth.method, options, body);
+		assertClientIdConfigured(auth.method, clientId);
+		if (!tokenEndpoint) {
+			throw new Error(
+				"private_key_jwt token endpoint authentication requires tokenEndpoint",
+			);
+		}
+		const assertionParams = await resolveClientAssertionParams({
+			getClientAssertion: auth.getClientAssertion,
+			context: {
+				clientId,
+				tokenEndpoint,
+				grantType,
+			},
+		});
+		setClientId(body, clientId);
+		for (const [key, value] of Object.entries(assertionParams)) {
+			body.set(key, value);
+		}
+		return;
+	}
+
+	if (auth.method === "none") {
+		assertNoClientSecret(auth.method, options, body);
+		if (grantType === "client_credentials") {
+			throw new Error(
+				"none token endpoint authentication cannot be used with client_credentials grant",
+			);
+		}
+		assertClientIdConfigured(auth.method, clientId);
+		setClientId(body, clientId);
+		return;
+	}
+
+	if (auth.method === "client_secret_basic") {
+		setClientSecretBasicAuth({ headers, options, clientId, body });
+		return;
+	}
+
+	setClientSecretPostAuth({
+		body,
+		options,
+		clientId,
+		requireClientSecret: tokenEndpointAuth?.method === "client_secret_post",
+	});
+}

package/src/oauth2/utils.ts

@@ -1,5 +1,6 @@
 import { base64Url } from "@better-auth/utils/base64";
 import type { OAuth2Tokens } from "./oauth-provider";
+import { parseScopeField } from "./scopes";
 
 export function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens {
 	const getDate = (seconds: number) => {
@@ -17,17 +18,32 @@ export function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens {
 		refreshTokenExpiresAt: data.refresh_token_expires_in
 			? getDate(data.refresh_token_expires_in)
 			: undefined,
-		scopes: data?.scope
-			? typeof data.scope === "string"
-				? data.scope.split(" ")
-				: data.scope
-			: [],
+		scopes: parseScopeField(data.scope),
 		idToken: data.id_token,
 		// Preserve the raw token response for provider-specific fields
 		raw: data,
 	};
 }
 
+/**
+ * Fill in `accessTokenExpiresAt` from the provider's configured
+ * `accessTokenExpiresIn` when the token response omitted `expires_in`. Without a
+ * known expiry, `getAccessToken` cannot tell the token is expired and never
+ * refreshes it. No-op when the provider already supplied an expiry or no
+ * fallback is configured.
+ */
+export function applyDefaultAccessTokenExpiry(
+	tokens: OAuth2Tokens,
+	accessTokenExpiresIn: number | undefined,
+): OAuth2Tokens {
+	if (!tokens.accessTokenExpiresAt && accessTokenExpiresIn) {
+		tokens.accessTokenExpiresAt = new Date(
+			Date.now() + accessTokenExpiresIn * 1000,
+		);
+	}
+	return tokens;
+}
+
 /**
  * Return the provider's primary Client ID: the single string, or the entry at
  * array index 0 for the cross-platform form used by ID token audience

package/src/oauth2/validate-authorization-code.ts

@@ -1,11 +1,42 @@
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import type { AwaitableFunction } from "../types";
-import type { ClientAssertionConfig } from "./client-assertion";
-import { resolveAssertionParams } from "./client-assertion";
 import type { ProviderOptions } from "./index";
 import { getOAuth2Tokens } from "./index";
+import type {
+	TokenEndpointAuth,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth";
+
+interface AuthorizationCodeRequestInput {
+	code: string;
+	redirectURI: string;
+	options: AwaitableFunction<Partial<ProviderOptions>>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	tokenEndpoint?: string | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface AuthorizationCodeRequestBaseInput {
+	code: string;
+	redirectURI: string;
+	options: Partial<ProviderOptions>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface ValidateAuthorizationCodeInput extends AuthorizationCodeRequestInput {
+	tokenEndpoint: string;
+}
 
 export async function authorizationCodeRequest({
 	code,
@@ -13,84 +44,50 @@ export async function authorizationCodeRequest({
 	redirectURI,
 	options,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	tokenEndpoint,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	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;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: AuthorizationCodeRequestInput) {
 	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,
-		});
-		additionalParams = { ...additionalParams, ...assertionParams };
-	}
-
-	return createAuthorizationCodeRequest({
+	const request = buildAuthorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
-		authentication,
 		deviceId,
 		headers,
 		additionalParams,
 		resource,
 	});
+
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "authorization_code",
+		tokenEndpointAuth,
+		authentication,
+	});
+
+	return request;
 }
 
-/**
- * @deprecated use async'd authorizationCodeRequest instead
- */
-export function createAuthorizationCodeRequest({
+function buildAuthorizationCodeRequest({
 	code,
 	codeVerifier,
 	redirectURI,
 	options,
-	authentication,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: Partial<ProviderOptions>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: AuthorizationCodeRequestBaseInput) {
 	const body = new URLSearchParams();
-	const requestHeaders: Record<string, any> = {
+	const requestHeaders: Record<string, string> = {
 		"content-type": "application/x-www-form-urlencoded",
 		accept: "application/json",
 		...headers,
@@ -111,21 +108,6 @@ export function createAuthorizationCodeRequest({
 			}
 		}
 	}
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
-	if (authentication === "basic") {
-		const encodedCredentials = base64.encode(
-			`${primaryClientId}:${options.clientSecret ?? ""}`,
-		);
-		requestHeaders["authorization"] = `Basic ${encodedCredentials}`;
-	} else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) {
-			body.set("client_secret", options.clientSecret);
-		}
-	}
-
 	for (const [key, value] of Object.entries(additionalParams)) {
 		if (!body.has(key)) body.append(key, value);
 	}
@@ -143,31 +125,19 @@ export async function validateAuthorizationCode({
 	options,
 	tokenEndpoint,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	tokenEndpoint: string;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: ValidateAuthorizationCodeInput) {
 	const { body, headers: requestHeaders } = await authorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		deviceId,
 		headers,

package/src/oauth2/verify-id-token.ts

@@ -0,0 +1,111 @@
+import { decodeProtectedHeader, jwtVerify } from "jose";
+import type { ProviderOptions, UpstreamProvider } from "./oauth-provider";
+
+async function sha256Hex(value: string) {
+	const data = new TextEncoder().encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(digest))
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+async function nonceMatches(
+	claimNonce: unknown,
+	nonce: string,
+	comparison: "exact" | "exact-or-sha256" = "exact",
+) {
+	if (typeof claimNonce !== "string") {
+		return false;
+	}
+	if (claimNonce === nonce) {
+		return true;
+	}
+	if (comparison === "exact-or-sha256") {
+		return claimNonce === (await sha256Hex(nonce));
+	}
+	return false;
+}
+
+/**
+ * Whether a provider can verify a client-submitted id_token.
+ *
+ * A provider supports id_token sign-in when it declares an {@link UpstreamProvider.idToken}
+ * verification config, or when the integrator supplies a `verifyIdToken` override on the
+ * provider options. A provider whose options set `disableIdTokenSignIn`, or that declares
+ * neither, rejects the client id_token sign-in path with `ID_TOKEN_NOT_SUPPORTED`.
+ */
+export function supportsIdTokenSignIn(provider: UpstreamProvider<any, any>) {
+	const options = (provider.options ?? {}) as Partial<ProviderOptions>;
+	if (options.disableIdTokenSignIn) {
+		return false;
+	}
+	return Boolean(provider.idToken || options.verifyIdToken);
+}
+
+/**
+ * Verify a client-submitted id_token against a provider's verification config.
+ *
+ * This is the single id_token verifier for every social provider. Providers no longer
+ * implement their own boolean `verifyIdToken`; they declare an {@link UpstreamProvider.idToken}
+ * config and this function performs the cryptographic check. The contract is fail-closed: a
+ * provider without a config (and without an integrator `verifyIdToken` override) returns
+ * `false`, so a forged token can never be accepted by omission.
+ *
+ * @returns `true` only when the token is authentic for the provider.
+ */
+export async function verifyProviderIdToken(
+	provider: UpstreamProvider<any, any>,
+	token: string,
+	nonce?: string,
+): Promise<boolean> {
+	const options = (provider.options ?? {}) as Partial<ProviderOptions>;
+	if (options.disableIdTokenSignIn) {
+		return false;
+	}
+	// Every verification path is fail-closed: a throw from the integrator override, a custom
+	// remote verifier, the JWKS resolver, or signature checking resolves to `false` instead of
+	// escaping to the caller as a server error.
+	try {
+		if (options.verifyIdToken) {
+			return await options.verifyIdToken(token, nonce);
+		}
+		const config = provider.idToken;
+		if (!config) {
+			return false;
+		}
+		if ("verify" in config) {
+			return await config.verify(token, nonce);
+		}
+		// Opaque (non-JWS) tokens carry no signature to check. They are accepted only when the
+		// provider opts in, in which case getUserInfo resolves identity from the access token via
+		// the provider's userinfo endpoint, which validates it (e.g. Facebook Graph access tokens).
+		if (token.split(".").length !== 3) {
+			return config.allowOpaqueToken === true;
+		}
+		// `kid` is optional in JWS: a JWKS resolver can still select a key by algorithm, so
+		// key selection is left to config.jwks. The token's `alg` only seeds the default
+		// allowed-algorithms list when the provider does not pin one.
+		const { alg } = decodeProtectedHeader(token);
+		const { payload } = await jwtVerify(token, config.jwks, {
+			issuer: config.issuer,
+			audience: config.audience,
+			algorithms: config.algorithms ?? (alg ? [alg] : undefined),
+			maxTokenAge: config.maxTokenAge,
+		});
+		if (
+			nonce &&
+			!(await nonceMatches(payload.nonce, nonce, config.nonceComparison))
+		) {
+			return false;
+		}
+		// Provider-specific claim check on the now-verified payload (e.g. Google's
+		// hosted-domain `hd`). Standard checks have already passed, so a token that
+		// fails here is authentic but does not meet the provider's extra constraint.
+		if (config.verifyClaims && !config.verifyClaims(payload)) {
+			return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}