@better-auth/core 1.7.0-rc.2 → 1.7.0-rc.3

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-rc.2";
+const __betterAuthVersion = "1.7.0-rc.3";
 /**
 * We store context instance in the globalThis.
 *

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-rc.2";
+const INSTRUMENTATION_VERSION = "1.7.0-rc.3";
 /**
 * 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/index.d.mts

@@ -9,6 +9,6 @@ import { AccessTokenAuthorization, AccessTokenAuthorizationScheme, BEARER_AUTHOR
 import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.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 { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, createInsufficientScopeError, getJwks, isInsufficientScopeError, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
 import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
-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 OAuthAccountKeyContext, type OAuthAccountSubject, type OAuthIdTokenConfig, type OAuthMappedUser, 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 };
+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 OAuthAccountKeyContext, type OAuthAccountSubject, type OAuthIdTokenConfig, type OAuthMappedUser, 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, createInsufficientScopeError, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, isInsufficientScopeError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/index.mjs

@@ -7,6 +7,6 @@ import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-
 import { BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, 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 { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
-import { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
+import { createInsufficientScopeError, getJwks, isInsufficientScopeError, 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, isDpopBindingError, isDpopProofError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, 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, createInsufficientScopeError, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, isInsufficientScopeError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

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

@@ -199,6 +199,15 @@ interface OAuthProvider<T extends object = object, O extends object = Partial<Pr
    */
   refreshAccessToken?: ((refreshToken: string, ctx?: OAuthRefreshContext) => Promise<OAuth2Tokens>) | undefined;
   revokeToken?: ((token: string) => Promise<void>) | undefined;
+  /**
+   * Builds an OpenID Connect RP-Initiated Logout URL for this provider.
+   * Returns `null` when provider logout is unavailable or disabled.
+   */
+  createEndSessionURL?: ((data: {
+    idToken?: string | null | undefined;
+    postLogoutRedirectURI?: string | undefined;
+    state?: string | undefined;
+  }) => Awaitable<URL | null>) | undefined;
   /**
    * Declarative id_token verification config consumed by the shared
    * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean

package/dist/oauth2/verify.d.mts

@@ -1,4 +1,5 @@
 import { DpopReplayStore } from "./dpop.mjs";
+import { APIError } from "better-call";
 import { JSONWebKeySet, JWTPayload, JWTVerifyOptions } from "jose";
 //#region src/oauth2/verify.d.ts
 type JwksFetchOptions = {
@@ -42,8 +43,13 @@ interface VerifyAccessTokenRemote {
 interface VerifyAccessTokenOptions {
   /** Verify options */
   verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-  /** Scopes to additionally verify. Token must include all but not exact. */
-  scopes?: string[];
+  /** Scopes the token must satisfy. */
+  requiredScopes?: readonly string[];
+  /**
+   * Determines whether a required scope is satisfied by the granted scope
+   * set. Defaults to exact set membership.
+   */
+  isScopeSatisfied?: (requiredScope: string, grantedScopes: ReadonlySet<string>) => boolean;
   /** Required to verify access token locally */
   jwksUrl?: string;
   /** If provided, can verify a token remotely */
@@ -88,6 +94,11 @@ declare function verifyJwsAccessToken(token: string, opts: JwksFetchOptions & {
   verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
 }): Promise<JWTPayload>;
 declare function getJwks(token: string, opts: JwksFetchOptions): Promise<JSONWebKeySet>;
+declare function createInsufficientScopeError(requiredScopes: readonly string[], description?: string): APIError;
+/**
+ * Returns whether an error is a typed RFC 6750 insufficient-scope failure.
+ */
+declare function isInsufficientScopeError(error: unknown): error is APIError;
 /**
  * Performs local verification of a bearer access token for your API.
  *
@@ -110,4 +121,4 @@ declare function verifyBearerToken(token: string, opts: VerifyAccessTokenOptions
  */
 declare function verifyAccessTokenRequest(request: ResourceRequestInput, opts: VerifyAccessTokenRequestOptions): Promise<JWTPayload>;
 //#endregion
-export { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRemote, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };
+export { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRemote, VerifyAccessTokenRequestOptions, createInsufficientScopeError, getJwks, isInsufficientScopeError, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };

package/dist/oauth2/verify.mjs

@@ -207,12 +207,73 @@ async function verifyAccessTokenPayload(token, opts) {
 		}
 	}
 	if (!payload) throw new APIError("UNAUTHORIZED", { message: `no token payload` });
-	if (opts.scopes) {
-		const validScopes = new Set(payload.scope?.split(" "));
-		for (const sc of opts.scopes) if (!validScopes.has(sc)) throw new APIError("FORBIDDEN", { message: `invalid scope ${sc}` });
+	const grantedScopes = parseGrantedScopes(payload.scope);
+	if (opts.requiredScopes) {
+		const isScopeSatisfied = opts.isScopeSatisfied ?? ((requiredScope, scopes) => scopes.has(requiredScope));
+		const missingScopes = opts.requiredScopes.filter((scope) => !isScopeSatisfied(scope, grantedScopes));
+		if (missingScopes.length > 0) throw createInsufficientScopeError(missingScopes);
 	}
 	return payload;
 }
+/**
+* Build the RFC 6750 §3.1 insufficient-scope failure: the access token is valid
+* but lacks scopes the operation needs.
+*
+* Resource-server challenge builders turn this into a `403` carrying a
+* `WWW-Authenticate: Bearer error="insufficient_scope"` challenge that names
+* `scopes`, so the client knows what to request when it re-authorizes. Throw it
+* from a route handler to challenge for scopes only that operation needs; a
+* plain `FORBIDDEN` stays a plain `403`, since a permission denial the client
+* cannot fix by re-authorizing must not send the user through consent again.
+*
+* @param requiredScopes - Every scope the operation requires but the token lacks.
+* @param description - RFC 6750 `error_description` text. It must use the
+* printable ASCII character set allowed by the specification.
+*/
+const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5b\x5d-\x7e]+$/;
+const OAUTH_ERROR_DESCRIPTION_PATTERN = /^[\x20-\x21\x23-\x5b\x5d-\x7e]+$/;
+const insufficientScopeErrors = /* @__PURE__ */ new WeakSet();
+function isOAuthScopeToken(value) {
+	return OAUTH_SCOPE_TOKEN_PATTERN.test(value);
+}
+function validateScopeTokens(scopes, label) {
+	for (const scope of scopes) if (!isOAuthScopeToken(scope)) throw new TypeError(`invalid ${label}: ${JSON.stringify(scope)}`);
+}
+function validateRequiredScopes(opts) {
+	if (opts.requiredScopes) validateScopeTokens(opts.requiredScopes, "required scope");
+}
+function parseGrantedScopes(scope) {
+	if (scope === void 0) return /* @__PURE__ */ new Set();
+	if (typeof scope !== "string" || scope.length === 0 || scope.split(" ").some((token) => !isOAuthScopeToken(token))) throw new APIError("UNAUTHORIZED", {
+		message: "access token scope claim is invalid",
+		error: "invalid_token",
+		error_description: "access token scope claim is invalid"
+	});
+	return new Set(scope.split(" "));
+}
+function createInsufficientScopeError(requiredScopes, description = `access token is missing required scope: ${requiredScopes.join(" ")}`) {
+	if (requiredScopes.length === 0) throw new TypeError("requiredScopes must contain at least one scope");
+	validateScopeTokens(requiredScopes, "required scope");
+	if (typeof description !== "string" || !OAUTH_ERROR_DESCRIPTION_PATTERN.test(description)) throw new TypeError("invalid error_description");
+	const error = new APIError("FORBIDDEN", {
+		message: description,
+		error: "insufficient_scope",
+		error_description: description,
+		scope: [...new Set(requiredScopes)].join(" ")
+	});
+	insufficientScopeErrors.add(error);
+	return error;
+}
+/**
+* Returns whether an error is a typed RFC 6750 insufficient-scope failure.
+*/
+function isInsufficientScopeError(error) {
+	if (!(error instanceof APIError) || !insufficientScopeErrors.has(error) || error.status !== "FORBIDDEN") return false;
+	const body = error.body;
+	if (body?.error !== "insufficient_scope" || typeof body.scope !== "string") return false;
+	const scopes = body.scope.split(" ");
+	return scopes.length > 0 && scopes.every(isOAuthScopeToken);
+}
 function throwDpopUnauthorized(message, error) {
 	throw new APIError("UNAUTHORIZED", error ? {
 		message,
@@ -231,6 +292,7 @@ function throwDpopUnauthorized(message, error) {
 * alone.
 */
 async function verifyBearerToken(token, opts) {
+	validateRequiredScopes(opts);
 	const payload = await verifyAccessTokenPayload(token, opts);
 	if (getDpopJktFromPayload(payload)) throwDpopUnauthorized("DPoP-bound access token requires verifyAccessTokenRequest", "invalid_token");
 	return payload;
@@ -245,6 +307,7 @@ async function verifyBearerToken(token, opts) {
 * scheme, method, URL, DPoP proof, `ath`, and `cnf.jkt` binding.
 */
 async function verifyAccessTokenRequest(request, opts) {
+	validateRequiredScopes(opts);
 	const authorization = parseAccessTokenAuthorization(request.authorizationHeader);
 	if (!authorization?.token) throwDpopUnauthorized("missing authorization header");
 	if (authorization.scheme === "Unknown") throwDpopUnauthorized("authorization scheme must be Bearer or DPoP", "invalid_token");
@@ -267,4 +330,4 @@ async function verifyAccessTokenRequest(request, opts) {
 	return payload;
 }
 //#endregion
-export { getJwks, jwksCache, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };
+export { createInsufficientScopeError, getJwks, isInsufficientScopeError, jwksCache, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };

package/dist/social-providers/microsoft-entra-id.mjs

@@ -29,7 +29,7 @@ const microsoft = (options) => {
 	return {
 		id: "microsoft",
 		name: "Microsoft EntraID",
-		accountSubject: ({ profile }) => profile.sub,
+		accountSubject: ({ profile }) => profile.oid,
 		accountIssuer: ({ profile }) => profile.iss,
 		createAuthorizationURL(data) {
 			if (!getPrimaryClientId(options.clientId)) {
@@ -99,11 +99,15 @@ const microsoft = (options) => {
 			if (options.getUserInfo) return options.getUserInfo(token);
 			if (!token.idToken) return null;
 			const user = decodeJwt(token.idToken);
+			if (typeof user.oid !== "string" || user.oid.trim().length === 0) {
+				logger.error("Microsoft Entra ID token did not include a valid oid claim; unable to resolve a stable account identifier.");
+				return null;
+			}
 			const profilePhotoSize = options.profilePhotoSize || 48;
-			await betterFetch(`https://graph.microsoft.com/v1.0/me/photos/${profilePhotoSize}x${profilePhotoSize}/$value`, {
+			if (!options.disableProfilePhoto && token.accessToken) await betterFetch(`https://graph.microsoft.com/v1.0/me/photos/${profilePhotoSize}x${profilePhotoSize}/$value`, {
 				headers: { Authorization: `Bearer ${token.accessToken}` },
 				async onResponse(context) {
-					if (options.disableProfilePhoto || !context.response.ok) return;
+					if (!context.response.ok) return;
 					try {
 						const pictureBuffer = await context.response.clone().arrayBuffer();
 						const pictureBase64 = base64.encode(pictureBuffer);

package/dist/utils/redirect-uri.d.mts

@@ -1,5 +1,10 @@
 import * as z from "zod";
 //#region src/utils/redirect-uri.d.ts
+/**
+ * Returns whether a parsed redirect URI uses an authority-free, reverse-domain
+ * private-use scheme as recommended by RFC 8252 §7.1.
+ */
+declare function isReverseDomainPrivateUseRedirectUri(uri: URL): boolean;
 /**
  * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
  * server stores and later hands back to a browser.
@@ -16,4 +21,4 @@ import * as z from "zod";
  */
 declare const SafeUrlSchema: z.ZodURL;
 //#endregion
-export { SafeUrlSchema };
+export { SafeUrlSchema, isReverseDomainPrivateUseRedirectUri };

package/dist/utils/redirect-uri.mjs

@@ -2,6 +2,16 @@ import { isLoopbackHost } from "./host.mjs";
 import { DANGEROUS_URL_SCHEMES } from "./url.mjs";
 import * as z from "zod";
 //#region src/utils/redirect-uri.ts
+const REVERSE_DOMAIN_PRIVATE_USE_SCHEME = /^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i;
+/**
+* Returns whether a parsed redirect URI uses an authority-free, reverse-domain
+* private-use scheme as recommended by RFC 8252 §7.1.
+*/
+function isReverseDomainPrivateUseRedirectUri(uri) {
+	const scheme = uri.protocol.slice(0, -1);
+	const schemeSpecificPart = uri.href.slice(uri.protocol.length);
+	return uri.protocol !== "http:" && uri.protocol !== "https:" && uri.host.length === 0 && schemeSpecificPart.startsWith("/") && !schemeSpecificPart.startsWith("//") && REVERSE_DOMAIN_PRIVATE_USE_SCHEME.test(scheme);
+}
 /**
 * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
 * server stores and later hands back to a browser.
@@ -45,4 +55,4 @@ const SafeUrlSchema = z.url().superRefine((val, ctx) => {
 	});
 });
 //#endregion
-export { SafeUrlSchema };
+export { SafeUrlSchema, isReverseDomainPrivateUseRedirectUri };

package/package.json

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

package/src/db/adapter/factory.ts

@@ -863,8 +863,8 @@ export const createAdapterFactory =
 			}: {
 				model: string;
 				data: T;
-				select?: string[];
-				forceAllowId?: boolean;
+				select?: string[] | undefined;
+				forceAllowId?: boolean | undefined;
 			}): Promise<R> => {
 				transactionId++;
 				const thisTransactionId = transactionId;
@@ -1098,8 +1098,8 @@ export const createAdapterFactory =
 			}: {
 				model: string;
 				where: Where[];
-				select?: string[];
-				join?: JoinOption;
+				select?: string[] | undefined;
+				join?: JoinOption | undefined;
 			}) => {
 				transactionId++;
 				const thisTransactionId = transactionId;
@@ -1181,12 +1181,12 @@ export const createAdapterFactory =
 				join: unsafeJoin,
 			}: {
 				model: string;
-				where?: Where[];
-				limit?: number;
+				where?: Where[] | undefined;
+				limit?: number | undefined;
 				select?: string[] | undefined;
-				sortBy?: { field: string; direction: "asc" | "desc" };
-				offset?: number;
-				join?: JoinOption;
+				sortBy?: { field: string; direction: "asc" | "desc" } | undefined;
+				offset?: number | undefined;
+				join?: JoinOption | undefined;
 			}) => {
 				transactionId++;
 				const thisTransactionId = transactionId;
@@ -1509,7 +1509,7 @@ export const createAdapterFactory =
 				where: unsafeWhere,
 			}: {
 				model: string;
-				where?: Where[];
+				where?: Where[] | undefined;
 			}) => {
 				transactionId++;
 				const thisTransactionId = transactionId;

package/src/error/codes.ts

@@ -1,3 +1,4 @@
+import type {} from "@better-auth/core";
 import { defineErrorCodes } from "../utils/error-codes";
 
 declare module "@better-auth/core" {

package/src/oauth2/index.ts

@@ -100,7 +100,9 @@ export type {
 	VerifyAccessTokenRequestOptions,
 } from "./verify";
 export {
+	createInsufficientScopeError,
 	getJwks,
+	isInsufficientScopeError,
 	requestToResourceInput,
 	verifyAccessTokenRequest,
 	verifyBearerToken,

package/src/oauth2/oauth-provider.ts

@@ -228,6 +228,17 @@ export interface OAuthProvider<
 		  ) => Promise<OAuth2Tokens>)
 		| undefined;
 	revokeToken?: ((token: string) => Promise<void>) | undefined;
+	/**
+	 * Builds an OpenID Connect RP-Initiated Logout URL for this provider.
+	 * Returns `null` when provider logout is unavailable or disabled.
+	 */
+	createEndSessionURL?:
+		| ((data: {
+				idToken?: string | null | undefined;
+				postLogoutRedirectURI?: string | undefined;
+				state?: string | undefined;
+		  }) => Awaitable<URL | null>)
+		| undefined;
 	/**
 	 * Declarative id_token verification config consumed by the shared
 	 * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean

package/src/oauth2/verify.ts

@@ -164,8 +164,16 @@ export interface VerifyAccessTokenOptions {
 	/** Verify options */
 	verifyOptions: JWTVerifyOptions &
 		Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-	/** Scopes to additionally verify. Token must include all but not exact. */
-	scopes?: string[];
+	/** Scopes the token must satisfy. */
+	requiredScopes?: readonly string[];
+	/**
+	 * Determines whether a required scope is satisfied by the granted scope
+	 * set. Defaults to exact set membership.
+	 */
+	isScopeSatisfied?: (
+		requiredScope: string,
+		grantedScopes: ReadonlySet<string>,
+	) => boolean;
 	/** Required to verify access token locally */
 	jwksUrl?: string;
 	/** If provided, can verify a token remotely */
@@ -442,23 +450,122 @@ async function verifyAccessTokenPayload(
 			message: `no token payload`,
 		});
 
-	// Check scopes if provided
-	if (opts.scopes) {
-		const validScopes = new Set(
-			(payload.scope as string | undefined)?.split(" "),
+	const grantedScopes = parseGrantedScopes(payload.scope);
+
+	// Check scopes if provided.
+	if (opts.requiredScopes) {
+		const isScopeSatisfied =
+			opts.isScopeSatisfied ??
+			((requiredScope: string, scopes: ReadonlySet<string>) =>
+				scopes.has(requiredScope));
+		// RFC 6750 §3.1: report every missing scope at once. Challenging with one
+		// scope at a time costs the user a browser round-trip per scope.
+		const missingScopes = opts.requiredScopes.filter(
+			(scope) => !isScopeSatisfied(scope, grantedScopes),
 		);
-		for (const sc of opts.scopes) {
-			if (!validScopes.has(sc)) {
-				throw new APIError("FORBIDDEN", {
-					message: `invalid scope ${sc}`,
-				});
-			}
+		if (missingScopes.length > 0) {
+			throw createInsufficientScopeError(missingScopes);
 		}
 	}
 
 	return payload;
 }
 
+/**
+ * Build the RFC 6750 §3.1 insufficient-scope failure: the access token is valid
+ * but lacks scopes the operation needs.
+ *
+ * Resource-server challenge builders turn this into a `403` carrying a
+ * `WWW-Authenticate: Bearer error="insufficient_scope"` challenge that names
+ * `scopes`, so the client knows what to request when it re-authorizes. Throw it
+ * from a route handler to challenge for scopes only that operation needs; a
+ * plain `FORBIDDEN` stays a plain `403`, since a permission denial the client
+ * cannot fix by re-authorizing must not send the user through consent again.
+ *
+ * @param requiredScopes - Every scope the operation requires but the token lacks.
+ * @param description - RFC 6750 `error_description` text. It must use the
+ * printable ASCII character set allowed by the specification.
+ */
+const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5b\x5d-\x7e]+$/;
+const OAUTH_ERROR_DESCRIPTION_PATTERN = /^[\x20-\x21\x23-\x5b\x5d-\x7e]+$/;
+const insufficientScopeErrors = new WeakSet<APIError>();
+
+function isOAuthScopeToken(value: string): boolean {
+	return OAUTH_SCOPE_TOKEN_PATTERN.test(value);
+}
+
+function validateScopeTokens(scopes: readonly string[], label: string): void {
+	for (const scope of scopes) {
+		if (!isOAuthScopeToken(scope)) {
+			throw new TypeError(`invalid ${label}: ${JSON.stringify(scope)}`);
+		}
+	}
+}
+
+function validateRequiredScopes(opts: VerifyAccessTokenOptions): void {
+	if (opts.requiredScopes) {
+		validateScopeTokens(opts.requiredScopes, "required scope");
+	}
+}
+
+function parseGrantedScopes(scope: unknown): ReadonlySet<string> {
+	if (scope === undefined) return new Set();
+	if (
+		typeof scope !== "string" ||
+		scope.length === 0 ||
+		scope.split(" ").some((token) => !isOAuthScopeToken(token))
+	) {
+		throw new APIError("UNAUTHORIZED", {
+			message: "access token scope claim is invalid",
+			error: "invalid_token",
+			error_description: "access token scope claim is invalid",
+		});
+	}
+	return new Set(scope.split(" "));
+}
+
+export function createInsufficientScopeError(
+	requiredScopes: readonly string[],
+	description = `access token is missing required scope: ${requiredScopes.join(" ")}`,
+): APIError {
+	if (requiredScopes.length === 0) {
+		throw new TypeError("requiredScopes must contain at least one scope");
+	}
+	validateScopeTokens(requiredScopes, "required scope");
+	if (
+		typeof description !== "string" ||
+		!OAUTH_ERROR_DESCRIPTION_PATTERN.test(description)
+	) {
+		throw new TypeError("invalid error_description");
+	}
+	const error = new APIError("FORBIDDEN", {
+		message: description,
+		error: "insufficient_scope",
+		error_description: description,
+		scope: [...new Set(requiredScopes)].join(" "),
+	});
+	insufficientScopeErrors.add(error);
+	return error;
+}
+
+/**
+ * Returns whether an error is a typed RFC 6750 insufficient-scope failure.
+ */
+export function isInsufficientScopeError(error: unknown): error is APIError {
+	if (
+		!(error instanceof APIError) ||
+		!insufficientScopeErrors.has(error) ||
+		error.status !== "FORBIDDEN"
+	)
+		return false;
+	const body = error.body as { error?: unknown; scope?: unknown } | undefined;
+	if (body?.error !== "insufficient_scope" || typeof body.scope !== "string") {
+		return false;
+	}
+	const scopes = body.scope.split(" ");
+	return scopes.length > 0 && scopes.every(isOAuthScopeToken);
+}
+
 function throwDpopUnauthorized(
 	message: string,
 	error?: "invalid_dpop_proof" | "invalid_token",
@@ -489,6 +596,7 @@ export async function verifyBearerToken(
 	token: string,
 	opts: VerifyAccessTokenOptions,
 ) {
+	validateRequiredScopes(opts);
 	const payload = await verifyAccessTokenPayload(token, opts);
 	if (getDpopJktFromPayload(payload)) {
 		throwDpopUnauthorized(
@@ -512,6 +620,7 @@ export async function verifyAccessTokenRequest(
 	request: ResourceRequestInput,
 	opts: VerifyAccessTokenRequestOptions,
 ) {
+	validateRequiredScopes(opts);
 	const authorization = parseAccessTokenAuthorization(
 		request.authorizationHeader,
 	);

package/src/social-providers/microsoft-entra-id.ts

@@ -187,7 +187,7 @@ export const microsoft = (options: MicrosoftOptions) => {
 	return {
 		id: "microsoft",
 		name: "Microsoft EntraID",
-		accountSubject: ({ profile }) => profile.sub,
+		accountSubject: ({ profile }) => profile.oid,
 		accountIssuer: ({ profile }) => profile.iss,
 		createAuthorizationURL(data) {
 			// Microsoft Entra supports public clients (SPA / native apps with
@@ -279,33 +279,41 @@ export const microsoft = (options: MicrosoftOptions) => {
 				return null;
 			}
 			const user = decodeJwt(token.idToken) as MicrosoftEntraIDProfile;
+			if (typeof user.oid !== "string" || user.oid.trim().length === 0) {
+				logger.error(
+					"Microsoft Entra ID token did not include a valid oid claim; unable to resolve a stable account identifier.",
+				);
+				return null;
+			}
 			const profilePhotoSize = options.profilePhotoSize || 48;
-			await betterFetch<ArrayBuffer>(
-				`https://graph.microsoft.com/v1.0/me/photos/${profilePhotoSize}x${profilePhotoSize}/$value`,
-				{
-					headers: {
-						Authorization: `Bearer ${token.accessToken}`,
-					},
-					async onResponse(context) {
-						if (options.disableProfilePhoto || !context.response.ok) {
-							return;
-						}
-						try {
-							const response = context.response.clone();
-							const pictureBuffer = await response.arrayBuffer();
-							const pictureBase64 = base64.encode(pictureBuffer);
-							user.picture = `data:image/jpeg;base64, ${pictureBase64}`;
-						} catch (e) {
-							logger.error(
-								e && typeof e === "object" && "name" in e
-									? (e.name as string)
-									: "",
-								e,
-							);
-						}
+			if (!options.disableProfilePhoto && token.accessToken) {
+				await betterFetch<ArrayBuffer>(
+					`https://graph.microsoft.com/v1.0/me/photos/${profilePhotoSize}x${profilePhotoSize}/$value`,
+					{
+						headers: {
+							Authorization: `Bearer ${token.accessToken}`,
+						},
+						async onResponse(context) {
+							if (!context.response.ok) {
+								return;
+							}
+							try {
+								const response = context.response.clone();
+								const pictureBuffer = await response.arrayBuffer();
+								const pictureBase64 = base64.encode(pictureBuffer);
+								user.picture = `data:image/jpeg;base64, ${pictureBase64}`;
+							} catch (e) {
+								logger.error(
+									e && typeof e === "object" && "name" in e
+										? (e.name as string)
+										: "",
+									e,
+								);
+							}
+						},
 					},
-				},
-			);
+				);
+			}
 			const userMap = await options.mapProfileToUser?.(user);
 			// Microsoft Entra ID does NOT include email_verified claim by default.
 			// It must be configured as an optional claim in the app registration.

package/src/utils/redirect-uri.ts

@@ -2,6 +2,26 @@ import * as z from "zod";
 import { isLoopbackHost } from "./host";
 import { DANGEROUS_URL_SCHEMES } from "./url";
 
+const REVERSE_DOMAIN_PRIVATE_USE_SCHEME =
+	/^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i;
+
+/**
+ * Returns whether a parsed redirect URI uses an authority-free, reverse-domain
+ * private-use scheme as recommended by RFC 8252 §7.1.
+ */
+export function isReverseDomainPrivateUseRedirectUri(uri: URL): boolean {
+	const scheme = uri.protocol.slice(0, -1);
+	const schemeSpecificPart = uri.href.slice(uri.protocol.length);
+	return (
+		uri.protocol !== "http:" &&
+		uri.protocol !== "https:" &&
+		uri.host.length === 0 &&
+		schemeSpecificPart.startsWith("/") &&
+		!schemeSpecificPart.startsWith("//") &&
+		REVERSE_DOMAIN_PRIVATE_USE_SCHEME.test(scheme)
+	);
+}
+
 /**
  * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
  * server stores and later hands back to a browser.