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

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";
@@ -31,6 +33,7 @@ type DBAdapterDebugLogOption = boolean | {
   delete?: boolean | undefined;
   deleteMany?: boolean | undefined;
   consumeOne?: boolean | undefined;
+  incrementOne?: boolean | undefined;
   count?: boolean | undefined;
 } | {
   /**
@@ -206,7 +209,7 @@ interface DBAdapterFactoryConfig<Options extends BetterAuthOptions = BetterAuthO
     /**
      * The action which was called from the adapter.
      */
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "incrementOne" | "count";
     /**
      * The model name.
      */
@@ -435,15 +438,43 @@ type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
    * race-safe primitive for consuming single-use credentials
    * (verification tokens, authorization codes, one-time tokens).
    *
-   * Always defined on the factory-wrapped adapter. When the underlying
-   * `CustomAdapter` does not implement `consumeOne`, the factory provides
-   * a fallback that wraps `findMany + deleteMany` in `transaction(...)`
-   * and returns the row only when the delete reports an affected row.
+   * Always defined on the factory-wrapped adapter. The underlying
+   * `CustomAdapter` must implement this natively; there is no portable
+   * fallback that can guarantee cross-process single-use semantics.
    */
   consumeOne: <T>(data: {
     model: string;
     where: Where[];
   }) => Promise<T | null>;
+  /**
+   * Atomically apply signed numeric deltas to a single row matching the where
+   * clause. For each entry in `increment`, the operation applies
+   * `field = field + delta` in one atomic step; a negative delta decrements.
+   *
+   * The `where` clause is both the selector AND the guard: comparison
+   * operators are honored, so passing `{ field: "remaining", operator: "gt",
+   * value: 0 }` only mutates the row while `remaining` is still above zero.
+   * When the guard matches no row, the operation makes no change and returns
+   * `null`.
+   *
+   * The optional `set` map assigns absolute values to fields in the same
+   * atomic operation, alongside the increments.
+   *
+   * Returns the updated row, or `null` when the guard matched no row. Under
+   * concurrent invocation against the same row, this is the race-safe
+   * primitive for guarded counter updates (e.g. decrementing a remaining-uses
+   * counter only while it is still positive).
+   *
+   * Always defined on the factory-wrapped adapter. The underlying
+   * `CustomAdapter` must implement this natively; there is no portable
+   * fallback that can guarantee guarded counter semantics across runtimes.
+   */
+  incrementOne: <T>(data: {
+    model: string;
+    where: Where[];
+    increment: Record<string, number>;
+    set?: Record<string, unknown> | undefined;
+  }) => Promise<T | null>;
   /**
    * Execute multiple operations in a transaction.
    * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -526,18 +557,33 @@ interface CustomAdapter {
     where: CleanedWhere[];
   }) => Promise<number>;
   /**
-   * Optional native atomic single-row consume. When omitted, the adapter
-   * factory falls back to `transaction(findMany + deleteMany)`.
+   * Native atomic single-row consume.
    * Implementing this method natively (e.g. `DELETE ... RETURNING *`,
    * `findOneAndDelete`, `OUTPUT deleted.*`) gives one round trip and the
    * strongest race-safety guarantee. Implementations must delete at most
-   * one matching row. TODO(consume-one-required): tighten to required in the
-   * next minor on `next`.
+   * one matching row.
    */
-  consumeOne?: <T>(data: {
+  consumeOne: <T>(data: {
     model: string;
     where: CleanedWhere[];
   }) => Promise<T | null>;
+  /**
+   * Native atomic guarded counter mutation. Applies
+   * `field = field + delta` for each entry in `increment` (negative deltas
+   * decrement), with `where` acting as both selector and guard and `set`
+   * assigning absolute values in the same operation. Returns the updated row,
+   * or `null` when the guard matched no row.
+   *
+   * Implementing this natively (e.g. `UPDATE ... SET n = n + $delta WHERE ...
+   * RETURNING *`) gives one round trip and the strongest race-safety
+   * guarantee.
+   */
+  incrementOne: <T>(data: {
+    model: string;
+    where: CleanedWhere[];
+    increment: Record<string, number>;
+    set?: Record<string, unknown> | undefined;
+  }) => Promise<T | null>;
   count: ({
     model,
     where
@@ -575,7 +621,6 @@ type BaseRateLimit = z.infer<typeof rateLimitSchema>;
 /**
  * Rate limit schema type used by better-auth for rate limiting
  */
-type RateLimit<DBOptions extends BetterAuthOptions["rateLimit"] = BetterAuthOptions["rateLimit"], Plugins extends BetterAuthOptions["plugins"] = BetterAuthOptions["plugins"]> = Prettify$1<BaseRateLimit & InferDBFieldsFromOptions<DBOptions> & InferDBFieldsFromPlugins<"rateLimit", Plugins>>; //#endregion
 //#endregion
 //#region ../core/dist/db/schema/session.d.mts
 //#region src/db/schema/session.d.ts
@@ -644,6 +689,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 +756,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 +822,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 +850,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 +995,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 +1326,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 +1446,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 +1510,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 +2396,7 @@ declare const socialProviders: {
   apple: (options: AppleOptions) => {
     id: "apple";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2217,7 +2410,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 +2424,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 +2456,7 @@ declare const socialProviders: {
   atlassian: (options: AtlassianOptions) => {
     id: "atlassian";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2268,7 +2471,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 +2510,7 @@ declare const socialProviders: {
   cognito: (options: CognitoOptions) => {
     id: "cognito";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2318,7 +2525,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 +2540,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 +2570,7 @@ declare const socialProviders: {
   discord: (options: DiscordOptions) => {
     id: "discord";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2368,7 +2584,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 +2622,7 @@ declare const socialProviders: {
   facebook: (options: FacebookOptions) => {
     id: "facebook";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2417,7 +2637,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 +2650,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 +2689,7 @@ declare const socialProviders: {
   figma: (options: FigmaOptions) => {
     id: "figma";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2467,7 +2704,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 +2743,7 @@ declare const socialProviders: {
   github: (options: GithubOptions) => {
     id: "github";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2518,7 +2759,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 +2798,7 @@ declare const socialProviders: {
   microsoft: (options: MicrosoftOptions) => {
     id: "microsoft";
     name: string;
+    callbackPath: string;
     createAuthorizationURL(data: {
       state: string;
       codeVerifier: string;
@@ -2562,7 +2807,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 +2821,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>;
+      audience: string | string[];
+      maxTokenAge: string;
+      issuer: string | undefined;
+      verifyClaims: (claims: Record<string, unknown>) => boolean;
+    };
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -2599,6 +2853,8 @@ declare const socialProviders: {
   google: (options: GoogleOptions) => {
     id: "google";
     name: string;
+    callbackPath: string;
+    grantAuthority: "full-grant" | "projection";
     createAuthorizationURL({
       state,
       scopes,
@@ -2615,7 +2871,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 +2886,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 +2917,7 @@ declare const socialProviders: {
   huggingface: (options: HuggingFaceOptions) => {
     id: "huggingface";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2666,7 +2932,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 +2971,7 @@ declare const socialProviders: {
   slack: (options: SlackOptions) => {
     id: "slack";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2715,7 +2985,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 +3023,7 @@ declare const socialProviders: {
   spotify: (options: SpotifyOptions) => {
     id: "spotify";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2764,7 +3038,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 +3077,7 @@ declare const socialProviders: {
   twitch: (options: TwitchOptions) => {
     id: "twitch";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2813,7 +3091,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 +3129,7 @@ declare const socialProviders: {
   twitter: (options: TwitterOption) => {
     id: "twitter";
     name: string;
+    callbackPath: string;
     createAuthorizationURL(data: {
       state: string;
       codeVerifier: string;
@@ -2856,7 +3138,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 +3177,7 @@ declare const socialProviders: {
   dropbox: (options: DropboxOptions) => {
     id: "dropbox";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -2906,7 +3192,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 +3231,7 @@ declare const socialProviders: {
   kick: (options: KickOptions) => {
     id: "kick";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -2956,7 +3246,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 +3285,7 @@ declare const socialProviders: {
   linear: (options: LinearOptions) => {
     id: "linear";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3006,7 +3300,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 +3338,7 @@ declare const socialProviders: {
   linkedin: (options: LinkedInOptions) => {
     id: "linkedin";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -3055,7 +3353,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 +3391,7 @@ declare const socialProviders: {
   gitlab: (options: GitlabOptions) => {
     id: "gitlab";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
       scopes,
@@ -3105,7 +3407,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 +3467,7 @@ declare const socialProviders: {
   tiktok: (options: TiktokOptions) => {
     id: "tiktok";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3175,7 +3481,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 +3519,7 @@ declare const socialProviders: {
   reddit: (options: RedditOptions) => {
     id: "reddit";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3223,7 +3533,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 +3571,7 @@ declare const socialProviders: {
   roblox: (options: RobloxOptions) => {
     id: "roblox";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3271,7 +3585,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 +3623,7 @@ declare const socialProviders: {
   salesforce: (options: SalesforceOptions) => {
     id: "salesforce";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3320,7 +3638,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 +3677,7 @@ declare const socialProviders: {
   vk: (options: VkOption) => {
     id: "vk";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3370,7 +3692,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 +3732,10 @@ declare const socialProviders: {
   zoom: (userOptions: ZoomOptions) => {
     id: "zoom";
     name: string;
+    callbackPath: string;
     createAuthorizationURL: ({
       state,
+      scopes,
       redirectURI,
       codeVerifier,
       additionalParams
@@ -3420,7 +3747,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 +3785,7 @@ declare const socialProviders: {
   notion: (options: NotionOptions) => {
     id: "notion";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3469,7 +3800,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 +3838,7 @@ declare const socialProviders: {
   kakao: (options: KakaoOptions) => {
     id: "kakao";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3517,7 +3852,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 +3911,7 @@ declare const socialProviders: {
   naver: (options: NaverOptions) => {
     id: "naver";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3586,7 +3925,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 +3984,7 @@ declare const socialProviders: {
   line: (options: LineOptions) => {
     id: "line";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3657,7 +4000,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 +4015,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 +4063,7 @@ declare const socialProviders: {
   paybin: (options: PaybinOptions) => {
     id: "paybin";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3730,7 +4079,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 +4118,7 @@ declare const socialProviders: {
   paypal: (options: PayPalOptions) => {
     id: "paypal";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       codeVerifier,
@@ -3779,7 +4132,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 +4155,6 @@ declare const socialProviders: {
       refreshToken: any;
       accessTokenExpiresAt: Date | undefined;
     }>);
-    verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
     getUserInfo(token: OAuth2Tokens & {
       user?: {
         name?: {
@@ -3845,6 +4200,7 @@ declare const socialProviders: {
   polar: (options: PolarOptions) => {
     id: "polar";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3859,7 +4215,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 +4254,7 @@ declare const socialProviders: {
   railway: (options: RailwayOptions) => {
     id: "railway";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3909,7 +4269,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 +4308,7 @@ declare const socialProviders: {
   vercel: (options: VercelOptions) => {
     id: "vercel";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -3959,7 +4323,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 +4361,7 @@ declare const socialProviders: {
   wechat: (options: WeChatOptions) => {
     id: "wechat";
     name: string;
+    callbackPath: string;
     createAuthorizationURL({
       state,
       scopes,
@@ -4007,7 +4375,10 @@ declare const socialProviders: {
       display?: string | undefined;
       loginHint?: string | undefined;
       additionalParams?: Record<string, string> | undefined;
-    }): URL;
+    }): {
+      url: URL;
+      requestedScopes: string[];
+    };
     validateAuthorizationCode: ({
       code
     }: {
@@ -4073,7 +4444,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 +4453,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 +4518,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 +4596,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 +4686,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 +4708,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 +5029,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 +5087,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 +5194,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 +5330,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;
@@ -5023,6 +5412,23 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
    * pair at single-use credential consumption sites.
    */
   consumeVerificationValue(identifier: string): Promise<Verification | null>;
+  /**
+   * First-writer-wins create keyed by a deterministic primary key derived from
+   * `identifier`. Returns `true` when this caller created the row and `false`
+   * when a row for the same identifier already existed.
+   *
+   * The dual of `consumeVerificationValue`: reserve races to create a marker
+   * exactly once, where consume races to delete one exactly once. Use it for
+   * replay tombstones (a SAML assertion id, a JWT `jti`) where the first caller
+   * wins. The database path is atomic via the primary key. Secondary-storage-only
+   * verification is not supported for reservation and runtime implementations
+   * should fail closed unless verification is backed by the database.
+   */
+  reserveVerificationValue(data: {
+    identifier: string;
+    value: string;
+    expiresAt: Date;
+  }): Promise<boolean>;
   updateVerificationByIdentifier(identifier: string, data: Partial<Verification>): Promise<Verification>;
   refreshUserSessions(user: User): Promise<void>;
 }
@@ -5102,7 +5508,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 +5674,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 +5803,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 +5869,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).
@@ -5507,8 +5980,30 @@ type DynamicBaseURLConfig = {
  */
 type BaseURLConfig = string | DynamicBaseURLConfig;
 interface BetterAuthRateLimitStorage {
-  get: (key: string) => Promise<RateLimit | null | undefined>;
-  set: (key: string, value: RateLimit, update?: boolean | undefined) => Promise<void>;
+  /**
+   * Atomically records one request against `key` within the rolling `window`
+   * (in seconds) and reports whether it is allowed.
+   *
+   * When `allowed` is true the count was incremented within the active window,
+   * or the window had elapsed and was reset to start at 1. When `allowed` is
+   * false the limit was already reached and `retryAfter` is the number of
+   * seconds until the window frees up.
+   *
+   * Performing the check and the increment in a single step closes the
+   * concurrent-bypass gap of the separate `get`/`set` path: N simultaneous
+   * requests can no longer all pass a stale read before any increment lands.
+   *
+   * Custom storages must implement this operation directly. Better Auth no
+   * longer accepts separate `get`/`set` rate-limit storage because that shape
+   * cannot enforce a distributed limit under concurrent requests.
+   */
+  consume: (key: string, rule: {
+    window: number;
+    max: number;
+  }) => Promise<{
+    allowed: boolean;
+    retryAfter: number | null;
+  }>;
 }
 type BetterAuthRateLimitRule = {
   /**
@@ -6125,6 +6620,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
      */
@@ -6266,6 +6785,20 @@ type BetterAuthOptions = {
        * @default "compact"
        */
       strategy?: "compact" | "jwt" | "jwe";
+      /**
+       * JWT-specific configuration for `strategy: "jwt"`.
+       */
+      jwt?: {
+        /**
+         * Which signing key is used for cookie-cache JWTs.
+         *
+         * - `"secret"`: uses the Better Auth secret with HS256.
+         * - `"jwt-plugin"`: uses the installed `jwt()` plugin's asymmetric signing keys.
+         *
+         * @default "secret"
+         */
+        signingKey?: "secret" | "jwt-plugin";
+      };
       /**
        * Controls stateless cookie cache refresh behavior.
        *
@@ -6445,9 +6978,13 @@ type BetterAuthOptions = {
      */
     storeStateStrategy?: "database" | "cookie";
     /**
-     * Store account data after oauth flow on a cookie
+     * Store provider account data after an OAuth flow in an encrypted
+     * cookie. This includes OAuth token material such as access tokens,
+     * refresh tokens, ID tokens, scopes, and token expiry.
      *
-     * This is useful for database-less flow
+     * This is useful for database-less flows, but large provider tokens can
+     * still hit browser or proxy cookie/header limits even though Better Auth
+     * chunks oversized account cookies.
      *
      * @default false
      *
@@ -6952,16 +7489,21 @@ interface SecondaryStorage {
   get: (key: string) => Awaitable<unknown>;
   /**
    * Atomically get a value and delete it from storage.
+   */
+  getAndDelete: (key: string) => Awaitable<unknown>;
+  /**
+   * Atomically increment the counter at `key` by one, returning the
+   * post-increment value.
    *
-   * This is optional for backwards compatibility with existing secondary
-   * storage implementations. Single-use credential consumers use it when
-   * present to avoid a read-then-delete race.
+   * When the key is absent, it is created with a value of `1` and the given
+   * `ttl` (in SECONDS). The TTL is applied only on creation; later increments
+   * never extend it, so the counter expires a fixed window after it was first
+   * created.
    *
-   * TODO(secondary-storage-atomic-consume): make this required in the next
-   * breaking release, or require database-backed verification storage for
-   * security-sensitive consume paths.
+   * Required so secondary-storage-backed rate limiting can enforce the limit
+   * in one distributed-safe operation.
    */
-  getAndDelete?: (key: string) => Awaitable<unknown>;
+  increment: (key: string, ttl: number) => Awaitable<number>;
   set: (
   /**
    * Key to store