@dotpress/auth 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# Dotpress Auth
+
+Authentication plugin for [dotpress](https://www.npmjs.com/package/dotpress) library using JWT tokens.
+You can use Prisma or any other ORM and easily connect it using the plugin DataProvider interface.
+
+
+[Full documentation here](https://dotpress.dev)
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @dotpress/auth
+```
+
+### 2. Register your plugin
+
+```ts
+// index.ts
+import { createApp, defineRoute } from 'dotpress'
+import { configurePlugin } from '@dotpress/auth'
+
+const authPlugin = configurePlugin({
+  // See configuration object below
+})
+
+const app = await createApp({
+  plugins: [authPlugin]
+})
+
+app.listen(3000, () => {
+  console.log('Server listening on port 3000')
+})
+```
+
+### 3. Usage
+
+The plugin will check and parse bearer token from Authorization header and will register the following routes (full API below)
+
+- `POST /auth/login`
+- `POST /auth/refresh`
+- `GET /auth/me`
+- `POST /auth/logout`
+
+---
+
+## 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
+
+### DataProvider type
+
+```ts
+type DataProvider = {
+  storeRefreshToken: (payload: StoreRefreshTokenDto) => Promise<void>
+  findRefreshToken: (tokenHash: string) => Promise<RefreshTokenData | undefined>
+  markRefreshTokenAsUsed: (tokenHash: string) => Promise<void>
+  revokeTokens: (userId: string) => Promise<void>
+  findUserById: <TUser = Record<string, unknown>>(
+    userId: string
+  ) => Promise<TUser | undefined>
+  findUserIdentifiers: (
+    username: string
+  ) => Promise<{ userId: string; passwordHash: string } | undefined>
+}
+
+
+type StoreRefreshTokenDto = {
+  token: string
+  tokenHash: string
+  userId: string
+  jwtId: string
+  expiresAt: Date
+}
+
+type RefreshTokenData = {
+  userId: string
+  jwtId: string
+  expiresAt: Date
+  isUsed: boolean
+  revokedAt?: Date | null
+}
+```
+
+## Endpoints
+
+### `POST /auth/login`
+
+Authenticate a user and generate tokens.
+
+Request Body:
+- username: string
+- password: string
+- client: optional user agent string
+
+Response:
+- userId: string
+- accessToken: string
+- refreshToken: string
+
+Returns 401 on failed login.
+
+### `POST /auth/refresh`
+
+Refresh tokens using previous token pair.
+
+Request Body:
+- accessToken: Previous access token, can be expired or still valid
+- refreshToken: Refresh token, must be valid, not used, not revoked
+
+Response:
+- userId: string
+- accessToken: string
+- refreshToken: string
+
+Returns 401 if tokens are not valid.
+
+### `POST /auth/logout`
+
+Revoke tokens for current authenticated user.
+
+Response:
+- 200 OK on success
+- 401 if user is not authenticated
+
+### `GET /auth/me`
+
+Get current authenticated user
+
+Response:
+- User object if user is authenticated
+- 401 if user is not authenticated
+
+
+## Prisma schema examples
+
+You will find below recommended schema for User and RefreshToken entities. Feel free to adapt them according to your needs.
+
+```text
+model User {
+  id                    String                 @id @default(cuid())
+  firstName             String?                @db.VarChar(100)
+  lastName              String?                @db.VarChar(100)
+  username              String                 @unique @db.VarChar(50)
+  pwdHash               String                 @db.VarChar(200)
+  email                 String                 @db.VarChar(200)
+  role                  String                 @db.VarChar(50)
+  createdAt             DateTime               @default(now())
+  updatedAt             DateTime               @updatedAt
+
+  @@map("users")
+}
+
+model RefreshToken {
+  id        String    @id @default(cuid())
+  userId    String    @db.VarChar(50)
+  jwtId     String    @db.VarChar(100)
+  tokenHash String    @unique @db.VarChar(100)
+  expiresAt DateTime
+  revokedAt DateTime?
+  isUsed    Boolean
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+
+  @@map("refresh_tokens")
+}
+```

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

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

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

@@ -0,0 +1,235 @@
+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('Handlers', () => {
+    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 onLoginFailedCallback = vi.fn();
+    const onLoginSuccessCallback = vi.fn();
+    const authPlugin = configurePlugin({
+        keys: {
+            secretKey: '',
+            publicKey: '',
+        },
+        dataProvider,
+        onLoginFailed: onLoginFailedCallback,
+        onLoginSuccess: onLoginSuccessCallback,
+    });
+    describe('Login Route', () => {
+        it('should return 401 if user not found', async () => {
+            const findUserIdentifiersFn = vi
+                .mocked(dataProvider.findUserIdentifiers)
+                .mockResolvedValue(undefined);
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+                client: 'User-Agent String',
+            });
+            expect(res.status).toBe(401);
+            expect(findUserIdentifiersFn).toHaveBeenCalledTimes(1);
+            expect(findUserIdentifiersFn).toHaveBeenCalledWith('JaneDoe');
+            expect(onLoginFailedCallback).toHaveBeenCalledTimes(1);
+            expect(onLoginFailedCallback).toHaveBeenCalledWith({
+                username: 'JaneDoe',
+                errorType: 'invalid_username',
+                client: 'User-Agent String',
+                ipAddress: '',
+            });
+        });
+        it('should return 401 if user password mismatches', async () => {
+            const findUserIdentifiersFn = vi
+                .mocked(dataProvider.findUserIdentifiers)
+                .mockResolvedValue({
+                userId: '101',
+                passwordHash: '',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/login').send({
+                username: 'JaneDoe',
+                password: '123456',
+            });
+            expect(res.status).toBe(401);
+            expect(findUserIdentifiersFn).toHaveBeenCalledTimes(1);
+            expect(findUserIdentifiersFn).toHaveBeenCalledWith('JaneDoe');
+            expect(onLoginFailedCallback).toHaveBeenCalledTimes(1);
+            expect(onLoginFailedCallback).toHaveBeenCalledWith({
+                username: 'JaneDoe',
+                errorType: 'invalid_password',
+                client: '',
+                ipAddress: '',
+            });
+        });
+        it('should return tokens if password is correct', async () => {
+            const pwdHash = await bcrypt.hash('123456', 10);
+            const findUserIdentifiersFn = 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);
+            expect(findUserIdentifiersFn).toHaveBeenCalledTimes(1);
+            expect(findUserIdentifiersFn).toHaveBeenCalledWith('JaneDoe');
+            expect(onLoginSuccessCallback).toHaveBeenCalledTimes(1);
+            expect(onLoginSuccessCallback).toHaveBeenCalledWith({
+                userId: '101',
+                username: 'JaneDoe',
+                client: '',
+                ipAddress: '',
+            });
+            expect(res.body).toEqual({
+                userId: '101',
+                accessToken: 'acc-111222333',
+                refreshToken: 'ref-999888777',
+            });
+        });
+    });
+    describe('Refresh Token Route', () => {
+        it('should return 401 if refresh token is invalid', async () => {
+            const generateTokenFn = vi
+                .spyOn(tokenFns, 'generateTokensFromRefreshToken')
+                .mockImplementation(() => {
+                throw new Error('Invalid_Refresh_Token');
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/refresh').send({
+                accessToken: '123456789',
+                refreshToken: '000000000',
+            });
+            expect(res.status).toBe(401);
+            expect(res.body).toEqual({
+                status: 401,
+                error: 'UNAUTHORIZED',
+                message: 'INVALID_REFRESH_TOKEN',
+            });
+            expect(generateTokenFn).toHaveBeenCalledTimes(1);
+            expect(generateTokenFn).toHaveBeenCalledWith({
+                accessToken: '123456789',
+                refreshToken: '000000000',
+            });
+        });
+        it('should return 200 OK and new tokens if refresh token is valid', async () => {
+            const generateTokenFn = vi
+                .spyOn(tokenFns, 'generateTokensFromRefreshToken')
+                .mockResolvedValue({
+                userId: '102',
+                accessToken: '111222333',
+                refreshToken: '111111111',
+            });
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/refresh').send({
+                accessToken: '123456789',
+                refreshToken: '000000000',
+            });
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({
+                userId: '102',
+                accessToken: '111222333',
+                refreshToken: '111111111',
+            });
+            expect(generateTokenFn).toHaveBeenCalledTimes(1);
+            expect(generateTokenFn).toHaveBeenCalledWith({
+                accessToken: '123456789',
+                refreshToken: '000000000',
+            });
+        });
+    });
+    describe('Current User Route', () => {
+        it('should return 401 if no current user', async () => {
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).get('/auth/me');
+            expect(res.status).toBe(401);
+        });
+        it('should load current user', async () => {
+            const findUserFn = vi
+                .mocked(dataProvider.findUserById)
+                .mockResolvedValue({
+                id: 'usr-123',
+                username: 'JohnDoe111',
+                email: 'JohnDoe111@example.com',
+            });
+            const decodeFn = 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 0123456789');
+            expect(decodeFn).toBeCalledWith('0123456789');
+            expect(findUserFn).toBeCalledTimes(1);
+            expect(findUserFn).toBeCalledWith('usr-123');
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({
+                id: 'usr-123',
+                username: 'JohnDoe111',
+                email: 'JohnDoe111@example.com',
+            });
+        });
+    });
+    describe('Logout Route', () => {
+        it('should return 401 if no current user', async () => {
+            const app = await createApp({
+                plugins: [authPlugin],
+            });
+            const res = await request(app).post('/auth/logout');
+            expect(res.status).toBe(401);
+        });
+        it('should revoke token and return 200 OK', async () => {
+            vi.mocked(dataProvider.findUserById).mockResolvedValue({
+                id: 'usr-123',
+                username: 'JohnDoe111',
+                email: 'JohnDoe111@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 0123456789');
+            expect(vi.mocked(dataProvider.revokeTokens)).toBeCalledTimes(1);
+            expect(vi.mocked(dataProvider.revokeTokens)).toBeCalledWith('usr-123');
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ success: true });
+        });
+    });
+});

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

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

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

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import request from 'supertest';
+import { createApp, defineRoute } from 'dotpress';
+import * as tokenFns from '../../lib/tokens.js';
+import { configurePlugin } from '../../index.js';
+describe('Middlewares', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    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,
+    });
+    it('should not attach a user if token not provided', async () => {
+        defineRoute({
+            path: '/test',
+            handler: async ({ req }) => {
+                return {
+                    status: 'ok',
+                    user: req.user,
+                };
+            },
+        });
+        const app = await createApp({
+            plugins: [authPlugin],
+        });
+        const res = await request(app).get('/test');
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({
+            status: 'ok',
+        });
+    });
+    it('should attach a user to request if authenticated', async () => {
+        const decodeFn = vi
+            .spyOn(tokenFns, 'validateAndDecodeAccessToken')
+            .mockReturnValue({ userId: 'usr-123' });
+        const findUserFn = vi.mocked(dataProvider.findUserById).mockResolvedValue({
+            id: 'usr-123',
+            username: 'JohnDoe111',
+            email: 'JohnDoe111@example.com',
+        });
+        defineRoute({
+            path: '/test',
+            handler: async ({ req }) => {
+                return {
+                    status: 'ok',
+                    user: req.user,
+                };
+            },
+        });
+        const app = await createApp({
+            plugins: [authPlugin],
+        });
+        const res = await request(app)
+            .get('/test')
+            .set('Authorization', 'Bearer 1234567890');
+        expect(decodeFn).toBeCalledWith('1234567890');
+        expect(findUserFn).toBeCalledTimes(1);
+        expect(findUserFn).toBeCalledWith('usr-123');
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({
+            status: 'ok',
+            user: {
+                id: 'usr-123',
+                username: 'JohnDoe111',
+                email: 'JohnDoe111@example.com',
+            },
+        });
+    });
+    it('should not attach a user if token is valid but user provider returns nothing', async () => {
+        const decodeFn = vi
+            .spyOn(tokenFns, 'validateAndDecodeAccessToken')
+            .mockReturnValue({ userId: 'usr-123' });
+        const findUserFn = vi
+            .mocked(dataProvider.findUserById)
+            .mockResolvedValue(undefined);
+        defineRoute({
+            path: '/test',
+            handler: async ({ req }) => {
+                return {
+                    status: 'ok',
+                    user: req.user,
+                };
+            },
+        });
+        const app = await createApp({
+            plugins: [authPlugin],
+        });
+        const res = await request(app)
+            .get('/test')
+            .set('Authorization', 'Bearer 1234567890');
+        expect(decodeFn).toBeCalledWith('1234567890');
+        expect(findUserFn).toBeCalledTimes(1);
+        expect(findUserFn).toBeCalledWith('usr-123');
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({
+            status: 'ok',
+        });
+    });
+});

package/dist/__tests__/unit/tokens.test.d.ts

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

package/dist/__tests__/unit/tokens.test.js

@@ -0,0 +1,225 @@
+import { describe, it, expect, beforeEach, vi, beforeAll, afterEach, } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { setSettings } from '../../lib/settings.js';
+import * as tokenFns from '../../lib/tokens.js';
+import * as generators from '../../lib/generators.js';
+describe('Tokens', () => {
+    const dataProvider = {
+        storeRefreshToken: vi.fn(),
+        findRefreshToken: vi.fn(),
+        markRefreshTokenAsUsed: vi.fn(),
+        revokeTokens: vi.fn(),
+        findUserById: vi.fn(),
+        findUserIdentifiers: vi.fn(),
+    };
+    beforeAll(() => {
+        setSettings({
+            keys: {
+                secretKey: 'secret_111222',
+                publicKey: 'public_111222',
+            },
+            issuer: 'auth.myapp.com',
+            accessTokenTTL: 3600,
+            dataProvider,
+        });
+    });
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2025-01-01T00:00:00Z'));
+        vi.spyOn(generators, 'generateUUID').mockReturnValue('000-000-000-000-000');
+    });
+    afterEach(() => {
+        vi.resetAllMocks();
+        vi.useRealTimers();
+    });
+    describe('Function: createAccessTokenFromPayload()', () => {
+        it('should generate token and return expected data', () => {
+            // @ts-expect-error issues with jsonwebtoken types
+            const jwtSignFn = vi.spyOn(jwt, 'sign').mockReturnValue('acc-1111111111');
+            const output = tokenFns.createAccessTokenFromPayload({
+                sub: '101',
+                username: 'JaneDoe',
+                auth_time: 1735689600000,
+            });
+            expect(jwtSignFn).toHaveBeenCalledTimes(1);
+            expect(jwtSignFn).toHaveBeenCalledWith({
+                sub: '101',
+                username: 'JaneDoe',
+                auth_time: 1735689600000,
+            }, 'secret_111222', {
+                algorithm: 'RS256',
+                issuer: 'auth.myapp.com',
+                expiresIn: 3600,
+                jwtid: '000-000-000-000-000',
+            });
+            expect(output).toEqual({
+                jwtId: '000-000-000-000-000',
+                accessToken: 'acc-1111111111',
+            });
+        });
+    });
+    describe('Function: generateRefreshToken()', () => {
+        it('should return token and hashed token', () => {
+            const output = tokenFns.generateRefreshToken();
+            expect(output).toEqual({
+                token: expect.any(String),
+                tokenHash: expect.any(String),
+            });
+        });
+    });
+    describe('Function: generateTokensForUser()', () => {
+        it('should generate tokens and return expected data', async () => {
+            const storeRefreshTokenFn = vi
+                .mocked(dataProvider.storeRefreshToken)
+                .mockResolvedValue();
+            // @ts-expect-error issues with jsonwebtoken types
+            vi.spyOn(jwt, 'sign').mockReturnValue('acc-1111111111');
+            const output = await tokenFns.generateTokensForUser({
+                userId: '110',
+                username: 'JaneDoe',
+            });
+            expect(storeRefreshTokenFn).toHaveBeenCalledTimes(1);
+            expect(storeRefreshTokenFn).toHaveBeenCalledWith({
+                token: expect.any(String),
+                tokenHash: expect.any(String),
+                userId: '110',
+                jwtId: '000-000-000-000-000',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+            });
+            expect(output).toEqual({
+                accessToken: 'acc-1111111111',
+                refreshToken: expect.any(String),
+            });
+        });
+    });
+    describe('Function: generateTokensFromRefreshToken()', () => {
+        beforeEach(() => {
+            // @ts-expect-error issues with jsonwebtoken types
+            vi.spyOn(jwt, 'verify').mockReturnValue({
+                sub: '110',
+                jti: 'jwt900',
+            });
+        });
+        it('should throw error if token not found', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue(undefined);
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Invalid_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should throw error if token is revoked found', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '110',
+                jwtId: 'jwt900',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+                isUsed: false,
+                revokedAt: new Date(),
+            });
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Invalid_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should throw error if token is used', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '110',
+                jwtId: 'jwt900',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+                isUsed: true,
+                revokedAt: null,
+            });
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Invalid_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should throw error if userId mismatches', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '200',
+                jwtId: 'jwt900',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+                isUsed: false,
+                revokedAt: null,
+            });
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Invalid_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should throw error if jwtid mismatches', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '110',
+                jwtId: 'jwt100',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+                isUsed: false,
+                revokedAt: null,
+            });
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Invalid_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should throw error if refresh token is expired', async () => {
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '110',
+                jwtId: 'jwt900',
+                expiresAt: new Date('2024-12-31T00:00:00.000Z'),
+                isUsed: false,
+                revokedAt: null,
+            });
+            await expect(tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            })).rejects.toThrow('Expired_Refresh_Token');
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should generate new tokens if refresh token is valid', async () => {
+            // @ts-expect-error issues with jsonwebtoken types
+            vi.spyOn(jwt, 'sign').mockReturnValue('acc-1111111111');
+            const findRefreshTokenSpy = vi
+                .spyOn(dataProvider, 'findRefreshToken')
+                .mockResolvedValue({
+                userId: '110',
+                jwtId: 'jwt900',
+                expiresAt: new Date('2025-01-15T00:00:00.000Z'),
+                isUsed: false,
+                revokedAt: null,
+            });
+            const storeRefreshTokenFn = vi
+                .mocked(dataProvider.storeRefreshToken)
+                .mockResolvedValue();
+            const markRefreshTokenAsUsedFn = vi
+                .mocked(dataProvider.markRefreshTokenAsUsed)
+                .mockResolvedValue();
+            const output = await tokenFns.generateTokensFromRefreshToken({
+                accessToken: 'acc100',
+                refreshToken: 'refr100',
+            });
+            expect(findRefreshTokenSpy).toHaveBeenCalledTimes(1);
+            expect(storeRefreshTokenFn).toHaveBeenCalledTimes(1);
+            expect(markRefreshTokenAsUsedFn).toHaveBeenCalledTimes(1);
+            expect(output).toEqual({
+                userId: '110',
+                accessToken: 'acc-1111111111',
+                refreshToken: expect.any(String),
+            });
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { Plugin } from 'dotpress';
+import { AuthSettings, DataProvider, KeyPairSettings } from './types/types.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 {};

package/dist/index.js

@@ -0,0 +1,16 @@
+import { setSettings } from './lib/settings.js';
+import { registerHandlers } from './lib/handlers.js';
+import { attachAuthenticatedUser } from './lib/middleware.js';
+import bcrypt from 'bcryptjs';
+export const configurePlugin = (settings) => {
+    setSettings(settings);
+    return (plugin) => {
+        plugin.useBeforeRoutes((app) => {
+            app.use(attachAuthenticatedUser);
+        });
+        registerHandlers(plugin);
+    };
+};
+export const generatePasswordHash = (password, salt = 10) => {
+    return bcrypt.hash(password, salt);
+};

package/dist/lib/generators.d.ts

@@ -0,0 +1 @@
+export declare const generateUUID: () => `${string}-${string}-${string}-${string}-${string}`;

package/dist/lib/generators.js

@@ -0,0 +1,4 @@
+import { randomUUID } from 'crypto';
+export const generateUUID = () => {
+    return randomUUID();
+};

package/dist/lib/handlers.d.ts

@@ -0,0 +1,2 @@
+import type { PluginAPI } from 'dotpress';
+export declare const registerHandlers: (plugin: PluginAPI) => void;

package/dist/lib/handlers.js

@@ -0,0 +1,131 @@
+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';
+export const registerHandlers = (plugin) => {
+    const authGroup = plugin.addGroup('/auth');
+    const settings = getSettings();
+    authGroup.defineRoute({
+        method: 'post',
+        path: '/login',
+        schema: (z) => ({
+            body: z.object({
+                username: z.string(),
+                password: z.string(),
+                client: z.string().optional(),
+            }),
+            response: z.object({
+                userId: z.string(),
+                accessToken: z.string(),
+                refreshToken: z.string(),
+            }),
+        }),
+        handler: async ({ req }) => {
+            const { username, password, client } = req.body;
+            const ipAddress = getRequestIp(req);
+            const user = await settings.dataProvider.findUserIdentifiers(username);
+            if (!user) {
+                if (settings.onLoginFailed) {
+                    await settings.onLoginFailed({
+                        username,
+                        errorType: 'invalid_username',
+                        client: client || '',
+                        ipAddress: ipAddress || '',
+                    });
+                }
+                return unauthorizedError('INVALID_LOGIN');
+            }
+            const isPasswordValid = await bcrypt.compare(password, user.passwordHash);
+            if (!isPasswordValid) {
+                if (settings.onLoginFailed) {
+                    await settings.onLoginFailed({
+                        username,
+                        errorType: 'invalid_password',
+                        client: client || '',
+                        ipAddress: ipAddress || '',
+                    });
+                }
+                return unauthorizedError('INVALID_LOGIN');
+            }
+            const { accessToken, refreshToken } = await generateTokensForUser({
+                username,
+                userId: user.userId,
+            });
+            if (settings.onLoginSuccess) {
+                await settings.onLoginSuccess({
+                    userId: user.userId,
+                    username,
+                    client: client || '',
+                    ipAddress: ipAddress || '',
+                });
+            }
+            return {
+                userId: user.userId,
+                accessToken,
+                refreshToken,
+            };
+        },
+    });
+    authGroup.defineRoute({
+        method: 'post',
+        path: '/refresh',
+        schema: (z) => ({
+            body: z.object({
+                accessToken: z.string(),
+                refreshToken: z.string(),
+            }),
+            response: z.object({
+                userId: z.string(),
+                accessToken: z.string(),
+                refreshToken: z.string(),
+            }),
+        }),
+        handler: async ({ req }) => {
+            const { accessToken, refreshToken } = req.body;
+            try {
+                const tokens = await generateTokensFromRefreshToken({
+                    accessToken,
+                    refreshToken,
+                });
+                return {
+                    userId: tokens.userId,
+                    accessToken: tokens.accessToken,
+                    refreshToken: tokens.refreshToken,
+                };
+            }
+            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('Can not refresh tokens.');
+            }
+        },
+    });
+    authGroup.defineRoute({
+        method: 'get',
+        path: '/me',
+        handler: async ({ req }) => {
+            if (!req.user) {
+                return unauthorizedError();
+            }
+            return req.user;
+        },
+    });
+    authGroup.defineRoute({
+        method: 'post',
+        path: '/logout',
+        handler: async ({ req }) => {
+            const userId = req.user?.id || '';
+            if (!userId) {
+                return unauthorizedError();
+            }
+            await settings.dataProvider.revokeTokens(userId);
+            return { success: true };
+        },
+    });
+};

package/dist/lib/ip.d.ts

@@ -0,0 +1,2 @@
+import type { Request } from 'express';
+export declare const getRequestIp: (req: Request) => string | null;

package/dist/lib/ip.js

@@ -0,0 +1,15 @@
+import requestIp from 'request-ip';
+export const getRequestIp = (req) => {
+    const clientIp = requestIp.getClientIp(req);
+    const localIps = [
+        '127.0.0.1',
+        'localhost',
+        '::1',
+        '::ffff',
+        '::ffff:127.0.0.1',
+    ];
+    if (clientIp && localIps.includes(clientIp)) {
+        return null;
+    }
+    return clientIp;
+};

package/dist/lib/middleware.d.ts

@@ -0,0 +1,2 @@
+import type { Request, Response, NextFunction } from 'express';
+export declare const attachAuthenticatedUser: (req: Request, _res: Response, next: NextFunction) => Promise<void>;

package/dist/lib/middleware.js

@@ -0,0 +1,24 @@
+import { getSettings } from './settings.js';
+import { validateAndDecodeAccessToken } from './tokens.js';
+export const attachAuthenticatedUser = async (req, _res, next) => {
+    const accessToken = req.headers && req.headers.authorization
+        ? req.headers.authorization.replace('Bearer ', '')
+        : '';
+    if (!accessToken) {
+        next();
+        return;
+    }
+    try {
+        const settings = getSettings();
+        const { userId } = validateAndDecodeAccessToken(accessToken);
+        const user = await settings.dataProvider.findUserById(userId);
+        if (user) {
+            req.user = user;
+        }
+        next();
+    }
+    catch (e) {
+        console.warn(e);
+        next();
+    }
+};

package/dist/lib/settings.d.ts

@@ -0,0 +1,3 @@
+import { PluginSettings } from '../types/types.js';
+export declare const setSettings: (settings: Partial<PluginSettings>) => void;
+export declare const getSettings: () => PluginSettings;

package/dist/lib/settings.js

@@ -0,0 +1,42 @@
+let pluginSettings = {
+    accessTokenTTL: 3600,
+    refreshTokenTTLInDays: 14,
+    issuer: '',
+    keys: {
+        secretKey: '',
+        publicKey: '',
+    },
+    dataProvider: {
+        storeRefreshToken: () => {
+            throw new Error('storeRefreshToken() is not implemented.');
+        },
+        findRefreshToken: () => {
+            throw new Error('findRefreshToken() is not implemented.');
+        },
+        markRefreshTokenAsUsed: () => {
+            throw new Error('markRefreshTokenAsUsed() is not implemented.');
+        },
+        revokeTokens: () => {
+            throw new Error('revokeTokens() is not implemented.');
+        },
+        findUserById: () => {
+            throw new Error('findUserById() is not implemented.');
+        },
+        findUserIdentifiers: () => {
+            throw new Error('findUserByUsername() is not implemented.');
+        },
+    },
+    onLoginFailed: () => {
+        return Promise.resolve();
+    },
+    onLoginSuccess: () => {
+        return Promise.resolve();
+    },
+};
+export const setSettings = (settings) => {
+    pluginSettings = {
+        ...pluginSettings,
+        ...settings,
+    };
+};
+export const getSettings = () => pluginSettings;

package/dist/lib/tokens.d.ts

@@ -0,0 +1,35 @@
+import { TokenPair } from '../types/types.js';
+type CreateTokenPayload = {
+    sub: string;
+    username: string;
+    auth_time: number;
+};
+type CreatedAccessToken = {
+    jwtId: string;
+    accessToken: string;
+};
+type CreatedRefreshToken = {
+    token: string;
+    tokenHash: string;
+};
+type UserIdentifiers = {
+    userId: string;
+    username: string;
+};
+export declare const createAccessTokenFromPayload: (payload: CreateTokenPayload) => CreatedAccessToken;
+export declare const generateRefreshToken: () => CreatedRefreshToken;
+/**
+ * Generate a pair of access and refresh tokens for a given user
+ */
+export declare const generateTokensForUser: ({ userId, username, }: UserIdentifiers) => Promise<TokenPair>;
+/**
+ * Regenerate a pair of token using a refresh token
+ * Expired access token must be provided in order to validate userId and jwtId
+ */
+export declare const generateTokensFromRefreshToken: ({ accessToken, refreshToken, }: TokenPair) => Promise<TokenPair & {
+    userId: string;
+}>;
+export declare const validateAndDecodeAccessToken: (accessToken: string) => {
+    userId: string;
+};
+export {};

package/dist/lib/tokens.js

@@ -0,0 +1,107 @@
+import jwt from 'jsonwebtoken';
+import { randomBytes, createHash } from 'crypto';
+import { getSettings } from './settings.js';
+import { generateUUID } from './generators.js';
+export const createAccessTokenFromPayload = (payload) => {
+    const jwtId = generateUUID();
+    const settings = getSettings();
+    const accessToken = jwt.sign(payload, settings.keys.secretKey, {
+        algorithm: 'RS256',
+        issuer: settings.issuer,
+        expiresIn: settings.accessTokenTTL,
+        jwtid: jwtId,
+    });
+    return {
+        jwtId,
+        accessToken,
+    };
+};
+export const generateRefreshToken = () => {
+    const token = randomBytes(128).toString('hex');
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    return {
+        token,
+        tokenHash,
+    };
+};
+/**
+ * Generate a pair of access and refresh tokens for a given user
+ */
+export const generateTokensForUser = async ({ userId, username, }) => {
+    const settings = getSettings();
+    const { jwtId, accessToken } = createAccessTokenFromPayload({
+        sub: userId,
+        username,
+        auth_time: Math.floor(Date.now() / 1000),
+    });
+    const { token: refreshToken, tokenHash: refreshTokenHash } = generateRefreshToken();
+    await settings.dataProvider.storeRefreshToken({
+        token: refreshToken,
+        tokenHash: refreshTokenHash,
+        userId,
+        jwtId,
+        expiresAt: addDaysFromNow(settings.refreshTokenTTLInDays),
+    });
+    return {
+        accessToken,
+        refreshToken,
+    };
+};
+const addDaysFromNow = (days) => {
+    const now = new Date();
+    now.setDate(now.getDate() + days);
+    return now;
+};
+/**
+ * Regenerate a pair of token using a refresh token
+ * Expired access token must be provided in order to validate userId and jwtId
+ */
+export const generateTokensFromRefreshToken = async ({ accessToken, refreshToken, }) => {
+    const settings = getSettings();
+    const decodedToken = jwt.verify(accessToken, settings.keys.publicKey, {
+        ignoreExpiration: true,
+    });
+    const userId = String(decodedToken.sub);
+    const refreshTokenHash = createHash('sha256')
+        .update(refreshToken)
+        .digest('hex');
+    const refreshTokenData = await settings.dataProvider.findRefreshToken(refreshTokenHash);
+    if (!refreshTokenData ||
+        refreshTokenData.revokedAt ||
+        refreshTokenData.isUsed ||
+        refreshTokenData.userId !== userId ||
+        refreshTokenData.jwtId !== decodedToken.jti) {
+        throw new Error('Invalid_Refresh_Token');
+    }
+    if (refreshTokenData.expiresAt.getTime() <= Date.now()) {
+        throw new Error('Expired_Refresh_Token');
+    }
+    const { jwtId, accessToken: newAccessToken } = createAccessTokenFromPayload({
+        sub: userId,
+        username: decodedToken.username,
+        auth_time: decodedToken.auth_time,
+    });
+    const newRefreshToken = generateRefreshToken();
+    await settings.dataProvider.storeRefreshToken({
+        ...newRefreshToken,
+        userId,
+        jwtId,
+        expiresAt: addDaysFromNow(settings.refreshTokenTTLInDays),
+    });
+    await settings.dataProvider.markRefreshTokenAsUsed(refreshTokenHash);
+    return {
+        userId,
+        accessToken: newAccessToken,
+        refreshToken: newRefreshToken.token,
+    };
+};
+export const validateAndDecodeAccessToken = (accessToken) => {
+    const settings = getSettings();
+    const { sub: userId } = jwt.verify(accessToken, settings.keys.publicKey);
+    if (!userId) {
+        throw new Error('Invalid_Access_Token');
+    }
+    return {
+        userId: String(userId),
+    };
+};

package/dist/types/types.d.ts

@@ -0,0 +1,74 @@
+import type { JwtPayload } from 'jsonwebtoken';
+declare global {
+    namespace Express {
+        interface Request {
+            user?: unknown;
+        }
+    }
+}
+export type KeyPairSettings = {
+    secretKey: string;
+    publicKey: string;
+};
+export type AuthSettings = {
+    accessTokenTTL: number;
+    refreshTokenTTLInDays: number;
+    issuer: string;
+    onLoginFailed?: (e: LoginFailedEvent) => Promise<void>;
+    onLoginSuccess?: (e: LoginSuccessEvent) => Promise<void>;
+};
+type LoginFailedEvent = {
+    username: string;
+    errorType: 'invalid_username' | 'invalid_password' | string;
+    client: string;
+    ipAddress: string;
+};
+type LoginSuccessEvent = {
+    userId: string;
+    username: string;
+    client: string;
+    ipAddress: string;
+};
+export type PluginSettings = AuthSettings & {
+    keys: KeyPairSettings;
+    dataProvider: DataProvider;
+};
+export interface AppJwtPayload extends JwtPayload {
+    username: string;
+    auth_time: number;
+}
+export type TokenPair = {
+    accessToken: string;
+    refreshToken: string;
+};
+export type CreateTokenPayload = {
+    sub: string;
+    username: string;
+    auth_time: number;
+};
+export type StoreRefreshTokenDto = {
+    token: string;
+    tokenHash: string;
+    userId: string;
+    jwtId: string;
+    expiresAt: Date;
+};
+export type RefreshTokenData = {
+    userId: string;
+    jwtId: string;
+    expiresAt: Date;
+    isUsed: boolean;
+    revokedAt?: Date | null;
+};
+export type DataProvider = {
+    storeRefreshToken: (payload: StoreRefreshTokenDto) => Promise<void>;
+    findRefreshToken: (tokenHash: string) => Promise<RefreshTokenData | undefined>;
+    markRefreshTokenAsUsed: (tokenHash: string) => Promise<void>;
+    revokeTokens: (userId: string) => Promise<void>;
+    findUserById: <TUser = Record<string, unknown>>(userId: string) => Promise<TUser | undefined>;
+    findUserIdentifiers: (username: string) => Promise<{
+        userId: string;
+        passwordHash: string;
+    } | undefined>;
+};
+export {};

package/dist/types/types.js

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@dotpress/auth",
+  "version": "1.0.0",
+  "description": "JWT Authentication plugin for Dotpress library",
+  "author": "Renaud Guyon",
+  "license": "MIT",
+  "homepage": "https://dotpress.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/renoguyon/dotpress-auth-plugin"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:watch": "vitest watch"
+  },
+  "peerDependencies": {
+    "dotpress": "^1",
+    "zod": "^3"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "jsonwebtoken": "^9.0.2",
+    "request-ip": "^3.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/bcrypt": "^5.0.2",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/request-ip": "^0.0.41",
+    "@types/supertest": "^6.0.3",
+    "@vitest/ui": "^3.1.1",
+    "dotpress": "^1",
+    "eslint": "^9.24.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "^3.5.3",
+    "supertest": "^7.1.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1",
+    "vitest": "^3.1.2"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "auth",
+    "authentication",
+    "node",
+    "backend",
+    "rest",
+    "jwt",
+    "plugin",
+    "dotpress"
+  ]
+}