@better-auth/core 1.7.0-beta.4 → 1.7.0-beta.6

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;
@@ -42,7 +149,7 @@ export interface OAuthProvider<
 		 * before applying them.
 		 */
 		additionalParams?: Record<string, string> | undefined;
-	}) => Awaitable<URL>;
+	}) => Awaitable<AuthorizationURLResult>;
 	name: string;
 	validateAuthorizationCode: (data: {
 		code: string;
@@ -76,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
@@ -180,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;
@@ -244,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

@@ -119,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",
@@ -133,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;
+}

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,11 +18,7 @@ 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,

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;
+	}
+}