Medusa Plugin - Passwordless Authentication

Documentation |
Website

A plugin for implementing passwordless authentication in Medusa

Features

- 🔐 Phone number based authentication
- 🔢 Secure verification code generation and validation
- ⏱️ Rate limiting with maximum attempt controls
- ⏳ Code expiration management
- 🔌 Easy integration with existing Medusa stores

This plugin requires:

- Medusa backend
- Medusa framework version >= 2.7.0

Installation

1. Install the plugin:

``bash
npm install @devx-commerce/passwordless
`

2. Add the plugin to your medusa-config.js:

`javascript
{
resolve: "@medusajs/medusa/auth",
options: {
providers: [
{
resolve: @devx-commerce/passwordless/providers/passwordless,
id: "passwordless",
options: {
jwtSecret: "secret", // JWT secret for token generation

limeChatOptions: {
webhookUrl: process.env.LIMECHAT_WEBHOOK_URL,
typeId: process.env.LIMECHAT_TYPE_ID,
},

// Optional configuration
codeLength: 6, // Length of verification code (default: 4)
codeExpiryMinutes: 10, // Code expiration time in minutes (default: 15)
maxAttempts: 5, // Maximum verification attempts (default: 3)
smsRateLimitMinutes: 5, // Time between SMS requests in minutes (default: 10)
blockDurationMinutes: 10, // Block duration after max attempts in minutes (default: 5)

}
}
]
}
}
`

Configuration Options

$3

- codeLength: Length of verification code (default: 4)
- codeExpiryMinutes: Code expiration time in minutes (default: 3)
- maxAttempts: Maximum verification attempts (default: 3)
- smsRateLimitMinutes: Time between SMS requests in minutes (default: 10)
- blockDurationMinutes: Block duration after max attempts in minutes (default: 5)

How It Works

1. Authentication Flow:

- User provides phone number
- System generates a secure verification code
- User enters the code to complete authentication

2. Security Features:
- Rate limiting prevents abuse
- Maximum attempt controls
- Code expiration
- Secure code generation

Usage

The plugin provides two main endpoints:

1. Authentication Request

`json
POST /auth/customer/passwordless
{
"phone": "+1234567890"
}
`

2. Verification

`json
POST /auth/customer/passwordless/callback
{
"phone": "+1234567890",
"code": "1234"
}
``

Phone Number Format

Phone numbers must be in E.164 format:

- Starts with '+'
- Country code
- National number
- Example: +1234567890

Error Handling

The plugin provides clear error messages for various scenarios:

- Invalid phone number format
- Rate limit exceeded
- Maximum attempts exceeded
- Invalid or expired code
- Provider-specific errors