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

package/dist/api/index.d.mts

@@ -2,7 +2,7 @@ import { BetterAuthDBSchema, ModelNames, SecondaryStorage } from "../db/type.mjs
 import { DBAdapter } from "../db/adapter/index.mjs";
 import { createLogger } from "../env/logger.mjs";
 import { AuthContext } from "../types/context.mjs";
-import { OAuthProvider } from "../oauth2/oauth-provider.mjs";
+import { UpstreamProvider } from "../oauth2/oauth-provider.mjs";
 import * as better_call0 from "better-call";
 import { EndpointContext, EndpointOptions, StrictEndpoint } from "better-call";
 import * as _better_auth_core0 from "@better-auth/core";
@@ -87,7 +87,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: _better_auth_core0.BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {
@@ -216,7 +216,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: _better_auth_core0.BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.7.0-beta.4";
+const __betterAuthVersion = "1.7.0-beta.5";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/adapter/factory.mjs

@@ -1,7 +1,7 @@
 import { BetterAuthError } from "../../error/index.mjs";
+import { getAuthTables } from "../get-tables.mjs";
 import { getColorDepth } from "../../env/color-depth.mjs";
 import { TTY_COLORS, createLogger } from "../../env/logger.mjs";
-import { getAuthTables } from "../get-tables.mjs";
 import { safeJSONParse } from "../../utils/json.mjs";
 import { initGetDefaultModelName } from "./get-default-model-name.mjs";
 import { initGetDefaultFieldName } from "./get-default-field-name.mjs";
@@ -722,7 +722,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 						}]
 					});
 					if (typeof deleted !== "number") throw new BetterAuthError(`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`);
-					return deleted > 0 ? target : null;
+					return Number.isFinite(deleted) && deleted > 0 ? target : null;
 				}));
 				resultNeedsOutputTransform = false;
 			}

package/dist/db/get-tables.mjs

@@ -228,10 +228,10 @@ const getAuthTables = (options) => {
 					returned: false,
 					fieldName: options.account?.fields?.refreshTokenExpiresAt || "refreshTokenExpiresAt"
 				},
-				scope: {
-					type: "string",
+				grantedScopes: {
+					type: "string[]",
 					required: false,
-					fieldName: options.account?.fields?.scope || "scope"
+					fieldName: options.account?.fields?.grantedScopes || "grantedScopes"
 				},
 				password: {
 					type: "string",

package/dist/db/schema/account.d.mts

@@ -16,7 +16,7 @@ declare const accountSchema: z.ZodObject<{
   idToken: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   accessTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
   refreshTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
-  scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  grantedScopes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
   password: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 type BaseAccount = z.infer<typeof accountSchema>;

package/dist/db/schema/account.mjs

@@ -10,7 +10,7 @@ const accountSchema = coreSchema.extend({
 	idToken: z.string().nullish(),
 	accessTokenExpiresAt: z.date().nullish(),
 	refreshTokenExpiresAt: z.date().nullish(),
-	scope: z.string().nullish(),
+	grantedScopes: z.array(z.string()).nullish(),
 	password: z.string().nullish()
 });
 //#endregion

package/dist/env/env-impl.mjs

@@ -27,7 +27,7 @@ const env = new Proxy(_envShim, {
 function toBoolean(val) {
 	return val ? val !== "false" : false;
 }
-const nodeENV = typeof process !== "undefined" && process.env && process.env.NODE_ENV || "";
+const nodeENV = env.NODE_ENV ?? "";
 /** Detect if `NODE_ENV` environment variable is `production` */
 const isProduction = nodeENV === "production";
 /** Detect if `NODE_ENV` environment variable is `dev` or `development` */

package/dist/error/codes.d.mts

@@ -29,6 +29,11 @@ declare const BASE_ERROR_CODES: {
   TOKEN_EXPIRED: RawError<"TOKEN_EXPIRED">;
   ID_TOKEN_NOT_SUPPORTED: RawError<"ID_TOKEN_NOT_SUPPORTED">;
   FAILED_TO_GET_USER_INFO: RawError<"FAILED_TO_GET_USER_INFO">;
+  PROVIDER_NOT_SUPPORTED: RawError<"PROVIDER_NOT_SUPPORTED">;
+  TOKEN_REFRESH_NOT_SUPPORTED: RawError<"TOKEN_REFRESH_NOT_SUPPORTED">;
+  REFRESH_TOKEN_NOT_FOUND: RawError<"REFRESH_TOKEN_NOT_FOUND">;
+  FAILED_TO_GET_ACCESS_TOKEN: RawError<"FAILED_TO_GET_ACCESS_TOKEN">;
+  FAILED_TO_REFRESH_ACCESS_TOKEN: RawError<"FAILED_TO_REFRESH_ACCESS_TOKEN">;
   USER_EMAIL_NOT_FOUND: RawError<"USER_EMAIL_NOT_FOUND">;
   EMAIL_NOT_VERIFIED: RawError<"EMAIL_NOT_VERIFIED">;
   PASSWORD_TOO_SHORT: RawError<"PASSWORD_TOO_SHORT">;

package/dist/error/codes.mjs

@@ -16,6 +16,11 @@ const BASE_ERROR_CODES = defineErrorCodes({
 	TOKEN_EXPIRED: "Token expired",
 	ID_TOKEN_NOT_SUPPORTED: "id_token not supported",
 	FAILED_TO_GET_USER_INFO: "Failed to get user info",
+	PROVIDER_NOT_SUPPORTED: "Provider not supported",
+	TOKEN_REFRESH_NOT_SUPPORTED: "Token refresh not supported",
+	REFRESH_TOKEN_NOT_FOUND: "Refresh token not found",
+	FAILED_TO_GET_ACCESS_TOKEN: "Failed to get a valid access token",
+	FAILED_TO_REFRESH_ACCESS_TOKEN: "Failed to refresh access token",
 	USER_EMAIL_NOT_FOUND: "User email not found",
 	EMAIL_NOT_VERIFIED: "Email not verified",
 	PASSWORD_TOO_SHORT: "Password too short",

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { Awaitable, AwaitableFunction, LiteralString, LiteralUnion, Prettify, Primitive, UnionToIntersection } from "./types/helper.mjs";
 import { BetterAuthPlugin, BetterAuthPluginErrorCodePart, HookEndpointContext } from "./types/plugin.mjs";
-import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption } from "./types/init-options.mjs";
+import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource } from "./types/init-options.mjs";
 import { BetterAuthCookie, BetterAuthCookies } from "./types/cookie.mjs";
 import { SecretConfig } from "./types/secret.mjs";
 import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./types/context.mjs";
 import { BetterAuthClientOptions, BetterAuthClientPlugin, ClientAtomListener, ClientFetchOption, ClientStore } from "./types/plugin-client.mjs";
 import { StandardSchemaV1 } from "./types/index.mjs";
-export { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, DynamicBaseURLConfig, GenerateIdFn, GenericEndpointContext, HookEndpointContext, InfoContext, InternalAdapter, LiteralString, LiteralUnion, PluginContext, Prettify, Primitive, SecretConfig, StandardSchemaV1, StoreIdentifierOption, UnionToIntersection };
+export { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, DynamicBaseURLConfig, GenerateIdFn, GenericEndpointContext, HookEndpointContext, InfoContext, InternalAdapter, LiteralString, LiteralUnion, PluginContext, Prettify, Primitive, SecretConfig, StandardSchemaV1, StoreIdentifierOption, UnionToIntersection, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };

package/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.7.0-beta.4";
+const INSTRUMENTATION_VERSION = "1.7.0-beta.5";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/oauth2/create-authorization-url.d.mts

@@ -47,6 +47,9 @@ declare function createAuthorizationURL({
   responseMode?: string | undefined;
   additionalParams?: Record<string, string> | undefined;
   scopeJoiner?: string | undefined;
-}): Promise<URL>;
+}): Promise<{
+  url: URL;
+  requestedScopes: string[];
+}>;
 //#endregion
 export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/create-authorization-url.mjs

@@ -24,7 +24,7 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 	if (!primaryClientId) throw new Error("OAuth provider requires clientId");
 	url.searchParams.set("client_id", primaryClientId);
 	url.searchParams.set("state", state);
-	if (scopes) url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
+	if (scopes?.length) url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
 	url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
 	duration && url.searchParams.set("duration", duration);
 	display && url.searchParams.set("display", display);
@@ -53,7 +53,10 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 		if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
 		url.searchParams.set(key, value);
 	}
-	return url;
+	return {
+		url,
+		requestedScopes: scopes ?? []
+	};
 }
 //#endregion
 export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/index.d.mts

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

package/dist/oauth2/index.mjs

@@ -1,3 +1,4 @@
+import { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes } from "./scopes.mjs";
 import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
 import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
@@ -7,4 +8,5 @@ import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-
 import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
 import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/oauth-provider.d.mts

@@ -1,5 +1,53 @@
 import { Awaitable, LiteralString } from "../types/helper.mjs";
+import { JWTVerifyGetKey } from "jose";
+
 //#region src/oauth2/oauth-provider.d.ts
+/**
+ * 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.
+ */
+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>;
+};
 interface OAuth2Tokens {
   tokenType?: string | undefined;
   accessToken?: string | undefined;
@@ -21,8 +69,58 @@ type OAuth2UserInfo = {
   image?: string | undefined;
   emailVerified: boolean;
 };
-interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
+/**
+ * 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).
+ */
+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
+ */
+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.
+ */
+type ProviderGrantAuthority = Exclude<GrantAuthority, "absent-echo">;
+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;
@@ -37,7 +135,7 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
      * before applying them.
      */
     additionalParams?: Record<string, string> | undefined;
-  }) => Awaitable<URL>;
+  }) => Awaitable<AuthorizationURLResult>;
   name: string;
   validateAuthorizationCode: (data: {
     code: string;
@@ -65,14 +163,12 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
    * Custom function to refresh a token
    */
   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
@@ -212,6 +308,29 @@ 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;
 };
 //#endregion
-export { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions };
+export { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider };

package/dist/oauth2/refresh-access-token.mjs

@@ -56,7 +56,7 @@ async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authen
 		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
 	};
 	if (data.expires_in) {

package/dist/oauth2/scopes.d.mts

@@ -0,0 +1,76 @@
+import { ProviderOptions } from "./oauth-provider.mjs";
+
+//#region src/oauth2/scopes.d.ts
+/**
+ * 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
+ */
+declare function parseScopeField(scope: unknown): string[];
+/**
+ * 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
+ */
+declare function normalizeScopes(stored: string[] | null | undefined, incoming?: string[] | undefined): string[];
+/**
+ * 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
+ */
+declare function unionGrantedScopes(stored: string[] | null | undefined, echoed: string[] | undefined, requested: string[] | undefined): string[];
+/**
+ * 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.
+ */
+declare function readGrantedScopes(stored: string[] | null | undefined): string[];
+/**
+ * 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
+ */
+declare function includesGrantedScope(granted: string[] | null | undefined, scope: string): boolean;
+/**
+ * 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
+ */
+declare function resolveRequestedScopes(options: Pick<ProviderOptions, "scope" | "disableDefaultScope"> | undefined, defaultScopes: string[], perRequestScopes: string[] | undefined): string[];
+//#endregion
+export { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes };

package/dist/oauth2/scopes.mjs

@@ -0,0 +1,96 @@
+//#region src/oauth2/scopes.ts
+/**
+* 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
+*/
+function parseScopeField(scope) {
+	if (Array.isArray(scope)) return scope.filter((s) => 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
+*/
+function normalizeScopes(stored, incoming) {
+	const normalized = /* @__PURE__ */ new Set();
+	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
+*/
+function unionGrantedScopes(stored, echoed, requested) {
+	return normalizeScopes(stored, echoed?.length ? echoed : requested);
+}
+/**
+* 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.
+*/
+function readGrantedScopes(stored) {
+	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
+*/
+function includesGrantedScope(granted, scope) {
+	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
+*/
+function resolveRequestedScopes(options, defaultScopes, perRequestScopes) {
+	const scopes = options?.disableDefaultScope ? [] : [...defaultScopes];
+	if (options?.scope) scopes.push(...options.scope);
+	if (perRequestScopes) scopes.push(...perRequestScopes);
+	return scopes;
+}
+//#endregion
+export { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes };

package/dist/oauth2/utils.mjs

@@ -1,3 +1,4 @@
+import { parseScopeField } from "./scopes.mjs";
 import { base64Url } from "@better-auth/utils/base64";
 //#region src/oauth2/utils.ts
 function getOAuth2Tokens(data) {
@@ -11,7 +12,7 @@ function getOAuth2Tokens(data) {
 		refreshToken: data.refresh_token,
 		accessTokenExpiresAt: data.expires_in ? getDate(data.expires_in) : void 0,
 		refreshTokenExpiresAt: data.refresh_token_expires_in ? getDate(data.refresh_token_expires_in) : void 0,
-		scopes: data?.scope ? typeof data.scope === "string" ? data.scope.split(" ") : data.scope : [],
+		scopes: parseScopeField(data.scope),
 		idToken: data.id_token,
 		raw: data
 	};

package/dist/oauth2/verify-id-token.d.mts

@@ -0,0 +1,26 @@
+import { UpstreamProvider } from "./oauth-provider.mjs";
+
+//#region src/oauth2/verify-id-token.d.ts
+/**
+ * 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`.
+ */
+declare function supportsIdTokenSignIn(provider: UpstreamProvider<any, any>): boolean;
+/**
+ * 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.
+ */
+declare function verifyProviderIdToken(provider: UpstreamProvider<any, any>, token: string, nonce?: string): Promise<boolean>;
+//#endregion
+export { supportsIdTokenSignIn, verifyProviderIdToken };