电子邮件一次性密码

Email OTP 插件允许用户使用发送到其邮箱的一次性密码（OTP）登录、验证邮箱或重置密码。

【The Email OTP plugin allows user to sign in, verify their email, or reset their password using a one-time password (OTP) sent to their email address.】

安装

【Installation】

import { betterAuth } from "better-auth"
import { emailOTP } from "better-auth/plugins"

export const auth = betterAuth({
    // ... other config options
    plugins: [
        emailOTP({ 
            async sendVerificationOTP({ email, otp, type }) { 
                if (type === "sign-in") { 
                    // Send the OTP for sign in
                } else if (type === "email-verification") { 
                    // Send the OTP for email verification
                } else { 
                    // Send the OTP for password reset
                } 
            }, 
        }) 
    ]
})

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

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

用法

【Usage】

发送一次性密码

【Send an OTP】

使用 sendVerificationOtp() 方法向用户的电子邮箱发送一次性密码（OTP）。

【Use the sendVerificationOtp() method to send an OTP to the user's email address.】

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required    },});

验证一次性密码（可选）

【Check an OTP (optional)】

使用 checkVerificationOtp() 方法来检查 OTP 是否有效。

【Use the checkVerificationOtp() method to check if an OTP is valid.】

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required    otp: "123456", // required});

const data = await auth.api.checkVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required        otp: "123456", // required    },});

使用一次性密码登录

【Sign In with OTP】

要使用 OTP 登录，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送“登录” OTP。

【To sign in with OTP, use the sendVerificationOtp() method to send a "sign-in" OTP to the user's email address.】

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required    },});

一旦用户提供了 OTP，你可以使用 signIn.emailOtp() 方法登录用户。

【Once the user provides the OTP, you can sign in the user using the signIn.emailOtp() method.】

const { data, error } = await authClient.signIn.emailOtp({    email: "user@example.com", // required    otp: "123456", // required});

const data = await auth.api.signInEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required    },});

使用一次性密码验证邮箱

【Verify Email with OTP】

要通过一次性密码（OTP）验证用户的电子邮件地址，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送一个“电子邮件验证”OTP。

【To verify the user's email address with OTP, use the sendVerificationOtp() method to send an "email-verification" OTP to the user's email address.】

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "email-verification", // required});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "email-verification", // required    },});

一旦用户提供 OTP，使用 verifyEmail() 方法完成邮箱验证。

【Once the user provides the OTP, use the verifyEmail() method to complete email verification.】

const { data, error } = await authClient.emailOtp.verifyEmail({    email: "user@example.com", // required    otp: "123456", // required});

const data = await auth.api.verifyEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required    },});

使用一次性密码重置密码

【Reset Password with OTP】

要使用一次性密码（OTP）重置用户密码，请使用 forgetPassword.emailOTP() 方法向用户的电子邮箱发送“忘记密码”OTP。

【To reset the user's password with OTP, use the forgetPassword.emailOTP() method to send a "forget-password" OTP to the user's email address.】

const { data, error } = await authClient.forgetPassword.emailOtp({    email: "user@example.com", // required});

const data = await auth.api.forgetPasswordEmailOTP({    body: {        email: "user@example.com", // required    },});

一旦用户提供 OTP，可以使用 checkVerificationOtp() 方法检查其是否有效（可选）。

【Once the user provides the OTP, use the checkVerificationOtp() method to check if it's valid (optional).】

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "forget-password", // required    otp: "123456", // required});

const data = await auth.api.checkVerificationOTP({    body: {        email: "user@example.com", // required        type: "forget-password", // required        otp: "123456", // required    },});

然后，使用 resetPassword() 方法重置用户的密码。

【Then, use the resetPassword() method to reset the user's password.】

const { data, error } = await authClient.emailOtp.resetPassword({    email: "user@example.com", // required    otp: "123456", // required    password: "new-secure-password", // required});

const data = await auth.api.resetPasswordEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required        password: "new-secure-password", // required    },});

覆盖默认电子邮件验证

【Override Default Email Verification】

要覆盖默认的电子邮件验证，请在选项中传入 overrideDefaultEmailVerification: true。这将使系统在触发电子邮件验证时使用电子邮件一次性密码（OTP）而不是默认的验证链接。换句话说，用户将使用一次性密码验证他们的电子邮件，而不是点击链接。

【To override the default email verification, pass overrideDefaultEmailVerification: true in the options. This will make the system use an email OTP instead of the default verification link whenever email verification is triggered. In other words, the user will verify their email using an OTP rather than clicking a link.】

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  plugins: [
    emailOTP({
      overrideDefaultEmailVerification: true, 
      async sendVerificationOTP({ email, otp, type }) {
        // Implement the sendVerificationOTP method to send the OTP to the user's email address
      },
    }),
  ],
});

选项

【Options】

• sendVerificationOTP：一个将一次性密码（OTP）发送到用户邮箱的函数。该函数接收一个具有以下属性的对象：

  • email：用户的电子邮件地址。
  • otp: 要发送的 OTP。
  • type：要发送的 OTP 类型。可以是“登录”、“邮箱验证”或“忘记密码”.

  建议不要等待电子邮件发送完成，以避免时间攻击。在无服务器平台上，使用 waitUntil 或类似方法确保电子邮件已发送。

• otpLength：一次性密码（OTP）的长度。默认值为 6。

• expiresIn：OTP 的有效期，单位为秒。默认值为 300 秒。

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            otpLength: 8,
            expiresIn: 600
        })
    ]
})

• sendVerificationOnSignUp：一个布尔值，用于确定在用户注册时是否发送一次性密码（OTP）。默认值为 false。
• disableSignUp：一个布尔值，用于确定是否在用户未注册时阻止自动注册。默认为 false。
• generateOTP：一个生成一次性密码（OTP）的函数。默认生成一个随机的六位数。
• allowedAttempts：验证 OTP 允许的最大尝试次数。默认值为 3。超过此限制后，OTP 将失效，用户需要请求新的 OTP。

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            allowedAttempts: 5, // Allow 5 attempts before invalidating the OTP
            expiresIn: 300
        })
    ]
})

当超过最大尝试次数时，verifyOTP、signIn.emailOtp、verifyEmail 和 resetPassword 方法将返回代码为 TOO_MANY_ATTEMPTS 的错误。

【When the maximum attempts are exceeded, the verifyOTP, signIn.emailOtp, verifyEmail, and resetPassword methods will return an error with code TOO_MANY_ATTEMPTS.】

• storeOTP：在数据库中存储一次性密码（OTP）的方法，无论是 encrypted、hashed 还是 plain 文本。默认是 plain 文本。

或者，你可以传入自定义的加密器或哈希器，将一次性密码存储在你的数据库中。

【Alternatively, you can pass a custom encryptor or hasher to store the OTP in your database.】

自定义加密器

emailOTP({
    storeOTP: { 
        encrypt: async (otp) => {
            return myCustomEncryptor(otp);
        },
        decrypt: async (otp) => {
            return myCustomDecryptor(otp);
        },
    }
})

自定义哈希器

emailOTP({
    storeOTP: {
        hash: async (otp) => {
            return myCustomHasher(otp);
        },
    }
})