魔法链接

魔法链接或电子邮件链接是一种无需密码即可验证用户身份的方式。当用户输入他们的电子邮件时，会向其发送一个链接。当用户点击该链接时，他们的身份将得到验证。

【Magic link or email link is a way to authenticate users without a password. When a user enters their email, a link is sent to their email. When the user clicks on the link, they are authenticated.】

安装

【Installation】

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

export const auth = betterAuth({
    plugins: [
        magicLink({
            sendMagicLink: async ({ email, token, url }, ctx) => {
                // send email to user
            }
        })
    ]
})

import { createAuthClient } from "better-auth/client";
import { magicLinkClient } from "better-auth/client/plugins";
export const authClient = createAuthClient({
    plugins: [
        magicLinkClient()
    ]
});

用法

【Usage】

使用魔法链接登录

【Sign In with Magic Link】

要使用魔法链接登录，你需要使用用户的电子邮件地址调用 signIn.magicLink。sendMagicLink 函数会被调用以将魔法链接发送到用户的电子邮件。

【To sign in with a magic link, you need to call signIn.magicLink with the user's email address. The sendMagicLink function is called to send the magic link to the user's email.】

const { data, error } = await authClient.signIn.magicLink({    email: "user@email.com", // required    name: "my-name",    callbackURL: "/dashboard",    newUserCallbackURL: "/welcome",    errorCallbackURL: "/error",});

const data = await auth.api.signInMagicLink({    body: {        email: "user@email.com", // required        name: "my-name",        callbackURL: "/dashboard",        newUserCallbackURL: "/welcome",        errorCallbackURL: "/error",    },    // This endpoint requires session cookies.    headers: await headers(),});

验证魔术链接

【Verify Magic Link】

当你将 sendMagicLink 函数生成的 URL 发送给用户时，用户点击该链接将会进行身份验证，并重定向到在 signIn.magicLink 函数中指定的 callbackURL。如果发生错误，用户将会被重定向到带有错误查询参数的 callbackURL。

【When you send the URL generated by the sendMagicLink function to a user, clicking the link will authenticate them and redirect them to the callbackURL specified in the signIn.magicLink function. If an error occurs, the user will be redirected to the callbackURL with an error query parameter.】

如果你想手动处理验证（例如，如果你发送给用户一个不同的 URL），你可以使用 verify 函数。

【If you want to handle the verification manually, (e.g, if you send the user a different URL), you can use the verify function.】

const { data, error } = await authClient.magicLink.verify({    query: {        token: "123456", // required        callbackURL: "/dashboard",    },});

const data = await auth.api.magicLinkVerify({    query: {        token: "123456", // required        callbackURL: "/dashboard",    },    // This endpoint requires session cookies.    headers: await headers(),});

配置选项

【Configuration Options】

sendMagicLink：当用户请求魔法链接时，会调用 sendMagicLink 函数。它接受一个具有以下属性的对象：

• email：用户的电子邮件地址。
• url：要发送给用户的 URL。此 URL 包含令牌。
• token：如果你想通过自定义 URL 发送令牌，请使用该令牌。

以及一个 ctx 上下文对象作为第二个参数。

【and a ctx context object as the second parameter.】

expiresIn：指定魔法链接在多少秒后过期。默认值为 300 秒（5 分钟）。

disableSignUp：如果设置为 true，用户将无法使用魔法链接注册。默认值为 false。

generateToken: generateToken 函数用于生成一个用于唯一标识用户的令牌。默认值是一个随机字符串。它有一个参数：

• email：用户的电子邮件地址。

storeToken：storeToken 函数被调用以将魔法链接令牌存储到数据库中。默认值是 "plain"。

storeToken 函数可以是以下之一：

【The storeToken function can be one of the following:】

• "plain": 令牌以明文形式存储。
• "hashed": 令牌使用默认哈希器进行哈希。
• { type: "custom-hasher", hash: (token: string) => Promise<string> }: 令牌使用自定义哈希器进行哈希处理。