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

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

@@ -14,7 +14,6 @@ interface VercelOptions extends ProviderOptions<VercelProfile> {
 declare const vercel: (options: VercelOptions) => {
   id: "vercel";
   name: string;
-  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
@@ -28,11 +27,9 @@ declare const vercel: (options: VercelOptions) => {
     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,
@@ -44,6 +41,7 @@ declare const vercel: (options: VercelOptions) => {
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/vercel.mjs

@@ -1,22 +1,25 @@
 import { BetterAuthError } from "../error/index.mjs";
-import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/vercel.ts
-const VERCEL_DEFAULT_SCOPES = [];
 const vercel = (options) => {
 	return {
 		id: "vercel",
 		name: "Vercel",
-		callbackPath: "/callback/vercel",
 		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI, additionalParams }) {
 			if (!codeVerifier) throw new BetterAuthError("codeVerifier is required for Vercel");
+			let _scopes = void 0;
+			if (options.scope !== void 0 || scopes !== void 0) {
+				_scopes = [];
+				if (options.scope) _scopes.push(...options.scope);
+				if (scopes) _scopes.push(...scopes);
+			}
 			return createAuthorizationURL({
 				id: "vercel",
 				options,
 				authorizationEndpoint: "https://vercel.com/oauth/authorize",
-				scopes: resolveRequestedScopes(options, VERCEL_DEFAULT_SCOPES, scopes),
+				scopes: _scopes,
 				state,
 				codeVerifier,
 				redirectURI,

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

@@ -20,7 +20,6 @@ interface VkOption extends ProviderOptions {
 declare const vk: (options: VkOption) => {
   id: "vk";
   name: string;
-  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
@@ -34,11 +33,9 @@ declare const vk: (options: VkOption) => {
     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 vk: (options: VkOption) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(data: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/vk.mjs

@@ -1,22 +1,22 @@
-import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/vk.ts
-const VK_DEFAULT_SCOPES = ["email", "phone"];
 const vk = (options) => {
 	const tokenEndpoint = "https://id.vk.com/oauth2/auth";
 	return {
 		id: "vk",
 		name: "VK",
-		callbackPath: "/callback/vk",
-		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI, additionalParams }) {
+		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI, additionalParams }) {
+			const _scopes = options.disableDefaultScope ? [] : ["email", "phone"];
+			if (options.scope) _scopes.push(...options.scope);
+			if (scopes) _scopes.push(...scopes);
 			return createAuthorizationURL({
 				id: "vk",
 				options,
 				authorizationEndpoint: "https://id.vk.com/authorize",
-				scopes: resolveRequestedScopes(options, VK_DEFAULT_SCOPES, scopes),
+				scopes: _scopes,
 				state,
 				redirectURI,
 				codeVerifier,

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

@@ -53,7 +53,6 @@ interface WeChatOptions extends ProviderOptions<WeChatProfile> {
 declare const wechat: (options: WeChatOptions) => {
   id: "wechat";
   name: string;
-  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
@@ -66,11 +65,9 @@ declare const wechat: (options: WeChatOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
-  }): {
-    url: URL;
-    requestedScopes: string[];
-  };
+  }): URL;
   validateAuthorizationCode: ({
     code
   }: {
@@ -95,6 +92,7 @@ declare const wechat: (options: WeChatOptions) => {
     scopes: string[];
   }>);
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/wechat.mjs

@@ -1,17 +1,16 @@
-import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS_SET } from "../oauth2/create-authorization-url.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/wechat.ts
-const WECHAT_DEFAULT_SCOPES = ["snsapi_login"];
 const wechat = (options) => {
 	return {
 		id: "wechat",
 		name: "WeChat",
-		callbackPath: "/callback/wechat",
 		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
-			const requestedScopes = resolveRequestedScopes(options, WECHAT_DEFAULT_SCOPES, scopes);
+			const _scopes = options.disableDefaultScope ? [] : ["snsapi_login"];
+			options.scope && _scopes.push(...options.scope);
+			scopes && _scopes.push(...scopes);
 			const url = new URL("https://open.weixin.qq.com/connect/qrconnect");
-			url.searchParams.set("scope", requestedScopes.join(","));
+			url.searchParams.set("scope", _scopes.join(","));
 			url.searchParams.set("response_type", "code");
 			url.searchParams.set("appid", options.clientId);
 			url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
@@ -23,10 +22,7 @@ const wechat = (options) => {
 				url.searchParams.set(key, value);
 			}
 			url.hash = "wechat_redirect";
-			return {
-				url,
-				requestedScopes
-			};
+			return url;
 		},
 		validateAuthorizationCode: async ({ code }) => {
 			const { data: tokenData, error } = await betterFetch("https://api.weixin.qq.com/sns/oauth2/access_token?" + new URLSearchParams({

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

@@ -116,10 +116,8 @@ interface ZoomOptions extends ProviderOptions<ZoomProfile> {
 declare const zoom: (userOptions: ZoomOptions) => {
   id: "zoom";
   name: string;
-  callbackPath: string;
   createAuthorizationURL: ({
     state,
-    scopes,
     redirectURI,
     codeVerifier,
     additionalParams
@@ -130,11 +128,9 @@ declare const zoom: (userOptions: ZoomOptions) => {
     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,
     redirectURI,
@@ -147,6 +143,7 @@ declare const zoom: (userOptions: ZoomOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/zoom.mjs

@@ -1,10 +1,8 @@
-import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/zoom.ts
-const ZOOM_DEFAULT_SCOPES = [];
 const zoom = (userOptions) => {
 	const options = {
 		pkce: true,
@@ -13,19 +11,15 @@ const zoom = (userOptions) => {
 	return {
 		id: "zoom",
 		name: "Zoom",
-		callbackPath: "/callback/zoom",
-		createAuthorizationURL: ({ state, scopes, redirectURI, codeVerifier, additionalParams }) => {
-			return createAuthorizationURL({
-				id: "zoom",
-				options,
-				authorizationEndpoint: "https://zoom.us/oauth/authorize",
-				scopes: resolveRequestedScopes(options, ZOOM_DEFAULT_SCOPES, scopes),
-				state,
-				redirectURI,
-				codeVerifier: options.pkce ? codeVerifier : void 0,
-				additionalParams
-			});
-		},
+		createAuthorizationURL: async ({ state, redirectURI, codeVerifier, additionalParams }) => createAuthorizationURL({
+			id: "zoom",
+			options,
+			authorizationEndpoint: "https://zoom.us/oauth/authorize",
+			state,
+			redirectURI,
+			codeVerifier: options.pkce ? codeVerifier : void 0,
+			additionalParams
+		}),
 		validateAuthorizationCode: async ({ code, redirectURI, codeVerifier }) => {
 			return validateAuthorizationCode({
 				code,

package/dist/types/context.d.mts

@@ -10,7 +10,7 @@ import { BetterAuthOptions, BetterAuthRateLimitOptions, UserProvisioningSource }
 import { Account } from "../db/schema/account.mjs";
 import { BetterAuthCookie, BetterAuthCookies } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
-import { UpstreamProvider } from "../oauth2/oauth-provider.mjs";
+import { OAuthProvider } from "../oauth2/oauth-provider.mjs";
 import { CookieOptions, EndpointContext } from "better-call";
 
 //#region src/types/context.d.ts
@@ -54,6 +54,10 @@ type GenericEndpointContext<Options extends BetterAuthOptions = BetterAuthOption
   context: AuthContext<Options>;
 };
 interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions> {
+  createOAuthUser(user: Omit<User, "id" | "createdAt" | "updatedAt">, account: Omit<Account, "userId" | "id" | "createdAt" | "updatedAt"> & Partial<Account>): Promise<{
+    user: User;
+    account: Account;
+  }>;
   createUser<T extends Record<string, any>>(user: Omit<User, "id" | "createdAt" | "updatedAt" | "emailVerified"> & Partial<User> & Record<string, any>,
   /**
    * Provisioning source. The creation seam adds `action: "create-user"` and
@@ -232,7 +236,7 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
     session: Session & Record<string, any>;
     user: User & Record<string, any>;
   } | null) => void;
-  socialProviders: UpstreamProvider[];
+  socialProviders: OAuthProvider[];
   authCookies: BetterAuthCookies;
   logger: ReturnType<typeof createLogger>;
   rateLimit: {

package/dist/utils/host.d.mts

@@ -26,7 +26,7 @@
  * The semantic kind of a host, derived from RFC 6890 special-purpose registries
  * plus a few domain-name categories (localhost, cloud metadata FQDNs).
  */
-type HostKind = /** IPv4 `127.0.0.0/8` or IPv6 `::1`. */"loopback" /** DNS name `localhost` or RFC 6761 `.localhost` TLD. */ | "localhost" /** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */ | "unspecified" /** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */ | "private" /** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */ | "linkLocal" /** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */ | "sharedAddressSpace" /** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */ | "documentation" /** RFC 2544 `198.18.0.0/15`. */ | "benchmarking" /** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */ | "multicast" /** IPv4 limited broadcast `255.255.255.255`. */ | "broadcast" /** Other RFC 6890 special-purpose ranges (0/8, 192.0.0/24, 240/4, 2001::/32, etc.). */ | "reserved" /** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */ | "cloudMetadata" /** Any host not matching a special-purpose range above. */ | "public";
+type HostKind = /** IPv4 `127.0.0.0/8` or IPv6 `::1`. */"loopback" /** DNS name `localhost` or RFC 6761 `.localhost` TLD. */ | "localhost" /** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */ | "unspecified" /** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */ | "private" /** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */ | "linkLocal" /** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */ | "sharedAddressSpace" /** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */ | "documentation" /** RFC 2544 `198.18.0.0/15`. */ | "benchmarking" /** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */ | "multicast" /** IPv4 limited broadcast `255.255.255.255`. */ | "broadcast" /** Other RFC 6890 special-purpose ranges (0.0.0.0/8, 192.0.0.0/24, 192.88.99.0/24, 240.0.0.0/4, 2001::/32, etc.). */ | "reserved" /** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */ | "cloudMetadata" /** Any host not matching a special-purpose range above. */ | "public";
 /**
  * The syntactic form of the input host: an IPv4 literal, an IPv6 literal, or
  * a domain name. IPv4-mapped IPv6 (`::ffff:192.0.2.1`) is reported as `ipv4`

package/dist/utils/host.mjs

@@ -86,6 +86,7 @@ function classifyIPv4(ip) {
 	if (inIPv4Range(n, ipv4ToUint32("224.0.0.0"), 4)) return "multicast";
 	if (inIPv4Range(n, ipv4ToUint32("0.0.0.0"), 8)) return "reserved";
 	if (inIPv4Range(n, ipv4ToUint32("192.0.0.0"), 24)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("192.88.99.0"), 24)) return "reserved";
 	if (inIPv4Range(n, ipv4ToUint32("240.0.0.0"), 4)) return "reserved";
 	return "public";
 }
@@ -124,6 +125,7 @@ function classifyIPv6(expanded) {
 	const secondByte = Number.parseInt(expanded.slice(2, 4), 16);
 	if (firstByte === 255) return "multicast";
 	if (firstByte === 254 && (secondByte & 192) === 128) return "linkLocal";
+	if (firstByte === 254 && (secondByte & 192) === 192) return "reserved";
 	if ((firstByte & 254) === 252) return "private";
 	if (expanded.startsWith("2001:0db8:")) return "documentation";
 	if (expanded.startsWith("2001:0002:0000:")) return "benchmarking";
@@ -146,6 +148,7 @@ function classifyIPv6(expanded) {
 	if (expanded.startsWith("0100:0000:0000:0000:")) return "reserved";
 	if (expanded.startsWith("3fff:0")) return "documentation";
 	if (expanded.startsWith("5f00:")) return "reserved";
+	if (expanded.startsWith("0000:0000:0000:0000:0000:0000:")) return "reserved";
 	return "public";
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-beta.6",
+  "version": "1.7.0-beta.8",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",

package/src/db/get-tables.ts

@@ -261,15 +261,10 @@ export const getAuthTables = (
 						options.account?.fields?.refreshTokenExpiresAt ||
 						"refreshTokenExpiresAt",
 				},
-				// Renamed from the legacy `scope` column. The migration generator
-				// only adds this column; it does not transform the legacy `scope`
-				// value. Upgrading installs need a manual data migration (split
-				// legacy `scope` on comma/space, trim, drop empties, dedupe). Order
-				// is insignificant per RFC 6749 §3.3.
-				grantedScopes: {
-					type: "string[]",
+				scope: {
+					type: "string",
 					required: false,
-					fieldName: options.account?.fields?.grantedScopes || "grantedScopes",
+					fieldName: options.account?.fields?.scope || "scope",
 				},
 				password: {
 					type: "string",

package/src/db/schema/account.ts

@@ -23,21 +23,12 @@ export const accountSchema = coreSchema.extend({
 	 */
 	refreshTokenExpiresAt: z.date().nullish(),
 	/**
-	 * The scopes the user has granted, as last observed (durable, per-account,
-	 * the unit of revocation and the refresh ceiling). A native array, not a
-	 * delimited string: scope order is insignificant per RFC 6749 §3.3, so the
-	 * value is normalized (trimmed, deduped, sorted) on write.
-	 *
-	 * Renamed from the legacy comma-joined `scope` string. Breaking, with no
-	 * automatic data migration (and no read-time shim): the migration generator
-	 * only adds the new `grantedScopes` column, so legacy accounts read as empty
-	 * here until an upgrade backfills `grantedScopes` from the old `scope` values
-	 * (split on comma/space, trim, drop empties, dedupe). See the release
-	 * changeset for the backfill.
-	 *
-	 * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+	 * The set of OAuth scopes the user has granted to this account, stored
+	 * as a comma-separated list. Represents the accumulated grant rather
+	 * than the latest token's `scope` claim, since per RFC 6749 Section 1.5 a
+	 * token's scope may be narrower than the user's grant.
 	 */
-	grantedScopes: z.array(z.string()).nullish(),
+	scope: z.string().nullish(),
 	/**
 	 * Password is only stored in the credential provider
 	 */

package/src/error/codes.ts

@@ -29,11 +29,6 @@ export 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/src/oauth2/create-authorization-url.ts

@@ -15,6 +15,7 @@ export const RESERVED_AUTHORIZATION_PARAMS = [
 	"response_type",
 	"code_challenge",
 	"code_challenge_method",
+	"nonce",
 	"scope",
 ] as const;
 
@@ -37,6 +38,7 @@ export async function createAuthorizationURL({
 	responseType,
 	display,
 	loginHint,
+	nonce,
 	hd,
 	responseMode,
 	additionalParams,
@@ -56,6 +58,7 @@ export async 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;
@@ -77,6 +80,7 @@ export async function createAuthorizationURL({
 	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);
@@ -107,5 +111,5 @@ export async function createAuthorizationURL({
 			url.searchParams.set(key, value);
 		}
 	}
-	return { url, requestedScopes: scopes ?? [] };
+	return url;
 }

package/src/oauth2/index.ts

@@ -63,27 +63,17 @@ export {
 	verifyDpopProof,
 } from "./dpop";
 export type {
-	AuthorizationURLResult,
-	GrantAuthority,
 	OAuth2Tokens,
 	OAuth2UserInfo,
 	OAuthIdTokenConfig,
-	ProviderGrantAuthority,
+	OAuthProvider,
+	OAuthRefreshContext,
 	ProviderOptions,
-	UpstreamProvider,
 } from "./oauth-provider";
 export {
 	refreshAccessToken,
 	refreshAccessTokenRequest,
 } from "./refresh-access-token";
-export {
-	includesGrantedScope,
-	normalizeScopes,
-	parseScopeField,
-	readGrantedScopes,
-	resolveRequestedScopes,
-	unionGrantedScopes,
-} from "./scopes";
 export type {
 	TokenEndpointAuth,
 	TokenEndpointAuthMethod,
@@ -94,6 +84,7 @@ export {
 	generateCodeChallenge,
 	getOAuth2Tokens,
 	getPrimaryClientId,
+	mergeScopes,
 } from "./utils";
 export {
 	authorizationCodeRequest,

package/src/oauth2/oauth-provider.ts

@@ -78,63 +78,33 @@ export type OAuth2UserInfo = {
 };
 
 /**
- * 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.
  */
-export interface AuthorizationURLResult {
-	url: URL;
-	requestedScopes: string[];
+export 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
- */
-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<
+export 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.
 	 *
-	 * @default "projection"
+	 * Custom paths must start with `/`.
+	 *
+	 * 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;
@@ -142,6 +112,12 @@ export interface UpstreamProvider<
 		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,
@@ -149,7 +125,7 @@ export interface UpstreamProvider<
 		 * before applying them.
 		 */
 		additionalParams?: Record<string, string> | undefined;
-	}) => Awaitable<AuthorizationURLResult>;
+	}) => Awaitable<URL>;
 	name: string;
 	validateAuthorizationCode: (data: {
 		code: string;
@@ -159,6 +135,12 @@ export interface UpstreamProvider<
 	}) => 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
@@ -178,11 +160,19 @@ export interface UpstreamProvider<
 		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>)
+		| ((
+				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
@@ -195,6 +185,13 @@ export interface UpstreamProvider<
 	 * 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.
@@ -283,10 +280,6 @@ 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;