11.10.0: Passkey

Author: kaihaase

migration-guides/11.9.x-to-11.10.x.md

@@ -0,0 +1,313 @@
+# Migration Guide: 11.9.x → 11.10.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | 1. `trustedOrigins` now required when Passkey enabled (TypeScript compile-time check) |
+| **New Features** | Logging helpers, improved session lookup, enhanced cookie handling, native Better Auth plugin endpoints |
+| **Bugfixes** | Session token forwarding to Better Auth plugins |
+| **Migration Effort** | Low (~10 minutes) - Only affects projects using Passkey |
+
+---
+
+## Quick Migration
+
+### Projects WITHOUT Passkey
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.10.x
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+**That's it!** No code changes required.
+
+### Projects WITH Passkey
+
+If you use `passkey: true` in your BetterAuth config, you must now provide `trustedOrigins`:
+
+```typescript
+// config.env.ts - BEFORE (11.9.x)
+betterAuth: {
+  passkey: true,  // This worked without trustedOrigins
+}
+
+// config.env.ts - AFTER (11.10.x)
+betterAuth: {
+  passkey: true,
+  trustedOrigins: ['http://localhost:3001', 'https://app.example.com'],  // REQUIRED
+}
+```
+
+---
+
+## What's New in 11.10.x
+
+### 1. TypeScript Compile-Time Validation for Passkey CORS
+
+The `IBetterAuth` type is now a **Discriminated Union** that enforces `trustedOrigins` when Passkey is enabled.
+
+**Why this change?**
+Passkey (WebAuthn) uses `credentials: 'include'` for API calls. Browsers don't allow CORS wildcard `*` with credentials, so explicit origins must be configured. This was previously a runtime error - now it's caught at compile time.
+
+```typescript
+// TypeScript ERROR: Property 'trustedOrigins' is missing
+const config: IBetterAuth = {
+  passkey: true,
+  // ❌ Compile error!
+};
+
+// CORRECT: trustedOrigins provided
+const config: IBetterAuth = {
+  passkey: true,
+  trustedOrigins: ['http://localhost:3001'],  // ✅
+};
+
+// CORRECT: No Passkey, trustedOrigins optional
+const config: IBetterAuth = {
+  twoFactor: true,
+  // trustedOrigins is optional when passkey is disabled
+};
+```
+
+### 2. Logging Helper for Secure Logging
+
+New helper functions for safely logging sensitive data (GDPR compliant):
+
+```typescript
+import { maskToken, maskEmail, maskCookieHeader, isProduction } from '@lenne.tech/nest-server';
+
+// Mask tokens: 'abc123xyz789' → 'abc1...9789'
+this.logger.debug(`Token: ${maskToken(token)}`);
+
+// Mask emails: 'john.doe@example.com' → 'jo***@example.com'
+this.logger.debug(`User: ${maskEmail(user.email)}`);
+
+// Mask cookie headers: 'session=abc123; token=xyz' → 'session=***; token=***'
+this.logger.debug(`Cookies: ${maskCookieHeader(req.headers.cookie)}`);
+
+// Conditional logging for non-production only
+if (!isProduction()) {
+  this.logger.debug('Debug info...');
+}
+```
+
+### 3. Improved Session Lookup Performance
+
+The `getSessionByToken()` method now uses a MongoDB aggregation pipeline for single-query session+user lookup, improving performance and handling both ObjectId and string userId formats automatically.
+
+### 4. Enhanced Cookie Handling for Plugin Compatibility
+
+Session tokens are now set in multiple cookies to ensure compatibility with Better Auth plugins (especially Passkey):
+
+| Cookie | Purpose |
+|--------|---------|
+| `token` | nest-server compatibility |
+| `{basePath}.session_token` | Better Auth native (e.g., `iam.session_token`) |
+| `better-auth.session_token` | Legacy Better Auth |
+
+### 5. Native Better Auth Plugin Endpoints
+
+2FA and Passkey endpoints now use Better Auth's native plugin handlers, providing more features:
+
+**Two-Factor Authentication (2FA):**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/iam/two-factor/enable` | POST | Enable 2FA, get TOTP URI |
+| `/iam/two-factor/disable` | POST | Disable 2FA |
+| `/iam/two-factor/verify-totp` | POST | Verify TOTP code |
+| `/iam/two-factor/generate-backup-codes` | POST | Generate backup codes |
+| `/iam/two-factor/verify-backup-code` | POST | Verify backup code |
+
+**Passkey (WebAuthn):**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/iam/passkey/generate-register-options` | POST | Get WebAuthn registration options |
+| `/iam/passkey/verify-registration` | POST | Verify and store passkey |
+| `/iam/passkey/generate-authenticate-options` | POST | Get WebAuthn authentication options |
+| `/iam/passkey/verify-authentication` | POST | Verify passkey authentication |
+| `/iam/passkey/list-user-passkeys` | POST | List user's passkeys |
+| `/iam/passkey/delete-passkey` | POST | Delete a passkey |
+| `/iam/passkey/update-passkey` | POST | Update passkey name |
+
+---
+
+## Breaking Changes
+
+### 1. `trustedOrigins` Required for Passkey
+
+**Impact:** Projects using `passkey: true` without `trustedOrigins`
+
+**Symptom:** TypeScript compile error:
+```
+Property 'trustedOrigins' is missing in type '{ passkey: true; }' but required in type 'IBetterAuthWithPasskey'.
+```
+
+**Before (11.9.x):**
+```typescript
+betterAuth: {
+  passkey: true,
+  // trustedOrigins was optional (caused runtime CORS errors)
+}
+```
+
+**After (11.10.x):**
+```typescript
+betterAuth: {
+  passkey: true,
+  trustedOrigins: ['http://localhost:3001', 'https://app.example.com'],
+}
+```
+
+### 2. 2FA Endpoint Changes
+
+**Impact:** Projects calling 2FA endpoints directly
+
+The endpoint for verifying TOTP codes changed:
+
+| Before (11.9.x) | After (11.10.x) |
+|-----------------|-----------------|
+| `POST /iam/two-factor/verify` | `POST /iam/two-factor/verify-totp` |
+
+Additionally, new endpoints are available for backup codes.
+
+---
+
+## Detailed Migration Steps
+
+### Step 1: Update Package
+
+```bash
+npm install @lenne.tech/nest-server@11.10.x
+```
+
+### Step 2: Add trustedOrigins (If Using Passkey)
+
+If you have `passkey: true` in your config, add `trustedOrigins`:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  passkey: true,
+  trustedOrigins: [
+    'http://localhost:3001',      // Development frontend
+    'https://app.example.com',    // Production frontend
+  ],
+}
+```
+
+### Step 3: Update 2FA API Calls (If Using 2FA)
+
+If your frontend calls the 2FA verify endpoint, update the path:
+
+```typescript
+// Before
+await fetch('/iam/two-factor/verify', { body: { code: '123456' } });
+
+// After
+await fetch('/iam/two-factor/verify-totp', { body: { code: '123456' } });
+```
+
+### Step 4: Verify Build and Tests
+
+```bash
+npm run build
+npm test
+```
+
+---
+
+## Compatibility Notes
+
+### Existing Projects Without Passkey
+
+No changes required. The migration is seamless.
+
+### Existing Projects With 2FA Only
+
+No breaking changes for basic 2FA usage. The new endpoints provide additional features (backup codes) but the core flow remains the same.
+
+### Custom BetterAuthController Extensions
+
+If you extend `CoreBetterAuthController`, note that the `handleBetterAuthPlugins()` method is now used for plugin endpoints. Your existing overrides should continue to work.
+
+---
+
+## Troubleshooting
+
+### TypeScript Error: trustedOrigins Missing
+
+**Symptom:**
+```
+Property 'trustedOrigins' is missing in type '{ passkey: true; }'
+```
+
+**Solution:** Add `trustedOrigins` array to your betterAuth config:
+```typescript
+betterAuth: {
+  passkey: true,
+  trustedOrigins: ['http://localhost:3001'],
+}
+```
+
+### CORS Error with Passkey
+
+**Symptom:** Browser console shows CORS error when using Passkey
+
+**Solution:** Ensure `trustedOrigins` includes your frontend URL (including protocol and port):
+```typescript
+trustedOrigins: ['http://localhost:3001'],  // Include port!
+```
+
+### 2FA Verify Returns 404
+
+**Symptom:** `POST /iam/two-factor/verify` returns 404
+
+**Solution:** Update to new endpoint: `POST /iam/two-factor/verify-totp`
+
+### Debug Logging Not Appearing
+
+**Symptom:** Debug logs missing in development
+
+**Solution:** Debug logs are now suppressed in production. Ensure `NODE_ENV` is not set to `production` during development.
+
+---
+
+## Module Documentation
+
+### BetterAuth Module
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/modules/better-auth/`
+
+---
+
+## New Exports
+
+The following are now exported from `@lenne.tech/nest-server`:
+
+```typescript
+// Logging helpers (new)
+export { isProduction, maskCookieHeader, maskEmail, maskId, maskSensitive, maskToken } from './core/common/helpers/logging.helper';
+
+// BetterAuth types (updated)
+export { IBetterAuth, IBetterAuthWithPasskey, IBetterAuthWithoutPasskey } from './core/common/interfaces/server-options.interface';
+```
+
+---
+
+## References
+
+- [BetterAuth README](../src/core/modules/better-auth/README.md)
+- [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [Better Auth Documentation](https://www.better-auth.com/docs)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.9.0",
+  "version": "11.10.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -62,6 +62,7 @@
     "vitest:watch": "NODE_ENV=local vitest --config vitest-e2e.config.ts",
     "vitest:unit": "vitest run --config vitest.config.ts",
     "test:unit:watch": "vitest --config vitest.config.ts",
+    "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
     "watch": "npm-watch",
     "link:eslint": "yalc add @lenne.tech/eslint-config-ts && yalc link @lenne.tech/eslint-config-ts && npm install",
     "unlink:eslint": "yalc remove @lenne.tech/eslint-config-ts && npm install"

src/config.env.ts

@@ -69,6 +69,12 @@ const config: { [env: string]: IServerOptions } = {
         appName: 'Nest Server Development',
         enabled: false,
       },
+      // CORS trustedOrigins configuration:
+      // - Not set + Passkey disabled: All origins allowed (default)
+      // - Not set + Passkey enabled: Server startup FAILS (trustedOrigins required)
+      // - Set explicitly: Only configured origins allowed
+      // Uncomment and configure when enabling Passkey:
+      // trustedOrigins: ['http://localhost:3000', 'http://localhost:3001'],
     },
     compression: true,
     cookies: false,
@@ -223,6 +229,10 @@ const config: { [env: string]: IServerOptions } = {
           enabled: false,
         },
       },
+      // REQUIRED when Passkey is enabled!
+      // Passkey uses credentials: 'include' which requires explicit CORS origins.
+      // Server startup will fail if Passkey is enabled without trustedOrigins.
+      trustedOrigins: ['http://localhost:3000', 'http://localhost:3001'],
       twoFactor: {
         appName: 'Nest Server Local',
         enabled: true,
@@ -399,10 +409,15 @@ const config: { [env: string]: IServerOptions } = {
           enabled: !!process.env.SOCIAL_GOOGLE_CLIENT_ID,
         },
       },
+      // REQUIRED for Passkey in production!
+      // Passkey uses credentials: 'include' which requires explicit origins (no wildcard '*')
+      // Configure all frontend URLs that need Passkey authentication:
+      trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || [],
       twoFactor: {
         appName: process.env.TWO_FACTOR_APP_NAME || 'Nest Server',
         enabled: process.env.TWO_FACTOR_ENABLED === 'true',
       },
+      // Example: TRUSTED_ORIGINS=https://app.example.com,https://admin.example.com
     },
     compression: true,
     cookies: false,