Passwordless

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:

npm install @devx-commerce/passwordless

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

1{
2  resolve: "@medusajs/medusa/auth",
3  options: {
4    providers: [
5      {
6        resolve: `@devx-commerce/passwordless/providers/passwordless`,
7        id: "passwordless",
8        options: {
9          jwtSecret: "secret",              // JWT secret for token generation
10
11          limeChatOptions: {
12            webhookUrl: process.env.LIMECHAT_WEBHOOK_URL,
13            typeId: process.env.LIMECHAT_TYPE_ID,
14          },
15
16          // Optional configuration
17          codeLength: 6,                    // Length of verification code (default: 4)
18          codeExpiryMinutes: 10,            // Code expiration time in minutes (default: 15)
19          maxAttempts: 5,                   // Maximum verification attempts (default: 3)
20          smsRateLimitMinutes: 5,           // Time between SMS requests in minutes (default: 10)
21          blockDurationMinutes: 10,         // Block duration after max attempts in minutes (default: 5)
22
23        }
24      }
25    ]
26  }
27}

Configuration Options

Security Settings

• 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

1POST /auth/customer/passwordless
2{
3  "phone": "+1234567890"
4}

1. Verification

1POST /auth/customer/passwordless/callback
2{
3  "phone": "+1234567890",
4  "code": "1234"
5}

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