npx auth upgrade

npx auth init

npx auth migrate   # 运行数据库迁移
npx auth generate  # 生成认证 Schema
npx auth upgrade   # 升级 Better Auth 到最新版本

npx auth generate --adapter prisma
npx auth generate --adapter drizzle

import { createMcpAuthClient } from "better-auth/plugins/mcp/client";

const mcpAuth = createMcpAuthClient({
    authURL: "<https://my-app.com/api/auth>",
});

// 作为请求处理器包装器使用
const handler = mcpAuth.handler(async (req, session) => {
    // session 包含 userId, scopes, accessToken, clientId 等信息
    return new Response("OK");
});

// 或直接验证令牌
const session = await mcpAuth.verifyToken(token);

import { mcpAuthHono } from "better-auth/plugins/mcp/client/adapters";

const middleware = mcpAuthHono(mcpAuth);

import { betterAuth } from "better-auth";
import { jwt } from "better-auth/plugins";
import { oauthProvider } from "@better-auth/oauth-provider";

export const auth = betterAuth({
    plugins: [
        jwt(),
        oauthProvider({
            loginPage: "/sign-in",
            consentPage: "/consent",
        }),
    ],
});

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

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

import { createAuthClient } from "better-auth/client";
import { electronClient } from "@better-auth/electron/client";

const client = createAuthClient({
    plugins: [
        electronClient({
            protocol: "com.example.myapp",
        }),
    ],
});

// 打开系统浏览器，处理回调，返回会话
await client.requestAuth();

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

export const auth = betterAuth({
    plugins: [
        i18n({
            defaultLocale: "en",
            detection: ["header", "cookie"],
            translations: {
                en: { USER_NOT_FOUND: "User not found" },
                fr: { USER_NOT_FOUND: "Utilisateur non trouvé" },
                es: { USER_NOT_FOUND: "Usuario no encontrado" },
            },
        }),
    ],
});

import { defineErrorCodes } from "@better-auth/core";

export const MY_ERROR_CODES = defineErrorCodes({
    USER_NOT_FOUND: "User not found",
    INVALID_TOKEN: "The provided token is invalid",
});

// 路由处理器中使用：
throw APIError.from("BAD_REQUEST", MY_ERROR_CODES.USER_NOT_FOUND);

{
    "code": "USER_NOT_FOUND",
    "message": "User not found"
}

https://dash.better-auth.com/[project]/organization/[orgId]/enterprise

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

- import { apiKeyClient } from "better-auth/client/plugins";
+ import { apiKeyClient } from "@better-auth/api-key/client";

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

export const auth = betterAuth({
    plugins: [apiKey({ references: "organization" })],
});

import { auth } from "@/lib/auth";

const apiKey = await auth.api.createApiKey({
    body: { organizationId: "org_123" },
});

export const auth = betterAuth({
    plugins: [
        apiKey([
            {
                configId: "user-keys",
                prefix: "usr_"
            },
            {
                configId: "org-keys",
                prefix: "org_",
                references: "organization"
            }
        ])
    ]
});

const key = auth.api.createApiKey({
    body: {
        configId: "user-keys",
        //...
    }
});

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

export const auth = betterAuth({
    hooks: {
        before: createAuthMiddleware(async (ctx) => {
            // 在每个端点前执行
            console.log("请求路径:", ctx.path);
        }),
        after: createAuthMiddleware(async (ctx) => {
            // 在每个端点后执行，访问响应内容
            console.log("响应内容:", ctx.context.returned);
        }),
    },
});

hooks: {
    before: [{
        matcher: (ctx) => ctx.path === "/sign-in/email",
        handler: createAuthMiddleware(async (ctx) => { /* ... */ }),
    }],
},

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    baseURL: {
        allowedHosts: [
            "myapp.com",
            "*.vercel.app",       // 任意 Vercel 预览域
            "preview-*.myapp.com", // 模式匹配
        ],
        fallback: "<https://myapp.com>",
        protocol: "auto",
    },
});

verification: {
    storeIdentifier: {
        default: "plain",
        overrides: {
            "email-verification": "hashed",
            "password-reset": "hashed",
        },
    },
},

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    advanced: {
        ipAddress: {
            ipv6Subnet: 64, // 按 /64 子网限流
        },
    },
});

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    secrets: [
        { version: 2, value: "new-secret-key-at-least-32-chars" },   // 当前（数组第一项为活动密钥）
        { version: 1, value: "old-secret-key-still-used-to-decrypt" }, // 旧密钥
    ],
});

BETTER_AUTH_SECRETS="2:new-secret-key,1:old-secret-key"

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

export const auth = betterAuth({
    plugins: [testUtils({ captureOTP: true })],
});

const ctx = await auth.$context;
const test = ctx.test;

// 创建并保存测试用户
const user = test.createUser({ email: "test@example.com" });
const savedUser = await test.saveUser(user);

// 登录并获取认证请求头
const { headers, session, token } = await test.login({ userId: user.id });

// 捕获一次性密码用于验证测试
const otp = test.getOTP("test@example.com");

// 客户端调用
await authClient.updateSession({
    theme: "dark",
    language: "en",
});

import { drizzleAdapter } from "@better-auth/drizzle-adapter";
import { betterAuth } from "better-auth/minimal";

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

npm install @better-auth/api-key

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

export const auth = betterAuth({
    plugins: [
        apiKey({
            permissions: {
-               defaultPermissions: async (userId, ctx) => {
+               defaultPermissions: async (referenceId, ctx) => {
                    return {
                        files: ["read"],
                        users: ["read"],
                    };
                },
            }
        })
    ]
})

- const ownerId = apiKey.userId;
+ const ownerId = apiKey.referenceId;
+ const ownerType = apiKey.references; // "user" 或 "organization"
+ const configId = apiKey.configId;

- import { generateId, safeJSONParse, defineErrorCodes } from "@better-auth/core/utils";
+ import { generateId } from "@better-auth/core/utils/id";
+ import { safeJSONParse } from "@better-auth/core/utils/json";
+ import { defineErrorCodes } from "@better-auth/core/utils/error-codes";

- $ERROR_CODES: {
-     MY_ERROR: "My error message",
- },
+ $ERROR_CODES: defineErrorCodes({
+     MY_ERROR: "My error message",
+ }),
+ // 返回：{ MY_ERROR: { code: "MY_ERROR", message: "My error message" } }

import { APIError } from "@better-auth/core/error";

throw APIError.from("BAD_REQUEST", MY_ERROR_CODES.MY_ERROR);

type PluginContext<Options extends BetterAuthOptions> = {
    getPlugin: <ID extends string>(pluginId: ID) => /* 从注册表推断的结果 */ | null;
    hasPlugin: <ID extends string>(pluginId: ID) => boolean; // 如果返回 true，类型收窄为已注册插件
};

declare module "@better-auth/core" {
    interface BetterAuthPluginRegistry<AuthOptions, Options> {
        "my-plugin": { creator: typeof myPlugin };
    }
}

- import type { InferUser, InferSession } from "better-auth/types";
- type MyUser = InferUser<typeof auth>;
+ import type { User, Session } from "better-auth";
+ type MyUser = User<typeof auth.$options["user"], typeof auth.$options["plugins"]>;

- import { getMigrations } from "better-auth";
+ import { getMigrations } from "better-auth/db/migration";