Better Auth 1.4

Better Auth 1.4 发布

我们很高兴宣布 Better Auth 1.4 版本发布。本次发布包含多项新功能、性能及安全改进。

升级请运行：

npm install better-auth@1.4

🚀 重点功能

无状态认证

You can now enable stateless session management without any database by omitting the database option in your auth config.

👉 详情请阅读无状态认证

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    // 无数据库配置
    socialProviders: {
        google: {
            clientId: process.env.GOOGLE_CLIENT_ID,
            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
        },
    },
});

此外，还支持无数据库环境下获取 accessToken、accountInfo 和 refreshToken 端点。

import { authClient } from "@/lib/auth-client";

const accessToken = await authClient.getAccessToken();

// 获取账户信息
const accountInfo = await authClient.accountInfo();

SCIM 通过标准协议简化多域场景下身份管理的支持。

👉 详情请阅读 SCIM 配置

import { scim } from "@better-auth/scim";
import { betterAuth } from "better-auth";

export const auth = betterAuth({
    plugins: [scim()]
});

现在可以在 OAuth 流程中传递任意额外的状态数据。

👉 详情请阅读 OAuth 流程中的自定义状态

import { authClient } from "@/lib/auth-client";

await authClient.signIn.social({
    provider: "google",
    additionalData: { 
        referralCode: "ABC123", 
        source: "landing-page", 
    }, 
});

可在任意钩子、中间件或端点中访问这些额外数据：

import { betterAuth } from "better-auth";
import { getOAuthState, createAuthMiddleware } from "better-auth/api";

const auth = betterAuth({
    hooks: {
      before: createAuthMiddleware(async (ctx) => {
        const additionalData = await getOAuthState<{ referralCode: string, source: string }>();
        console.log(additionalData);
      })
    }
});

Better-Auth 现在支持数据库连接，使用数据库连接技术，提升 50 多个端点 2 到 3 倍的响应速度。

启用方法：在认证配置的 experimental 中设置 joins 为 true。 然后重新运行迁移或架构生成以使用支持连接的更新架构。

👉 详情请阅读数据库连接

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    experimental: {
        joins: true,
    },
});

API 密钥支持二级存储

API-Key 插件新增对二级存储的支持，加快密钥查询速度！

👉 Read more about secondary storage for API keys

import { apiKey } from "@better-auth/api-key";
import { betterAuth } from "better-auth";

export const auth = betterAuth({
    secondaryStorage: {
        //...
    },
    plugins: [apiKey({ storage: "secondary-storage" })], 
});

SSO 域验证

域验证可让应用自动信任新的 SSO 提供者，通过自动验证关联域的所有权来实现：

👉 Read more about error page improvements

SSO Domain Verification

Domain verification allows your application to automatically trust a new SSO provider by automatically validating ownership via the associated domain:

👉 Read more about domain verification

import { sso } from "@better-auth/sso";
import { betterAuth } from "better-auth";

export const auth = betterAuth({
    plugins: [sso({ domainVerification: { enabled: true } })],
});

CLI 支持数据库索引

Better-Auth CLI 现在内置支持数据库索引，大大提升应用性能。

npx auth generate

npx auth migrate

JWT 密钥轮换支持

JWT 插件现支持密钥轮换，允许无停机地替换 JWT 密钥。

import { jwt } from "@better-auth/jwt";
import { betterAuth } from "better-auth";

export const auth = betterAuth({
    plugins: [
      jwt({ 
        jwks: { rotationInterval: 60 * 60 * 24 * 30, gracePeriod: 60 * 60 * 24 * 30 } 
      })
    ],
});

👉 Read more about JWT key rotation

改进的通用 OAuth 插件

尚未原生支持的 OAuth 提供者将作为预配置选项加入通用 OAuth 插件，计划最终支持 Auth.js 的所有提供者。

import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { keycloak } from "better-auth/plugins/generic-oauth";

export const auth = betterAuth({
    plugins: [genericOAuth({
        config: [
            keycloak({
                clientId: process.env.KEYCLOAK_CLIENT_ID,
                clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
                issuer: process.env.KEYCLOAK_ISSUER,
            })
        ]
    })
    ]
});

包体积优化

如果使用自定义适配器（如 Prisma、Drizzle 或 MongoDB），
可通过使用 better-auth/minimal 替代 better-auth 来减小包体积。
该版本不包含 Kysely，仅在直接数据库连接时需要。

👉 详情请阅读包体积优化

import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { betterAuth } from "better-auth/minimal"; 
import { db } from "./database";

export const auth = betterAuth({
    database: drizzleAdapter(db, { provider: "pg" }),
});

UUID 支持

现在开箱即用支持将 UUID 作为主 ID 字段类型。

👉 详情请阅读 UUID 支持

import { betterAuth } from "better-auth";
import { db } from "./database";

export const auth = betterAuth({
    database: db,
    advanced: {
        database: { generateId: "uuid" }, 
    },
});

改进的邮箱更改流程

For added security, you can now require users to confirm the change via their current email before the verification email is sent to the new address.

👉 详情请阅读改进的邮箱更改流程

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    user: {
        changeEmail: {
            enabled: true,
            sendChangeEmailConfirmation: async ({ user, newEmail, url, token }, request) => {
                sendEmail({
                    to: user.email, // 发送到当前邮箱
                    subject: '批准邮箱更改',
                    text: `点击链接以批准更改至 ${newEmail}：${url}`
                })
            }
        }
    }
});

设备授权插件

完整支持 OAuth 2.0 设备授权协议（RFC 8628），允许用户在输入受限设备（智能电视、游戏机等）上登录。

👉 详情请阅读设备授权

import { betterAuth } from "better-auth";
import { deviceAuthorization } from "better-auth/plugins";

export const auth = betterAuth({
    plugins: [
        deviceAuthorization()
    ]
});

基于 Cookie 的账户存储

现在支持将用户账户数据存储于签名 Cookie 中，非常适合无状态应用或延迟数据库持久化。

export const auth = betterAuth({
    account: {
        storeAccountCookie: true
    } 
});

建议逐项检查破坏性变更，确保升级顺利。

现有认证流程

小幅调整以提升流畅度、速度和可靠性。

• 邮箱更改流程：移除 changeEmail 流程中的 sendChangeEmailVerification，改用 emailVerification.sendVerificationEmail。
• 忘记密码流程：将 authClient.forgotPassword 改名为 authClient.requestPasswordReset。
• 账户信息端点：accountInfo 端点从 POST /account-info 改为 GET /account-info。

• Change-Email Flow: We've removed sendChangeEmailVerification from the changeEmail flow to use emailVerification.sendVerificationEmail instead.

• Forgot Password Flow: authClient.forgotPassword is now authClient.requestPasswordReset.

• Account Info Endpoint: The accountInfo endpoint has changed from POST /account-info to GET /account-info.

  This means any auth.api calls must change from:

  auth.api.accountInfo({
      body: {
          // ...
      }
  });

  改为：

  auth.api.accountInfo({
      query: {
          // ...
      }
  });

插件选项变更

多个插件回调中的 request 参数改为 ctx。
Passkey 插件独立成包，API Key 的模拟会话默认关闭。

• Passkey Plugin: The passkey plugin is now moved to its own package.

  Install it today:

  npm

  pnpm

  yarn

  bun

  npm install @better-auth/passkey

• Email OTP Plugin: Plugin options for sendVerificationOTP and generateOTP now use ctx instead of request in its callback function. You can still access request via ctx.request.

• Magic Link Plugin: Plugin options for sendMagicLink now uses ctx instead of request for one of its callback options. You can still access request via ctx.request.

• Phone Number Plugin: Plugin options for sendOTP, sendPasswordResetOTP & callbackOnVerification have now replaced request with ctx in one of its callback options. You can still access request via ctx.request.

• Organization Plugin: Plugin options for teams.defaultTeam.customCreateDefaultTeam & teams.maximumTeams have now replaced request with ctx for one of its callback options. You can still access request via ctx.request.

• OIDC Plugin: The field redirectURLs have been updated to redirectUrls, this requires database migration.

• API Key Plugin: Mock-sessions by api-keys are now disabled by default, and should be enabled through the auth-config first.

认证配置变更

数据库配置选项调整。

• advanced.generateId removed: The long-deprecated advanced.generateId has been removed. Please use advanced.database.generateId instead.
• advanced.database.useNumberId moved: advanced.database.useNumberId has been moved to advanced.database.generateId: "serial" instead.

Tanstack Start

The Better-Auth offered reactStartCookies plugin is now moved to tanstackStartCookies plugin.

- import { reactStartCookies } from "better-auth/react-start";
+ import { tanstackStartCookies } from "better-auth/tanstack-start";

export const auth = betterAuth({
-    plugins: [reactStartCookies()],
+    plugins: [tanstackStartCookies()],
});

Expo

Expo 上的 useSession 新增轮询特性，需要安装 expo-network：

npx expo install expo-network

Cloudflare 运行时

Better Auth 使用 AsyncLocalStorage 进行异步上下文跟踪。
在 Cloudflare Workers 需于 wrangler.toml 中添加 nodejs_compat 标记以启用：

compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-09-23"

Alternatively, if you only need AsyncLocalStorage support:

compatibility_flags = ["nodejs_als"]

下一大版本将默认假设支持 AsyncLocalStorage，此配置届时必需。

✨ 更多功能

• Cookie 分块: 不再出现 Cookie 大小超限错误。
• MongoDB 字符串 ID: 支持在 MongoDB 中使用字符串 ID 而非 ObjectID。
• JWE Cookie 缓存: 会话存储 Cookie 缓存默认使用 JWE 以增强安全性。
• OIDC RP 启动注销: 在 OIDC 提供程序触发注销。
• 服务端 IP 检测: 自动客户端 IP 检测工具。
• 自定义 OTP 验证: 允许在电话号码插件中使用自定义逻辑进行 OTP 验证。
• 客户端 disableSignal: 可选项，用于禁用默认的中止信号行为。
• AuthClient 类型助手: 新的类型助手，用于更好的客户端类型推断。
• 新提供者: 添加了 Polar 和 Paybin OAuth 提供者。
• 仅 ESM: Better-Auth 现在完全支持 ESM。
• 会话重新获取: 支持轮询和窗口聚焦时重新获取。
• Cloudflare Workers: CLI 支持虚拟模块导入。
• 错误文档: 常见的 OAuth 流程错误现已 记录在案。
• 最后登录方式: 支持跟踪 SIWE 和密钥登录。

🐛 错误修复与改进

本次发布共修复 250 多个问题，涵盖多个领域：

• 适配器修复: 改进查询处理、更佳的类型转换 UUID 列类型，并解决了可为空的外键问题。
• 会话管理: 修复会话刷新触发器，改进 Cookie 处理及缓存管理。
• OAuth: 修复状态管理，改进回调处理，并解决跨来源问题。
• 组织: 修复成员删除、团队管理、权限检查和推断问题。
• 双因素认证: 改进 TOTP 错误信息，修复备份代码加密，并增强设备信任处理。
• 电子邮件 OTP: 防止重复发送验证邮件，并改进会话信号触发。
• SSO: 修复 SAML 回调处理，改进 OIDC 作用域回退，并增强同意强制执行。
• API 密钥: 修复使用量跟踪，并改进请求验证。
• 电话号码: 防止未经授权的电话号码更新，并改进验证流程。
• 以及更多！

大量细节优化让一切更顺畅、更快速、更可靠。
👉 查看完整更新日志

❤️ 贡献者

感谢所有贡献者使本次发布成为可能！