feat: password reset url is configurable

rrd108 · rrd108 · commit 0a3d443b84e7 · 2025-08-19T13:24:37.000+02:00
diff --git a/docs/api/types.md b/docs/api/types.md
@@ -126,7 +126,7 @@ interface RuntimeModuleOptions {
     passwordResetTokens?: string
   }
   mailer?: MailerOptions
-  passwordResetBaseUrl?: string
+  passwordResetUrl?: string
   auth?: {
     whitelist?: string[]
     tokenExpiration?: number
@@ -161,7 +161,7 @@ interface ModuleOptions {
     passwordResetTokens: string
   }
   mailer?: MailerOptions
-  passwordResetBaseUrl?: string
+  passwordResetUrl: string
   auth: {
     whitelist: string[]
     tokenExpiration: number
diff --git a/docs/examples/advanced-configuration.md b/docs/examples/advanced-configuration.md
@@ -39,8 +39,8 @@ export default defineNuxtConfig({
       }
     },
     
-    // Production URLs
-    passwordResetBaseUrl: process.env.PASSWORD_RESET_BASE_URL || 'https://myapp.com',
+    // Password reset URL path
+    passwordResetUrl: process.env.PASSWORD_RESET_URL || '/reset-password',
     
     // Security settings
     auth: {
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -59,8 +59,8 @@ export default defineNuxtConfig({
       }
     },
     
-    // Password reset URL
-    passwordResetBaseUrl: 'https://yourapp.com',
+    // Password reset URL path
+    passwordResetUrl: '/reset-password',
     
     // Authentication settings
     auth: {
@@ -159,7 +159,7 @@ nuxtUsers: {
       from: '"My App" <noreply@example.com>'
     }
   },
-  passwordResetBaseUrl: 'http://localhost:3000'
+  passwordResetUrl: '/reset-password'
 }
 ```
 
@@ -181,7 +181,7 @@ nuxtUsers: {
       from: '"Your App" <noreply@yourapp.com>'
     }
   },
-  passwordResetBaseUrl: 'https://yourapp.com'
+  passwordResetUrl: '/reset-password'
 }
 ```
 
@@ -248,7 +248,7 @@ nuxtUsers: {
 }
 ```
 
-**Note:** Login (`/login`) and password reset routes are always whitelisted automatically.
+**Note:** Login (`/login`), password reset page (default `/reset-password` or your custom `passwordResetUrl`), and password reset API endpoints are always whitelisted automatically.
 
 ### Role-Based Access Control (RBAC)
 
@@ -397,7 +397,7 @@ export default defineNuxtConfig({
       }
     },
     
-    passwordResetBaseUrl: process.env.PASSWORD_RESET_BASE_URL,
+    passwordResetUrl: process.env.PASSWORD_RESET_URL || '/reset-password',
     
     auth: {
       tokenExpiration: Number(process.env.TOKEN_EXPIRATION) || 1440
@@ -428,7 +428,7 @@ MAILER_PASS=app_specific_password
 MAILER_FROM="My App <noreply@myapp.com>"
 
 # URLs
-PASSWORD_RESET_BASE_URL=https://myapp.com
+PASSWORD_RESET_URL=/auth/reset-password
 
 # Auth
 TOKEN_EXPIRATION=1440
@@ -474,7 +474,7 @@ const defaults = {
       from: '"Nuxt Users Module" <noreply@example.com>'
     }
   },
-  passwordResetBaseUrl: 'http://localhost:3000',
+  passwordResetUrl: '/reset-password',
   auth: {
     whitelist: [],
     tokenExpiration: 1440,
diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
@@ -58,8 +58,8 @@ export default defineNuxtConfig({
     //     from: '"Your App Name" <noreply@example.com>',
     //   },
     // },
-    // Optional: Configure base URL for password reset links
-    // passwordResetBaseUrl: 'http://localhost:3000', // Default
+    // Optional: Configure URL path for password reset page
+    // passwordResetUrl: '/reset-password', // Default
   }
 })
 ```
diff --git a/docs/user-guide/password-reset.md b/docs/user-guide/password-reset.md
@@ -30,6 +30,52 @@ https://yourapp.com/reset-password?token=abc123...&email=user@example.com
 
 Your reset password page should read these query parameters to populate the reset form.
 
+## Reset URL Configuration
+
+The module automatically constructs password reset URLs using your application's base URL and the configured path.
+
+### Default Behavior
+
+By default, reset links use `/reset-password` as the path:
+
+```
+https://yourapp.com/reset-password?token=abc123...&email=user@example.com
+```
+
+### Custom Reset URL Path
+
+You can customize the path portion of the reset URL:
+
+```ts
+nuxtUsers: {
+  passwordResetUrl: '/auth/reset-password', // Custom path
+}
+```
+
+This will generate reset links like:
+
+```
+https://yourapp.com/auth/reset-password?token=abc123...&email=user@example.com
+```
+
+### Zero Configuration
+
+The module automatically detects your application's base URL from the incoming request, so you don't need to configure a full base URL. The system intelligently combines:
+
+- **Request host**: Automatically detected from headers
+- **Protocol**: Detected from `x-forwarded-proto` header or defaults to `http`
+- **Reset path**: Your configured `passwordResetUrl` (default: `/reset-password`)
+
+### Development vs Production
+
+**Development** (automatic detection):
+- Request to `http://localhost:3000` → Reset URL: `http://localhost:3000/reset-password`
+
+**Production** (automatic detection):
+- Request to `https://myapp.com` → Reset URL: `https://myapp.com/reset-password`
+
+No manual configuration of base URLs required!
+
 ## Configuration
 
 Configure the mailer in your `nuxt.config.ts`:
@@ -57,7 +103,7 @@ export default defineNuxtConfig({
         from: '"Your App" <noreply@yourapp.com>',
       },
     },
-    passwordResetBaseUrl: 'https://yourapp.com', // Base URL for reset links
+    passwordResetUrl: '/reset-password', // URL path for password reset page
   }
 })
 ```
@@ -81,7 +127,7 @@ nuxtUsers: {
       from: '"My Nuxt App" <noreply@example.com>',
     },
   },
-  passwordResetBaseUrl: 'http://localhost:3000',
+  passwordResetUrl: '/reset-password', // Custom URL path (optional)
 }
 ```
 
diff --git a/package.json b/package.json
@@ -66,7 +66,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "pretest": "node -v | grep -q 'v22' || (echo 'Please use Node.js v22 for testing' && exit 1)",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "test:types": "yarn dev:prepare && vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
     "test:unit": "./scripts/test-unit.sh",
     "test:sqlite": "./scripts/test-sqlite.sh",
     "test:mysql": "./scripts/test-mysql.sh",
diff --git a/src/module.ts b/src/module.ts
@@ -28,7 +28,7 @@ export const defaultOptions: ModuleOptions = {
       from: '"Nuxt Users Module" <noreply@example.com>',
     },
   },
-  passwordResetBaseUrl: 'http://localhost:3000',
+  passwordResetUrl: '/reset-password',
   auth: {
     whitelist: [],
     tokenExpiration: 24 * 60, // 24 hours
@@ -61,6 +61,7 @@ export default defineNuxtModule<RuntimeModuleOptions>({
     nuxt.options.runtimeConfig.nuxtUsers = {
       ...runtimeConfigOptions,
       apiBasePath: options.apiBasePath || defaultOptions.apiBasePath,
+      passwordResetUrl: options.passwordResetUrl || defaultOptions.passwordResetUrl,
       tables: {
         migrations: options.tables?.migrations || defaultOptions.tables.migrations,
         users: options.tables?.users || defaultOptions.tables.users,
diff --git a/src/runtime/constants.ts b/src/runtime/constants.ts
@@ -1,5 +1,5 @@
 // Page routes that don't require authentication
-export const NO_AUTH_PATHS = ['/login']
+export const NO_AUTH_PATHS = ['/login', '/reset-password']
 
 // API routes that don't require authentication (will be prefixed with apiBasePath)
 export const NO_AUTH_API_PATHS = ['/session', '/password/forgot', '/password/reset']
diff --git a/src/runtime/server/api/nuxt-users/password/forgot.post.ts b/src/runtime/server/api/nuxt-users/password/forgot.post.ts
@@ -1,4 +1,4 @@
-import { defineEventHandler, readBody, createError } from 'h3'
+import { defineEventHandler, readBody, createError, getHeader } from 'h3'
 import { sendPasswordResetLink } from '../../../services/password'
 import { useRuntimeConfig } from '#imports'
 import type { ModuleOptions } from 'nuxt-users/utils'
@@ -18,7 +18,12 @@ export default defineEventHandler(async (event) => {
   }
 
   try {
-    await sendPasswordResetLink(email, options)
+    // Try to determine the base URL from the request
+    const host = getHeader(event, 'host')
+    const protocol = getHeader(event, 'x-forwarded-proto') || 'http'
+    const baseUrl = host ? `${protocol}://${host}` : undefined
+
+    await sendPasswordResetLink(email, options, baseUrl)
     // Always return a success-like message to prevent email enumeration
     return { message: 'If a user with that email exists, a password reset link has been sent.' }
   }
diff --git a/src/runtime/server/middleware/authorization.server.ts b/src/runtime/server/middleware/authorization.server.ts
@@ -20,8 +20,14 @@ export default defineEventHandler(async (event) => {
     return
   }
 
-  // internal no-auth paths (e.g., /login)
-  if (NO_AUTH_PATHS.includes(event.path)) {
+  // internal no-auth paths (e.g., /login, /reset-password) and custom password reset URL
+  const noAuthPaths = [...NO_AUTH_PATHS]
+  // Add custom password reset URL if different from default
+  if (options.passwordResetUrl && options.passwordResetUrl !== '/reset-password') {
+    noAuthPaths.push(options.passwordResetUrl)
+  }
+
+  if (noAuthPaths.includes(event.path)) {
     console.log(`[Nuxt Users] server.middleware.auth.global: NO_AUTH_PATH: ${event.path}`)
     return
   }
diff --git a/src/runtime/server/services/password.ts b/src/runtime/server/services/password.ts
@@ -11,7 +11,8 @@ const TOKEN_EXPIRATION_HOURS = 1
  */
 export const sendPasswordResetLink = async (
   email: string,
-  options: ModuleOptions): Promise<void> => {
+  options: ModuleOptions,
+  baseUrl?: string): Promise<void> => {
   const user = await findUserByEmail(email, options)
 
   if (!user) {
@@ -54,7 +55,9 @@ export const sendPasswordResetLink = async (
   })
 
   // Construct the complete password reset URL with token and email
-  const resetUrl = new URL('/reset-password', options.passwordResetBaseUrl || 'http://localhost:3000')
+  // Use the provided baseUrl, or fall back to a sensible default for development
+  const appBaseUrl = baseUrl || 'http://localhost:3000'
+  const resetUrl = new URL(options.passwordResetUrl, appBaseUrl)
   resetUrl.searchParams.set('token', token)
   resetUrl.searchParams.set('email', email)
 
diff --git a/src/types.ts b/src/types.ts
@@ -38,10 +38,10 @@ export interface RuntimeModuleOptions {
   mailer?: MailerOptions
 
   /**
-   * Base URL for password reset links
-   * @default 'http://localhost:3000' // Example, will be set in module defaults
+   * URL path for password reset page
+   * @default '/reset-password'
    */
-  passwordResetBaseUrl?: string
+  passwordResetUrl?: string
   /**
    * Skip database checks during module setup to prevent hanging
    * @default false
@@ -120,7 +120,7 @@ export interface ModuleOptions {
     passwordResetTokens: string
   }
   mailer?: MailerOptions
-  passwordResetBaseUrl?: string
+  passwordResetUrl: string
   auth: {
     whitelist: string[]
     tokenExpiration: number
diff --git a/test/test-setup.ts b/test/test-setup.ts
@@ -58,6 +58,7 @@ export const getTestOptions = (dbType: DatabaseType, dbConfig: DatabaseConfig) =
       pass: process.env.MAILER_PASSWORD || 'test'
     }
   },
+  passwordResetUrl: '/reset-password',
   auth: {
     whitelist: [],
     tokenExpiration: 1440,
diff --git a/test/unit/api.forgot-password.test.ts b/test/unit/api.forgot-password.test.ts
@@ -10,14 +10,16 @@ vi.mock('#imports', () => ({
 // Mock h3 functions
 const mockReadBody = vi.fn()
 const mockCreateError = vi.fn()
+const mockGetHeader = vi.fn()
 const mockDefineEventHandler = vi.fn(handler => handler)
 const mockUseRuntimeConfig = vi.fn()
 const mockSendPasswordResetLink = vi.fn()
 
 vi.mock('h3', () => ({
   defineEventHandler: mockDefineEventHandler,
   readBody: mockReadBody,
-  createError: mockCreateError
+  createError: mockCreateError,
+  getHeader: mockGetHeader
 }))
 
 vi.mock('../../src/runtime/server/services/password', () => ({
@@ -37,14 +39,21 @@ describe('Forgot Password API Route', () => {
     // Mock test options
     testOptions = {
       ...defaultOptions,
-      passwordResetBaseUrl: 'http://localhost:3000/reset-password'
+      passwordResetUrl: '/reset-password'
     }
 
     // Mock runtime config
     mockUseRuntimeConfig.mockReturnValue({
       nuxtUsers: testOptions
     })
 
+    // Mock getHeader to return default values
+    mockGetHeader.mockImplementation((event, headerName) => {
+      if (headerName === 'host') return 'localhost:3000'
+      if (headerName === 'x-forwarded-proto') return null
+      return null
+    })
+
     // Create mock event
     mockEvent = {
       context: {
@@ -75,8 +84,8 @@ describe('Forgot Password API Route', () => {
     // Verify readBody was called correctly
     expect(mockReadBody).toHaveBeenCalledWith(mockEvent)
 
-    // Verify sendPasswordResetLink was called with correct parameters
-    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions)
+    // Verify sendPasswordResetLink was called with correct parameters (including baseUrl)
+    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions, 'http://localhost:3000')
 
     // Verify response structure
     expect(response).toBeDefined()
@@ -233,7 +242,7 @@ describe('Forgot Password API Route', () => {
 
     // Verify readBody was called
     expect(mockReadBody).toHaveBeenCalledWith(mockEvent)
-    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions)
+    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions, 'http://localhost:3000')
     expect(mockCreateError).toHaveBeenCalledWith({
       statusCode: 500,
       statusMessage: 'An internal server error occurred.'
@@ -269,7 +278,7 @@ describe('Forgot Password API Route', () => {
 
     // Verify readBody was called
     expect(mockReadBody).toHaveBeenCalledWith(mockEvent)
-    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions)
+    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(validEmail, testOptions, 'http://localhost:3000')
     expect(mockCreateError).toHaveBeenCalledWith({
       statusCode: 500,
       statusMessage: 'An internal server error occurred.'
@@ -292,7 +301,7 @@ describe('Forgot Password API Route', () => {
     expect(mockReadBody).toHaveBeenCalledWith(mockEvent)
 
     // Verify sendPasswordResetLink was called with correct parameters
-    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(specialEmail, testOptions)
+    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(specialEmail, testOptions, 'http://localhost:3000')
 
     // Verify response structure
     expect(response).toBeDefined()
@@ -315,7 +324,7 @@ describe('Forgot Password API Route', () => {
     expect(mockReadBody).toHaveBeenCalledWith(mockEvent)
 
     // Verify sendPasswordResetLink was called with correct parameters
-    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(longEmail, testOptions)
+    expect(mockSendPasswordResetLink).toHaveBeenCalledWith(longEmail, testOptions, 'http://localhost:3000')
 
     // Verify response structure
     expect(response).toBeDefined()
diff --git a/test/unit/api.reset-password.test.ts b/test/unit/api.reset-password.test.ts
@@ -65,7 +65,7 @@ describe('Reset Password API Route', () => {
     // Mock test options
     testOptions = {
       ...defaultOptions,
-      passwordResetBaseUrl: 'http://localhost:3000/reset-password'
+      passwordResetUrl: '/reset-password'
     }
 
     // Mock password validation options
diff --git a/test/unit/api.users-list.test.ts b/test/unit/api.users-list.test.ts

Original file line number	Diff line number	Diff line change
`@@ -39,8 +39,8 @@ export default defineNuxtConfig({`
`39`	`39`	`}`
`40`	`40`	`},`
`41`	`41`
`42`		`- // Production URLs`
`43`		`- passwordResetBaseUrl: process.env.PASSWORD_RESET_BASE_URL \|\| 'https://myapp.com',`
	`42`	`+ // Password reset URL path`
	`43`	`+ passwordResetUrl: process.env.PASSWORD_RESET_URL \|\| '/reset-password',`
`44`	`44`
`45`	`45`	`// Security settings`
`46`	`46`	`auth: {`