@better-auth/core 1.7.0-beta.5 → 1.7.0-beta.7

package/dist/social-providers/naver.d.mts

@@ -37,6 +37,7 @@ declare const naver: (options: NaverOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -53,6 +54,7 @@ declare const naver: (options: NaverOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/notion.d.mts

@@ -30,6 +30,7 @@ declare const notion: (options: NotionOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -46,6 +47,7 @@ declare const notion: (options: NotionOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/paybin.d.mts

@@ -36,6 +36,7 @@ declare const paybin: (options: PaybinOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -53,6 +54,7 @@ declare const paybin: (options: PaybinOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/paypal.d.mts

@@ -64,6 +64,7 @@ declare const paypal: (options: PayPalOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -89,6 +90,7 @@ declare const paypal: (options: PayPalOptions) => {
     accessTokenExpiresAt: Date | undefined;
   }>);
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/polar.d.mts

@@ -39,6 +39,7 @@ declare const polar: (options: PolarOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -56,6 +57,7 @@ declare const polar: (options: PolarOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/railway.d.mts

@@ -30,6 +30,7 @@ declare const railway: (options: RailwayOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -47,6 +48,7 @@ declare const railway: (options: RailwayOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/reddit.d.mts

@@ -28,6 +28,7 @@ declare const reddit: (options: RedditOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -44,6 +45,7 @@ declare const reddit: (options: RedditOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/reddit.mjs

@@ -62,7 +62,7 @@ const reddit = (options) => {
 			} });
 			if (error) return null;
 			const userMap = await options.mapProfileToUser?.(profile);
-			const email = userMap?.email || `${profile.id}@reddit.com`;
+			const email = userMap?.email || `${profile.id}@reddit.invalid`;
 			return {
 				user: {
 					id: profile.id,

package/dist/social-providers/roblox.d.mts

@@ -36,6 +36,7 @@ declare const roblox: (options: RobloxOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -52,6 +53,7 @@ declare const roblox: (options: RobloxOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/salesforce.d.mts

@@ -44,6 +44,7 @@ declare const salesforce: (options: SalesforceOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -61,6 +62,7 @@ declare const salesforce: (options: SalesforceOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/slack.d.mts

@@ -49,6 +49,7 @@ declare const slack: (options: SlackOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -65,6 +66,7 @@ declare const slack: (options: SlackOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/spotify.d.mts

@@ -28,6 +28,7 @@ declare const spotify: (options: SpotifyOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -45,6 +46,7 @@ declare const spotify: (options: SpotifyOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/tiktok.d.mts

@@ -134,6 +134,7 @@ declare const tiktok: (options: TiktokOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): {
     url: URL;
@@ -150,6 +151,7 @@ declare const tiktok: (options: TiktokOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/twitch.d.mts

@@ -45,6 +45,7 @@ declare const twitch: (options: TwitchOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -61,6 +62,7 @@ declare const twitch: (options: TwitchOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/twitter.d.mts

@@ -90,6 +90,7 @@ declare const twitter: (options: TwitterOption) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -107,6 +108,7 @@ declare const twitter: (options: TwitterOption) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/vercel.d.mts

@@ -28,6 +28,7 @@ declare const vercel: (options: VercelOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -44,6 +45,7 @@ declare const vercel: (options: VercelOptions) => {
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/vk.d.mts

@@ -34,6 +34,7 @@ declare const vk: (options: VkOption) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): Promise<{
     url: URL;
@@ -52,6 +53,7 @@ declare const vk: (options: VkOption) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(data: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/wechat.d.mts

@@ -66,6 +66,7 @@ declare const wechat: (options: WeChatOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }): {
     url: URL;
@@ -95,6 +96,7 @@ declare const wechat: (options: WeChatOptions) => {
     scopes: string[];
   }>);
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/wechat.mjs

@@ -76,7 +76,7 @@ const wechat = (options) => {
 				user: {
 					id: profile.unionid || profile.openid || openid,
 					name: profile.nickname,
-					email: profile.email || null,
+					email: profile.email || `${profile.unionid || profile.openid || openid}@wechat.invalid`,
 					image: profile.headimgurl,
 					emailVerified: false,
 					...userMap

package/dist/social-providers/zoom.d.mts

@@ -130,6 +130,7 @@ declare const zoom: (userOptions: ZoomOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
     additionalParams?: Record<string, string> | undefined;
   }) => Promise<{
     url: URL;
@@ -147,6 +148,7 @@ declare const zoom: (userOptions: ZoomOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/types/context.d.mts

@@ -136,6 +136,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>;
 }

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

@@ -1,6 +1,6 @@
 import { DBFieldAttribute, ModelNames, SecondaryStorage } from "../db/type.mjs";
 import { DBAdapterDebugLogOption, DBAdapterInstance } from "../db/adapter/index.mjs";
-import { BaseRateLimit, RateLimit } from "../db/schema/rate-limit.mjs";
+import { BaseRateLimit } from "../db/schema/rate-limit.mjs";
 import { BaseSession, Session } from "../db/schema/session.mjs";
 import { BaseUser, User } from "../db/schema/user.mjs";
 import { BaseVerification, Verification } from "../db/schema/verification.mjs";
@@ -138,8 +138,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 = {
   /**
@@ -916,6 +938,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.
        *
@@ -1095,9 +1131,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
      *

package/dist/types/plugin-client.d.mts

@@ -1,10 +1,20 @@
 import { LiteralString } from "./helper.mjs";
-import { BetterAuthPlugin } from "./plugin.mjs";
 import { BetterAuthOptions } from "./init-options.mjs";
 import { BetterFetch, BetterFetchOption, BetterFetchPlugin } from "@better-fetch/fetch";
 import { Atom, WritableAtom } from "nanostores";
 
 //#region src/types/plugin-client.d.ts
+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;
+};
 interface ClientStore {
   notify: (signal: string) => void;
   listen: (signal: string, listener: () => void) => void;
@@ -71,7 +81,7 @@ interface BetterAuthClientPlugin {
    * only used for type inference. don't pass the
    * actual plugin
    */
-  $InferServerPlugin?: BetterAuthPlugin | undefined;
+  $InferServerPlugin?: InferableServerPlugin | undefined;
   /**
    * Custom actions
    */

package/dist/utils/host.d.mts

@@ -26,7 +26,7 @@
  * The semantic kind of a host, derived from RFC 6890 special-purpose registries
  * plus a few domain-name categories (localhost, cloud metadata FQDNs).
  */
-type HostKind = /** IPv4 `127.0.0.0/8` or IPv6 `::1`. */"loopback" /** DNS name `localhost` or RFC 6761 `.localhost` TLD. */ | "localhost" /** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */ | "unspecified" /** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */ | "private" /** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */ | "linkLocal" /** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */ | "sharedAddressSpace" /** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */ | "documentation" /** RFC 2544 `198.18.0.0/15`. */ | "benchmarking" /** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */ | "multicast" /** IPv4 limited broadcast `255.255.255.255`. */ | "broadcast" /** Other RFC 6890 special-purpose ranges (0/8, 192.0.0/24, 240/4, 2001::/32, etc.). */ | "reserved" /** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */ | "cloudMetadata" /** Any host not matching a special-purpose range above. */ | "public";
+type HostKind = /** IPv4 `127.0.0.0/8` or IPv6 `::1`. */"loopback" /** DNS name `localhost` or RFC 6761 `.localhost` TLD. */ | "localhost" /** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */ | "unspecified" /** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */ | "private" /** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */ | "linkLocal" /** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */ | "sharedAddressSpace" /** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */ | "documentation" /** RFC 2544 `198.18.0.0/15`. */ | "benchmarking" /** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */ | "multicast" /** IPv4 limited broadcast `255.255.255.255`. */ | "broadcast" /** Other RFC 6890 special-purpose ranges (0.0.0.0/8, 192.0.0.0/24, 192.88.99.0/24, 240.0.0.0/4, 2001::/32, etc.). */ | "reserved" /** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */ | "cloudMetadata" /** Any host not matching a special-purpose range above. */ | "public";
 /**
  * The syntactic form of the input host: an IPv4 literal, an IPv6 literal, or
  * a domain name. IPv4-mapped IPv6 (`::ffff:192.0.2.1`) is reported as `ipv4`

package/dist/utils/host.mjs

@@ -86,6 +86,7 @@ function classifyIPv4(ip) {
 	if (inIPv4Range(n, ipv4ToUint32("224.0.0.0"), 4)) return "multicast";
 	if (inIPv4Range(n, ipv4ToUint32("0.0.0.0"), 8)) return "reserved";
 	if (inIPv4Range(n, ipv4ToUint32("192.0.0.0"), 24)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("192.88.99.0"), 24)) return "reserved";
 	if (inIPv4Range(n, ipv4ToUint32("240.0.0.0"), 4)) return "reserved";
 	return "public";
 }
@@ -124,8 +125,10 @@ function classifyIPv6(expanded) {
 	const secondByte = Number.parseInt(expanded.slice(2, 4), 16);
 	if (firstByte === 255) return "multicast";
 	if (firstByte === 254 && (secondByte & 192) === 128) return "linkLocal";
+	if (firstByte === 254 && (secondByte & 192) === 192) return "reserved";
 	if ((firstByte & 254) === 252) return "private";
 	if (expanded.startsWith("2001:0db8:")) return "documentation";
+	if (expanded.startsWith("2001:0002:0000:")) return "benchmarking";
 	if (expanded.startsWith("2002:")) {
 		const embedded = extractEmbeddedIPv4(expanded, 1);
 		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
@@ -136,12 +139,16 @@ function classifyIPv6(expanded) {
 		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
 		return "reserved";
 	}
+	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";
 		return "reserved";
 	}
 	if (expanded.startsWith("0100:0000:0000:0000:")) return "reserved";
+	if (expanded.startsWith("3fff:0")) return "documentation";
+	if (expanded.startsWith("5f00:")) return "reserved";
+	if (expanded.startsWith("0000:0000:0000:0000:0000:0000:")) return "reserved";
 	return "public";
 }
 /**

package/dist/utils/url.mjs

@@ -22,9 +22,10 @@ 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;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-beta.5",
+  "version": "1.7.0-beta.7",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -152,8 +152,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.4.1",
-    "@better-fetch/fetch": "1.2.2",
+    "@better-auth/utils": "0.4.2",
+    "@better-fetch/fetch": "1.3.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
@@ -165,8 +165,8 @@
     "tsdown": "0.21.1"
   },
   "peerDependencies": {
-    "@better-auth/utils": "0.4.1",
-    "@better-fetch/fetch": "1.2.2",
+    "@better-auth/utils": "0.4.2",
+    "@better-fetch/fetch": "1.3.1",
     "@opentelemetry/api": "^1.9.0",
     "better-call": "1.3.6",
     "@cloudflare/workers-types": ">=4",

package/src/api/index.ts

@@ -12,6 +12,25 @@ 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
@@ -101,8 +120,23 @@ 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));
@@ -132,6 +166,54 @@ export function createAuthEndpoint<
 	);
 }
 
+/**
+ * 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,