魔法链接

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

安装

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

export const auth = betterAuth({
    plugins: [
        magicLink({ 
            sendMagicLink: async ({ email, token, url }, ctx) => { 
                // 发送邮件给用户
            } 
        }) 
    ]
})

import { createAuthClient } from "better-auth/client";
import { magicLinkClient } from "better-auth/client/plugins"; 

export const authClient = createAuthClient({
    plugins: [
        magicLinkClient() 
    ]
});

使用方法

使用魔法链接登录

要通过魔法链接登录，需调用 signIn.magicLink 并传入用户的电子邮件地址。sendMagicLink 函数会被调用以向用户邮箱发送魔法链接。

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(),});

验证魔法链接

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

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

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(),});

配置选项

sendMagicLink：当用户请求魔法链接时调用 sendMagicLink 函数。该函数接收一个包含以下属性的对象：

• email：用户的电子邮件地址。
• url：发送给用户的 URL，该 URL 包含令牌。
• token：如果你想用自定义 URL 发送令牌，则为令牌内容。

此外，函数的第二个参数为上下文对象 ctx。

expiresIn：指定魔法链接过期的时间，单位为秒。默认值为 300 秒（5 分钟）。

allowedAttempts：指定验证魔法链接的允许尝试次数。默认值为 1。当超过限制时，令牌将被删除，用户会被重定向并附带 ?error=ATTEMPTS_EXCEEDED 参数。可设置为 Infinity 以允许无限次尝试。

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

generateToken：调用该函数生成用于唯一标识用户的令牌。默认生成一个随机字符串。函数参数：

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

storeToken：调用该函数将魔法链接令牌存储在数据库中。默认值为 "plain"。

storeToken 可为以下之一：

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