@better-auth/core 1.7.0-beta.0 → 1.7.0-beta.10

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

@@ -0,0 +1,20 @@
+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:`).
+ * - Rejects URIs with a fragment component (`#...`) per RFC 6749 §3.1.2.
+ * - 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,48 @@
+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:`).
+* - Rejects URIs with a fragment component (`#...`) per RFC 6749 §3.1.2.
+* - 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) => {
+	let u;
+	try {
+		u = new URL(val);
+	} catch {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL must be parseable",
+			fatal: true
+		});
+		return z.NEVER;
+	}
+	if (DANGEROUS_URL_SCHEMES.includes(u.protocol)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL cannot use javascript:, data:, or vbscript: scheme"
+		});
+		return;
+	}
+	if (val.includes("#")) ctx.addIssue({
+		code: "custom",
+		message: "Redirect URI must not contain a fragment component"
+	});
+	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

@@ -22,10 +22,40 @@ function normalizePathname(requestUrl, basePath) {
 	} catch {
 		return "/";
 	}
-	if (basePath === "/" || basePath === "") return pathname;
-	if (pathname === basePath) return "/";
-	if (pathname.startsWith(basePath + "/")) return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
+	const normalizedBasePath = basePath.replace(/\/+$/, "");
+	if (normalizedBasePath === "") return pathname;
+	if (pathname === normalizedBasePath) return "/";
+	if (pathname.startsWith(normalizedBasePath + "/")) return pathname.slice(normalizedBasePath.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) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return true;
+	}
+	return !DANGEROUS_URL_SCHEMES.includes(parsed.protocol);
+}
 //#endregion
-export { normalizePathname };
+export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-beta.0",
+  "version": "1.7.0-beta.10",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -93,6 +93,13 @@
     "./instrumentation": {
       "dev-source": "./src/instrumentation/index.ts",
       "types": "./dist/instrumentation/index.d.mts",
+      "workerd": "./dist/instrumentation/pure.index.mjs",
+      "edge": "./dist/instrumentation/pure.index.mjs",
+      "browser": "./dist/instrumentation/pure.index.mjs",
+      "node": "./dist/instrumentation/index.mjs",
+      "deno": "./dist/instrumentation/index.mjs",
+      "bun": "./dist/instrumentation/index.mjs",
+      "import": "./dist/instrumentation/index.mjs",
       "default": "./dist/instrumentation/index.mjs"
     }
   },
@@ -140,36 +147,39 @@
     }
   },
   "dependencies": {
-    "@opentelemetry/semantic-conventions": "^1.39.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
     "@standard-schema/spec": "^1.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.4.0",
-    "@better-fetch/fetch": "1.1.21",
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^1.30.0",
-    "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "better-call": "1.3.5",
+    "@better-auth/utils": "0.4.2",
+    "@better-fetch/fetch": "1.3.1",
     "@cloudflare/workers-types": "^4.20250121.0",
-    "jose": "^6.1.3",
-    "kysely": "^0.28.14",
-    "nanostores": "^1.1.1",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "better-call": "1.3.7",
+    "jose": "^6.2.3",
+    "kysely": "^0.28.17 || ^0.29.0",
+    "nanostores": "^1.3.0",
     "tsdown": "0.21.1"
   },
   "peerDependencies": {
-    "@better-auth/utils": "0.4.0",
-    "@better-fetch/fetch": "1.1.21",
-    "@opentelemetry/api": "^1.9.0",
-    "better-call": "1.3.5",
+    "@better-auth/utils": "0.4.2",
+    "@better-fetch/fetch": "1.3.1",
     "@cloudflare/workers-types": ">=4",
+    "@opentelemetry/api": "^1.9.0",
+    "better-call": "1.3.7",
     "jose": "^6.1.0",
-    "kysely": "^0.28.5",
+    "kysely": "^0.28.5 || ^0.29.0",
     "nanostores": "^1.0.1"
   },
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {
       "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
     }
   },
   "scripts": {

package/src/api/index.ts

@@ -3,9 +3,53 @@ import type {
 	EndpointOptions,
 	StrictEndpoint,
 } from "better-call";
-import { createEndpoint, createMiddleware } from "better-call";
+import {
+	createEndpoint,
+	createMiddleware,
+	kAPIErrorHeaderSymbol,
+} from "better-call";
 import { runWithEndpointContext } from "../context";
 import type { AuthContext } from "../types";
+import { isAPIError } from "../utils/is-api-error";
+
+/**
+ * Response headers that forbid any intermediary (proxy, CDN, browser) from
+ * caching a response body. Credential-bearing responses (access/refresh tokens,
+ * ID tokens, client secrets, device codes) must carry them.
+ *
+ * Set `metadata: { noStore: true }` on an endpoint and {@link createAuthEndpoint}
+ * applies these to the responses its handler produces: the success body and any
+ * error the handler throws. A request rejected by schema or media-type
+ * validation before the handler runs is not covered, and carries no credentials
+ * to protect. Spread them into a hand-built `Response` or `APIError`'s headers
+ * for the rare endpoint that constructs its own response.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+ */
+export const NO_STORE_HEADERS = {
+	"Cache-Control": "no-store",
+	Pragma: "no-cache",
+} as const;
+
+/**
+ * Better-call's createEndpoint re-throws APIError without exposing the headers
+ * accumulated on ctx.responseHeaders (e.g. Set-Cookie from deleteSessionCookie
+ * before throw). Attach them to the error via kAPIErrorHeaderSymbol — matching
+ * better-call's createMiddleware contract so the outer pipeline can merge them
+ * into the response.
+ */
+function attachResponseHeadersToAPIError(
+	responseHeaders: Headers | undefined,
+	e: unknown,
+): void {
+	if (!isAPIError(e) || !responseHeaders) return;
+	Object.defineProperty(e, kAPIErrorHeaderSymbol, {
+		enumerable: false,
+		configurable: true,
+		value: responseHeaders,
+		writable: false,
+	});
+}
 
 export const optionsMiddleware = createMiddleware(async () => {
 	/**
@@ -76,6 +120,32 @@ export function createAuthEndpoint<
 	const handler: EndpointHandler<Path, Opts, R> =
 		typeof handlerOrOptions === "function" ? handlerOrOptions : handlerOrNever;
 
+	// Endpoints that return credentials declare `metadata: { noStore: true }`.
+	// Emit the no-store headers at the boundary, before the handler runs, so they
+	// land on every response the handler produces: a success harvests
+	// `responseHeaders`, and a thrown error carries the same headers through
+	// `attachResponseHeadersToAPIError`. Validation that rejects the request
+	// before the handler runs is not covered (and returns no credentials).
+	const noStore =
+		(options as { metadata?: { noStore?: boolean } }).metadata?.noStore ===
+		true;
+
+	// todo: prettify the code, we want to call `runWithEndpointContext` to top level
+	const wrapped: EndpointHandler<Path, Opts, R> = async (ctx) => {
+		if (noStore) {
+			for (const [name, value] of Object.entries(NO_STORE_HEADERS)) {
+				ctx.setHeader(name, value);
+			}
+		}
+		const runtimeCtx = ctx as unknown as { responseHeaders?: Headers };
+		try {
+			return await runWithEndpointContext(ctx as any, () => handler(ctx));
+		} catch (e) {
+			attachResponseHeadersToAPIError(runtimeCtx.responseHeaders, e);
+			throw e;
+		}
+	};
+
 	if (path) {
 		return createEndpoint(
 			path,
@@ -83,8 +153,7 @@ export function createAuthEndpoint<
 				...options,
 				use: [...(options?.use || []), ...use],
 			},
-			// todo: prettify the code, we want to call `runWithEndpointContext` to top level
-			async (ctx) => runWithEndpointContext(ctx as any, () => handler(ctx)),
+			wrapped,
 		);
 	}
 
@@ -93,11 +162,58 @@ export function createAuthEndpoint<
 			...options,
 			use: [...(options?.use || []), ...use],
 		},
-		// todo: prettify the code, we want to call `runWithEndpointContext` to top level
-		async (ctx) => runWithEndpointContext(ctx as any, () => handler(ctx)),
+		wrapped,
 	);
 }
 
+/**
+ * Set `metadata.SERVER_ONLY` while preserving any existing metadata
+ * (`$Infer`, `openapi`, ...).
+ */
+function withServerOnly<Options extends EndpointOptions>(
+	options: Options,
+): Options {
+	return {
+		...options,
+		metadata: { ...options.metadata, SERVER_ONLY: true },
+	} as Options;
+}
+
+export namespace createAuthEndpoint {
+	/**
+	 * Declare a **server-only** endpoint.
+	 *
+	 * The endpoint is callable through `auth.api.*` from trusted server code but is
+	 * never registered on the HTTP router and never emitted into the OpenAPI
+	 * schema. It takes no path because it has no URL to be reached at.
+	 *
+	 * Prefer this over the path-less `createAuthEndpoint({ ... }, handler)` form.
+	 * Setting `metadata.SERVER_ONLY` makes the intent explicit at the call site and
+	 * keeps the endpoint off the HTTP surface even if a path is later added by
+	 * mistake: better-call's router skips an endpoint when its path is missing *or*
+	 * when `SERVER_ONLY` is set, so the two together are defense in depth. Relying
+	 * on path omission alone is invisible and one keystroke away from exposure.
+	 *
+	 * @example
+	 * ```ts
+	 * viewBackupCodes: createAuthEndpoint.serverOnly(
+	 * 	{ method: "POST", body: schema },
+	 * 	async (ctx) => { ... },
+	 * )
+	 * ```
+	 */
+	export function serverOnly<
+		Path extends string,
+		Options extends EndpointOptions,
+		R,
+	>(
+		options: Options,
+		handler: EndpointHandler<Path, Options, R>,
+	): StrictEndpoint<Path, Options, R> {
+		return createAuthEndpoint(withServerOnly(options), handler);
+	}
+}
+
 export type AuthEndpoint<
 	Path extends string,
 	Opts extends EndpointOptions,

package/src/context/transaction.ts

@@ -1,11 +1,15 @@
 import type { AsyncLocalStorage } from "node:async_hooks";
 import { getAsyncLocalStorage } from "@better-auth/core/async_hooks";
 import type { DBAdapter, DBTransactionAdapter } from "../db/adapter";
+import type { BetterAuthOptions } from "../types";
 import { __getBetterAuthGlobal } from "./global";
 
+type StoredAdapter = DBTransactionAdapter<BetterAuthOptions>;
+
 type HookContext = {
-	adapter: DBTransactionAdapter;
+	adapter: StoredAdapter;
 	pendingHooks: Array<() => Promise<void>>;
+	isTransactionActive: boolean;
 };
 
 const ensureAsyncStorage = async () => {
@@ -27,21 +31,29 @@ export const getCurrentDBAdapterAsyncLocalStorage = async () => {
 	return ensureAsyncStorage();
 };
 
-export const getCurrentAdapter = async (
-	fallback: DBTransactionAdapter,
-): Promise<DBTransactionAdapter> => {
+export const getCurrentAdapter = async <
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	fallback: DBTransactionAdapter<Options>,
+): Promise<DBTransactionAdapter<Options>> => {
 	return ensureAsyncStorage()
 		.then((als) => {
 			const store = als.getStore();
-			return store?.adapter || fallback;
+			return (
+				(store?.adapter as DBTransactionAdapter<Options> | undefined) ||
+				fallback
+			);
 		})
 		.catch(() => {
 			return fallback;
 		});
 };
 
-export const runWithAdapter = async <R>(
-	adapter: DBAdapter,
+export const runWithAdapter = async <
+	R,
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	adapter: DBAdapter<Options>,
 	fn: () => R,
 ): Promise<R> => {
 	let called = false;
@@ -53,7 +65,14 @@ export const runWithAdapter = async <R>(
 			let error: unknown;
 			let hasError = false;
 			try {
-				result = await als.run({ adapter, pendingHooks }, fn);
+				result = await als.run(
+					{
+						adapter: adapter as unknown as StoredAdapter,
+						pendingHooks,
+						isTransactionActive: false,
+					},
+					fn,
+				);
 			} catch (err) {
 				error = err;
 				hasError = true;
@@ -75,21 +94,35 @@ export const runWithAdapter = async <R>(
 		});
 };
 
-export const runWithTransaction = async <R>(
-	adapter: DBAdapter,
+export const runWithTransaction = async <
+	R,
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	adapter: DBAdapter<Options>,
 	fn: () => R,
 ): Promise<R> => {
-	let called = true;
+	let called = false;
 	return ensureAsyncStorage()
 		.then(async (als) => {
 			called = true;
+			const store = als.getStore();
+			if (store?.isTransactionActive) {
+				return fn();
+			}
 			const pendingHooks: Array<() => Promise<void>> = [];
 			let result: Awaited<R>;
 			let error: unknown;
 			let hasError = false;
 			try {
 				result = await adapter.transaction(async (trx) => {
-					return als.run({ adapter: trx, pendingHooks }, fn);
+					return als.run(
+						{
+							adapter: trx as unknown as StoredAdapter,
+							pendingHooks,
+							isTransactionActive: true,
+						},
+						fn,
+					);
 				});
 			} catch (e) {
 				hasError = true;