customer-registration 0.0.111 → 0.0.113

package/README.md

@@ -1,18 +1,20 @@
 # Medusa Plugin: Customer Registration & OTP Verification
 
-A comprehensive Medusa v2 plugin that provides OTP-based verification for email and phone functionality, with support for Medusa's built-in password reset flow.
+A comprehensive Medusa v2 plugin that provides OTP-based verification for email and phone functionality, with support for flexible registration identifiers, phone-only authentication, contact change flows, and account deletion.
 
 ## Features
 
-- ✅ **Unified OTP API**: Single endpoints for sending and verifying OTPs
-- ✅ **Token-based Verification**: Secure JWT token system for OTP verification
-- ✅ **Multiple Verification Types**: Email verification and phone verification
-- ✅ **Workflow-based Processing**: Automatic handling of verification flags
-- ✅ **Password Reset Support**: Notification subscriber for Medusa's built-in password reset flow
-- ✅ **Flexible Configuration**: Per-purpose channel configuration (email/SMS)
-- ✅ **Automatic Contact Detection**: Automatically selects email/phone from customer based on channel
-- ✅ **Throttling & Rate Limiting**: Built-in protection against abuse
-- ✅ **Database Migrations**: Automatic schema updates for verification columns
+- **Unified OTP API**: Single endpoints for sending and verifying OTPs
+- **Token-based Verification**: Secure JWT token system for OTP verification
+- **Multiple Verification Types**: Email verification and phone verification
+- **Workflow-based Processing**: Automatic handling of verification flags
+- **Password Reset Support**: Notification subscriber for Medusa's built-in password reset flow
+- **Flexible Configuration**: Per-purpose channel configuration (email/SMS)
+- **Throttling & Rate Limiting**: Built-in protection against OTP spam
+- **Database Migrations**: Automatic schema updates for verification columns
+- **Account Deletion Request Flow**: Two-step OTP flow to request and confirm account deletion with optional cancel flow
+- **Phone-only Authentication**: `phonepass` auth provider for registering and logging in with phone + password (no email required)
+- **Authenticated Contact Change**: Dedicated OTP-verified routes for updating phone or email — new value is embedded in the signed JWT, no metadata staging required
 
 ## Quick Start
 
@@ -30,16 +32,31 @@ export default defineConfig({
     {
       resolve: "customer-registration",
       options: {
-        // Storefront URL for constructing reset password links
-        storefrontUrl: "http://localhost:8000", // Optional: base URL for reset links
-        
-        // Password reset configuration
+        storefrontUrl: "http://localhost:8000",
+
+        registration: {
+          identifier: "phone", // "email" | "phone" | "both"
+          require_verification: true,
+        },
+        login: {
+          identifier: "phone", // defaults to registration.identifier
+        },
+
         password_reset: {
-          template: "src/templates/emails/password-reset.html", // Required: path to HTML template
-          subject: "Reset Your Password", // Optional: email subject
+          template: "src/templates/emails/password-reset.html",
+          subject: "Reset Your Password",
+        },
+
+        account_deletion_request: {
+          template: "src/templates/emails/account-deletion-request.html",
+          subject: "Confirm your account deletion request",
+          scheduled_days: 7,
         },
-        
-        // OTP channel configuration
+        account_deletion_cancel: {
+          template: "src/templates/emails/account-deletion-cancel.html",
+          subject: "Confirm cancellation of account deletion",
+        },
+
         email_verification: {
           channel: "email",
           subject: "Verify your email",
@@ -53,33 +70,17 @@ export default defineConfig({
 })
 ```
 
-**Required Options:**
-- `password_reset.template` - Path to HTML template file for password reset emails
-
 3. **Run migrations**:
 ```bash
 npx medusa db:migrate
 ```
 
-4. **Use the API**:
-```bash
-# Send OTP
-POST /store/customers/otp/send
-{
-  "customer_id": "cus_...",
-  "type": "email_verification"
-}
-
-# Verify OTP
-POST /store/customers/otp/verify
-{
-  "token": "...",
-  "code": "123456"
-}
-```
+4. **Use the API** — see [API Endpoints](#api-endpoints) below.
 
 📖 **For complete documentation, see [USAGE.md](./USAGE.md)**
 
+---
+
 ## Installation
 
 ### Local Development
@@ -96,18 +97,7 @@ cd ../../test-medusa
 npx medusa plugin:add customer-registration
 ```
 
-3. Register the plugin in `medusa-config.ts`:
-```typescript
-module.exports = defineConfig({
-  // ... other config
-  plugins: [
-    {
-      resolve: "customer-registration",
-      options: {},
-    },
-  ],
-})
-```
+3. Register the plugin in `medusa-config.ts` (see Quick Start above).
 
 4. Start development mode (in plugin directory):
 ```bash
@@ -121,137 +111,386 @@ cd ../../test-medusa
 yarn dev
 ```
 
-## Usage
-
-### Registration lifecycle hook
-
-The plugin no longer overrides `POST /store/customers`. Instead, it listens to the `customer.created` event and automatically issues an email OTP (when `email.autoSendOnRegistration` is enabled). Because the default Medusa route still handles persistence and response formatting, there are no behavioral differences for registration requests aside from the verification guard.
+---
 
-### API Endpoints
+## Configuration
 
-The plugin provides unified OTP endpoints:
-
-| Endpoint | Method | Description |
-| --- | --- | --- |
-| `/store/customers/otp/send` | POST | Send OTP for email/phone verification |
-| `/store/customers/otp/verify` | POST | Verify OTP code and execute appropriate workflow |
+### `registration.identifier`
 
-**Request Types**:
-- `email_verification` - Verify customer email
-- `phone_verification` - Verify customer phone
-- Note: Password reset uses Medusa's built-in flow (see Password Reset section below)
+Controls which field is required at sign-up:
 
-See [USAGE.md](./USAGE.md) for detailed API documentation and examples.
+| Value | Behaviour |
+|---|---|
+| `"email"` (default) | Email required; standard Medusa registration |
+| `"phone"` | Phone required; no email needed; uses `phonepass` provider |
+| `"both"` | Both email and phone required |
 
-### Example Flow
+### `login.identifier`
 
-1. **Register Customer** - Use standard Medusa customer registration endpoint
-2. **Send OTP** - Request OTP using unified endpoint with type
-3. **Verify OTP** - Verify code using token from send response
-4. **Login** - Customer can login after email verification
+Controls which auth providers are accepted at login. Defaults to `registration.identifier`.
 
-See [USAGE.md](./USAGE.md) for complete examples and integration guide.
+| Value | Accepted login methods |
+|---|---|
+| `"email"` | `POST /auth/customer/emailpass` only |
+| `"phone"` | `POST /auth/customer/phonepass` only |
+| `"both"` | Both emailpass and phonepass accepted |
 
-### Configuration
-
-The plugin uses purpose-based configuration:
+### Full options reference
 
 ```typescript
 {
   resolve: "customer-registration",
   options: {
-    otpLength: 6,
-    otpCharset: "numeric",
-    otpExpiryMinutes: 15,
-    maxAttempts: 5,
-    email_verification: {
-      channel: "email",
-      template: "otp-email-verify",
-      subject: "Verify your email",
-      resendThrottleSeconds: 90,
+    storefrontUrl?: string,          // Base URL for password reset links
+
+    registration?: {
+      identifier?: "email" | "phone" | "both",  // default: "email"
+      require_verification?: boolean,            // default: true
+    },
+    login?: {
+      identifier?: "email" | "phone" | "both",  // default: registration.identifier
+    },
+
+    // OTP settings (apply to all types)
+    otpLength?: number,              // default: 6
+    otpCharset?: "numeric" | "alphanumeric",  // default: "numeric"
+    otpExpiryMinutes?: number,       // default: 15
+    maxAttempts?: number,            // default: 5
+
+    email_verification?: {
+      channel: string,               // e.g. "email"
+      template?: string,
+      subject?: string,
+      resendThrottleSeconds?: number,
+      autoSendOnRegistration?: boolean,
     },
-    phone_verification: {
-      channel: "sms",
-      template: "otp-phone-verify",
-      resendThrottleSeconds: 60,
+    phone_verification?: {
+      channel: string,               // e.g. "sms"
+      template?: string,
+      resendThrottleSeconds?: number,
+    },
+
+    password_reset?: {
+      template: string,              // Required when using password reset
+      subject?: string,
+    },
+    account_deletion_request?: {
+      template: string,
+      subject?: string,
+      scheduled_days?: number,       // default: 7
+    },
+    account_deletion_cancel?: {
+      template: string,
+      subject?: string,
     },
   },
 }
 ```
 
-See [USAGE.md](./USAGE.md) for complete configuration reference.
+---
 
-### Database Migrations
+## API Endpoints
 
-The plugin includes two migrations:
+### Registration & Initial Verification
 
-1. **Migration20250120000000AddCustomerVerificationColumns**
-   - Adds `email_verified` and `phone_verified` columns to customer table
-   - Creates indexes for performance
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/store/customers` | POST | Bearer (pre-customer) | Create customer account |
+| `/store/customers/otp/send` | POST | — | Send OTP for initial email/phone verification |
+| `/store/customers/otp/verify` | POST | — | Verify OTP code; returns login token on success |
 
-2. **Migration20250118001000CreateOtpVerificationTable**
-   - Creates `otp_verification` table for storing OTP records
+#### Send OTP
 
-Run migrations after installation:
 ```bash
-npx medusa db:migrate
+POST /store/customers/otp/send
+{
+  "customer_id": "cus_...",
+  "type": "phone_verification"  # or "email_verification"
+}
+# Response: { "token": "...", "expires_at": "..." }
 ```
 
-## Requirements
+#### Verify OTP
 
-- Medusa v2.11.2 or higher
-- Node.js >= 20
-- Notification module configured with at least one provider (email/SMS)
-- Database migrations applied (`npx medusa db:migrate`)
+```bash
+POST /store/customers/otp/verify
+{
+  "token": "<token from send>",
+  "code": "482917"
+}
+# Response: { "verified": true, "customer": {...}, "token": "<login jwt>", "needs_login": false }
+```
 
-## Documentation
+---
 
-- **[USAGE.md](./USAGE.md)** - Complete usage guide with examples
-- **[README.md](./README.md)** - This file (overview and quick start)
+### Login
 
-## Modules
+| Endpoint | Method | Description |
+|---|---|---|
+| `/auth/customer/emailpass` | POST | Login with email + password |
+| `/auth/customer/phonepass` | POST | Login with phone + password |
+| `/auth/customer/emailpass/register` | POST | Create emailpass auth identity |
+| `/auth/customer/phonepass/register` | POST | Create phonepass auth identity |
 
-The plugin includes two modules:
+---
 
-1. **`otp-verification`** - OTP generation, verification, and management
-2. **`customer-registration`** - Customer registration logic and overrides
+### Contact Change (Phone or Email Update)
 
-## Workflows
+> These are the dedicated authenticated routes for changing a customer's phone or email.
+> `PATCH /store/customers/me` **rejects** `phone` and `email` fields — all contact changes must go through these endpoints.
 
-The plugin uses workflows for different verification types:
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/store/customers/me/contact` | POST | Customer JWT | Request contact change — validates new value, sends OTP, returns token |
+| `/store/customers/me/contact/verify` | POST | Customer JWT | Verify OTP and apply the change |
 
-- `verify-email` - Sets email_verified flag
-- `verify-phone` - Sets phone_verified flag
+#### How it works
 
-## Password Reset
+The new phone or email is embedded directly in the signed OTP JWT. No metadata is written to the customer record during the pending state. On successful verification:
 
-This plugin provides password reset functionality using Medusa's AUTH module:
+1. `customer.phone` / `customer.email` is updated
+2. `phone_verified` / `email_verified` is set to `true`
+3. `provider_identity.entity_id` is updated for `phonepass` / `emailpass` **only when the changed field is the active `login.identifier`** — so login continues to work with the new value
 
-1. **Request Reset**: POST to `/auth/customer/emailpass/reset-password` with email (or `identifier`)
-   - Custom route that generates JWT reset token using Medusa's `generateJwtTokenForAuthIdentity`
-   - Sends password reset email directly via notification service
-   - Returns 201 status (matches Medusa's built-in route behavior)
-2. **Email Sent**: Password reset email is sent with reset token and URL
-3. **Complete Reset**: POST to `/auth/customer/emailpass/update` with token and new password
-   - Uses AUTH module's `authenticate()` method with `update-password` action
-   - AUTH module validates token and updates password
+#### Step 1 — Request the change
 
-**Key Features:**
-- Uses Medusa's AUTH module for token generation and password updates
-- Custom routes that match Medusa's built-in route behavior
-- Email sending handled directly in the route (subscriber available for `auth.password_reset` event)
-- Consistent with Medusa's authentication patterns
+```bash
+curl -X POST http://localhost:9000/store/customers/me/contact \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $CUSTOMER_JWT" \
+  -d '{ "phone": "+15559998888" }'
 
-**Note:** These custom routes override Medusa's built-in routes at the same paths. The subscriber listens to `auth.password_reset` event (emitted by Medusa's built-in route) but since we're using custom routes, emails are sent directly from the route.
+# Response
+{ "token": "<otp_token>", "expires_at": "2026-03-12T10:15:00.000Z" }
+```
 
-**Configuration Required:**
-- Set `password_reset.template` in plugin options (path to HTML template file)
-- Configure email template with ID `password-reset` in your notification provider (optional, subscriber includes HTML)
-- Ensure AUTH module is configured with `emailpass` provider
+Only one field at a time is accepted. Sending both `phone` and `email` returns a `400`.
 
-**Helper Functions:**
+#### Step 2 — Verify the OTP
 
-The plugin provides helper functions for password reset operations:
+```bash
+curl -X POST http://localhost:9000/store/customers/me/contact/verify \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $CUSTOMER_JWT" \
+  -d '{
+    "token": "<otp_token from step 1>",
+    "code": "482917"
+  }'
+
+# Response
+{
+  "customer": { "id": "cus_...", "phone": "+15559998888", ... },
+  "token": "<fresh_login_jwt>"
+}
+```
+
+The response includes a **fresh login JWT** so the caller is immediately re-authenticated after the change.
+
+#### Security notes
+
+- The OTP token is signed with the server's `jwtSecret` — the new value cannot be tampered with
+- The verify route checks that `token.customer_id === auth_context.actor_id`, preventing one customer from applying another's OTP
+- `provider_identity.entity_id` sync has a compensation function: if a later workflow step fails the `entity_id` is rolled back to the original value
+- If the current phone/email is `null` (first-time contact assignment), the flow works identically — the field is set from null to the new value and marked verified
+
+#### What `PATCH /store/customers/me` does now
+
+Non-contact fields (e.g. `first_name`, `last_name`) continue to work as before. Passing `phone` or `email` in the body returns:
+
+```json
+{
+  "type": "not_allowed",
+  "message": "Phone changes require OTP verification. Use POST /store/customers/me/contact to request a change."
+}
+```
+
+---
+
+### Profile Update
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/store/customers/me` | PATCH | Customer JWT | Update non-contact profile fields (first_name, last_name, etc.) |
+
+---
+
+### Password Reset
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/auth/customer/emailpass/reset-password` | POST | Request password reset email |
+| `/auth/customer/emailpass/update` | POST | Complete password reset with token |
+
+```bash
+# Request reset
+POST /auth/customer/emailpass/reset-password
+{ "identifier": "customer@example.com" }
+
+# Complete reset
+POST /auth/customer/emailpass/update
+{ "token": "<reset_token>", "password": "NewPassword123!" }
+```
+
+---
+
+### Account Deletion
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/store/customers/account-deletion/request` | POST | Customer JWT | Request deletion — sends OTP, returns token |
+| `/store/customers/account-deletion/confirm` | POST | — | Confirm deletion with OTP code |
+| `/store/customers/account-deletion/cancel-request` | POST | — | Request cancellation (lookup by email/phone) |
+| `/store/customers/account-deletion/cancel-confirm` | POST | — | Confirm cancellation with OTP code |
+| `/admin/account-deletion-requests` | GET | Admin JWT | List deletion requests |
+
+```bash
+# 1. Request deletion
+curl -X POST http://localhost:9000/store/customers/account-deletion/request \
+  -H "Authorization: Bearer $CUSTOMER_JWT" \
+  -d '{"reason": "No longer need account"}'
+# Response: { "token": "...", "expires_at": "..." }
+
+# 2. Confirm deletion
+curl -X POST http://localhost:9000/store/customers/account-deletion/confirm \
+  -d '{"token": "...", "code": "123456"}'
+
+# 3. Request cancel (no auth; email lookup)
+curl -X POST http://localhost:9000/store/customers/account-deletion/cancel-request \
+  -d '{"email": "customer@example.com"}'
+
+# 4. Confirm cancel
+curl -X POST http://localhost:9000/store/customers/account-deletion/cancel-confirm \
+  -d '{"token": "...", "code": "123456"}'
+```
+
+---
+
+## Phone-only Registration & Login (`phonepass`)
+
+When `registration.identifier = "phone"`, customers register and log in with phone + password only. No email address is required.
+
+### 1. Register the provider in `medusa-config.ts`
+
+```typescript
+import { Modules } from "@medusajs/framework/utils"
+
+export default defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/auth",
+      options: {
+        providers: [
+          {
+            resolve: "customer-registration/providers/phonepass",
+            id: "phonepass",
+          },
+        ],
+      },
+    },
+  ],
+  plugins: [
+    {
+      resolve: "customer-registration",
+      options: {
+        registration: {
+          identifier: "phone",
+          require_verification: true,
+        },
+        login: {
+          identifier: "phone",
+        },
+        phone_verification: {
+          channel: "sms",
+        },
+      },
+    },
+  ],
+})
+```
+
+### 2. Registration flow
+
+```bash
+# Step 1 — create phonepass auth identity
+POST /auth/customer/phonepass/register
+{ "phone": "+15551234567", "password": "SecretPass1!" }
+# Response: { "token": "<pre-customer jwt>" }
+
+# Step 2 — create customer record
+POST /store/customers
+Authorization: Bearer <token>
+{ "phone": "+15551234567", "first_name": "Jane" }
+
+# Step 3 — send phone OTP
+POST /store/customers/otp/send
+{ "customer_id": "cus_...", "type": "phone_verification" }
+# Response: { "token": "<otp_token>", "expires_at": "..." }
+
+# Step 4 — verify phone OTP (returns login token)
+POST /store/customers/otp/verify
+{ "token": "<otp_token>", "code": "482917" }
+# Response: { "verified": true, "phone_verified": true, "token": "<login jwt>" }
+```
+
+### 3. Login flow
+
+```bash
+POST /auth/customer/phonepass
+{ "phone": "+15551234567", "password": "SecretPass1!" }
+# Response: { "token": "<jwt>" }
+```
+
+### 4. Update phone (after registration)
+
+```bash
+# Request change
+POST /store/customers/me/contact
+Authorization: Bearer <login jwt>
+{ "phone": "+15559998888" }
+# Response: { "token": "<otp_token>", "expires_at": "..." }
+
+# Verify and apply
+POST /store/customers/me/contact/verify
+Authorization: Bearer <login jwt>
+{ "token": "<otp_token>", "code": "739201" }
+# Response: { "customer": { "phone": "+15559998888", ... }, "token": "<fresh jwt>" }
+```
+
+---
+
+## Modules
+
+The plugin includes three modules:
+
+1. **`otp-verification`** — OTP generation, verification, and management
+2. **`customer-registration`** — Customer registration logic and route overrides
+3. **`account-deletion-request`** — Account deletion request lifecycle (pending → confirmed → completed/cancelled)
+
+## Workflows
+
+| Workflow | Description |
+|---|---|
+| `verify-email` | Sets `email_verified = true` on the customer record |
+| `verify-phone` | Sets `phone_verified = true` on the customer record |
+| `update-contact` | Updates `customer.phone` / `customer.email`, sets verified flag, syncs `provider_identity.entity_id` when applicable |
+| `send-otp` | Resolves channel config, generates OTP, sends notification |
+| `send-contact-change-otp` | Generates OTP with `new_value` embedded in JWT, sends to the new contact address |
+| `change-password` | Updates customer password via the auth module |
+
+## Database Migrations
+
+| Migration | Description |
+|---|---|
+| `Migration20250120000000AddCustomerVerificationColumns` | Adds `email_verified` and `phone_verified` columns to the customer table |
+| `Migration20250118001000CreateOtpVerificationTable` | Creates `otp_verification` table |
+| `Migration20250221000000CreateAccountDeletionRequestTable` | Creates `account_deletion_request` table |
+| `Migration20250221000000AddAccountDeletionOtpPurposes` | Extends `otp_verification.purpose` enum for account deletion flows |
+
+```bash
+npx medusa db:migrate
+```
+
+## Password Reset (Helper Functions)
 
 ```typescript
 import {
@@ -259,13 +498,11 @@ import {
   completePasswordReset,
 } from "customer-registration/helpers"
 
-// Request password reset
 await requestPasswordReset(
   { email: "customer@example.com" },
   { baseUrl: "https://store.example.com", publishableApiKey: "pk_..." }
 )
 
-// Complete password reset
 await completePasswordReset(
   {
     email: "customer@example.com",
@@ -276,24 +513,29 @@ await completePasswordReset(
 )
 ```
 
-See [USAGE.md](./USAGE.md) for complete helper function documentation.
+## Requirements
 
-## Development
+- Medusa v2.11.2 or higher
+- Node.js >= 20
+- Notification module configured with at least one provider (email/SMS)
+- Database migrations applied (`npx medusa db:migrate`)
+- `phonepass` provider registered in auth module (required when `registration.identifier` is `"phone"` or `"both"`)
 
-### Build
+## Documentation
 
-```bash
-npm run build
-```
+- **[USAGE.md](./USAGE.md)** — Complete usage guide with examples
+- **[README.md](./README.md)** — This file (overview and quick start)
 
-### Watch for Changes
+## Development
 
 ```bash
+# Build
+npm run build
+
+# Watch mode
 npx medusa plugin:develop
 ```
 
-This command watches for changes and automatically rebuilds and publishes the plugin to the local registry.
-
 ## License
 
 MIT