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

package/dist/preload.d.mts

@@ -1,5 +1,7 @@
 import electron from "electron";
 import * as z from "zod";
+import * as jose from "jose";
+import { JWTVerifyGetKey } from "jose";
 import { Database } from "bun:sqlite";
 import { DatabaseSync } from "node:sqlite";
 import { D1Database } from "@cloudflare/workers-types";
@@ -644,6 +646,52 @@ declare const createLogger: (options?: Logger | undefined) => InternalLogger;
 //#endregion
 //#region ../core/dist/oauth2/oauth-provider.d.mts
 //#region src/oauth2/oauth-provider.d.ts
+/**
+ * id_token verification config for a social provider.
+ *
+ * Declares how a client-submitted id_token is verified. The shared verifier
+ * (`verifyProviderIdToken`) consumes this instead of each provider implementing its own
+ * boolean check, so verification is centralized and fail-closed: a provider without a config
+ * cannot accept a forged token by omission.
+ */
+type OAuthIdTokenConfig = {
+  /**
+   * JWKS resolver used to verify the JWS signature. Accepts a jose
+   * `createRemoteJWKSet` resolver or a key-resolving function
+   * `(protectedHeader) => key`.
+   */
+  jwks: JWTVerifyGetKey; /** Expected `iss`. Omit for providers whose issuer varies per tenant. */
+  issuer?: (string | string[]) | undefined; /** Expected `aud`, usually the client ID. */
+  audience: string | string[]; /** Permitted JWS algorithms. Defaults to the token's `alg` header. */
+  algorithms?: string[] | undefined; /** Maximum token age passed to jose (e.g. `"1h"`). */
+  maxTokenAge?: string | undefined;
+  /**
+   * How the `nonce` claim is compared to the expected nonce.
+   * - `"exact"` (default): strict equality.
+   * - `"exact-or-sha256"`: matches the raw nonce or its SHA-256 hex digest (Apple).
+   */
+  nonceComparison?: ("exact" | "exact-or-sha256") | undefined;
+  /**
+   * Accept non-JWS (opaque) tokens without signature verification. Identity is then
+   * resolved by getUserInfo from the access token via the provider userinfo endpoint,
+   * which validates it (e.g. Facebook Graph access tokens).
+   */
+  allowOpaqueToken?: boolean | undefined;
+  /**
+   * Provider-specific claim check applied after the signature, issuer,
+   * audience, max-age, and nonce checks pass. Return `false` to reject the
+   * token. Used to enforce constraints the standard checks cannot express,
+   * e.g. Google's hosted-domain (`hd`) restriction. Omitted by providers
+   * that have no extra claim requirement.
+   */
+  verifyClaims?: ((claims: Record<string, unknown>) => boolean) | undefined;
+} | {
+  /**
+   * Custom verifier for providers that cannot verify against a local JWKS, such as a
+   * remote verification endpoint (e.g. LINE).
+   */
+  verify: (token: string, nonce?: string) => Promise<boolean>;
+};
 interface OAuth2Tokens {
   tokenType?: string | undefined;
   accessToken?: string | undefined;
@@ -665,8 +713,58 @@ type OAuth2UserInfo = {
   image?: string | undefined;
   emailVerified: boolean;
 };
-interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
+/**
+ * The result of building a provider authorization URL.
+ *
+ * `requestedScopes` is the effective set of scopes encoded in the URL (the
+ * provider's built-in defaults + configured `options.scope` + per-request
+ * `scopes`, composed by `resolveRequestedScopes`). Callers persist it so the
+ * callback can fall back to the request when the provider omits `scope` from
+ * its token response (RFC 6749 §5.1).
+ */
+interface AuthorizationURLResult {
+  url: URL;
+  requestedScopes: string[];
+}
+/**
+ * How much an RP trusts a provider's echoed token-response `scope` when
+ * persisting `account.grantedScopes`.
+ *
+ * - `"full-grant"`: the echo is the user's complete current grant, so the seam
+ *   replaces the stored grant with it. This is the only path that may narrow
+ *   the grant. Declare it only for providers whose token response reports the
+ *   full combined grant, e.g. Google with `include_granted_scopes`.
+ * - `"projection"`: the echo is this request's subset, so the seam unions it
+ *   onto the stored grant. The safe default for every provider.
+ * - `"absent-echo"`: the provider omitted `scope`, so the grant equals what was
+ *   requested (RFC 6749 §5.1) and the seam unions the requested set. Resolved
+ *   at runtime by the persistence seam, never declared by a provider.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+type GrantAuthority = "full-grant" | "projection" | "absent-echo";
+/**
+ * The authority a provider may declare for its own echoed scope. `"absent-echo"`
+ * is excluded because it is a runtime condition (an omitted echo), not a
+ * provider trait.
+ */
+type ProviderGrantAuthority = Exclude<GrantAuthority, "absent-echo">;
+interface UpstreamProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
   id: LiteralString;
+  /**
+   * The path the provider redirects back to, relative to the app base URL,
+   * e.g. `/callback/google`.
+   */
+  callbackPath: string;
+  /**
+   * How the persistence seam treats this provider's echoed token-response
+   * `scope`. Declare `"full-grant"` only when the echo is the user's complete
+   * current grant (e.g. Google with `include_granted_scopes`); otherwise the
+   * echo is unioned onto the stored grant.
+   *
+   * @default "projection"
+   */
+  grantAuthority?: ProviderGrantAuthority | undefined;
   createAuthorizationURL: (data: {
     state: string;
     codeVerifier: string;
@@ -681,7 +779,7 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
      * before applying them.
      */
     additionalParams?: Record<string, string> | undefined;
-  }) => Awaitable<URL>;
+  }) => Awaitable<AuthorizationURLResult>;
   name: string;
   validateAuthorizationCode: (data: {
     code: string;
@@ -709,14 +807,12 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
    * Custom function to refresh a token
    */
   refreshAccessToken?: ((refreshToken: string) => Promise<OAuth2Tokens>) | undefined;
-  revokeToken?: ((token: string) => Promise<void>) | undefined;
   /**
-   * Verify the id token
-   * @param token - The id token
-   * @param nonce - The nonce
-   * @returns True if the id token is valid, false otherwise
+   * Declarative id_token verification config consumed by the shared
+   * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
+   * verify method, which keeps verification centralized and fail-closed.
    */
-  verifyIdToken?: ((token: string, nonce?: string) => Promise<boolean>) | undefined;
+  idToken?: OAuthIdTokenConfig | undefined;
   /**
    * The expected issuer identifier for this provider (RFC 9207).
    * When set, the callback handler validates the `iss` query parameter
@@ -856,6 +952,29 @@ type ProviderOptions<Profile extends Record<string, any> = any> = {
    * @default false
    */
   overrideUserInfoOnSignIn?: boolean | undefined;
+  /**
+   * Require this provider's email to be verified before a session is created.
+   *
+   * When the provider reports the email as unverified, the user and account are
+   * still created/linked, but no session is issued: the OAuth callback redirects
+   * with `?error=email_not_verified` and id-token sign-in returns a `403`
+   * `EMAIL_NOT_VERIFIED`. A verification email is (re)sent per the
+   * `emailVerification` settings (`sendOnSignUp` / `sendOnSignIn`).
+   *
+   * The gate checks the local user's verification state, not the provider's
+   * claim on each request: a user already verified through another method (or a
+   * prior verified sign-in) keeps access even if the provider later reports the
+   * email as unverified.
+   *
+   * This is opt-in per provider and is independent of
+   * `emailAndPassword.requireEmailVerification`; enabling that does not gate
+   * social sign-in. Only enable it for providers that report a trustworthy
+   * `email_verified` signal: several providers always report the email as
+   * unverified, which would block every sign-in.
+   *
+   * @default false
+   */
+  requireEmailVerification?: boolean | undefined;
 }; //#endregion
 //#endregion
 //#region ../core/dist/social-providers/apple.d.mts
@@ -1164,6 +1283,15 @@ interface GithubOptions extends ProviderOptions<GithubProfile> {
   clientId: string;
 }
 //#endregion
+//#region ../core/dist/oauth2/client-assertion.d.mts
+type ClientAssertionGrantType = "authorization_code" | "refresh_token" | "client_credentials";
+interface ClientAssertionContext {
+  clientId: string;
+  tokenEndpoint: string;
+  grantType: ClientAssertionGrantType;
+}
+type ClientAssertionGetter = (context: ClientAssertionContext) => Awaitable<string>;
+//#endregion
 //#region ../core/dist/social-providers/microsoft-entra-id.d.mts
 //#region src/social-providers/microsoft-entra-id.d.ts
 /**
@@ -1275,21 +1403,29 @@ interface MicrosoftOptions extends ProviderOptions<MicrosoftEntraIDProfile> {
    * The tenant ID of the Microsoft account
    * @default "common"
    */
-  tenantId?: string | undefined;
+  tenantId?: string;
   /**
    * The authentication authority URL. Use the default "https://login.microsoftonline.com" for standard Entra ID or "https://<tenant-id>.ciamlogin.com" for CIAM scenarios.
    * @default "https://login.microsoftonline.com"
    */
-  authority?: string | undefined;
+  authority?: string;
+  /**
+   * Function that returns a JWT client assertion for token endpoint authentication.
+   *
+   * Use this instead of `clientSecret` when your Microsoft Entra ID app is
+   * configured for client authentication with assertions (private_key_jwt or
+   * workload identity federation).
+   */
+  clientAssertion?: ClientAssertionGetter;
   /**
    * The size of the profile photo
    * @default 48
    */
-  profilePhotoSize?: (48 | 64 | 96 | 120 | 240 | 360 | 432 | 504 | 648) | undefined;
+  profilePhotoSize?: 48 | 64 | 96 | 120 | 240 | 360 | 432 | 504 | 648;
   /**
    * Disable profile photo
    */
-  disableProfilePhoto?: boolean | undefined;
+  disableProfilePhoto?: boolean;
 }
 //#endregion
 //#region ../core/dist/social-providers/google.d.mts
@@ -1331,9 +1467,22 @@ interface GoogleOptions extends ProviderOptions<GoogleProfile> {
    */
   display?: ("page" | "popup" | "touch" | "wap") | undefined;
   /**
-   * The hosted domain of the user
+   * The hosted domain (Google Workspace) the user must belong to.
+   *
+   * This is sent to Google as the `hd` authorization hint and, when set, is
+   * also enforced against the `hd` claim of the returned id token/profile.
+   * Sign-in is rejected when the claim is missing or does not match, so this
+   * can be used to restrict sign-in to a Workspace domain.
    */
   hd?: string | undefined;
+  /**
+   * Enable incremental authorization via Google's `include_granted_scopes`
+   * parameter. When enabled, Google reports the user's full granted scope set
+   * in the token response.
+   *
+   * @default true
+   */
+  includeGrantedScopes?: boolean | undefined;
 }
 //#endregion
 //#region ../core/dist/social-providers/huggingface.d.mts
@@ -2204,6 +2353,7 @@ declare const socialProviders: {
   apple: (options: AppleOptions) => {
     id: "apple";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2217,7 +2367,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2228,7 +2381,13 @@ declare const socialProviders: {
       codeVerifier?: string | undefined;
       deviceId?: string | undefined;
     }) => Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+      issuer: string;
+      audience: string | string[];
+      maxTokenAge: string;
+      nonceComparison: "exact-or-sha256";
+    };
     refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
     getUserInfo(token: OAuth2Tokens & {
       user?: {
@@ -2254,6 +2413,7 @@ declare const socialProviders: {
   atlassian: (options: AtlassianOptions) => {
     id: "atlassian";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2268,7 +2428,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2304,6 +2467,7 @@ declare const socialProviders: {
   cognito: (options: CognitoOptions) => {
     id: "cognito";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2318,7 +2482,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2330,7 +2497,12 @@ declare const socialProviders: {
       deviceId?: string | undefined;
     }) => Promise<OAuth2Tokens>;
     refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+      issuer: string;
+      audience: string | string[];
+      maxTokenAge: string;
+    };
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -2355,6 +2527,7 @@ declare const socialProviders: {
   discord: (options: DiscordOptions) => {
     id: "discord";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2368,7 +2541,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -2403,6 +2579,7 @@ declare const socialProviders: {
   facebook: (options: FacebookOptions) => {
     id: "facebook";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2417,7 +2594,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -2427,7 +2607,20 @@ declare const socialProviders: {
       codeVerifier?: string | undefined;
       deviceId?: string | undefined;
     }) => Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      jwks: {
+        (protectedHeader?: jose.JWSHeaderParameters, token?: jose.FlattenedJWSInput): Promise<jose.CryptoKey>;
+        coolingDown: boolean;
+        fresh: boolean;
+        reloading: boolean;
+        reload: () => Promise<void>;
+        jwks: () => jose.JSONWebKeySet | undefined;
+      };
+      issuer: string;
+      audience: string | string[];
+      algorithms: string[];
+      allowOpaqueToken: true;
+    };
     refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
     getUserInfo(token: OAuth2Tokens & {
       user?: {
@@ -2453,6 +2646,7 @@ declare const socialProviders: {
   figma: (options: FigmaOptions) => {
     id: "figma";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2467,7 +2661,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2503,6 +2700,7 @@ declare const socialProviders: {
   github: (options: GithubOptions) => {
     id: "github";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2518,7 +2716,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2554,6 +2755,7 @@ declare const socialProviders: {
   microsoft: (options: MicrosoftOptions) => {
     id: "microsoft";
     name: string;
+    callbackPath: string;
     createAuthorizationURL(data: {
       state: string;
       codeVerifier: string;
@@ -2562,7 +2764,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode({
       code,
       codeVerifier,
@@ -2573,7 +2778,12 @@ declare const socialProviders: {
       codeVerifier?: string | undefined;
       deviceId?: string | undefined;
     }): Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+      audience: string | string[];
+      maxTokenAge: string;
+      issuer: string | undefined;
+    };
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -2599,6 +2809,8 @@ declare const socialProviders: {
   google: (options: GoogleOptions) => {
     id: "google";
     name: string;
+    callbackPath: string;
+    grantAuthority: "full-grant" | "projection";
     createAuthorizationURL({
       state,
       scopes,
@@ -2615,7 +2827,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2627,7 +2842,13 @@ declare const socialProviders: {
       deviceId?: string | undefined;
     }) => Promise<OAuth2Tokens>;
     refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+      issuer: string[];
+      audience: string | string[];
+      maxTokenAge: string;
+      verifyClaims: ((claims: Record<string, unknown>) => boolean) | undefined;
+    };
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -2652,6 +2873,7 @@ declare const socialProviders: {
   huggingface: (options: HuggingFaceOptions) => {
     id: "huggingface";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2666,7 +2888,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2702,6 +2927,7 @@ declare const socialProviders: {
   slack: (options: SlackOptions) => {
     id: "slack";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2715,7 +2941,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -2750,6 +2979,7 @@ declare const socialProviders: {
   spotify: (options: SpotifyOptions) => {
     id: "spotify";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2764,7 +2994,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2800,6 +3033,7 @@ declare const socialProviders: {
   twitch: (options: TwitchOptions) => {
     id: "twitch";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2813,7 +3047,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -2848,6 +3085,7 @@ declare const socialProviders: {
   twitter: (options: TwitterOption) => {
     id: "twitter";
     name: string;
+    callbackPath: string;
     createAuthorizationURL(data: {
       state: string;
       codeVerifier: string;
@@ -2856,7 +3094,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2892,6 +3133,7 @@ declare const socialProviders: {
   dropbox: (options: DropboxOptions) => {
     id: "dropbox";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -2906,7 +3148,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }) => Promise<URL>;
+    }) => Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -2942,6 +3187,7 @@ declare const socialProviders: {
   kick: (options: KickOptions) => {
     id: "kick";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2956,7 +3202,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode({
       code,
       redirectURI,
@@ -2992,6 +3241,7 @@ declare const socialProviders: {
   linear: (options: LinearOptions) => {
     id: "linear";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3006,7 +3256,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3041,6 +3294,7 @@ declare const socialProviders: {
   linkedin: (options: LinkedInOptions) => {
     id: "linkedin";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -3055,7 +3309,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }) => Promise<URL>;
+    }) => Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3090,6 +3347,7 @@ declare const socialProviders: {
   gitlab: (options: GitlabOptions) => {
     id: "gitlab";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -3105,7 +3363,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }) => Promise<URL>;
+    }) => Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI,
@@ -3162,6 +3423,7 @@ declare const socialProviders: {
   tiktok: (options: TiktokOptions) => {
     id: "tiktok";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3175,7 +3437,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): URL;
+    }): {
+      url: URL;
+      requestedScopes: string[];
+    };
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3210,6 +3475,7 @@ declare const socialProviders: {
   reddit: (options: RedditOptions) => {
     id: "reddit";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3223,7 +3489,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3258,6 +3527,7 @@ declare const socialProviders: {
   roblox: (options: RobloxOptions) => {
     id: "roblox";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3271,7 +3541,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3306,6 +3579,7 @@ declare const socialProviders: {
   salesforce: (options: SalesforceOptions) => {
     id: "salesforce";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3320,7 +3594,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3356,6 +3633,7 @@ declare const socialProviders: {
   vk: (options: VkOption) => {
     id: "vk";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3370,7 +3648,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3407,8 +3688,10 @@ declare const socialProviders: {
   zoom: (userOptions: ZoomOptions) => {
     id: "zoom";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
+      scopes,
       redirectURI,
       codeVerifier,
       additionalParams
@@ -3420,7 +3703,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }) => Promise<URL>;
+    }) => Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI,
@@ -3455,6 +3741,7 @@ declare const socialProviders: {
   notion: (options: NotionOptions) => {
     id: "notion";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3469,7 +3756,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3504,6 +3794,7 @@ declare const socialProviders: {
   kakao: (options: KakaoOptions) => {
     id: "kakao";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3517,7 +3808,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3573,6 +3867,7 @@ declare const socialProviders: {
   naver: (options: NaverOptions) => {
     id: "naver";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3586,7 +3881,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3642,6 +3940,7 @@ declare const socialProviders: {
   line: (options: LineOptions) => {
     id: "line";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3657,7 +3956,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3669,7 +3971,9 @@ declare const socialProviders: {
       deviceId?: string | undefined;
     }) => Promise<OAuth2Tokens>;
     refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+    idToken: {
+      verify: (token: string, nonce: string | undefined) => Promise<boolean>;
+    };
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -3715,6 +4019,7 @@ declare const socialProviders: {
   paybin: (options: PaybinOptions) => {
     id: "paybin";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3730,7 +4035,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3766,6 +4074,7 @@ declare const socialProviders: {
   paypal: (options: PayPalOptions) => {
     id: "paypal";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       codeVerifier,
@@ -3779,7 +4088,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       redirectURI
@@ -3799,7 +4111,6 @@ declare const socialProviders: {
       refreshToken: any;
       accessTokenExpiresAt: Date | undefined;
     }>);
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -3845,6 +4156,7 @@ declare const socialProviders: {
   polar: (options: PolarOptions) => {
     id: "polar";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3859,7 +4171,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3895,6 +4210,7 @@ declare const socialProviders: {
   railway: (options: RailwayOptions) => {
     id: "railway";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3909,7 +4225,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3945,6 +4264,7 @@ declare const socialProviders: {
   vercel: (options: VercelOptions) => {
     id: "vercel";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3959,7 +4279,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): Promise<URL>;
+    }): Promise<{
+      url: URL;
+      requestedScopes: string[];
+    }>;
     validateAuthorizationCode: ({
       code,
       codeVerifier,
@@ -3994,6 +4317,7 @@ declare const socialProviders: {
   wechat: (options: WeChatOptions) => {
     id: "wechat";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -4007,7 +4331,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): URL;
+    }): {
+      url: URL;
+      requestedScopes: string[];
+    };
     validateAuthorizationCode: ({
       code
     }: {
@@ -4073,7 +4400,7 @@ declare const accountSchema: z.ZodObject<{
   idToken: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   accessTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
   refreshTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
-  scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  grantedScopes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
   password: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 type BaseAccount = z.infer<typeof accountSchema>;
@@ -4082,14 +4409,14 @@ type BaseAccount = z.infer<typeof accountSchema>;
  */
 type Account<DBOptions extends BetterAuthOptions["account"] = BetterAuthOptions["account"], Plugins extends BetterAuthOptions["plugins"] = BetterAuthOptions["plugins"]> = Prettify$1<BaseAccount & InferDBFieldsFromOptions<DBOptions> & InferDBFieldsFromPlugins<"account", Plugins>>; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/helper.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/helper.d.mts
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 type IsEmptyObject<T> = keyof T extends never ? true : false;
 type UnionToIntersection<Union> = (Union extends unknown ? (distributedUnion: Union) => void : never) extends ((mergedIntersection: infer Intersection) => void) ? Intersection & Union : never;
 type InferParamPath<Path> = Path extends `${infer _Start}:${infer Param}/${infer Rest}` ? { [K in Param | keyof InferParamPath<Rest>]: string } : Path extends `${infer _Start}:${infer Param}` ? { [K in Param]: string } : Path extends `${infer _Start}/${infer Rest}` ? InferParamPath<Rest> : {};
 type InferParamWildCard<Path> = Path extends `${infer _Start}/*:${infer Param}/${infer Rest}` | `${infer _Start}/**:${infer Param}/${infer Rest}` ? { [K in Param | keyof InferParamPath<Rest>]: string } : Path extends `${infer _Start}/*` ? { [K in "_"]: string } : Path extends `${infer _Start}/${infer Rest}` ? InferParamWildCard<Rest> : {}; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/standard-schema.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/standard-schema.d.mts
 //#region src/standard-schema.d.ts
 /** The Standard Schema interface. */
 interface StandardSchemaV1$1<Input = unknown, Output = Input> {
@@ -4147,7 +4474,7 @@ declare namespace StandardSchemaV1$1 {
   type InferOutput<Schema extends StandardSchemaV1$1> = NonNullable<Schema["~standard"]["types"]>["output"];
 } //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/error.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/error.d.mts
 declare const statusCodes: {
   OK: number;
   CREATED: number;
@@ -4225,7 +4552,7 @@ declare const APIError: new (status?: Status | "OK" | "CREATED" | "ACCEPTED" | "
   errorStack: string | undefined;
 }; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/cookies.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/cookies.d.mts
 //#region src/cookies.d.ts
 type CookiePrefixOptions = "host" | "secure";
 type CookieOptions = {
@@ -4315,7 +4642,7 @@ type CookieOptions = {
   prefix?: CookiePrefixOptions;
 };
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/openapi.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/openapi.d.mts
 //#region src/openapi.d.ts
 type OpenAPISchemaType = "string" | "number" | "integer" | "boolean" | "array" | "object";
 interface OpenAPIParameter {
@@ -4337,7 +4664,7 @@ interface OpenAPIParameter {
   };
 }
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/endpoint.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/endpoint.d.mts
 //#region src/endpoint.d.ts
 interface EndpointBaseOptions {
   /**
@@ -4658,6 +4985,22 @@ type EndpointContext<Path extends string, Options extends EndpointOptions, Conte
    * @returns - The cookie string
    */
   setSignedCookie: (key: string, value: string, secret: string, options?: CookieOptions) => Promise<string>;
+  /**
+   * Response headers
+   *
+   * The live `Headers` for the response being built in the current
+   * request. Read it to inspect what has already been queued, e.g. to
+   * avoid emitting a `Set-Cookie` twice or to check headers set by an
+   * earlier handler in the chain.
+   *
+   * @example
+   * ```ts
+   * const alreadySet = ctx.responseHeaders
+   *   .getSetCookie()
+   *   .some((c) => c.startsWith("session="));
+   * ```
+   */
+  responseHeaders: Headers;
   /**
    * JSON
    *
@@ -4700,7 +5043,7 @@ type Endpoint<Path extends string = string, Options extends EndpointOptions = En
   path: Path;
 }; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/middleware.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/middleware.d.mts
 //#region src/middleware.d.ts
 interface MiddlewareOptions extends Omit<EndpointOptions, "method"> {}
 type MiddlewareContext<Options extends MiddlewareOptions, Context = {}> = EndpointContext<string, Options & {
@@ -4807,7 +5150,7 @@ type Middleware<Options extends MiddlewareOptions = MiddlewareOptions, Handler e
   options: Options;
 }; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/better-call@1.3.5_zod@4.3.6/node_modules/better-call/dist/context.d.mts
+//#region ../../node_modules/.pnpm/better-call@1.3.6_zod@4.3.6/node_modules/better-call/dist/context.d.mts
 //#region src/context.d.ts
 type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 type Method = HTTPMethod | "*";
@@ -4943,11 +5286,13 @@ 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>): Promise<T & User>;
+  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
+   * runs the `user.validateUserInfo` gate.
+   */
+
+  source: UserProvisioningSource): Promise<T & User>;
   createAccount<T extends Record<string, any>>(account: Omit<Account, "id" | "createdAt" | "updatedAt"> & Partial<Account> & T): Promise<T & Account>;
   listSessions(userId: string, options?: {
     onlyActiveSessions?: boolean | undefined;
@@ -5102,7 +5447,7 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
     session: Session & Record<string, any>;
     user: User & Record<string, any>;
   } | null) => void;
-  socialProviders: OAuthProvider[];
+  socialProviders: UpstreamProvider[];
   authCookies: BetterAuthCookies;
   logger: ReturnType<typeof createLogger>;
   rateLimit: {
@@ -5268,7 +5613,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {
@@ -5397,7 +5742,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {
@@ -5463,6 +5808,73 @@ type GenerateIdFn = (options: {
   model: ModelNames;
   size?: number | undefined;
 }) => string | false;
+/**
+ * What Better Auth is about to do with an incoming identity when
+ * {@link BetterAuthOptions.user}'s `validateUserInfo` runs.
+ *
+ * - `create-user`: a brand-new user record is about to be created.
+ * - `link-account`: a new provider account is about to be linked to an
+ *   already-existing user.
+ * - `sign-in`: an existing OAuth or SSO user is signing in again. This is the
+ *   one case where the provider can assert *changed* data, so the hook receives
+ *   the fresh provider email and profile (not the stored row), letting a domain
+ *   or org policy reject a user whose provider identity moved out of bounds.
+ *
+ * Non-provider returning sign-ins are not re-validated: they carry only the
+ * stored row, which has not changed since `create-user` gated it. Use the admin
+ * plugin's ban controls or a `databaseHooks.session.create.before` hook to
+ * block those.
+ */
+type ValidateUserInfoAction = "create-user" | "link-account" | "sign-in";
+/**
+ * The authentication method that produced the incoming user info. The named
+ * methods cover Better Auth's built-ins; the open `string` keeps it extensible
+ * for plugins (for example `"scim"`).
+ */
+type ValidateUserInfoMethod = "oauth" | "sso-oidc" | "sso-saml" | "email-password" | "magic-link" | "email-otp" | "anonymous" | "siwe" | "phone-number" | "admin" | (string & {});
+/** OAuth-specific provisioning context; present only when `method` is `"oauth"`. */
+type ValidateUserInfoOAuthInfo = {
+  /** The social or generic OAuth provider id (e.g. `"google"`). */providerId: string; /** The raw provider profile (userinfo or id-token claims), unmapped. */
+  profile?: Record<string, unknown> | undefined;
+};
+/** SSO-specific provisioning context; present for OIDC and SAML SSO methods. */
+type ValidateUserInfoSSOInfo = {
+  /** The configured SSO provider id. */providerId: string; /** The raw OIDC claims or SAML assertion attributes, unmapped. */
+  profile?: Record<string, unknown> | undefined;
+};
+/** Provisioning origin passed to `createUser`; the creation seam adds `action: "create-user"` to build {@link ValidateUserInfoSource}. */
+type UserProvisioningSource = {
+  method: ValidateUserInfoMethod; /** Provider id and raw profile; present iff `method` is `"oauth"`. */
+  oauth?: ValidateUserInfoOAuthInfo | undefined; /** Provider id and raw profile; present iff `method` is `"sso-oidc"` or `"sso-saml"`. */
+  sso?: ValidateUserInfoSSOInfo | undefined;
+};
+/**
+ * The context passed to `validateUserInfo`: the lifecycle
+ * {@link ValidateUserInfoAction}, the {@link ValidateUserInfoMethod}, and (for
+ * OAuth/SSO provider methods) protocol-specific provider metadata.
+ *
+ * ```ts
+ * // Scope to one OAuth provider:
+ * if (source.oauth?.providerId !== "google") return;
+ * // Branch on the method:
+ * if (source.method === "anonymous") return { error: "no_anonymous" };
+ * // Inspect SSO claims:
+ * if (source.method === "sso-saml" && source.sso?.profile?.department !== "eng") {
+ *   return { error: "invalid_department" };
+ * }
+ * ```
+ */
+type ValidateUserInfoSource = UserProvisioningSource & {
+  action: ValidateUserInfoAction;
+};
+type ValidateUserInfoResult = {
+  /** A short, machine-readable rejection code, surfaced to the client. */error: string;
+  /**
+   * A human-readable reason, surfaced to the client. Do not put sensitive
+   * details here.
+   */
+  errorDescription?: string | undefined;
+};
 /**
  * Configuration for dynamic base URL resolution.
  * Allows Better Auth to work with multiple domains (e.g., Vercel preview deployments).
@@ -6125,6 +6537,30 @@ type BetterAuthOptions = {
    * User configuration
    */
   user?: (BetterAuthDBOptions<"user", keyof BaseUser> & {
+    /**
+     * Gate which identities Better Auth admits. Called just before
+     * `create-user`, `link-account`, and (for OAuth) `sign-in`, across
+     * every authentication method, including stateless setups with no
+     * persistent database. On `sign-in` the hook receives the *fresh*
+     * provider email and profile, so a domain policy can reject a user
+     * whose provider identity moved out of bounds.
+     *
+     * Non-provider returning sign-ins are not re-validated; use the admin
+     * plugin's ban controls or a `databaseHooks.session.create.before`
+     * hook for those.
+     *
+     * Return nothing to allow; return `{ error }` to reject. Browser flows
+     * redirect to the configured error URL; programmatic flows surface a
+     * `403`.
+     *
+     * TODO: rename to `validateUser` (and the `ValidateUserInfo*` types).
+     * "UserInfo" is the OIDC term and misleads for the email/password,
+     * SIWE, phone, and admin methods.
+     */
+    validateUserInfo?: (data: {
+      user: Partial<User> & Record<string, unknown>;
+      source: ValidateUserInfoSource;
+    }, context: GenericEndpointContext) => Awaitable<void | ValidateUserInfoResult>;
     /**
      * Changing email configuration
      */