@better-auth/core 1.6.11 → 1.6.13

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.6.11";
+const __betterAuthVersion = "1.6.13";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/adapter/factory.mjs

@@ -711,7 +711,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 						limit: 1
 					}))[0];
 					if (!target) return null;
-					return await trx.deleteMany({
+					const deleted = await trx.deleteMany({
 						model: unsafeModel,
 						where: [...unsafeWhere, {
 							field: "id",
@@ -720,7 +720,9 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 							connector: "AND",
 							mode: "sensitive"
 						}]
-					}) > 0 ? target : null;
+					});
+					if (typeof deleted !== "number") throw new BetterAuthError(`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`);
+					return deleted > 0 ? target : null;
 				}));
 				resultNeedsOutputTransform = false;
 			}

package/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.6.11";
+const INSTRUMENTATION_VERSION = "1.6.13";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/oauth2/index.d.mts

@@ -2,7 +2,7 @@ import { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions } from "./
 import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
 import { createAuthorizationURL } from "./create-authorization-url.mjs";
 import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
-import { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
 import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, type ProviderOptions, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, type ProviderOptions, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/index.mjs

@@ -1,7 +1,7 @@
 import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
-import { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
 import { createAuthorizationURL } from "./create-authorization-url.mjs";
 import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
 import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/utils.d.mts

@@ -2,6 +2,14 @@ import { OAuth2Tokens } from "./oauth-provider.mjs";
 
 //#region src/oauth2/utils.d.ts
 declare function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens;
+/**
+ * Fill in `accessTokenExpiresAt` from the provider's configured
+ * `accessTokenExpiresIn` when the token response omitted `expires_in`. Without a
+ * known expiry, `getAccessToken` cannot tell the token is expired and never
+ * refreshes it. No-op when the provider already supplied an expiry or no
+ * fallback is configured.
+ */
+declare function applyDefaultAccessTokenExpiry(tokens: OAuth2Tokens, accessTokenExpiresIn: number | undefined): OAuth2Tokens;
 /**
  * Return the provider's primary Client ID: the single string, or the entry at
  * array index 0 for the cross-platform form used by ID token audience
@@ -13,4 +21,4 @@ declare function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens;
 declare function getPrimaryClientId(clientId: unknown): string | undefined;
 declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
 //#endregion
-export { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };

package/dist/oauth2/utils.mjs

@@ -17,6 +17,17 @@ function getOAuth2Tokens(data) {
 	};
 }
 /**
+* Fill in `accessTokenExpiresAt` from the provider's configured
+* `accessTokenExpiresIn` when the token response omitted `expires_in`. Without a
+* known expiry, `getAccessToken` cannot tell the token is expired and never
+* refreshes it. No-op when the provider already supplied an expiry or no
+* fallback is configured.
+*/
+function applyDefaultAccessTokenExpiry(tokens, accessTokenExpiresIn) {
+	if (!tokens.accessTokenExpiresAt && accessTokenExpiresIn) tokens.accessTokenExpiresAt = new Date(Date.now() + accessTokenExpiresIn * 1e3);
+	return tokens;
+}
+/**
 * Return the provider's primary Client ID: the single string, or the entry at
 * array index 0 for the cross-platform form used by ID token audience
 * verification. Index 0 is the designated primary and pairs with
@@ -34,4 +45,4 @@ async function generateCodeChallenge(codeVerifier) {
 	return base64Url.encode(new Uint8Array(hash), { padding: false });
 }
 //#endregion
-export { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };

package/dist/oauth2/verify.mjs

@@ -1,8 +1,16 @@
 import { logger } from "../env/logger.mjs";
 import { APIError } from "better-call";
 import { betterFetch } from "@better-fetch/fetch";
-import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
+import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 //#region src/oauth2/verify.ts
+const joseInfrastructureErrorCodes = new Set([
+	errors.JWKSTimeout.code,
+	errors.JWKSInvalid.code,
+	errors.JWKSMultipleMatchingKeys.code
+]);
+function isJoseInfrastructureError(error) {
+	return joseInfrastructureErrorCodes.has(error.code);
+}
 /** Last fetched jwks used locally in getJwks @internal */
 let jwks;
 /**
@@ -28,7 +36,7 @@ async function getJwks(token, opts) {
 		if (error instanceof Error) throw error;
 		throw new Error(error);
 	}
-	if (!jwtHeaders.kid) throw new Error("Missing jwt kid");
+	if (!jwtHeaders.kid) throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
 	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
 		jwks = typeof opts.jwksFetch === "string" ? await betterFetch(opts.jwksFetch, { headers: { Accept: "application/json" } }).then(async (res) => {
 			if (res.error) throw new Error(`Jwks failed: ${res.error.message ?? res.error.statusText}`);
@@ -51,9 +59,11 @@ async function verifyAccessToken(token, opts) {
 			verifyOptions: opts.verifyOptions
 		});
 	} catch (error) {
-		if (error instanceof Error) if (error.name === "TypeError" || error.name === "JWSInvalid") {} else if (error.name === "JWTExpired") throw new APIError("UNAUTHORIZED", { message: "token expired" });
-		else if (error.name === "JWTInvalid") throw new APIError("UNAUTHORIZED", { message: "token invalid" });
-		else throw error;
+		if (error instanceof Error) if (error.name === "TypeError" || error.name === "JWSInvalid") {} else if (error instanceof errors.JWTExpired) throw new APIError("UNAUTHORIZED", { message: "token expired" });
+		else if (error instanceof errors.JOSEError) {
+			if (isJoseInfrastructureError(error)) throw error;
+			throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
+		} else throw error;
 		else throw new Error(error);
 	}
 	if (opts?.remoteVerify) {

package/dist/social-providers/apple.mjs

@@ -7,6 +7,16 @@ import { validateAuthorizationCode } from "../oauth2/validate-authorization-code
 import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 //#region src/social-providers/apple.ts
+async function sha256Hex(value) {
+	const data = new TextEncoder().encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function nonceMatches(jwtNonce, nonce) {
+	if (typeof jwtNonce !== "string") return false;
+	if (jwtNonce === nonce) return true;
+	return jwtNonce === await sha256Hex(nonce);
+}
 const apple = (options) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";
 	return {
@@ -55,7 +65,7 @@ const apple = (options) => {
 				["email_verified", "is_private_email"].forEach((field) => {
 					if (jwtClaims[field] !== void 0) jwtClaims[field] = Boolean(jwtClaims[field]);
 				});
-				if (nonce && jwtClaims.nonce !== nonce) return false;
+				if (nonce && !await nonceMatches(jwtClaims.nonce, nonce)) return false;
 				return !!jwtClaims;
 			} catch {
 				return false;

package/dist/types/context.d.mts

@@ -89,7 +89,14 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
    * @param id - The account row's primary key (the `id` column, not the `accountId` column).
    */
   deleteAccount(id: string): Promise<void>;
-  deleteSessions(userIdOrSessionTokens: string | string[]): Promise<void>;
+  /**
+   * Delete every session belonging to a user.
+   */
+  deleteUserSessions(userId: string): Promise<void>;
+  /**
+   * Delete sessions by their session tokens.
+   */
+  deleteSessions(sessionTokens: string[]): Promise<void>;
   findOAuthUser(email: string, accountId: string, providerId: string): Promise<{
     user: User;
     linkedAccount: Account | null;
@@ -107,7 +114,6 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
   updateUserByEmail<T extends Record<string, any>>(email: string, data: Partial<User & Record<string, any>>): Promise<User & T>;
   updatePassword(userId: string, password: string): Promise<void>;
   findAccounts(userId: string): Promise<Account[]>;
-  findAccount(accountId: string): Promise<Account | null>;
   findAccountByProviderId(accountId: string, providerId: string): Promise<Account | null>;
   findAccountByUserId(userId: string): Promise<Account[]>;
   updateAccount(id: string, data: Partial<Account>): Promise<Account>;
@@ -118,9 +124,11 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
    * Atomically consume a single-use verification row by `identifier` and
    * return it. Only the first concurrent caller receives the latest row;
    * subsequent callers receive `null`. Consuming one row invalidates the
-   * whole identifier so stale rows cannot be replayed. Callers MUST gate any
-   * state change (issue session, mint token, change password) on a non-null
-   * result.
+   * whole identifier so stale rows cannot be replayed. Rows past their
+   * `expiresAt` are treated as already invalid: the row is deleted but
+   * `null` is returned, so callers do not need to gate on `expiresAt`
+   * themselves. Callers MUST gate any state change (issue session, mint
+   * token, change password) on a non-null result.
    *
    * Replaces the racy `findVerificationValue` + `deleteVerificationByIdentifier`
    * pair at single-use credential consumption sites.
@@ -183,7 +191,7 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
      * - "cookie": Store state in an encrypted cookie (stateless)
      * - "database": Store state in the database
      *
-     * @default "cookie"
+     * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
      */
     storeStateStrategy: "database" | "cookie";
   };

package/dist/types/init-options.d.mts

@@ -963,7 +963,11 @@ type BetterAuthOptions = {
        */
       allowUnlinkingAll?: boolean;
       /**
-       * If enabled (true), this will update the user information based on the newly linked account
+       * When enabled, linking an account copies the provider's profile onto
+       * the local user, matching the fields persisted on sign-up (`name`,
+       * `image`, and any `mapProfileToUser` fields). The local `email` and
+       * `emailVerified` are never changed, so a link cannot rebind the
+       * account's identity.
        *
        * @default false
        */
@@ -996,7 +1000,7 @@ type BetterAuthOptions = {
      * - "cookie": Store state in an encrypted cookie (stateless)
      * - "database": Store state in the database
      *
-     * @default "cookie"
+     * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
      */
     storeStateStrategy?: "database" | "cookie";
     /**

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

@@ -0,0 +1,19 @@
+import * as z from "zod";
+
+//#region src/utils/redirect-uri.d.ts
+/**
+ * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+ * server stores and later hands back to a browser.
+ *
+ * - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+ * - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+ *   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+ * - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+ *
+ * This is the single source of truth for redirect-URI validation across the
+ * OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+ * rather than re-implementing the scheme policy per plugin.
+ */
+declare const SafeUrlSchema: z.ZodURL;
+//#endregion
+export { SafeUrlSchema };

package/dist/utils/redirect-uri.mjs

@@ -0,0 +1,41 @@
+import { isLoopbackHost } from "./host.mjs";
+import { DANGEROUS_URL_SCHEMES } from "./url.mjs";
+import * as z from "zod";
+//#region src/utils/redirect-uri.ts
+/**
+* Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+* server stores and later hands back to a browser.
+*
+* - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+* - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+*   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+* - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+*
+* This is the single source of truth for redirect-URI validation across the
+* OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+* rather than re-implementing the scheme policy per plugin.
+*/
+const SafeUrlSchema = z.url().superRefine((val, ctx) => {
+	if (!URL.canParse(val)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL must be parseable",
+			fatal: true
+		});
+		return z.NEVER;
+	}
+	const u = new URL(val);
+	if (DANGEROUS_URL_SCHEMES.includes(u.protocol)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL cannot use javascript:, data:, or vbscript: scheme"
+		});
+		return;
+	}
+	if (u.protocol === "http:" && !isLoopbackHost(u.host)) ctx.addIssue({
+		code: "custom",
+		message: "Redirect URI must use HTTPS (HTTP allowed only for loopback hosts)"
+	});
+});
+//#endregion
+export { SafeUrlSchema };

package/dist/utils/string.d.mts

@@ -1,4 +1,8 @@
 //#region src/utils/string.d.ts
 declare function capitalizeFirstLetter(str: string): string;
+declare function toSnakeCase(input: string): string;
+declare function toKebabCase(input: string): string;
+declare function toCamelCase(input: string): string;
+declare function toPascalCase(input: string): string;
 //#endregion
-export { capitalizeFirstLetter };
+export { capitalizeFirstLetter, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/utils/string.mjs

@@ -2,5 +2,24 @@
 function capitalizeFirstLetter(str) {
 	return str.charAt(0).toUpperCase() + str.slice(1);
 }
+const WORD_PATTERN = /[\p{Ll}\d]+|\p{Lu}+(?!\p{Ll})|\p{Lu}[\p{Ll}\d]+|\p{Lo}+/gu;
+const APOSTROPHE_PATTERN = /['\u2019]/g;
+function splitWords(input) {
+	return input.replace(APOSTROPHE_PATTERN, "").match(WORD_PATTERN) ?? [];
+}
+function toSnakeCase(input) {
+	return splitWords(input).map((word) => word.toLowerCase()).join("_");
+}
+function toKebabCase(input) {
+	return splitWords(input).map((word) => word.toLowerCase()).join("-");
+}
+function toCamelCase(input) {
+	return splitWords(input).reduce((acc, word, i) => {
+		return acc + (i === 0 ? word.toLowerCase() : `${word[0].toUpperCase()}${word.slice(1)}`);
+	}, "");
+}
+function toPascalCase(input) {
+	return splitWords(input).map((word) => `${word[0].toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
+}
 //#endregion
-export { capitalizeFirstLetter };
+export { capitalizeFirstLetter, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/utils/url.d.mts

@@ -16,5 +16,22 @@
  * // Returns: "/sso/saml2/callback/provider1"
  */
 declare function normalizePathname(requestUrl: string, basePath: string): string;
+/**
+ * Schemes that execute or embed code when navigated to or accepted as a
+ * redirect target. These are never safe as an OAuth `redirect_uri` or as a
+ * client-side navigation target (`window.location.href`, `location.assign`, ...).
+ */
+declare const DANGEROUS_URL_SCHEMES: string[];
+/**
+ * Returns `false` only when `value` is an absolute URL using a dangerous scheme
+ * (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+ * safe absolute schemes (`http`, `https`, custom app schemes such as
+ * `myapp://`) return `true`.
+ *
+ * Use this to guard browser navigation sinks and any redirect target that may
+ * originate from untrusted input. It is intentionally narrow: it blocks code
+ * execution schemes without rejecting relative paths or mobile deep links.
+ */
+declare function isSafeUrlScheme(value: string): boolean;
 //#endregion
-export { normalizePathname };
+export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };

package/dist/utils/url.mjs

@@ -27,5 +27,29 @@ function normalizePathname(requestUrl, basePath) {
 	if (pathname.startsWith(basePath + "/")) return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
 	return pathname;
 }
+/**
+* Schemes that execute or embed code when navigated to or accepted as a
+* redirect target. These are never safe as an OAuth `redirect_uri` or as a
+* client-side navigation target (`window.location.href`, `location.assign`, ...).
+*/
+const DANGEROUS_URL_SCHEMES = [
+	"javascript:",
+	"data:",
+	"vbscript:"
+];
+/**
+* Returns `false` only when `value` is an absolute URL using a dangerous scheme
+* (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+* safe absolute schemes (`http`, `https`, custom app schemes such as
+* `myapp://`) return `true`.
+*
+* Use this to guard browser navigation sinks and any redirect target that may
+* originate from untrusted input. It is intentionally narrow: it blocks code
+* execution schemes without rejecting relative paths or mobile deep links.
+*/
+function isSafeUrlScheme(value) {
+	if (!URL.canParse(value)) return true;
+	return !DANGEROUS_URL_SCHEMES.includes(new URL(value).protocol);
+}
 //#endregion
-export { normalizePathname };
+export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.6.11",
+  "version": "1.6.13",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -152,7 +152,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.4.0",
+    "@better-auth/utils": "0.4.1",
     "@better-fetch/fetch": "1.1.21",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
@@ -160,18 +160,18 @@
     "better-call": "1.3.5",
     "@cloudflare/workers-types": "^4.20250121.0",
     "jose": "^6.1.3",
-    "kysely": "^0.28.17",
+    "kysely": "^0.28.17 || ^0.29.0",
     "nanostores": "^1.1.1",
     "tsdown": "0.21.1"
   },
   "peerDependencies": {
-    "@better-auth/utils": "0.4.0",
+    "@better-auth/utils": "0.4.1",
     "@better-fetch/fetch": "1.1.21",
     "@opentelemetry/api": "^1.9.0",
     "better-call": "1.3.5",
     "@cloudflare/workers-types": ">=4",
     "jose": "^6.1.0",
-    "kysely": "^0.28.5",
+    "kysely": "^0.28.5 || ^0.29.0",
     "nanostores": "^1.0.1"
   },
   "peerDependenciesMeta": {

package/src/db/adapter/factory.ts

@@ -1391,6 +1391,12 @@ export const createAdapterFactory =
 										},
 									],
 								});
+								// A non-numeric count coerces to a false miss, so fail loud.
+								if (typeof deleted !== "number") {
+									throw new BetterAuthError(
+										`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`,
+									);
+								}
 								return deleted > 0 ? (target as T) : null;
 							}),
 					);

package/src/oauth2/index.ts

@@ -16,6 +16,7 @@ export {
 	refreshAccessTokenRequest,
 } from "./refresh-access-token";
 export {
+	applyDefaultAccessTokenExpiry,
 	generateCodeChallenge,
 	getOAuth2Tokens,
 	getPrimaryClientId,

package/src/oauth2/utils.ts

@@ -28,6 +28,25 @@ export function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens {
 	};
 }
 
+/**
+ * Fill in `accessTokenExpiresAt` from the provider's configured
+ * `accessTokenExpiresIn` when the token response omitted `expires_in`. Without a
+ * known expiry, `getAccessToken` cannot tell the token is expired and never
+ * refreshes it. No-op when the provider already supplied an expiry or no
+ * fallback is configured.
+ */
+export function applyDefaultAccessTokenExpiry(
+	tokens: OAuth2Tokens,
+	accessTokenExpiresIn: number | undefined,
+): OAuth2Tokens {
+	if (!tokens.accessTokenExpiresAt && accessTokenExpiresIn) {
+		tokens.accessTokenExpiresAt = new Date(
+			Date.now() + accessTokenExpiresIn * 1000,
+		);
+	}
+	return tokens;
+}
+
 /**
  * Return the provider's primary Client ID: the single string, or the entry at
  * array index 0 for the cross-platform form used by ID token audience

package/src/oauth2/verify.ts

@@ -9,11 +9,22 @@ import type {
 import {
 	createLocalJWKSet,
 	decodeProtectedHeader,
+	errors as joseErrors,
 	jwtVerify,
 	UnsecuredJWT,
 } from "jose";
 import { logger } from "../env";
 
+const joseInfrastructureErrorCodes = new Set([
+	joseErrors.JWKSTimeout.code,
+	joseErrors.JWKSInvalid.code,
+	joseErrors.JWKSMultipleMatchingKeys.code,
+]);
+
+function isJoseInfrastructureError(error: joseErrors.JOSEError) {
+	return joseInfrastructureErrorCodes.has(error.code);
+}
+
 /** Last fetched jwks used locally in getJwks @internal */
 let jwks: JSONWebKeySet | undefined;
 
@@ -82,7 +93,9 @@ export async function getJwks(
 		throw new Error(error as unknown as string);
 	}
 
-	if (!jwtHeaders.kid) throw new Error("Missing jwt kid");
+	if (!jwtHeaders.kid) {
+		throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
+	}
 
 	// Fetch jwks if not set or has a different kid than the one stored
 	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
@@ -137,13 +150,16 @@ export async function verifyAccessToken(
 			if (error instanceof Error) {
 				if (error.name === "TypeError" || error.name === "JWSInvalid") {
 					// likely an opaque token (continue)
-				} else if (error.name === "JWTExpired") {
+				} else if (error instanceof joseErrors.JWTExpired) {
 					throw new APIError("UNAUTHORIZED", {
 						message: "token expired",
 					});
-				} else if (error.name === "JWTInvalid") {
+				} else if (error instanceof joseErrors.JOSEError) {
+					if (isJoseInfrastructureError(error)) {
+						throw error;
+					}
 					throw new APIError("UNAUTHORIZED", {
-						message: "token invalid",
+						message: "invalid access token",
 					});
 				} else {
 					throw error;

package/src/social-providers/apple.ts

@@ -77,6 +77,24 @@ export interface AppleOptions extends ProviderOptions<AppleProfile> {
 	audience?: (string | string[]) | undefined;
 }
 
+async function sha256Hex(value: string) {
+	const data = new TextEncoder().encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(digest))
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+async function nonceMatches(jwtNonce: unknown, nonce: string) {
+	if (typeof jwtNonce !== "string") {
+		return false;
+	}
+	if (jwtNonce === nonce) {
+		return true;
+	}
+	return jwtNonce === (await sha256Hex(nonce));
+}
+
 export const apple = (options: AppleOptions) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";
 	return {
@@ -141,7 +159,7 @@ export const apple = (options: AppleOptions) => {
 						jwtClaims[field] = Boolean(jwtClaims[field]);
 					}
 				});
-				if (nonce && jwtClaims.nonce !== nonce) {
+				if (nonce && !(await nonceMatches(jwtClaims.nonce, nonce))) {
 					return false;
 				}
 				return !!jwtClaims;

package/src/types/context.ts

@@ -158,7 +158,15 @@ export interface InternalAdapter<
 	 */
 	deleteAccount(id: string): Promise<void>;
 
-	deleteSessions(userIdOrSessionTokens: string | string[]): Promise<void>;
+	/**
+	 * Delete every session belonging to a user.
+	 */
+	deleteUserSessions(userId: string): Promise<void>;
+
+	/**
+	 * Delete sessions by their session tokens.
+	 */
+	deleteSessions(sessionTokens: string[]): Promise<void>;
 
 	findOAuthUser(
 		email: string,
@@ -196,8 +204,6 @@ export interface InternalAdapter<
 
 	findAccounts(userId: string): Promise<Account[]>;
 
-	findAccount(accountId: string): Promise<Account | null>;
-
 	findAccountByProviderId(
 		accountId: string,
 		providerId: string,
@@ -220,9 +226,11 @@ export interface InternalAdapter<
 	 * Atomically consume a single-use verification row by `identifier` and
 	 * return it. Only the first concurrent caller receives the latest row;
 	 * subsequent callers receive `null`. Consuming one row invalidates the
-	 * whole identifier so stale rows cannot be replayed. Callers MUST gate any
-	 * state change (issue session, mint token, change password) on a non-null
-	 * result.
+	 * whole identifier so stale rows cannot be replayed. Rows past their
+	 * `expiresAt` are treated as already invalid: the row is deleted but
+	 * `null` is returned, so callers do not need to gate on `expiresAt`
+	 * themselves. Callers MUST gate any state change (issue session, mint
+	 * token, change password) on a non-null result.
 	 *
 	 * Replaces the racy `findVerificationValue` + `deleteVerificationByIdentifier`
 	 * pair at single-use credential consumption sites.
@@ -319,7 +327,7 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 				 * - "cookie": Store state in an encrypted cookie (stateless)
 				 * - "database": Store state in the database
 				 *
-				 * @default "cookie"
+				 * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
 				 */
 				storeStateStrategy: "database" | "cookie";
 			};

package/src/types/init-options.ts

@@ -1093,7 +1093,11 @@ export type BetterAuthOptions = {
 					 */
 					allowUnlinkingAll?: boolean;
 					/**
-					 * If enabled (true), this will update the user information based on the newly linked account
+					 * When enabled, linking an account copies the provider's profile onto
+					 * the local user, matching the fields persisted on sign-up (`name`,
+					 * `image`, and any `mapProfileToUser` fields). The local `email` and
+					 * `emailVerified` are never changed, so a link cannot rebind the
+					 * account's identity.
 					 *
 					 * @default false
 					 */
@@ -1126,7 +1130,7 @@ export type BetterAuthOptions = {
 				 * - "cookie": Store state in an encrypted cookie (stateless)
 				 * - "database": Store state in the database
 				 *
-				 * @default "cookie"
+				 * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
 				 */
 				storeStateStrategy?: "database" | "cookie";
 				/**

package/src/utils/redirect-uri.ts

@@ -0,0 +1,45 @@
+import * as z from "zod";
+import { isLoopbackHost } from "./host";
+import { DANGEROUS_URL_SCHEMES } from "./url";
+
+/**
+ * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+ * server stores and later hands back to a browser.
+ *
+ * - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+ * - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+ *   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+ * - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+ *
+ * This is the single source of truth for redirect-URI validation across the
+ * OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+ * rather than re-implementing the scheme policy per plugin.
+ */
+export const SafeUrlSchema = z.url().superRefine((val, ctx) => {
+	if (!URL.canParse(val)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL must be parseable",
+			fatal: true,
+		});
+		return z.NEVER;
+	}
+
+	const u = new URL(val);
+
+	if (DANGEROUS_URL_SCHEMES.includes(u.protocol)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL cannot use javascript:, data:, or vbscript: scheme",
+		});
+		return;
+	}
+
+	if (u.protocol === "http:" && !isLoopbackHost(u.host)) {
+		ctx.addIssue({
+			code: "custom",
+			message:
+				"Redirect URI must use HTTPS (HTTP allowed only for loopback hosts)",
+		});
+	}
+});

package/src/utils/string.ts

@@ -1,3 +1,40 @@
 export function capitalizeFirstLetter(str: string) {
 	return str.charAt(0).toUpperCase() + str.slice(1);
 }
+
+const WORD_PATTERN =
+	/[\p{Ll}\d]+|\p{Lu}+(?!\p{Ll})|\p{Lu}[\p{Ll}\d]+|\p{Lo}+/gu;
+const APOSTROPHE_PATTERN = /['\u2019]/g;
+
+function splitWords(input: string): string[] {
+	return input.replace(APOSTROPHE_PATTERN, "").match(WORD_PATTERN) ?? [];
+}
+
+export function toSnakeCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("_");
+}
+
+export function toKebabCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("-");
+}
+
+export function toCamelCase(input: string): string {
+	return splitWords(input).reduce((acc, word, i) => {
+		return (
+			acc +
+			(i === 0
+				? word.toLowerCase()
+				: `${word[0]!.toUpperCase()}${word.slice(1)}`)
+		);
+	}, "");
+}
+
+export function toPascalCase(input: string): string {
+	return splitWords(input)
+		.map((word) => `${word[0]!.toUpperCase()}${word.slice(1).toLowerCase()}`)
+		.join("");
+}

package/src/utils/url.ts

@@ -41,3 +41,28 @@ export function normalizePathname(
 
 	return pathname;
 }
+
+/**
+ * Schemes that execute or embed code when navigated to or accepted as a
+ * redirect target. These are never safe as an OAuth `redirect_uri` or as a
+ * client-side navigation target (`window.location.href`, `location.assign`, ...).
+ */
+export const DANGEROUS_URL_SCHEMES = ["javascript:", "data:", "vbscript:"];
+
+/**
+ * Returns `false` only when `value` is an absolute URL using a dangerous scheme
+ * (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+ * safe absolute schemes (`http`, `https`, custom app schemes such as
+ * `myapp://`) return `true`.
+ *
+ * Use this to guard browser navigation sinks and any redirect target that may
+ * originate from untrusted input. It is intentionally narrow: it blocks code
+ * execution schemes without rejecting relative paths or mobile deep links.
+ */
+export function isSafeUrlScheme(value: string): boolean {
+	if (!URL.canParse(value)) {
+		// Relative URLs carry no scheme to abuse.
+		return true;
+	}
+	return !DANGEROUS_URL_SCHEMES.includes(new URL(value).protocol);
+}