@coddletech/medusa-admin-2fa

A Two-Factor Authentication (2FA) plugin for Medusa.js v2.8+ Admin, powered by TOTP with QR code support.

This plugin is built specifically for enhancing the Medusa Admin panel with secure multi-factor authentication (MFA). It simplifies the integration of QR code-based 2FA using speakeasy and qrcode, and includes:

Secure session-based secret handling

OTP verification via time-based tokens

Auto-scaffolded authex module structure via a post-install script

Installation

npm install @coddletech/medusa-admin-2fa

Upon installation, a postinstall script will automatically generate the following folder structure:

src/ |---─ api/
|    └---middlewares.ts
|---- modules/ 
     └---authex/ 
        |--- models/ 
        | |--- info.ts
        | |---user.ts
        |----index.ts
        |─-- service.ts

Configuration

Register the Module

In your medusa-config.ts:

export default { modules: 
    [ { resolve: "./src/modules/authex", },
 // ...other modules ], }

Run Migrations

After scaffolding is complete, run the following commands to generate and apply your database schema:

npx medusa db:generate authex 

npx medusa db:migrate

Usage

Generate MFA QR Code

/src/api/admin/generate-qr/route.ts

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" 
import { handleMfaSetup } from "@coddletech/medusa-admin-2fa" 
import AuthexModuleService from "../../../modules/authex/service"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => { const authexService = req.scope.resolve("authex") as AuthexModuleService await handleMfaSetup(req, res, authexService) }

This route:

Generates a new TOTP secret (if not already set)

Stores the secret in the session

Returns a QR code as a Data URL to be scanned by an authenticator app

Verify MFA Code

/src/api/admin/verify-mfa/route.ts

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" 
import { handleMfaVerification } from "@coddletech/medusa-admin-2fa"
 import AuthexModuleService from "../../../modules/authex/service"

export const POST = async (req: MedusaRequest, res: MedusaResponse) => { const 
authexService = req.scope.resolve("authex") as AuthexModuleService await handleMfaVerification(req, res, authexService) }

This route:

Verifies the 6-digit passcode sent by the user

If valid, saves the TOTP secret in your DB

Cleans up the session and grants access

Features

TOTP (Google Authenticator-style) 2FA

Automatic module scaffolding

Session-based secret storage

Optional middleware protection

Built on MedusaJS v2 module system

Requirements

Node.js v18+

MedusaJS v2.8+

PostgreSQL (recommended)

Built With

MedusaJS

Speakeasy

QRCode

Express session for secure server-side secret handling