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

package/src/oauth2/index.ts

@@ -1,38 +1,66 @@
+export { additionalAuthorizationParamsSchema } from "./authorization-params";
+export {
+	decodeBasicCredentials,
+	encodeBasicCredentials,
+} from "./basic-credentials";
 export type {
-	AssertionSigningAlgorithm,
-	ClientAssertionConfig,
+	ClientAssertionContext,
+	ClientAssertionGetter,
+	ClientAssertionGrantType,
+	PrivateKeyJwtClientAssertionGetterOptions,
+	PrivateKeyJwtSigningAlgorithm,
 } from "./client-assertion";
 export {
-	ASSERTION_SIGNING_ALGORITHMS,
 	CLIENT_ASSERTION_TYPE,
-	resolveAssertionParams,
-	signClientAssertion,
+	createPrivateKeyJwtClientAssertionGetter,
+	PRIVATE_KEY_JWT_SIGNING_ALGORITHMS,
+	resolveClientAssertionParams,
+	signPrivateKeyJwtClientAssertion,
 } from "./client-assertion";
 export {
 	clientCredentialsToken,
 	clientCredentialsTokenRequest,
-	createClientCredentialsTokenRequest,
 } from "./client-credentials-token";
-export { createAuthorizationURL } from "./create-authorization-url";
+export {
+	createAuthorizationURL,
+	RESERVED_AUTHORIZATION_PARAMS,
+	RESERVED_AUTHORIZATION_PARAMS_SET,
+} from "./create-authorization-url";
 export type {
+	AuthorizationURLResult,
+	GrantAuthority,
 	OAuth2Tokens,
 	OAuth2UserInfo,
-	OAuthProvider,
+	OAuthIdTokenConfig,
+	ProviderGrantAuthority,
 	ProviderOptions,
+	UpstreamProvider,
 } from "./oauth-provider";
 export {
-	createRefreshAccessTokenRequest,
 	refreshAccessToken,
 	refreshAccessTokenRequest,
 } from "./refresh-access-token";
 export {
+	includesGrantedScope,
+	normalizeScopes,
+	parseScopeField,
+	readGrantedScopes,
+	resolveRequestedScopes,
+	unionGrantedScopes,
+} from "./scopes";
+export type {
+	TokenEndpointAuth,
+	TokenEndpointAuthMethod,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+export {
+	applyDefaultAccessTokenExpiry,
 	generateCodeChallenge,
 	getOAuth2Tokens,
 	getPrimaryClientId,
 } from "./utils";
 export {
 	authorizationCodeRequest,
-	createAuthorizationCodeRequest,
 	validateAuthorizationCode,
 	validateToken,
 } from "./validate-authorization-code";
@@ -41,3 +69,7 @@ export {
 	verifyAccessToken,
 	verifyJwsAccessToken,
 } from "./verify";
+export {
+	supportsIdTokenSignIn,
+	verifyProviderIdToken,
+} from "./verify-id-token";

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,64 @@ export type OAuth2UserInfo = {
 	emailVerified: boolean;
 };
 
-export interface OAuthProvider<
+/**
+ * The result of building a provider authorization URL.
+ *
+ * `requestedScopes` is the effective set of scopes encoded in the URL (the
+ * provider's built-in defaults + configured `options.scope` + per-request
+ * `scopes`, composed by `resolveRequestedScopes`). Callers persist it so the
+ * callback can fall back to the request when the provider omits `scope` from
+ * its token response (RFC 6749 §5.1).
+ */
+export interface AuthorizationURLResult {
+	url: URL;
+	requestedScopes: string[];
+}
+
+/**
+ * How much an RP trusts a provider's echoed token-response `scope` when
+ * persisting `account.grantedScopes`.
+ *
+ * - `"full-grant"`: the echo is the user's complete current grant, so the seam
+ *   replaces the stored grant with it. This is the only path that may narrow
+ *   the grant. Declare it only for providers whose token response reports the
+ *   full combined grant, e.g. Google with `include_granted_scopes`.
+ * - `"projection"`: the echo is this request's subset, so the seam unions it
+ *   onto the stored grant. The safe default for every provider.
+ * - `"absent-echo"`: the provider omitted `scope`, so the grant equals what was
+ *   requested (RFC 6749 §5.1) and the seam unions the requested set. Resolved
+ *   at runtime by the persistence seam, never declared by a provider.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+export type GrantAuthority = "full-grant" | "projection" | "absent-echo";
+
+/**
+ * The authority a provider may declare for its own echoed scope. `"absent-echo"`
+ * is excluded because it is a runtime condition (an omitted echo), not a
+ * provider trait.
+ */
+export type ProviderGrantAuthority = Exclude<GrantAuthority, "absent-echo">;
+
+export interface UpstreamProvider<
 	T extends Record<string, any> = Record<string, any>,
 	O extends Record<string, any> = Partial<ProviderOptions>,
 > {
 	id: LiteralString;
+	/**
+	 * The path the provider redirects back to, relative to the app base URL,
+	 * e.g. `/callback/google`.
+	 */
+	callbackPath: string;
+	/**
+	 * How the persistence seam treats this provider's echoed token-response
+	 * `scope`. Declare `"full-grant"` only when the echo is the user's complete
+	 * current grant (e.g. Google with `include_granted_scopes`); otherwise the
+	 * echo is unioned onto the stored grant.
+	 *
+	 * @default "projection"
+	 */
+	grantAuthority?: ProviderGrantAuthority | undefined;
 	createAuthorizationURL: (data: {
 		state: string;
 		codeVerifier: string;
@@ -35,7 +142,14 @@ export interface OAuthProvider<
 		redirectURI: string;
 		display?: string | undefined;
 		loginHint?: string | undefined;
-	}) => Awaitable<URL>;
+		/**
+		 * 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<AuthorizationURLResult>;
 	name: string;
 	validateAuthorizationCode: (data: {
 		code: string;
@@ -69,16 +183,12 @@ export interface OAuthProvider<
 	refreshAccessToken?:
 		| ((refreshToken: string) => 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
@@ -94,6 +204,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 +225,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
 	 */
@@ -161,6 +283,10 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 					emailVerified: boolean;
 					[key: string]: any;
 				};
+				// TODO: type as `Profile` once provider getUserInfo paths that return a
+				// narrower data shape than their declared profile are reconciled; today
+				// `any` is load-bearing for those (e.g. facebook) and tightening it ripples
+				// across ~10 providers, out of scope for the grant refactor.
 				data: any;
 		  } | null>)
 		| undefined;
@@ -225,4 +351,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,78 @@
-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 type {
+	TokenEndpointAuth,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth";
+
+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;
+}
 
 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 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);
@@ -120,23 +99,18 @@ 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<{
@@ -145,7 +119,7 @@ export async function refreshAccessToken({
 		expires_in?: number | undefined;
 		refresh_token_expires_in?: number | undefined;
 		token_type?: string | undefined;
-		scope?: string | undefined;
+		scope?: (string | string[]) | undefined;
 		id_token?: string | undefined;
 	}>(tokenEndpoint, {
 		method: "POST",
@@ -159,7 +133,7 @@ export async function refreshAccessToken({
 		accessToken: data.access_token,
 		refreshToken: data.refresh_token,
 		tokenType: data.token_type,
-		scopes: data.scope?.split(" "),
+		scopes: Array.isArray(data.scope) ? data.scope : data.scope?.split(" "),
 		idToken: data.id_token,
 	};
 

package/src/oauth2/scopes.ts

@@ -0,0 +1,118 @@
+import type { ProviderOptions } from "./oauth-provider";
+
+/**
+ * Parse a provider's `scope` token-response field into a string array.
+ *
+ * RFC 6749 §3.3 defines `scope` as a space-delimited string, but providers
+ * vary: some (e.g. Twitch) return an already-split array. Accept both, plus the
+ * omitted/empty case, without ever calling `.split` on a non-string. Returns
+ * `[]` when no scope is present.
+ *
+ * @see https://github.com/better-auth/better-auth/issues/9076
+ */
+export function parseScopeField(scope: unknown): string[] {
+	if (Array.isArray(scope))
+		return scope.filter((s): s is string => typeof s === "string" && s !== "");
+	if (typeof scope === "string") return scope.split(" ").filter(Boolean);
+	return [];
+}
+
+/**
+ * Normalize a scope set into a single deduped, sorted array.
+ *
+ * Scope order is insignificant per RFC 6749 §3.3, so normalize for idempotent
+ * writes and trivial comparisons: trim each token, drop empties, dedupe, and
+ * sort ascending. Returns `[]` when the union is empty.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ */
+export function normalizeScopes(
+	stored: string[] | null | undefined,
+	incoming?: string[] | undefined,
+): string[] {
+	const normalized = new Set<string>();
+	for (const scope of [...(stored ?? []), ...(incoming ?? [])]) {
+		const trimmed = scope.trim();
+		if (trimmed) normalized.add(trimmed);
+	}
+	return [...normalized].sort();
+}
+
+/**
+ * Union the stored granted-scope set with the scopes observed on an
+ * authorization or token exchange.
+ *
+ * The provider's echoed `scope` is authoritative when present. RFC 6749 §3.3
+ * and §5.1 say an omitted or empty echo means the grant equals what was
+ * requested, so fall back to `requested` in that case. The result unions onto
+ * the stored grant (never narrows on a normal write) and is normalized per
+ * {@link normalizeScopes}.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+export function unionGrantedScopes(
+	stored: string[] | null | undefined,
+	echoed: string[] | undefined,
+	requested: string[] | undefined,
+): string[] {
+	const granted = echoed?.length ? echoed : requested;
+	return normalizeScopes(stored, granted);
+}
+
+/**
+ * Coerce a stored granted-scope value into a usable array.
+ *
+ * `account.grantedScopes` is nullable (legacy rows and non-OAuth accounts read
+ * as unset), and on dialects that store the array as a JSON string a malformed
+ * operator backfill could deserialize to a non-array. Both collapse to `[]`
+ * here so every reader works against a real `string[]` without re-deriving the
+ * guard.
+ */
+export function readGrantedScopes(
+	stored: string[] | null | undefined,
+): string[] {
+	return Array.isArray(stored) ? stored : [];
+}
+
+/**
+ * Test whether a normalized granted-scope set contains a specific scope.
+ *
+ * Matching is exact and case-sensitive per RFC 6749 §3.3. The argument is the
+ * normalized `account.grantedScopes` array; a raw provider `scope` string must
+ * be run through {@link parseScopeField} first.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ */
+export function includesGrantedScope(
+	granted: string[] | null | undefined,
+	scope: string,
+): boolean {
+	return granted?.includes(scope) ?? false;
+}
+
+/**
+ * Compose the effective scope set to encode in a single authorization URL.
+ *
+ * Precedence: the provider's built-in defaults (unless `disableDefaultScope`),
+ * then the integrator's configured `options.scope`, then the per-request
+ * `scopes`. The result is the value persisted into OAuth state as the RFC 6749
+ * §5.1 fallback, so it is preserved verbatim (not normalized) to match what is
+ * sent to the provider.
+ *
+ * `defaultScopes` is a parameter rather than a provider-contract field so the
+ * runtime-synthesized generic OAuth provider, which has no static default set,
+ * can pass its configured scopes here.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+export function resolveRequestedScopes(
+	options: Pick<ProviderOptions, "scope" | "disableDefaultScope"> | undefined,
+	defaultScopes: string[],
+	perRequestScopes: string[] | undefined,
+): string[] {
+	const scopes = options?.disableDefaultScope ? [] : [...defaultScopes];
+	if (options?.scope) scopes.push(...options.scope);
+	if (perRequestScopes) scopes.push(...perRequestScopes);
+	return scopes;
+}