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

package/src/types/context.ts

@@ -10,12 +10,13 @@ import type {
 } from "../db";
 import type { DBAdapter, Where } from "../db/adapter";
 import type { createLogger } from "../env";
-import type { OAuthProvider } from "../oauth2";
+import type { UpstreamProvider } from "../oauth2";
 import type { BetterAuthCookie, BetterAuthCookies } from "./cookie";
 import type { Awaitable, LiteralString } from "./helper";
 import type {
 	BetterAuthOptions,
 	BetterAuthRateLimitOptions,
+	UserProvisioningSource,
 } from "./init-options";
 import type { BetterAuthPlugin } from "./plugin";
 import type { SecretConfig } from "./secret";
@@ -87,16 +88,15 @@ export type GenericEndpointContext<
 export interface InternalAdapter<
 	_Options extends BetterAuthOptions = BetterAuthOptions,
 > {
-	createOAuthUser(
-		user: Omit<User, "id" | "createdAt" | "updatedAt">,
-		account: Omit<Account, "userId" | "id" | "createdAt" | "updatedAt"> &
-			Partial<Account>,
-	): Promise<{ user: User; account: Account }>;
-
 	createUser<T extends Record<string, any>>(
 		user: Omit<User, "id" | "createdAt" | "updatedAt" | "emailVerified"> &
 			Partial<User> &
 			Record<string, any>,
+		/**
+		 * Provisioning source. The creation seam adds `action: "create-user"` and
+		 * runs the `user.validateUserInfo` gate.
+		 */
+		source: UserProvisioningSource,
 	): Promise<T & User>;
 
 	createAccount<T extends Record<string, any>>(
@@ -237,6 +237,24 @@ export interface InternalAdapter<
 	 */
 	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>,
@@ -351,7 +369,7 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 					user: User & Record<string, any>;
 				} | null,
 			) => void;
-			socialProviders: OAuthProvider[];
+			socialProviders: UpstreamProvider[];
 			authCookies: BetterAuthCookies;
 			logger: ReturnType<typeof createLogger>;
 			rateLimit: {

package/src/types/index.ts

@@ -24,6 +24,13 @@ export type {
 	DynamicBaseURLConfig,
 	GenerateIdFn,
 	StoreIdentifierOption,
+	UserProvisioningSource,
+	ValidateUserInfoAction,
+	ValidateUserInfoMethod,
+	ValidateUserInfoOAuthInfo,
+	ValidateUserInfoResult,
+	ValidateUserInfoSource,
+	ValidateUserInfoSSOInfo,
 } from "./init-options";
 export type {
 	BetterAuthPlugin,

package/src/types/init-options.ts

@@ -14,7 +14,6 @@ import type {
 	Account,
 	DBFieldAttribute,
 	ModelNames,
-	RateLimit,
 	SecondaryStorage,
 	Session,
 	User,
@@ -47,6 +46,98 @@ export type GenerateIdFn = (options: {
 	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.
+ */
+export 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"`).
+ */
+export 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"`. */
+export 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. */
+export 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}. */
+export 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" };
+ * }
+ * ```
+ */
+export type ValidateUserInfoSource = UserProvisioningSource & {
+	action: ValidateUserInfoAction;
+};
+
+export 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).
@@ -95,12 +186,27 @@ export type DynamicBaseURLConfig = {
 export type BaseURLConfig = string | DynamicBaseURLConfig;
 
 export interface BetterAuthRateLimitStorage {
-	get: (key: string) => Promise<RateLimit | null | undefined>;
-	set: (
+	/**
+	 * 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,
-		value: RateLimit,
-		update?: boolean | undefined,
-	) => Promise<void>;
+		rule: { window: number; max: number },
+	) => Promise<{ allowed: boolean; retryAfter: number | null }>;
 }
 
 export type BetterAuthRateLimitRule = {
@@ -777,6 +883,33 @@ export type BetterAuthOptions = {
 	 */
 	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
 				 */
@@ -926,6 +1059,20 @@ export 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.
 					 *
@@ -1134,9 +1281,13 @@ export 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
 				 *

package/src/types/plugin-client.ts

@@ -6,7 +6,21 @@ import type {
 import type { Atom, WritableAtom } from "nanostores";
 import type { LiteralString } from "./helper";
 import type { BetterAuthOptions } from "./init-options";
-import type { BetterAuthPlugin } from "./plugin";
+
+type InferableServerPlugin = {
+	id?: LiteralString | undefined;
+	endpoints?: Record<string, unknown> | undefined;
+	schema?: Record<string, { fields: Record<string, unknown> }> | undefined;
+	$ERROR_CODES?:
+		| Record<
+				string,
+				{
+					readonly code: string;
+					message: string;
+				}
+		  >
+		| undefined;
+};
 
 export interface ClientStore {
 	notify: (signal: string) => void;
@@ -84,7 +98,7 @@ export interface BetterAuthClientPlugin {
 	 * only used for type inference. don't pass the
 	 * actual plugin
 	 */
-	$InferServerPlugin?: BetterAuthPlugin | undefined;
+	$InferServerPlugin?: InferableServerPlugin | undefined;
 	/**
 	 * Custom actions
 	 */

package/src/utils/host.ts

@@ -235,6 +235,10 @@ function classifyIPv6(expanded: string): HostKind {
 
 	if (expanded.startsWith("2001:0db8:")) return "documentation";
 
+	// 2001:2::/48 — Benchmarking (RFC 5180). A specific non-globally-reachable
+	// block inside the otherwise-mixed 2001::/23 protocol-assignments space.
+	if (expanded.startsWith("2001:0002:0000:")) return "benchmarking";
+
 	if (expanded.startsWith("2002:")) {
 		const embedded = extractEmbeddedIPv4(expanded, 1);
 		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
@@ -247,6 +251,10 @@ function classifyIPv6(expanded: string): HostKind {
 		return "reserved";
 	}
 
+	// 64:ff9b:1::/48 — Local-Use IPv4/IPv6 Translation (RFC 8215). Distinct from
+	// the well-known NAT64 /96 prefix above and not globally reachable.
+	if (expanded.startsWith("0064:ff9b:0001:")) return "reserved";
+
 	if (expanded.startsWith("2001:0000:")) {
 		const embedded = extractEmbeddedIPv4(expanded, 6, { xor: true });
 		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
@@ -255,6 +263,13 @@ function classifyIPv6(expanded: string): HostKind {
 
 	if (expanded.startsWith("0100:0000:0000:0000:")) return "reserved";
 
+	// 3fff::/20 — Documentation (RFC 9637). The /20 fixes the first 16 bits to
+	// `3fff` and the next nibble to 0, so only `3fff:0xxx` is in range.
+	if (expanded.startsWith("3fff:0")) return "documentation";
+
+	// 5f00::/16 — SRv6 SIDs (RFC 9602), not globally reachable.
+	if (expanded.startsWith("5f00:")) return "reserved";
+
 	return "public";
 }
 

package/src/utils/url.ts

@@ -25,18 +25,24 @@ export function normalizePathname(
 		return "/";
 	}
 
-	if (basePath === "/" || basePath === "") {
+	// Canonicalize the basePath the same way as the request pathname. A baseURL
+	// with a trailing slash yields a basePath like "/api/auth/"; without this it
+	// would never match the slash-stripped pathname and the prefix would leak
+	// through to disabledPaths and rate-limit special-rule matching.
+	const normalizedBasePath = basePath.replace(/\/+$/, "");
+
+	if (normalizedBasePath === "") {
 		return pathname;
 	}
 
 	// Check for exact match or proper path boundary (basePath followed by "/" or end)
 	// This prevents "/api/auth" from matching "/api/authevil/..."
-	if (pathname === basePath) {
+	if (pathname === normalizedBasePath) {
 		return "/";
 	}
 
-	if (pathname.startsWith(basePath + "/")) {
-		return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
+	if (pathname.startsWith(normalizedBasePath + "/")) {
+		return pathname.slice(normalizedBasePath.length).replace(/\/+$/, "") || "/";
 	}
 
 	return pathname;