Medusa Plugin - Passwordless Authentication
A plugin for implementing passwordless authentication in Medusa using SMS verification codes with multiple provider support
## Features
- 🔐 Phone number based authentication
- 📱 Multiple SMS provider support (Gupshup and AWS SNS)
- 🔄 Fallback provider configuration with priority settings
- 🔢 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](https://docs.medusajs.com/development/backend/install)
- [Medusa framework](https://docs.medusajs.com/) version >= 2.4.0
- At least one SMS provider account (Gupshup or AWS SNS)
## Installation
1. Install the plugin:
```bash
npm install @devx-commerce/passwordless
# or
yarn add @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: {
// Configure SMS providers with priority
smsProviders: [
{ provider: "gupshup", priority: 1 },
{ provider: "sns", priority: 2 }
],
// 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)
// Gupshup Configuration (required if using Gupshup)
gupshupOptions: {
template: "Your verification code is {passCode}",
accountId: "YOUR_GUPSHUP_ACCOUNT_ID",
accountPassword: "YOUR_GUPSHUP_PASSWORD"
},
// AWS SNS Configuration (required if using SNS)
snsOptions: {
region: "YOUR_AWS_REGION",
accessKeyId: "YOUR_AWS_ACCESS_KEY_ID",
secretAccessKey: "YOUR_AWS_SECRET_ACCESS_KEY"
}
}
}
]
}
}
```
## Configuration Options
### SMS Providers
- `smsProviders`: Array of provider configurations with priority
- `provider`: "gupshup" or "sns"
- `priority`: Number (lower number = higher priority)
### Security Settings
- `codeLength`: Length of verification code (default: 4)
- `codeExpiryMinutes`: Code expiration time in minutes (default: 15)
- `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)
### Provider-Specific Configuration
#### Gupshup
```javascript
gupshupOptions: {
template: "Your verification code is {passCode}",
accountId: "YOUR_GUPSHUP_ACCOUNT_ID",
accountPassword: "YOUR_GUPSHUP_PASSWORD"
}
```
#### AWS SNS
```javascript
snsOptions: {
region: "YOUR_AWS_REGION",
accessKeyId: "YOUR_AWS_ACCESS_KEY_ID",
secretAccessKey: "YOUR_AWS_SECRET_ACCESS_KEY"
}
```
## How It Works
1. **Authentication Flow**:
- User provides phone number
- System generates a secure verification code
- Code is sent via SMS using configured providers
- User enters the code to complete authentication
2. **Provider Selection**:
- Providers are tried in order of priority
- If highest priority provider fails, next provider is tried
- Process stops as soon as one provider succeeds
3. **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
## License
MIT