Better Auth 1.3 发布

我们很高兴地宣布 Better Auth 1.3 的发布。此次发布包含了许多新功能和改进。

要升级，请运行：

npm install better-auth@1.3

🚀 亮点

SSO 插件

SSO 插件已被移至其自己的包中，现在支持 OIDC 和 SAML 2.0。

👉 阅读 SSO 文档

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

export const auth = betterAuth({
  plugins: [
    sso({
      oidc: {
        clientId: process.env.OIDC_CLIENT_ID!,
        clientSecret: process.env.OIDC_CLIENT_SECRET!,
      },
      saml: {
        entryPoint: "https://example.com/saml",
        issuer: "better-auth-example",
        certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      },
      providersLimit: async (user) => {
        const plan = await getUserPlan(user);
        return plan.name === "pro" ? 10 : 1;
      },
    }),
  ],
});

OIDC 和 MCP 插件 – 现已稳定

OIDC 和 MCP 插件均已生产就绪。

✅ 功能：

  • 发现和令牌端点中的刷新令牌支持
  • 公共客户端的 JWKs 和 PKCE
  • 受信任客户端
  • 加密和哈希客户端密钥

👉 阅读 OIDC 文档 👉 阅读 MCP 文档

auth.ts
import { mcp } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    mcp({
      loginPage: "/login",
    }),
  ],
});

Stripe 插件现已生产就绪

Stripe 插件现在已稳定，使用量计费定价即将推出。

👉 阅读 Stripe 文档

auth.ts
import { betterAuth } from "better-auth";
import { stripe } from "@better-auth/stripe";

export const auth = betterAuth({
  plugins: [
    stripe({
      // ...
    }),
  ],
});

SIWE 插件

原生支持 使用 Ethereum 登录。

👉 阅读 SIWE 文档

auth.ts
import { siwe } from "better-auth/plugins";

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

新社交提供商

我们添加了 Notion、Slack、Linear 和 Faceit 的提供商。

auth.ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  socialProviders: {
    notion: { /* ... */ },
    slack: { /* ... */ },
    linear: { /* ... */ },
    faceit: { /* ... */ },
  },
});

用于在 SvelteKit 服务器操作中处理 Cookie 的实用工具。

破坏性变更：现在必须将 building 和 getRequestEvent 作为 props 传入。

auth.ts
import { betterAuth } from "better-auth";
import { sveltekitCookies } from "better-auth/svelte-kit";
import { getRequestEvent } from "$app/server";

export const auth = betterAuth({
  plugins: [sveltekitCookies(getRequestEvent)],
});

登录时的电子邮件验证

auth.ts
export const auth = betterAuth({
  emailVerification: {
    sendOnSignIn: true, // 如果用户未验证，则在登录时发送验证电子邮件
  },
});

多团队支持

组织插件现在支持成员属于多个团队。

破坏性变更： member 表中已移除 teamId。需要一个新的 teamMembers 表。

auth.ts
export const auth = betterAuth({
  plugins: [
    organization({
      // ...
    }),
  ],
});
auth-client.ts
import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";
import { auth } from "./auth";

export const authClient = createAuthClient({
  // 将您的 auth 实例传入以推断附加字段
  plugins: [organizationClient({ $inferAuth: {} as typeof auth })], 
});

附加组织字段

向 organization、member 和 invitation 模型添加自定义字段。

auth.ts
export const auth = betterAuth({
  plugins: [
    organization({
      schema: {
        organization: { additionalFields: { /* ... */ } },
        member: { additionalFields: { /* ... */ } },
        invitation: { additionalFields: { /* ... */ } },
      },
    }),
  ],
});

其他新选项：

  • maximumMembersPerTeam – 设置团队成员限制
  • listUserInvitations – 列出用户的所有邀请

通用 OAuth 改进

  • 添加了对额外令牌 URL 参数的支持
  • OAuth 令牌加密选项
auth.ts
export const auth = betterAuth({
  plugins: [
    genericOAuth({
      // ...
    }),
  ],
});

API 密钥

  • 密钥创建的 requireName 选项
  • verifyKey 现在支持异步函数

用户名

  • 可用性检查
  • 自定义规范化

✨ 更多功能

  • 迁移到 Zod 4 以获得更好的类型安全性和性能
  • CLI 支持自定义适配器 createSchema
  • inferAuth 实用工具，用于从客户端推断类型
  • 带有 auth 和 authClient 示例的改进文档
  • signUp 中的 rememberMe 支持
  • afterEmailVerification 钩子
  • freshAge 和自定义 errorURL 得到正确尊重
  • OAuth2 令牌现在包含 refresh_token_expires_in

🐛 错误修复和改进

插件

  • Expo：修复类型路径导入

  • SSO：修复 SAML 重定向和类型检查

  • Dropbox：令牌访问类型支持

  • Stripe：

    • 防止重复客户
    • 允许升级不完整的订阅

  • Admin：

    • 修复钩子中缺少的 ctx
    • 移除无效用户 ID 时正确错误

OAuth 和提供商

  • 修复重复 OAuth 注册
  • 改进 Google/Microsoft 作用域处理
  • 修复通用 OAuth 中的畸形错误 URL
  • Facebook：更好地检测有限令牌 JWT
  • Twitter：改进电子邮件验证逻辑

核心身份验证

  • 从用户名唯一性检查中排除当前用户
  • 在 signInUsername 中支持 callbackURL
  • 允许无电子邮件的账户链接
  • 修复 /get-session 响应中缺少的 null 类型
  • 全局 onSuccess 钩子现在有效
  • JWT：JWKS 中支持备用算法
  • origin-check：支持通配符受信任来源

CLI、DB 和适配器

  • CLI：改进 Drizzle 架构格式化
  • MongoAdapter：与 create-adapter 兼容
  • 架构生成尊重 useNumberId
  • Postgres：更好的 varchar 规范化和类型比较
  • Drizzle CLI：如果启用 useNumberId，则使用 serial 作为 PK

电子邮件和 OTP

  • OTP 现在加密
  • 修复 onEmailVerification 未触发
  • 注册禁用时正确错误
  • 电话号码：重置清除验证值

双因素认证

  • 默认 OTP 周期修复
  • URI 生成不需要启用 2FA
  • 修复 OTP URI 分隔符不匹配

其他

  • 如果未找到成员，则删除组织
  • API 密钥速率限制的正确错误代码
  • 附加字段现在在 OpenAPI 中显示
  • 修复 MySQL 的 FK 约束生成
  • 各种账户链接改进
  • OIDC offline_access 不再需要 prompt=consent
  • 修复令牌验证的畸形 base64 编码

许多细微调整，使一切更流畅、更快速、更可靠。 👉 查看完整变更日志