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

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 { UpstreamProvider } from "../oauth2/oauth-provider.mjs";
+import { OAuthProvider } 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";
@@ -105,7 +105,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: UpstreamProvider[];
+    socialProviders: OAuthProvider[];
     authCookies: _better_auth_core0.BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {
@@ -234,7 +234,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: UpstreamProvider[];
+    socialProviders: OAuthProvider[];
     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.6";
+const __betterAuthVersion = "1.7.0-beta.8";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/get-tables.mjs

@@ -228,10 +228,10 @@ const getAuthTables = (options) => {
 					returned: false,
 					fieldName: options.account?.fields?.refreshTokenExpiresAt || "refreshTokenExpiresAt"
 				},
-				grantedScopes: {
-					type: "string[]",
+				scope: {
+					type: "string",
 					required: false,
-					fieldName: options.account?.fields?.grantedScopes || "grantedScopes"
+					fieldName: options.account?.fields?.scope || "scope"
 				},
 				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>>;
-  grantedScopes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  scope: z.ZodOptional<z.ZodNullable<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(),
-	grantedScopes: z.array(z.string()).nullish(),
+	scope: z.string().nullish(),
 	password: z.string().nullish()
 });
 //#endregion

package/dist/error/codes.d.mts

@@ -29,11 +29,6 @@ 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,11 +16,6 @@ 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/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.6";
+const INSTRUMENTATION_VERSION = "1.7.0-beta.8";
 /**
 * 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

@@ -7,7 +7,7 @@ import { ProviderOptions } from "./oauth-provider.mjs";
  * `additionalParams`. Overriding `state`, PKCE, or `redirect_uri` would
  * break the callback correlation and session pinning guarantees.
  */
-declare const RESERVED_AUTHORIZATION_PARAMS: readonly ["state", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method", "scope"];
+declare const RESERVED_AUTHORIZATION_PARAMS: readonly ["state", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method", "nonce", "scope"];
 declare const RESERVED_AUTHORIZATION_PARAMS_SET: ReadonlySet<string>;
 declare function createAuthorizationURL({
   id,
@@ -24,6 +24,7 @@ declare function createAuthorizationURL({
   responseType,
   display,
   loginHint,
+  nonce,
   hd,
   responseMode,
   additionalParams,
@@ -43,13 +44,11 @@ declare function createAuthorizationURL({
   responseType?: string | undefined;
   display?: string | undefined;
   loginHint?: string | undefined;
+  nonce?: string | undefined;
   hd?: string | undefined;
   responseMode?: string | undefined;
   additionalParams?: Record<string, string> | undefined;
   scopeJoiner?: string | undefined;
-}): Promise<{
-  url: URL;
-  requestedScopes: string[];
-}>;
+}): Promise<URL>;
 //#endregion
 export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

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

@@ -13,10 +13,11 @@ const RESERVED_AUTHORIZATION_PARAMS = [
 	"response_type",
 	"code_challenge",
 	"code_challenge_method",
+	"nonce",
 	"scope"
 ];
 const RESERVED_AUTHORIZATION_PARAMS_SET = new Set(RESERVED_AUTHORIZATION_PARAMS);
-async function createAuthorizationURL({ id, options, authorizationEndpoint, state, codeVerifier, scopes, claims, redirectURI, duration, prompt, accessType, responseType, display, loginHint, hd, responseMode, additionalParams, scopeJoiner }) {
+async function createAuthorizationURL({ id, options, authorizationEndpoint, state, codeVerifier, scopes, claims, redirectURI, duration, prompt, accessType, responseType, display, loginHint, nonce, hd, responseMode, additionalParams, scopeJoiner }) {
 	options = typeof options === "function" ? await options() : options;
 	const url = new URL(options.authorizationEndpoint || authorizationEndpoint);
 	url.searchParams.set("response_type", responseType || "code");
@@ -29,6 +30,7 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 	duration && url.searchParams.set("duration", duration);
 	display && url.searchParams.set("display", display);
 	loginHint && url.searchParams.set("login_hint", loginHint);
+	nonce && url.searchParams.set("nonce", nonce);
 	prompt && url.searchParams.set("prompt", prompt);
 	hd && url.searchParams.set("hd", hd);
 	accessType && url.searchParams.set("access_type", accessType);
@@ -53,10 +55,7 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 		if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
 		url.searchParams.set(key, value);
 	}
-	return {
-		url,
-		requestedScopes: scopes ?? []
-	};
+	return url;
 }
 //#endregion
 export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/index.d.mts

@@ -1,15 +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 { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider } from "./oauth-provider.mjs";
+import { OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthProvider, OAuthRefreshContext, ProviderOptions } 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 { AccessTokenAuthorization, AccessTokenAuthorizationScheme, BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, DpopBindingError, DpopBindingErrorCode, DpopProofError, DpopProofErrorCode, DpopReplayReservation, DpopReplayReservations, DpopReplayStore, DpopSigningAlgorithm, EnforceDpopBindingParams, VerifiedDpopProof, VerifyDpopProofOptions, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, deriveDpopAth, deriveDpopJkt, enforceDpopBinding, getConfirmationJkt, getDpopJktFromPayload, isDpopBindingError, isDpopProofError, normalizeDpopHtu, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof } from "./dpop.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 { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes } from "./utils.mjs";
 import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
 import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
-export { type AccessTokenAuthorization, type AccessTokenAuthorizationScheme, type AuthorizationURLResult, BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, type DpopBindingError, type DpopBindingErrorCode, type DpopProofError, type DpopProofErrorCode, type DpopReplayReservation, type DpopReplayReservations, type DpopReplayStore, type DpopSigningAlgorithm, type EnforceDpopBindingParams, 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 ResourceRequestInput, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, type UpstreamProvider, type VerifiedDpopProof, type VerifyAccessTokenOptions, type VerifyAccessTokenRequestOptions, type VerifyDpopProofOptions, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, includesGrantedScope, isDpopBindingError, isDpopProofError, normalizeDpopHtu, normalizeScopes, parseAccessTokenAuthorization, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };
+export { type AccessTokenAuthorization, type AccessTokenAuthorizationScheme, BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, type DpopBindingError, type DpopBindingErrorCode, type DpopProofError, type DpopProofErrorCode, type DpopReplayReservation, type DpopReplayReservations, type DpopReplayStore, type DpopSigningAlgorithm, type EnforceDpopBindingParams, type OAuth2Tokens, type OAuth2UserInfo, type OAuthIdTokenConfig, type OAuthProvider, type OAuthRefreshContext, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, type PrivateKeyJwtClientAssertionGetterOptions, type PrivateKeyJwtSigningAlgorithm, type ProviderOptions, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, type ResourceRequestInput, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, type VerifiedDpopProof, type VerifyAccessTokenOptions, type VerifyAccessTokenRequestOptions, type VerifyDpopProofOptions, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/index.mjs

@@ -1,5 +1,4 @@
-import { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes } from "./scopes.mjs";
-import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes } from "./utils.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
 import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
 import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
@@ -10,4 +9,4 @@ import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-
 import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
 import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
-export { BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, includesGrantedScope, isDpopBindingError, isDpopProofError, normalizeDpopHtu, normalizeScopes, parseAccessTokenAuthorization, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };
+export { BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

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

@@ -70,57 +70,29 @@ type OAuth2UserInfo = {
   emailVerified: boolean;
 };
 /**
- * The result of building a provider authorization URL.
+ * Request metadata available to provider refresh hooks.
  *
- * `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).
+ * The refresh flow may be triggered by endpoints such as `getAccessToken` or
+ * `refreshToken`; this context gives provider hooks access to the triggering
+ * request without exposing the full endpoint implementation surface.
  */
-interface AuthorizationURLResult {
-  url: URL;
-  requestedScopes: string[];
+interface OAuthRefreshContext {
+  headers?: Headers | undefined;
+  request?: Request | undefined;
 }
-/**
- * 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>> {
+interface OAuthProvider<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.
+   * Optional path under the resolved per-request `baseURL` where this
+   * provider's OAuth callback handler is mounted. Providers that use the
+   * shared `/callback/<id>` route can omit this.
+   *
+   * Custom paths must start with `/`.
    *
-   * @default "projection"
+   * Endpoints compose `redirectURI = ctx.context.baseURL + callbackPath` per
+   * request, so the provider must not hardcode an origin or `baseURL` here.
    */
-  grantAuthority?: ProviderGrantAuthority | undefined;
+  callbackPath?: string | undefined;
   createAuthorizationURL: (data: {
     state: string;
     codeVerifier: string;
@@ -128,6 +100,12 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    /**
+     * OIDC nonce generated by the redirect initiator and persisted in OAuth
+     * state. Providers that set `requiresIdTokenNonce` must forward this to
+     * the authorization URL as the `nonce` parameter.
+     */
+    idTokenNonce?: string | undefined;
     /**
      * Extra query parameters to append to the authorization URL.
      * Providers forward these to the shared `createAuthorizationURL` helper,
@@ -135,7 +113,7 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
      * before applying them.
      */
     additionalParams?: Record<string, string> | undefined;
-  }) => Awaitable<AuthorizationURLResult>;
+  }) => Awaitable<URL>;
   name: string;
   validateAuthorizationCode: (data: {
     code: string;
@@ -144,6 +122,12 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens | null>;
   getUserInfo: (token: OAuth2Tokens & {
+    /**
+     * OIDC nonce recovered from OAuth state. Providers that required an
+     * ID-token nonce must pass this to `verifyProviderIdToken` before
+     * trusting ID-token claims.
+     */
+    expectedIdTokenNonce?: string | undefined;
     /**
      * The user object from the provider
      * This is only available for some providers like Apple
@@ -160,9 +144,14 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     data: T;
   } | null>;
   /**
-   * Custom function to refresh a token
+   * Custom function to refresh a token.
+   *
+   * Receives request metadata from the endpoint that triggered the refresh.
+   * Providers that don't need request-scoped data can ignore the second
+   * argument.
    */
-  refreshAccessToken?: ((refreshToken: string) => Promise<OAuth2Tokens>) | undefined;
+  refreshAccessToken?: ((refreshToken: string, ctx?: OAuthRefreshContext) => Promise<OAuth2Tokens>) | undefined;
+  revokeToken?: ((token: string) => Promise<void>) | undefined;
   /**
    * Declarative id_token verification config consumed by the shared
    * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
@@ -175,6 +164,13 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
    * against this value to prevent authorization server mix-up attacks.
    */
   issuer?: string | undefined;
+  /**
+   * Require shared OAuth redirect routes to bind ID-token verification to an
+   * authorization request nonce. When true, routes generate `idTokenNonce`,
+   * pass it to `createAuthorizationURL`, persist it in state, and provide it
+   * back to `getUserInfo` as `expectedIdTokenNonce`.
+   */
+  requiresIdTokenNonce?: boolean | undefined;
   /**
    * Disable implicit sign up for new users. When set to true for the provider,
    * sign-in need to be called with with requestSignUp as true to create new users.
@@ -333,4 +329,4 @@ type ProviderOptions<Profile extends Record<string, any> = any> = {
   requireEmailVerification?: boolean | undefined;
 };
 //#endregion
-export { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider };
+export { OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthProvider, OAuthRefreshContext, ProviderOptions };

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

@@ -1,6 +1,14 @@
+import { parseScopeField } from "./utils.mjs";
 import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/refresh-access-token.ts
+const BLOCKED_REFRESH_TOKEN_PARAMS_SET = new Set([
+	"grant_type",
+	"refresh_token",
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
 async function refreshAccessTokenRequest({ refreshToken, options, authentication, tokenEndpointAuth, tokenEndpoint, extraParams, resource }) {
 	options = typeof options === "function" ? await options() : options;
 	const request = buildRefreshAccessTokenRequest({
@@ -20,6 +28,13 @@ async function refreshAccessTokenRequest({ refreshToken, options, authentication
 	});
 	return request;
 }
+function applyRefreshExtraParams(body, extraParams) {
+	if (!extraParams) return;
+	for (const [key, value] of Object.entries(extraParams)) {
+		if (BLOCKED_REFRESH_TOKEN_PARAMS_SET.has(key)) continue;
+		body.set(key, value);
+	}
+}
 function buildRefreshAccessTokenRequest({ refreshToken, options, extraParams, resource }) {
 	const body = new URLSearchParams();
 	const headers = {
@@ -30,7 +45,7 @@ function buildRefreshAccessTokenRequest({ refreshToken, options, extraParams, re
 	body.set("refresh_token", refreshToken);
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
-	if (extraParams) for (const [key, value] of Object.entries(extraParams)) body.set(key, value);
+	if (extraParams) applyRefreshExtraParams(body, extraParams);
 	return {
 		body,
 		headers
@@ -56,7 +71,7 @@ async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authen
 		accessToken: data.access_token,
 		refreshToken: data.refresh_token,
 		tokenType: data.token_type,
-		scopes: Array.isArray(data.scope) ? data.scope : data.scope?.split(" "),
+		scopes: parseScopeField(data.scope),
 		idToken: data.id_token
 	};
 	if (data.expires_in) {

package/dist/oauth2/utils.d.mts

@@ -10,6 +10,11 @@ declare function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens;
  * fallback is configured.
  */
 declare function applyDefaultAccessTokenExpiry(tokens: OAuth2Tokens, accessTokenExpiresIn: number | undefined): OAuth2Tokens;
+/**
+ * Compute the union of stored and incoming OAuth scopes, preserving
+ * stored insertion order and dropping duplicates.
+ */
+declare function mergeScopes(stored: string | null | undefined, incoming: string[] | undefined): string;
 /**
  * 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
@@ -21,4 +26,4 @@ declare function applyDefaultAccessTokenExpiry(tokens: OAuth2Tokens, accessToken
 declare function getPrimaryClientId(clientId: unknown): string | undefined;
 declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
 //#endregion
-export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes };

package/dist/oauth2/utils.mjs

@@ -1,6 +1,19 @@
-import { parseScopeField } from "./scopes.mjs";
 import { base64Url } from "@better-auth/utils/base64";
 //#region src/oauth2/utils.ts
+/**
+* Parse a provider's `scope` token-response field into a string array.
+*
+* RFC 6749 Section 3.3 defines `scope` as a space-delimited string, but
+* providers vary: some return an already-split array. Accept both forms and
+* drop empty or non-string entries.
+*
+* @see https://github.com/better-auth/better-auth/issues/9076
+*/
+function parseScopeField(scope) {
+	if (Array.isArray(scope)) return scope.map((s) => typeof s === "string" ? s.trim() : "").filter(Boolean);
+	if (typeof scope === "string") return scope.trim().split(/\s+/).filter(Boolean);
+	return [];
+}
 function getOAuth2Tokens(data) {
 	const getDate = (seconds) => {
 		const now = /* @__PURE__ */ new Date();
@@ -29,6 +42,15 @@ function applyDefaultAccessTokenExpiry(tokens, accessTokenExpiresIn) {
 	return tokens;
 }
 /**
+* Compute the union of stored and incoming OAuth scopes, preserving
+* stored insertion order and dropping duplicates.
+*/
+function mergeScopes(stored, incoming) {
+	const existing = stored ? stored.split(",").map((scope) => scope.trim()).filter(Boolean) : [];
+	const next = (incoming ?? []).map((scope) => scope.trim()).filter(Boolean);
+	return [...new Set([...existing, ...next])].join(",");
+}
+/**
 * 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
 * verification. Index 0 is the designated primary and pairs with
@@ -46,4 +68,4 @@ async function generateCodeChallenge(codeVerifier) {
 	return base64Url.encode(new Uint8Array(hash), { padding: false });
 }
 //#endregion
-export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes, parseScopeField };

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

@@ -1,26 +1,27 @@
-import { UpstreamProvider } from "./oauth-provider.mjs";
+import { OAuthProvider } from "./oauth-provider.mjs";
 
 //#region src/oauth2/verify-id-token.d.ts
+type ProviderWithIdTokenConfig = Pick<OAuthProvider, "idToken" | "options">;
 /**
  * Whether a provider can verify a client-submitted id_token.
  *
- * A provider supports id_token sign-in when it declares an {@link UpstreamProvider.idToken}
+ * A provider supports id_token sign-in when it declares an {@link OAuthProvider.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;
+declare function supportsIdTokenSignIn(provider: ProviderWithIdTokenConfig): 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}
+ * implement their own boolean `verifyIdToken`; they declare an {@link OAuthProvider.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>;
+declare function verifyProviderIdToken(provider: ProviderWithIdTokenConfig, token: string, nonce?: string): Promise<boolean>;
 //#endregion
 export { supportsIdTokenSignIn, verifyProviderIdToken };

package/dist/oauth2/verify-id-token.mjs

@@ -14,7 +14,7 @@ async function nonceMatches(claimNonce, nonce, comparison = "exact") {
 /**
 * Whether a provider can verify a client-submitted id_token.
 *
-* A provider supports id_token sign-in when it declares an {@link UpstreamProvider.idToken}
+* A provider supports id_token sign-in when it declares an {@link OAuthProvider.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`.
@@ -28,7 +28,7 @@ function supportsIdTokenSignIn(provider) {
 * 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}
+* implement their own boolean `verifyIdToken`; they declare an {@link OAuthProvider.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.

package/dist/social-providers/apple.d.mts

@@ -69,7 +69,6 @@ interface AppleOptions extends ProviderOptions<AppleProfile> {
 declare const apple: (options: AppleOptions) => {
   id: "apple";
   name: string;
-  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
@@ -82,11 +81,9 @@ declare const apple: (options: AppleOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
-  }): Promise<{
-    url: URL;
-    requestedScopes: string[];
-  }>;
+  }): Promise<URL>;
   validateAuthorizationCode: ({
     code,
     codeVerifier,
@@ -106,6 +103,7 @@ declare const apple: (options: AppleOptions) => {
   };
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/apple.mjs

@@ -1,6 +1,5 @@
 import { APIError, BetterAuthError } from "../error/index.mjs";
 import { logger } from "../env/logger.mjs";
-import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { getPrimaryClientId } from "../oauth2/utils.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
@@ -8,23 +7,24 @@ import { validateAuthorizationCode } from "../oauth2/validate-authorization-code
 import { decodeJwt, importJWK } from "jose";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/apple.ts
-const APPLE_DEFAULT_SCOPES = ["email", "name"];
 const apple = (options) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";
 	return {
 		id: "apple",
 		name: "Apple",
-		callbackPath: "/callback/apple",
 		async createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error("Client ID and client secret are required for Apple. Make sure to provide them in the options.");
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
 			}
-			return createAuthorizationURL({
+			const _scope = options.disableDefaultScope ? [] : ["email", "name"];
+			if (options.scope) _scope.push(...options.scope);
+			if (scopes) _scope.push(...scopes);
+			return await createAuthorizationURL({
 				id: "apple",
 				options,
 				authorizationEndpoint: "https://appleid.apple.com/auth/authorize",
-				scopes: resolveRequestedScopes(options, APPLE_DEFAULT_SCOPES, scopes),
+				scopes: _scope,
 				state,
 				redirectURI,
 				responseMode: "form_post",

package/dist/social-providers/atlassian.d.mts

@@ -21,7 +21,6 @@ interface AtlassianOptions extends ProviderOptions<AtlassianProfile> {
 declare const atlassian: (options: AtlassianOptions) => {
   id: "atlassian";
   name: string;
-  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
@@ -35,11 +34,9 @@ declare const atlassian: (options: AtlassianOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
-  }): Promise<{
-    url: URL;
-    requestedScopes: string[];
-  }>;
+  }): Promise<URL>;
   validateAuthorizationCode: ({
     code,
     codeVerifier,
@@ -52,6 +49,7 @@ declare const atlassian: (options: AtlassianOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;