@perseidesjs/medusa-plugin-otp

Website | Medusa

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.

Installation

npm install @perseidesjs/medusa-plugin-otp

Usage

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.

Plugin configuration

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)
		},
	},
]

---

Default configuration

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)

How to use

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:

1. Extend the Customer model to add a new field called otp_secret
2. When a Customer is created, generate a random secret and save it in the otp_secret field
3. When a Customer logs in, generate a new OTP
4. Send an e-mail to the customer using a Subscriber and the event used by the TOTPService included in the plugin.
5. Create a new route to verify and authenticate the Customer

1. Extending the Customer model, service and type

1.1. Extending the Customer model

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 select option in the Column decorator.

@Column({ type: 'text', select: false })
otp_secret: string

1.2. Extending the Customer service

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 CustomerService

Don't hesitate to extend other functions you need in the same way by just returning the super function with the extended parameters.

1.3. Creating the migration

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"`)
	}
}

1.4. Module augmentation

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_secret field everywhere the Customer type is used.

2. Generating a secret

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',
	},
}

3. Override the /store/auth route

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 = req.scope.resolve<AuthService>('authService')
	const manager = req.scope.resolve<EntityManager>('manager')

	const result = await manager.transaction(async (transactionManager) => {
		return await authService
			.withTransaction(transactionManager)
			.authenticateCustomer(validated.email, validated.password)
	})

	if (!result.success) {
		res.sendStatus(401)
		return
	}

	const customerService = req.scope.resolve<CustomerService>('customerService')
	const totpService = req.scope.resolve<TOTPService>('totpService')

	const customer = await customerService.retrieve(result.customer?.id || '', {
		relations: defaultRelations,
		select: [...defaultStoreCustomersFields, 'otp_secret'],
	})

	const otp = await totpService.generate(customer.id, customer.otp_secret)

	const { otp_secret, ...rest } = customer // We omit the otp_secret from the response

	res.json({ customer: rest })
}

Now whenever a customer logs in, it will no more register a session cookie, instead, it will generate a new OTP.

4. Subscribing to the event

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.

5. Verifying the OTP

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.

More information

You can find the TOTPService class in the src/services/totp.ts file.

Need Help?

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!

License

This project is licensed under the MIT License - see the LICENSE file for details