A Medusa's plugin for implementing OTP on Medusa v1.x.x
Here's a quick preview of the plugin in action allowing you to authenticate your customers using OTP and without the need of a password.
npm install @perseidesjs/medusa-plugin-otp
This plugin uses Redis under the hood, this plugin will also work in a development environment thanks to the fake Redis instance created by Medusa, remember to use Redis in production, by just passing the redis_url option to the medusa-config.js > projectConfig object.
You need to add the plugin to your Medusa configuration before you can use the OTPService. To do this, import the plugin as follows:
const plugins = [
`medusa-fulfillment-manual`,
`medusa-payment-manual`,
`@perseidesjs/medusa-plugin-otp`,
]You can also override the default configuration by passing an object to the plugin as follows:
const plugins = [
`medusa-fulfillment-manual`,
`medusa-payment-manual`,
{
resolve: `@perseidesjs/medusa-plugin-otp`,
/** @type {import('@perseidesjs/medusa-plugin-otp').PluginOptions} */
options: {
ttl: 30, // In seconds, the time to live of the OTP before expiration
digits: 6, // The number of digits of the OTP (e.g. 123456)
},
},
]| Option | Type | Default | Description |
|---|---|---|---|
| ttl | Number |
60 |
The time to live of the OTP before expiration |
| digits | Number |
6 |
The number of digits of the OTP (e.g. 123456) |
In this example, we're going to override the current authentication system for the store (`/store/auth`). The workflow we're going to implement is as follows:
- Extend the Customer model to add a new field called
otp_secret - When a Customer is created, generate a random secret and save it in the
otp_secretfield - When a Customer logs in, generate a new OTP
- Send an e-mail to the customer using a
Subscriberand the event used by theTOTPServiceincluded in the plugin. - Create a new route to verify and authenticate the Customer
First, we need to extend the Customer model to add a new field called otp_secret.
import { Customer as MedusaCustomer } from '@medusajs/medusa'
import { Column, Entity } from 'typeorm'
@Entity()
export class Customer extends MedusaCustomer {
@Column({ type: 'text' })
otp_secret: string
}If you don't want to expose the field to the API response, you can also add the
selectoption in theColumndecorator.@Column({ type: 'text', select: false }) otp_secret: string
We then need to extend the Customer service to make sure the update function will not throw a TypeScript error with the new otp_secret field.
// src/services/customer.ts
import {
Customer,
CustomerService as MedusaCustomerService,
} from '@medusajs/medusa'
// We alias the UpdateCustomerInput type to avoid name conflicts
import { UpdateCustomerInput as MedusaUpdateCustomerInput } from '@medusajs/medusa/dist/types/customers'
import { Lifetime } from 'awilix'
// 1. Extend the UpdateCustomerInput type to include the otp_secret field
type UpdateCustomerInput = MedusaUpdateCustomerInput & {
otp_secret?: string
}
class CustomerService extends MedusaCustomerService {
static LIFE_TIME = Lifetime.SCOPED
constructor() {
// @ts-ignore
super(...arguments)
}
// 2. Override the update method to use the new `UpdateCustomerInput` type that includes the `otp_secret` field
async update(
customerId: string,
update: UpdateCustomerInput,
): Promise<Customer> {
return await super.update(customerId, update)
}
}
export default CustomerServiceDon't hesitate to extend other functions you need in the same way by just returning the super function with the extended parameters.
Don't forget to create the migration for this model to add the otp_secret field to the customers table.
import { MigrationInterface, QueryRunner } from 'typeorm'
export class AddOtpSecretToCustomer1719843922955 implements MigrationInterface {
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE "customer" ADD "otp_secret" text`)
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE "customer" DROP COLUMN "otp_secret"`)
}
}
Finally, we need to tell TypeScript that the Customer model has a new field called otp_secret.
// src/index.d.ts
declare module '@medusajs/medusa/dist/models/customer' {
interface Customer {
otp_secret?: string
}
}This will allows you to get the
otp_secretfield everywhere theCustomertype is used.
When a new Customer is created, we need to generate a random secret and save it in the otp_secret field.
For this, we're going to register a Subscriber for the CustomerService.Events.CREATED event.
// src/subscribers/customer-created.ts
import type { Logger, SubscriberArgs, SubscriberConfig } from '@medusajs/medusa'
import type { TOTPService } from '@perseidesjs/medusa-plugin-otp'
import type { CustomerService } from '../services/customer'
type CustomerCreatedEventData = {
id: string // Customer ID
}
/**
* This subscriber will be triggered when a new customer is created.
* It will add an OTP secret to the customer for the sake of OTP authentication.
*/
export default async function setOtpSecretForCustomerHandler({
data,
container,
}: SubscriberArgs<CustomerCreatedEventData>) {
const logger = container.resolve<Logger>('logger')
const activityId = logger.activity(
`Adding OTP secret to customer with ID : ${data.id}`,
)
const customerService = container.resolve<CustomerService>('customerService')
const totpService = container.resolve<TOTPService>('totpService')
const otpSecret = totpService.generateSecret()
await customerService.update(data.id, {
otp_secret: otpSecret,
})
logger.success(
activityId,
`Successfully added OTP secret to customer with ID : ${data.id}!`,
)
}
export const config: SubscriberConfig = {
event: CustomerService.Events.CREATED,
context: {
subscriberId: 'set-otp-for-customer-handler',
},
}Now every customer who creates an account will have a unique key enabling him to generate unique OTPs for his account, we're now going to override the current auth route used by Medusa to generate an OTP for the customer instead of the default one.
// src/api/store/auth/route.ts
import {
StorePostAuthReq,
defaultStoreCustomersFields,
validator,
type AuthService,
type MedusaRequest,
type MedusaResponse,
} from '@medusajs/medusa'
import { defaultRelations } from '@medusajs/medusa/dist/api/routes/store/auth'
import type { TOTPService } from '@perseidesjs/medusa-plugin-otp'
import type { EntityManager } from 'typeorm'
import type { CustomerService } from '../../../services/customer'
export async function POST(req: MedusaRequest, res: MedusaResponse) {
const validated = await validator(StorePostAuthReq, req.body)
const authService: AuthService = req.scope.resolve('authService')
const manager: EntityManager = req.scope.resolve('manager')
const result = await manager.transaction(async (transactionManager) => {
return await authService
.withTransaction(transactionManager)
.authenticateCustomerOTP(validated.email)
})
if (!result.success) {
// ℹ️ We don't want to leak information about the email being invalid
res.status(200).json({
message: 'If the email is valid, you will receive an OTP to your email.',
})
return
}
const customerService: CustomerService = req.scope.resolve('customerService')
const totpService: TOTPService = req.scope.resolve('totpService')
const customer = await customerService.retrieve(result.customer?.id || '', {
relations: defaultRelations,
select: [...defaultStoreCustomersFields, 'otp_secret'],
})
await totpService.generate(customer.id, customer.otp_secret)
res.status(200).json({
message: 'If the email is valid, you will receive an OTP to your email.',
})
}Now whenever a customer logs in, it will no more register a session cookie, instead, it will generate a new OTP.
Before we move on, the current route needs an email and a password, we're going to change that, to make sure we only need an email.
We'll start by creating a new file in the `src/api` directory to override the `StorePostAuthReq` validator.
// src/api/index.ts
import { registerOverriddenValidators, StorePostAuthReq as MedusaStorePostAuthReq } from '@medusajs/medusa'
import { IsString, IsOptional } from 'class-validator'
class StorePostAuthReq extends MedusaStorePostAuthReq {
@IsString()
@IsOptional() // ℹ️ Since we can't remove a field on the original validator, we make it optional
password: string
}
registerOverriddenValidators(StorePostAuthReq) You can subscribe to the event TOTPService.Events.GENERATED to be notified when a new OTP is generated, the key used here for example is the customer ID :
// src/subscribers/otp-generated.ts
import type { Logger, SubscriberArgs, SubscriberConfig } from "@medusajs/medusa";
import type { TOTPService } from "@perseidesjs/medusa-plugin-otp";
import type { CustomerService } from '../services/customer'
type OTPGeneratedEventData = {
key: string // Customer ID
otp: string // The OTP generated
}
/**
* Send the OTP to the customer whenever the TOTP is generated.
*/
export default async function sendTOTPToCustomerHandler({
data,
container
}: SubscriberArgs<OTPGeneratedEventData>) { // The key here is the customer ID
const logger = container.resolve<Logger>("logger")
const customerService = container.resolve<CustomerService>("customerService")
const customer = await customerService.retrieve(data.key)
const activityId = logger.activity(`Sending OTP to customer with ID : ${customer.id}`)
// Use your NotificationService here to send the `data.otp` to the customer (e.g. SendGrid, SMS...)
logger.success(activityId, `Successfully sent OTP to customer with ID : ${customer.id}!`)
}
export const config: SubscriberConfig = {
event: TOTPService.Events.GENERATED,
context: {
subscriberId: 'send-totp-to-customer-handler'
}
}Your customer will now receive an OTP, let's see how to verify it once it's consumed by your customer.
We're now going to create a new route to verify the OTP, this route will be called by the customer when they want to log in, we're going to use the TOTPService to verify the OTP and authenticate the customer.
// src/api/store/auth/otp/route.ts
import { validator, type MedusaRequest, type MedusaResponse } from "@medusajs/medusa";
import { IsEmail, IsString, MaxLength, MinLength } from "class-validator";
import type { TOTPService } from "@perseidesjs/medusa-plugin-otp";
import type { CustomerService } from '../../../services/customer'
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const validated = await validator(StoreVerifyOTP, req.body);
const customerService = req.scope.resolve<CustomerService>("customerService");
const totpService = req.scope.resolve<TOTPService>("totpService");
const customer = await customerService.retrieveRegisteredByEmail(validated.email);
const isValid = await totpService.verify(customer.id, validated.otp)
if (!isValid) {
res.status(400).send({ error: "OTP is invalid" });
return
}
// Set customer id on session, this is stored on the server (connect_sid).
req.session.customer_id = customer.id;
res.status(200).json({ customer })
}
class StoreVerifyOTP {
@IsString()
otp: string;
@IsEmail()
email: string;
}Your customer is now authenticated, and the `connect_sid` cookie is set on the response.
You can find the TOTPService class in the src/services/totp.ts file.
If you encounter any issues or have any questions, please do not hesitate to open a new issue on our GitHub repository. We're here to help!
This project is licensed under the MIT License - see the LICENSE file for details