@dotpress/auth 1.2.1 → 1.3.1

package/README.md

@@ -45,6 +45,7 @@ The plugin will check and parse bearer token from Authorization header and will
 
 - `POST /auth/login`
 - `POST /auth/refresh`
+- `POST /auth/restore`
 - `GET /auth/me`
 - `POST /auth/logout`
 
@@ -228,6 +229,81 @@ Refresh tokens using previous token pair. The plugin automatically detects the a
 - `INVALID_REFRESH_TOKEN`: Refresh token is invalid or already used
 - `EXPIRED_REFRESH_TOKEN`: Refresh token has expired
 
+### `POST /auth/restore`
+
+Restore a user session from cookies. This endpoint validates the access token from cookies and automatically refreshes it if expired.
+
+**Use Case:**
+This route is designed for web applications to restore user sessions after page reload or when returning after inactivity. Instead of making multiple API calls (`/auth/me` → 401 → `/auth/refresh` → `/auth/me`), you can call `/auth/restore` once to validate or refresh the session in a single request.
+
+**Requirements:**
+- Cookie mode must be enabled (`cookies.enabled: true`)
+- Access token must be stored in cookies (`cookies.accessTokenInCookie: true`)
+- Both `accessToken` and `refreshToken` must be present in cookies
+
+**Request:**
+No body required. Tokens are automatically extracted from cookies.
+
+**Response:**
+```json
+{
+  "userId": "usr-123",
+  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "3f7b2a8c1e...",
+  "expiresIn": 3600,
+  "expiresAt": "2025-11-02T16:30:00.000Z",
+  "user": {
+    "id": "usr-123",
+    "username": "JohnDoe",
+    "email": "john@example.com"
+  }
+}
+```
+
+**Behavior:**
+1. If `accessToken` is valid: Returns existing tokens with user data
+2. If `accessToken` is expired but `refreshToken` is valid: Generates new token pair, updates cookies, and returns new tokens with user data
+3. If both tokens are invalid: Returns 401
+
+**Error Codes:**
+- `COOKIES_NOT_ENABLED`: Cookie mode is not enabled in plugin configuration
+- `ACCESS_TOKEN_NOT_IN_COOKIE`: `accessTokenInCookie` is not enabled
+- `NO_REFRESH_TOKEN`: Refresh token cookie is missing
+- `NO_ACCESS_TOKEN`: Access token cookie is missing
+- `INVALID_REFRESH_TOKEN`: Refresh token is invalid or already used
+- `EXPIRED_REFRESH_TOKEN`: Refresh token has expired
+- `USER_NOT_FOUND`: User ID from token not found in database
+
+**Example Usage:**
+
+```ts
+// React SPA: Restore session on app initialization
+useEffect(() => {
+  const restoreSession = async () => {
+    try {
+      const response = await fetch('/auth/restore', {
+        method: 'POST',
+        credentials: 'include', // Important: include cookies
+      })
+
+      if (response.ok) {
+        const { user, accessToken, expiresAt } = await response.json()
+        dispatch(setUser(user))
+        dispatch(setAccessToken(accessToken))
+        dispatch(setExpiresAt(expiresAt))
+      } else {
+        // Session invalid, redirect to login
+        navigate('/login')
+      }
+    } catch (error) {
+      console.error('Failed to restore session:', error)
+    }
+  }
+
+  restoreSession()
+}, [])
+```
+
 ### `GET /auth/me`
 
 Get current authenticated user.

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

@@ -383,4 +383,239 @@ describe('Cookie Mode Authentication', () => {
             expect(refreshCookie).toContain('Domain=.example.com');
         });
     });
+    describe('POST /auth/restore', () => {
+        it('should return 401 when cookies are not enabled', async () => {
+            const authPluginNoCookies = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: false,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginNoCookies],
+            });
+            const res = await request(app).post('/auth/restore');
+            expect(res.status).toBe(401);
+        });
+        it('should return 401 when accessTokenInCookie is not enabled', async () => {
+            const authPluginNoAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: false, // Required for restore
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginNoAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', ['dotpress_refresh_token=ref-token']);
+            expect(res.status).toBe(401);
+        });
+        it('should return 401 when refresh token is missing', async () => {
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', ['dotpress_access_token=acc-token']);
+            expect(res.status).toBe(401);
+        });
+        it('should return 401 when access token is missing', async () => {
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', ['dotpress_refresh_token=ref-token']);
+            expect(res.status).toBe(401);
+        });
+        it('should return user and tokens when access token is still valid', async () => {
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockReturnValue({
+                userId: 'usr-123',
+            });
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-123',
+                username: 'JohnDoe',
+                email: 'john@example.com',
+            });
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', [
+                'dotpress_access_token=valid-access-token',
+                'dotpress_refresh_token=valid-refresh-token',
+            ]);
+            expect(res.status).toBe(200);
+            expect(res.body).toMatchObject({
+                userId: 'usr-123',
+                accessToken: 'valid-access-token',
+                refreshToken: 'valid-refresh-token',
+                expiresIn: expect.any(Number),
+                expiresAt: expect.any(String),
+                user: {
+                    id: 'usr-123',
+                    username: 'JohnDoe',
+                    email: 'john@example.com',
+                },
+            });
+        });
+        it('should refresh tokens and return new tokens when access token is expired', async () => {
+            // First call: validateAndDecodeAccessToken throws (expired)
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockImplementation(() => {
+                throw new Error('Token expired');
+            });
+            // Second call: generateTokensFromRefreshToken returns new tokens
+            vi.spyOn(tokenFns, 'generateTokensFromRefreshToken').mockResolvedValue({
+                userId: 'usr-456',
+                accessToken: 'new-access-token',
+                refreshToken: 'new-refresh-token',
+            });
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-456',
+                username: 'JaneDoe',
+                email: 'jane@example.com',
+            });
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', [
+                'dotpress_access_token=expired-access-token',
+                'dotpress_refresh_token=valid-refresh-token',
+            ]);
+            expect(res.status).toBe(200);
+            expect(res.body).toMatchObject({
+                userId: 'usr-456',
+                accessToken: 'new-access-token',
+                refreshToken: 'new-refresh-token',
+                expiresIn: expect.any(Number),
+                expiresAt: expect.any(String),
+                user: {
+                    id: 'usr-456',
+                    username: 'JaneDoe',
+                    email: 'jane@example.com',
+                },
+            });
+            // Verify new cookies were set
+            expect(res.headers['set-cookie']).toBeDefined();
+            const cookies = Array.isArray(res.headers['set-cookie'])
+                ? res.headers['set-cookie']
+                : [res.headers['set-cookie']];
+            const accessCookie = cookies.find((c) => c.startsWith('dotpress_access_token='));
+            const refreshCookie = cookies.find((c) => c.startsWith('dotpress_refresh_token='));
+            expect(accessCookie).toBeDefined();
+            expect(refreshCookie).toBeDefined();
+        });
+        it('should return 401 when refresh token is invalid', async () => {
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockImplementation(() => {
+                throw new Error('Token expired');
+            });
+            vi.spyOn(tokenFns, 'generateTokensFromRefreshToken').mockRejectedValue(new Error('Invalid_Refresh_Token'));
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', [
+                'dotpress_access_token=expired-access-token',
+                'dotpress_refresh_token=invalid-refresh-token',
+            ]);
+            expect(res.status).toBe(401);
+        });
+        it('should return 401 when refresh token is expired', async () => {
+            vi.spyOn(tokenFns, 'validateAndDecodeAccessToken').mockImplementation(() => {
+                throw new Error('Token expired');
+            });
+            vi.spyOn(tokenFns, 'generateTokensFromRefreshToken').mockRejectedValue(new Error('Expired_Refresh_Token'));
+            const authPluginWithAccessCookie = configurePlugin({
+                keys: {
+                    secretKey: '',
+                    publicKey: '',
+                },
+                dataProvider,
+                cookies: {
+                    enabled: true,
+                    accessTokenInCookie: true,
+                },
+            });
+            const app = await createApp({
+                plugins: [authPluginWithAccessCookie],
+            });
+            const res = await request(app)
+                .post('/auth/restore')
+                .set('Cookie', [
+                'dotpress_access_token=expired-access-token',
+                'dotpress_refresh_token=expired-refresh-token',
+            ]);
+            expect(res.status).toBe(401);
+        });
+    });
 });

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import type { Plugin } from 'dotpress';
 import { AuthSettings, DataProvider, KeyPairSettings } from './types/types.js';
-import { generateAccessToken } from './lib/tokens.js';
+import { generateAccessToken, generateTokensForUser, generateRefreshToken } from './lib/tokens.js';
 type Settings = Partial<AuthSettings> & {
     keys: KeyPairSettings;
     dataProvider: DataProvider;
 };
 export declare const configurePlugin: (settings: Settings) => Plugin;
 export declare const generatePasswordHash: (password: string, salt?: number) => Promise<string>;
-export { generateAccessToken };
+export { generateAccessToken, generateRefreshToken, generateTokensForUser };

package/dist/index.js

@@ -3,7 +3,7 @@ import cookieParser from 'cookie-parser';
 import { setSettings } from './lib/settings.js';
 import { registerHandlers } from './lib/handlers.js';
 import { attachAuthenticatedUser } from './lib/middleware.js';
-import { generateAccessToken } from './lib/tokens.js';
+import { generateAccessToken, generateTokensForUser, generateRefreshToken, } from './lib/tokens.js';
 export const configurePlugin = (settings) => {
     setSettings(settings);
     return (plugin) => {
@@ -19,4 +19,4 @@ export const configurePlugin = (settings) => {
 export const generatePasswordHash = (password, salt = 10) => {
     return bcrypt.hash(password, salt);
 };
-export { generateAccessToken };
+export { generateAccessToken, generateRefreshToken, generateTokensForUser };

package/dist/lib/handlers.js

@@ -2,8 +2,8 @@ import { unauthorizedError, internalError } from 'dotpress';
 import bcrypt from 'bcryptjs';
 import { getSettings } from './settings.js';
 import { getRequestIp } from './ip.js';
-import { generateTokensForUser, generateTokensFromRefreshToken, } from './tokens.js';
-import { setAuthCookies, clearAuthCookies, extractTokensFromRequest, calculateExpiration, } from './cookies.js';
+import { generateTokensForUser, generateTokensFromRefreshToken, validateAndDecodeAccessToken, } from './tokens.js';
+import { setAuthCookies, clearAuthCookies, extractTokensFromRequest, calculateExpiration, getCookieSettings, } from './cookies.js';
 export const registerHandlers = (plugin) => {
     const authGroup = plugin.addGroup('/auth');
     const settings = getSettings();
@@ -162,6 +162,91 @@ export const registerHandlers = (plugin) => {
             return req.user;
         },
     });
+    authGroup.defineRoute({
+        method: 'post',
+        path: '/restore',
+        schema: (z) => ({
+            response: z.object({
+                userId: z.string(),
+                accessToken: z.string(),
+                refreshToken: z.string(),
+                expiresIn: z.number(),
+                expiresAt: z.string(),
+                user: z.unknown(),
+            }),
+        }),
+        handler: async ({ req, res }) => {
+            const cookieSettings = getCookieSettings();
+            // Only support cookie mode for restore
+            if (!cookieSettings.enabled) {
+                return unauthorizedError('COOKIES_NOT_ENABLED');
+            }
+            // This endpoint requires accessTokenInCookie to be enabled
+            if (!cookieSettings.accessTokenInCookie) {
+                return unauthorizedError('ACCESS_TOKEN_NOT_IN_COOKIE');
+            }
+            const refreshToken = req.cookies?.[cookieSettings.refreshTokenName];
+            const accessToken = req.cookies?.[cookieSettings.accessTokenName];
+            if (!refreshToken) {
+                return unauthorizedError('NO_REFRESH_TOKEN');
+            }
+            if (!accessToken) {
+                return unauthorizedError('NO_ACCESS_TOKEN');
+            }
+            // Try to validate access token first
+            try {
+                const { userId } = validateAndDecodeAccessToken(accessToken);
+                const user = await settings.dataProvider.findUserById(userId);
+                if (user) {
+                    const expiration = calculateExpiration(settings.accessTokenTTL);
+                    return {
+                        userId,
+                        accessToken,
+                        refreshToken,
+                        ...expiration,
+                        user,
+                    };
+                }
+            }
+            catch {
+                // Access token is invalid or expired, continue to refresh logic
+            }
+            // Access token is expired, try to refresh using refresh token
+            try {
+                const tokens = await generateTokensFromRefreshToken({
+                    accessToken,
+                    refreshToken,
+                });
+                // Set new cookies
+                setAuthCookies(res, {
+                    accessToken: tokens.accessToken,
+                    refreshToken: tokens.refreshToken,
+                }, settings.refreshTokenTTLInDays * 24 * 60 * 60);
+                const user = await settings.dataProvider.findUserById(tokens.userId);
+                if (!user) {
+                    return unauthorizedError('USER_NOT_FOUND');
+                }
+                const expiration = calculateExpiration(settings.accessTokenTTL);
+                return {
+                    userId: tokens.userId,
+                    accessToken: tokens.accessToken,
+                    refreshToken: tokens.refreshToken,
+                    ...expiration,
+                    user,
+                };
+            }
+            catch (e) {
+                const errorMessage = e.message;
+                if (errorMessage === 'Invalid_Refresh_Token') {
+                    return unauthorizedError('INVALID_REFRESH_TOKEN');
+                }
+                if (errorMessage === 'Expired_Refresh_Token') {
+                    return unauthorizedError('EXPIRED_REFRESH_TOKEN');
+                }
+                return internalError('Cannot restore session.');
+            }
+        },
+    });
     authGroup.defineRoute({
         method: 'post',
         path: '/logout',

package/dist/types/types.d.ts

@@ -65,6 +65,14 @@ export type TokenResponse = {
     expiresIn: number;
     expiresAt: string;
 };
+export type RestoreResponse = {
+    userId: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    expiresAt: string;
+    user: unknown;
+};
 export type CreateTokenPayload = {
     sub: string;
     username: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotpress/auth",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "JWT Authentication plugin for Dotpress library",
   "author": "Renaud Guyon",
   "license": "MIT",
@@ -70,5 +70,6 @@
     "jwt",
     "plugin",
     "dotpress"
-  ]
+  ],
+  "packageManager": "pnpm@10.8.1+sha512.c50088ba998c67b8ca8c99df8a5e02fd2ae2e2b29aaf238feaa9e124248d3f48f9fb6db2424949ff901cffbb5e0f0cc1ad6aedb602cd29450751d11c35023677"
 }