@kenmon/email-otp-authenticator

Email OTP authenticator for Kenmon.

Installation

npm install @kenmon/email-otp-authenticator

Usage

import { KenmonEmailOTPAuthenticator } from '@kenmon/email-otp-authenticator'

const emailOTP = new KenmonEmailOTPAuthenticator({
  mailer: new MyMailer(),
  otpStorage: new MyOTPStorage(),
  otpTtl: 300, // 5 minutes (optional)
  otpLength: 6, // (optional)
  emailFrom: '[email protected]',
})

// Send OTP
const result = await emailOTP.sendOTP('[email protected]')
if (result.success) {
  const { otpId, signature } = result.data
  // Show signature to user for verification
}

// Verify OTP
const verifyResult = await emailOTP.verifyOTP({
  email: '[email protected]',
  otpId: 'otp-id-from-send',
  code: '123456',
})
if (verifyResult.success) {
  const identifier = verifyResult.data // { type: 'email-otp', value: '[email protected]' }
}

Configuration

mailer (required)

You must implement this yourself. Instance of KenmonMailer for sending emails via your email service (SendGrid, AWS SES, etc.).

class MyMailer extends KenmonMailer {
  async sendEmail(params: {
    from: string
    to: string | string[]
    subject: string
    textContent?: string
    htmlContent?: string
  }): Promise<void> {
    // Send via your email service
  }
}

otpStorage (required)

You must implement this yourself. Implementation of KenmonEmailOTPStorage for OTP persistence in your database.

class MyOTPStorage implements KenmonEmailOTPStorage {
  async createOTP(
    email: string,
    code: string,
    expiresAt: Date,
    signature: string,
  ): Promise<KenmonEmailOTP> {
    // Save OTP to database and return it
  }

  async getOTPById(id: string): Promise<KenmonEmailOTP | null> {
    // Fetch OTP from database by ID
  }

  async markOTPAsUsed(id: string): Promise<void> {
    // Mark OTP as used in database
  }
}

emailFrom (required)

Sender email address.

otpTtl (optional)

OTP lifetime in seconds. Default: 300 (5 minutes)

otpLength (optional)

OTP code length. Default: 6

emailSubject (optional)

Function to generate email subject: (code: string, signature: string, otpTtl: number) => string

emailTextContent (optional)

Function to generate plain text email body: (code: string, signature: string, otpTtl: number) => string

emailHtmlContent (optional)

Function to generate HTML email body: (code: string, signature: string, otpTtl: number) => string

Custom Email Content

You can customize email content using generator functions:

new KenmonEmailOTPAuthenticator({
  mailer: new MyMailer(),
  otpStorage: new MyOTPStorage(),
  emailFrom: '[email protected]',
  emailSubject: (code, signature, otpTtl) => `Your code: ${code}`,
  emailTextContent: (code, signature, otpTtl) =>
    `Code: ${code}\nSignature: ${signature}\nExpires in ${otpTtl}s`,
  emailHtmlContent: (code, signature, otpTtl) =>
    `<h1>${code}</h1><p>Signature: ${signature}</p><p>Expires: ${otpTtl}s</p>`,
})

See Also

• kenmon - Core authentication service
• nextjs-example - Full implementation with Drizzle