Passwordless

Medusa Plugin - Passwordless Authentication

Documentation | Website

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, AWS SNS, and ValueFirst)
• 🔄 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
• Medusa framework version >= 2.4.0
• At least one SMS provider account (Gupshup, AWS SNS, or ValueFirst)

Installation

1. Install the plugin:

123
npm install @devx-commerce/passwordless
# or
yarn add @devx-commerce/passwordless

1. Add the plugin to your Copy to clipboardmedusa-config.js:

1234567891011121314151617181920
{
  resolve: "@medusajs/medusa/auth",
  options: {
    providers: [
      {
        resolve: `@devx-commerce/passwordless/providers/passwordless`,
        id: "passwordless",
        options: {
          // Configure SMS providers with priority
          smsProviders: [
            { provider: "limechat", priority: 1 },
            { provider: "valuefirst", priority: 2 },
            { provider: "gupshup", priority: 3 },
            { provider: "sns", priority: 4 }
          ],

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

Configuration Options

SMS Providers

• Copy to clipboardsmsProviders: Array of provider configurations with priority
  • Copy to clipboardprovider: "gupshup", "sns", "valuefirst", or "limechat"
  • Copy to clipboardpriority: Number (lower number = higher priority)

Security Settings

• Copy to clipboardcodeLength: Length of verification code (default: 4)
• Copy to clipboardcodeExpiryMinutes: Code expiration time in minutes (default: 15)
• Copy to clipboardmaxAttempts: Maximum verification attempts (default: 3)
• Copy to clipboardsmsRateLimitMinutes: Time between SMS requests in minutes (default: 10)
• Copy to clipboardblockDurationMinutes: Block duration after max attempts in minutes (default: 5)

Provider-Specific Configuration

Gupshup

12345
gupshupOptions: {
  template: "Your verification code is {passCode}",
  accountId: "YOUR_GUPSHUP_ACCOUNT_ID",
  accountPassword: "YOUR_GUPSHUP_PASSWORD"
}

AWS SNS

12345
snsOptions: {
  region: "YOUR_AWS_REGION",
  accessKeyId: "YOUR_AWS_ACCESS_KEY_ID",
  secretAccessKey: "YOUR_AWS_SECRET_ACCESS_KEY"
}

ValueFirst

123456
valueFirstOptions: {
  username: "YOUR_VALUEFIRST_USERNAME",
  password: "YOUR_VALUEFIRST_PASSWORD",
  fromAddress: "MYAPP1", // 6-character sender ID for Indian numbers
  apiUrl: "https://api.myvfirst.com/psms/servlet/psms.JsonEservice" // Optional
}

ValueFirst Features:

• Automatic token management (7-day token lifetime)
• Support for Indian and international numbers
• Sender ID compliance with TRAI guidelines
• Fallback support when combined with other providers

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

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

1. Verification

12345
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