@dotpress/auth 1.1.2 → 1.2.1

package/README.md

@@ -13,9 +13,12 @@ You can use Prisma or any other ORM and easily connect it using the plugin DataP
 ### 1. Install
 
 ```bash
-npm install @dotpress/auth
+npm install @dotpress/auth cookie-parser
+npm install --save-dev @types/cookie-parser
 ```
 
+**Note:** `cookie-parser` is required as a peer dependency if you want to use cookie-based authentication.
+
 ### 2. Register your plugin
 
 ```ts
@@ -49,14 +52,48 @@ The plugin will check and parse bearer token from Authorization header and will
 
 ## Configuration object properties
 
-- keys.publicKey (string, required): public RSA key to validate JWT tokens
-- keys.secretKey (string, required): private RSA key to generate JWT tokens
-- dataProvider (DataProvider, required): set of functions to store and retrieve data (see below)
-- accessTokenTTL (optional, default: 3600): Time-to-live, in seconds, for access tokens
-- refreshTokenTTLInDays (optional, default: 14): Time-to-live, in days, for refresh tokens
-- issuer (string, optional but recommended): Domain of your app or auth service
-- onLoginFailed (optional): Event handler triggered on failed logins
-- onLoginSuccess (optional): Event handler triggered on success logins
+- **keys.publicKey** (string, required): public RSA key to validate JWT tokens
+- **keys.secretKey** (string, required): private RSA key to generate JWT tokens
+- **dataProvider** (DataProvider, required): set of functions to store and retrieve data (see below)
+- **accessTokenTTL** (optional, default: 3600): Time-to-live, in seconds, for access tokens
+- **refreshTokenTTLInDays** (optional, default: 14): Time-to-live, in days, for refresh tokens
+- **issuer** (string, optional but recommended): Domain of your app or auth service
+- **cookies** (CookieSettings, optional): Cookie configuration for web authentication
+- **onLoginFailed** (optional): Event handler triggered on failed logins
+- **onLoginSuccess** (optional): Event handler triggered on success logins
+
+### Cookie Settings
+
+The `cookies` object supports the following properties:
+
+```ts
+type CookieSettings = {
+  enabled?: boolean              // Enable cookie mode (default: false)
+  httpOnly?: boolean             // HttpOnly flag (default: true)
+  secure?: boolean               // Secure flag (default: true in production)
+  sameSite?: 'strict' | 'lax' | 'none'  // SameSite policy (default: 'lax')
+  domain?: string                // Cookie domain for cross-subdomain auth
+  path?: string                  // Cookie path (default: '/')
+  accessTokenName?: string       // Access token cookie name (default: 'dotpress_access_token')
+  refreshTokenName?: string      // Refresh token cookie name (default: 'dotpress_refresh_token')
+  accessTokenInCookie?: boolean  // Store access token in cookie (default: false)
+}
+```
+
+**Example configuration for cross-subdomain authentication:**
+
+```ts
+const authPlugin = configurePlugin({
+  keys: { /* ... */ },
+  dataProvider: { /* ... */ },
+  cookies: {
+    enabled: true,
+    domain: '.myapp.com',  // Works for app.myapp.com, www.myapp.com, etc.
+    secure: true,
+    sameSite: 'lax',
+  }
+})
+```
 
 ### DataProvider type
 
@@ -92,55 +129,194 @@ type RefreshTokenData = {
 }
 ```
 
+## Authentication Modes
+
+This plugin supports two authentication modes that can coexist:
+
+### Body Mode (Default)
+Tokens are sent in request body. Suitable for mobile apps (Expo/React Native) and desktop apps (Electron).
+
+### Cookie Mode
+Tokens are stored in httpOnly cookies. Suitable for web applications (SPAs, SSR) for enhanced security against XSS attacks.
+
+The plugin automatically detects which mode to use based on the request.
+
+---
+
 ## Endpoints
 
 ### `POST /auth/login`
 
 Authenticate a user and generate tokens.
 
-Request Body:
-- username: string
-- password: string
-- client: optional user agent string
+**Request Body:**
+- `username` (string, required): Username
+- `password` (string, required): Password
+- `client` (string, optional): User agent string for tracking
+- `aud` (string, optional): Audience for role-based access control
+- `mode` (enum: 'body' | 'cookie', optional): Authentication mode
+
+**Response:**
+```json
+{
+  "userId": "usr-123",
+  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "3f7b2a8c1e...",
+  "expiresIn": 3600,
+  "expiresAt": "2025-11-02T15:30:00.000Z"
+}
+```
 
-Response:
-- userId: string
-- accessToken: string
-- refreshToken: string
+**Behavior:**
+- If `mode: 'cookie'` is provided, tokens are also set as httpOnly cookies
+- `accessToken` and `refreshToken` are always returned in the response body for flexibility
+- Returns 401 on failed login
 
-Returns 401 on failed login.
+**Cookie Mode Example:**
+
+```ts
+// Client login request with cookie mode
+const response = await fetch('/auth/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  credentials: 'include',  // Important for cookies!
+  body: JSON.stringify({
+    username: 'john@example.com',
+    password: 'secret123',
+    mode: 'cookie'
+  })
+})
+```
 
 ### `POST /auth/refresh`
 
-Refresh tokens using previous token pair.
+Refresh tokens using previous token pair. The plugin automatically detects the authentication mode.
 
-Request Body:
-- accessToken: Previous access token, can be expired or still valid
-- refreshToken: Refresh token, must be valid, not used, not revoked
+**Request Body (Body Mode):**
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "3f7b2a8c1e..."
+}
+```
 
-Response:
-- userId: string
-- accessToken: string
-- refreshToken: string
+**Request Body (Cookie Mode):**
+```json
+{}
+```
+*Tokens are automatically extracted from cookies.*
+
+**Response:**
+```json
+{
+  "userId": "usr-123",
+  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "9a1b3c5d7f...",
+  "expiresIn": 3600,
+  "expiresAt": "2025-11-02T16:30:00.000Z"
+}
+```
 
-Returns 401 if tokens are not valid.
+**Behavior:**
+- Automatically detects mode: checks cookies first, then falls back to body
+- If cookies are present, new tokens are automatically set as cookies
+- Old refresh token is marked as used (one-time use with rotation)
+- Returns 401 if tokens are not valid
+
+**Error Codes:**
+- `NO_TOKENS_PROVIDED`: No tokens found in cookies or body
+- `INVALID_REFRESH_TOKEN`: Refresh token is invalid or already used
+- `EXPIRED_REFRESH_TOKEN`: Refresh token has expired
+
+### `GET /auth/me`
+
+Get current authenticated user.
+
+**Request:**
+No body required. Token is extracted from:
+1. `Authorization: Bearer <token>` header (priority)
+2. Cookie (if cookie mode is enabled and `accessTokenInCookie: true`)
+
+**Response:**
+```json
+{
+  "id": "usr-123",
+  "username": "john@example.com",
+  "email": "john@example.com",
+  // ... other user fields
+}
+```
+
+Returns 401 if user is not authenticated.
 
 ### `POST /auth/logout`
 
 Revoke tokens for current authenticated user.
 
-Response:
-- 200 OK on success
-- 401 if user is not authenticated
+**Response:**
+```json
+{
+  "success": true
+}
+```
 
-### `GET /auth/me`
+**Behavior:**
+- Revokes all refresh tokens for the user in the database
+- Clears authentication cookies if cookie mode was used
+- Returns 401 if user is not authenticated
+
+
+## Multi-Platform Support
+
+The plugin is designed to support multiple client types simultaneously:
 
-Get current authenticated user
+| Client Type | Recommended Mode | Configuration |
+|-------------|-----------------|---------------|
+| React SPA | Cookie | `mode: 'cookie'` in login |
+| Next.js SSR | Cookie | `mode: 'cookie'` + `domain: '.yourapp.com'` |
+| React Native / Expo | Body | No `mode` parameter (default) |
+| Electron | Body | No `mode` parameter (default) |
 
-Response:
-- User object if user is authenticated
-- 401 if user is not authenticated
+**Cross-subdomain authentication example:**
 
+```ts
+// API configuration (api.myapp.com)
+const authPlugin = configurePlugin({
+  cookies: {
+    enabled: true,
+    domain: '.myapp.com',  // Share cookies across subdomains
+    secure: true,
+    sameSite: 'lax',
+  },
+  // ... other settings
+})
+
+// CORS configuration
+const app = await createApp({
+  cors: {
+    origin: [
+      'https://app.myapp.com',
+      'https://www.myapp.com',
+    ],
+    credentials: true,  // Required for cookies!
+  },
+  plugins: [authPlugin]
+})
+```
+
+**Client-side fetch configuration:**
+
+```ts
+// Always include credentials for cookie mode
+fetch('https://api.myapp.com/auth/login', {
+  method: 'POST',
+  credentials: 'include',  // Essential for cookies
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ username, password, mode: 'cookie' })
+})
+```
+
+---
 
 ## Prisma schema examples
 

package/dist/__tests__/functional/cookies.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/functional/cookies.test.js

@@ -0,0 +1,386 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import request from 'supertest';
+import bcrypt from 'bcryptjs';
+import { $clearRoutes, createApp } from 'dotpress';
+import * as tokenFns from '../../lib/tokens.js';
+import { configurePlugin } from '../../index.js';
+describe('Cookie Mode Authentication', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        $clearRoutes();
+    });
+    const dataProvider = {
+        storeRefreshToken: vi.fn(),
+        findRefreshToken: vi.fn(),
+        markRefreshTokenAsUsed: vi.fn(),
+        revokeTokens: vi.fn(),
+        findUserById: vi.fn(),
+        findUserIdentifiers: vi.fn(),
+    };
+    const authPlugin = configurePlugin({
+        keys: {
+            secretKey: '',
+            publicKey: '',
+        },
+        dataProvider,
+        cookies: {
+            enabled: true,
+            secure: false, // For testing
+            httpOnly: true,
+            sameSite: 'lax',
+        },
+    });
+    describe('POST /auth/login with cookie mode', () => {
+        it('should set cookies when mode is "cookie"', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                mode: 'cookie',
+            });
+            expect(res.status).toBe(200);
+            // Check response body
+            expect(res.body).toMatchObject({
+                userId: '101',
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+                expiresIn: expect.any(Number),
+                expiresAt: expect.any(String),
+            });
+            // Check cookies are set
+            expect(res.headers['set-cookie']).toBeDefined();
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            // Check refresh token cookie
+            const refreshCookie = cookies.find((c) => c.startsWith('dotpress_refresh_token='));
+            expect(refreshCookie).toBeDefined();
+            expect(refreshCookie).toContain('HttpOnly');
+            expect(refreshCookie).toContain('Path=/');
+            expect(refreshCookie).toContain('SameSite=Lax');
+            // Access token should NOT be in cookie by default
+            const accessCookie = cookies.find((c) => c.startsWith('dotpress_access_token='));
+            expect(accessCookie).toBeUndefined();
+        });
+        it('should set access token cookie when accessTokenInCookie is true', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    secure: false,
+                    accessTokenInCookie: true, // Enable access token in cookie
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                mode: 'cookie',
+            });
+            expect(res.status).toBe(200);
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            // Both tokens should be in cookies
+            const refreshCookie = cookies.find((c) => c.startsWith('dotpress_refresh_token='));
+            const accessCookie = cookies.find((c) => c.startsWith('dotpress_access_token='));
+            expect(refreshCookie).toBeDefined();
+            expect(accessCookie).toBeDefined();
+        });
+        it('should NOT set cookies when mode is "body"', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                mode: 'body',
+            });
+            expect(res.status).toBe(200);
+            expect(res.body.accessToken).toBe('acc-111222333');
+            // No cookies should be set
+            expect(res.headers['set-cookie']).toBeUndefined();
+        });
+        it('should NOT set cookies when mode is not specified (default)', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+            });
+            expect(res.status).toBe(200);
+            // No cookies should be set (backward compatibility)
+            expect(res.headers['set-cookie']).toBeUndefined();
+        });
+    });
+    describe('POST /auth/refresh with cookies', () => {
+        it('should refresh tokens using cookies', async () => {
+            vi.spyOn(tokenFns, 'generateTokensFromRefreshToken').mockResolvedValue({
+                userId: '102',
+                accessToken: 'new-acc-token',
+                refreshToken: 'new-ref-token',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            // Simulate request with cookies
+            const res = await request(app)
+                .post('/auth/refresh')
+                .set('Cookie', [
+                'dotpress_refresh_token=ref-999888777',
+                'dotpress_access_token=acc-111222333',
+            ])
+                .send({});
+            expect(res.status).toBe(200);
+            expect(res.body).toMatchObject({
+                userId: '102',
+                accessToken: 'new-acc-token',
+                refreshToken: 'new-ref-token',
+                expiresIn: expect.any(Number),
+                expiresAt: expect.any(String),
+            });
+            // New cookies should be set
+            expect(res.headers['set-cookie']).toBeDefined();
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            expect(cookies.some((c) => c.includes('new-ref-token'))).toBe(true);
+        });
+        it('should fallback to body mode when no cookies present', async () => {
+            vi.spyOn(tokenFns, 'generateTokensFromRefreshToken').mockResolvedValue({
+                userId: '102',
+                accessToken: 'new-acc-token',
+                refreshToken: 'new-ref-token',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/refresh').send({
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+            expect(res.status).toBe(200);
+            expect(res.body.accessToken).toBe('new-acc-token');
+            // No cookies should be set in body mode
+            expect(res.headers['set-cookie']).toBeUndefined();
+        });
+        it('should return 401 when no tokens provided', async () => {
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/refresh').send({});
+            expect(res.status).toBe(401);
+            expect(res.body.error).toBe('UNAUTHORIZED');
+            expect(res.body.message).toBe('NO_TOKENS_PROVIDED');
+        });
+    });
+    describe('POST /auth/logout with cookies', () => {
+        it('should clear cookies on logout', async () => {
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-123',
+                username: 'JohnDoe',
+                email: 'john@example.com',
+            });
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockReturnValue({
+                userId: 'usr-123',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app)
+                .post('/auth/logout')
+                .set('Authorization', 'Bearer valid-token')
+                .set('Cookie', ['dotpress_refresh_token=ref-token']);
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ success: true });
+            // Cookies should be cleared
+            expect(res.headers['set-cookie']).toBeDefined();
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            // Check that cookies are being cleared (Max-Age=0 or Expires in the past)
+            const refreshCookie = cookies.find((c) => c.startsWith('dotpress_refresh_token='));
+            expect(refreshCookie).toBeDefined();
+            // Cookie should have an expiry in the past or Max-Age=0
+            expect(refreshCookie.includes('Max-Age=0') ||
+                refreshCookie.includes('Expires=Thu, 01 Jan 1970')).toBe(true);
+        });
+    });
+    describe('GET /auth/me with cookies', () => {
+        it('should authenticate user with access token from Authorization header', async () => {
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-123',
+                username: 'JohnDoe',
+                email: 'john@example.com',
+            });
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockReturnValue({
+                userId: 'usr-123',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app)
+                .get('/auth/me')
+                .set('Authorization', 'Bearer valid-token');
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({
+                id: 'usr-123',
+                username: 'JohnDoe',
+                email: 'john@example.com',
+            });
+        });
+        it('should authenticate user with access token from cookie when accessTokenInCookie is true', async () => {
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-456',
+                username: 'JaneDoe',
+                email: 'jane@example.com',
+            });
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockReturnValue({
+                userId: 'usr-456',
+            });
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    secure: false,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .get('/auth/me')
+                .set('Cookie', ['dotpress_access_token=cookie-token']);
+            expect(res.status).toBe(200);
+            expect(res.body.username).toBe('JaneDoe');
+        });
+    });
+    describe('Custom cookie names', () => {
+        it('should use custom cookie names when configured', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-token',
+                refreshToken: 'ref-token',
+            });
+            const customAuthPlugin = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    secure: false,
+                    accessTokenName: 'custom_access',
+                    refreshTokenName: 'custom_refresh',
+                },
+            });
+            const app = await createApp({
+                plugins: [customAuthPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                mode: 'cookie',
+            });
+            expect(res.status).toBe(200);
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            expect(cookies.some((c) => c.startsWith('custom_refresh='))).toBe(true);
+        });
+    });
+    describe('Cross-domain cookie configuration', () => {
+        it('should set domain attribute when configured', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            vi.mocked(dataProvider.findUserIdentifiers).mockResolvedValue({
+                userId: '101',
+                passwordHash: pwdHash,
+            });
+            vi.spyOn(tokenFns, 'generateTokensForUser').mockResolvedValue({
+                accessToken: 'acc-token',
+                refreshToken: 'ref-token',
+            });
+            const domainAuthPlugin = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    secure: false,
+                    domain: '.example.com',
+                },
+            });
+            const app = await createApp({
+                plugins: [domainAuthPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                mode: 'cookie',
+            });
+            expect(res.status).toBe(200);
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            const refreshCookie = cookies.find((c) => c.startsWith('dotpress_refresh_token='));
+            expect(refreshCookie).toContain('Domain=.example.com');
+        });
+    });
+});