@maximemrf/adonisjs-jwt 0.5.0 → 0.6.0

package/README.md

@@ -13,10 +13,10 @@
 
 ## Prerequisites
 
-You have to install the auth package from AdonisJS with the session guard because the jwt package use some components from the session guard.
+You have to install the auth package from AdonisJS
 
 ```bash
-node ace add @adonisjs/auth --guard=session
+node ace add @adonisjs/auth
 ```
 
 ## Setup
@@ -35,6 +35,7 @@ Go to `config/auth.ts` and add the following configuration:
 import { defineConfig } from '@adonisjs/auth'
 import { InferAuthEvents, Authenticators } from '@adonisjs/auth/types'
 import { sessionGuard, sessionUserProvider } from '@adonisjs/auth/session'
+import { tokensUserProvider } from '@adonisjs/auth/access_tokens'
 import { jwtGuard } from '@maximemrf/adonisjs-jwt/jwt_config'
 import { JwtGuardUser, BaseJwtContent } from '@maximemrf/adonisjs-jwt/types'
 import User from '#models/user'
@@ -69,6 +70,11 @@ const authConfig = defineConfig({
       provider: sessionUserProvider({
         model: () => import('#models/user'),
       }),
+      // if you want to use refresh tokens, you have to set the refreshTokenUserProvider
+      refreshTokenUserProvider: tokensUserProvider({
+        tokens: 'refreshTokens',
+        model: () => import('#models/user'),
+      }),
       // content is a function that takes the user and returns the content of the token, it can be optional, by default it returns only the user id
       content: <T>(user: JwtGuardUser<T>): JwtContent => {
         return {
@@ -81,13 +87,13 @@ const authConfig = defineConfig({
 })
 ```
 
-`tokenName` is the name of the token passed as a cookie, it can be optional, by default it is `token`.
+`tokenName` is the name of the jwt token passed as a cookie, it can be optional, by default it is `token`.
 
 ```typescript
 tokenName: 'custom-name'
 ```
 
-`tokenExpiresIn` is the time before the token expires it can be a string or a number and it can be optional.
+`tokenExpiresIn` is the time before the jwt token expires it can be a string or a number and it can be optional.
 
 ```typescript
 // string
@@ -104,6 +110,67 @@ useCookies: true
 
 If you just want to use jwt with the bearer token no need to set `useCookies` to `false` you can just remove it.
 
+## Refresh Tokens
+
+To use refresh tokens, you have to set the `refreshTokenUserProvider` in the guard configuration, see the example above.
+
+Create a new AdonisJS migration file and run it to create the `jwt_refresh_tokens` table:
+
+```typescript
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'jwt_refresh_tokens'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments()
+      table.integer('tokenable_id').notNullable().unsigned()
+      table.string('type').notNullable()
+      table.string('name').nullable()
+      table.string('hash', 80).notNullable()
+      table.text('abilities').notNullable()
+      table.timestamp('created_at', { precision: 6, useTz: true }).notNullable()
+      table.timestamp('updated_at', { precision: 6, useTz: true }).notNullable()
+      table.timestamp('expires_at', { precision: 6, useTz: true }).nullable()
+      table.timestamp('last_used_at', { precision: 6, useTz: true }).nullable()
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}
+```
+
+And add the `refreshTokens` property to your User model:
+
+```typescript
+import { column, BaseModel } from '@adonisjs/lucid/orm'
+import { DbAccessTokensProvider } from '@adonisjs/auth/access_tokens'
+
+export default class User extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare username: string
+
+  @column()
+  declare email: string
+
+  @column()
+  declare password: string
+
+  static refreshTokens = DbAccessTokensProvider.forModel(User, {
+    prefix: 'rt_',
+    table: 'jwt_refresh_tokens',
+    type: 'jwt_refresh_token',
+    tokenSecretLength: 40,
+  })
+}
+```
+
 ## Authentication
 
 To make a protected route, you have to use the `auth` middleware with the `jwt` guard.
@@ -128,6 +195,26 @@ router.get('/', async ({ auth }) => {
   return auth.use('jwt').getUserOrFail()
 })
 .use(middleware.auth({ guards: ['jwt'] }))
+
+// to create a refresh token to a given user
+import User from '#models/user'
+const user  = auth.getUserOrFail()
+const refreshToken = await User.refreshTokens.create(user)
+
+// if you use the refresh token
+router.post('jwt/refresh', async ({ auth }) => {
+  // this will authenticate the user using the refresh token
+  // it will delete the old refresh token and generate a new one
+  const user = await auth.use('jwt').authenticateWithRefreshToken()
+  const newRefreshToken = user.currentToken
+  const newToken = await auth.use('jwt').generate(user)
+
+  return response.ok({
+    token: newToken,
+    refreshToken: newRefreshToken,
+    ...user.serialize(),
+  })
+})
 ```
 
 ## Security

package/build/src/define_config.d.ts

@@ -3,8 +3,10 @@ import type { HttpContext } from '@adonisjs/core/http';
 import { JwtGuardUser, JwtUserProviderContract } from './types.js';
 import { JwtGuard } from './jwt.js';
 import type { StringValue } from 'ms';
+import { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens';
 export declare function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>>(config: {
     provider: UserProvider;
+    refreshTokenUserProvider?: AccessTokensUserProviderContract<unknown>;
     tokenName?: string;
     tokenExpiresIn?: number | StringValue;
     useCookies?: boolean;

package/build/src/define_config.js

@@ -5,6 +5,7 @@ export function jwtGuard(config) {
             const appKey = app.config.get('app.appKey').release();
             const options = {
                 secret: config.secret ?? appKey,
+                refreshTokenUserProvider: config.refreshTokenUserProvider,
                 tokenName: config.tokenName,
                 expiresIn: config.tokenExpiresIn,
                 useCookies: config.useCookies,

package/build/src/jwt.d.ts

@@ -46,6 +46,9 @@ export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unkno
     authenticate(): Promise<UserProvider[typeof symbols.PROVIDER_REAL_USER] & {
         currentToken: string;
     }>;
+    authenticateWithRefreshToken(): Promise<UserProvider[typeof symbols.PROVIDER_REAL_USER] & {
+        currentToken: string;
+    }>;
     /**
      * Same as authenticate, but does not throw an exception
      */

package/build/src/jwt.js

@@ -1,14 +1,17 @@
 import { errors } from '@adonisjs/auth';
 import jwt from 'jsonwebtoken';
+import { Secret } from '@adonisjs/core/helpers';
 export class JwtGuard {
     #ctx;
     #userProvider;
+    #refreshTokenUserProvider;
     #options;
     #tokenName;
     constructor(ctx, userProvider, option) {
         this.#ctx = ctx;
         this.#userProvider = userProvider;
         this.#options = option;
+        this.#refreshTokenUserProvider = this.#options.refreshTokenUserProvider;
         if (!this.#options.content)
             this.#options.content = (user) => ({ userId: user.getId() });
         this.#tokenName = this.#options.tokenName ?? 'token';
@@ -132,6 +135,76 @@ export class JwtGuard {
         this.user.currentToken = token;
         return this.getUserOrFail();
     }
+    async authenticateWithRefreshToken() {
+        /**
+         * Avoid re-authentication when it has been done already
+         * for the given request
+         */
+        if (this.authenticationAttempted) {
+            return this.getUserOrFail();
+        }
+        this.authenticationAttempted = true;
+        /**
+         * Ensure the refresh token user provider is defined
+         */
+        if (!this.#refreshTokenUserProvider) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        /**
+         * Ensure the auth header exists
+         */
+        const authHeader = this.#ctx.request.header('authorization');
+        if (!authHeader) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        /**
+         * Split the header value and read the token from it
+         */
+        const [, refreshToken] = authHeader.split('Bearer ');
+        if (!refreshToken) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        const accessToken = await this.#refreshTokenUserProvider.verifyToken(new Secret(refreshToken));
+        if (!accessToken) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        /**
+         * Fetch the user by user ID
+         */
+        const providerUser = await this.#refreshTokenUserProvider.findById(accessToken.tokenableId);
+        if (!providerUser) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        this.isAuthenticated = true;
+        this.user = providerUser.getOriginal();
+        /**
+         * Delete the refresh token from the database
+         */
+        const isDeleted = await this.#refreshTokenUserProvider.invalidateToken(new Secret(refreshToken));
+        if (!isDeleted) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        const newRefreshToken = await this.#refreshTokenUserProvider.createToken(this.user);
+        if (!newRefreshToken.value) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
+        }
+        this.user.currentToken = newRefreshToken.value?.release();
+        return this.getUserOrFail();
+    }
     /**
      * Same as authenticate, but does not throw an exception
      */

package/build/src/types.d.ts

@@ -1,5 +1,6 @@
 import { symbols } from '@adonisjs/auth';
 import type { StringValue } from 'ms';
+import { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens';
 /**
  * The bridge between the User provider and the
  * Guard
@@ -39,6 +40,7 @@ export type BaseJwtContent = {
 };
 export type JwtGuardOptions<RealUser extends any = unknown> = {
     secret: string;
+    refreshTokenUserProvider?: AccessTokensUserProviderContract<RealUser>;
     tokenName?: string;
     expiresIn?: number | StringValue;
     useCookies?: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maximemrf/adonisjs-jwt",
   "description": "Adonisjs v6 package for authentication with jwt token",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "engines": {
     "node": ">=20.6.0"
   },
@@ -42,6 +42,7 @@
     "@adonisjs/prettier-config": "^1.4.4",
     "@adonisjs/tsconfig": "^1.4.0",
     "@japa/assert": "^4.0.1",
+    "@japa/file-system": "^2.3.2",
     "@japa/runner": "^4.2.0",
     "@swc/core": "1.11.24",
     "@types/node": "^22.15.18",
@@ -52,6 +53,7 @@
     "luxon": "^3.4.4",
     "np": "^10.0.0",
     "prettier": "^3.5.3",
+    "sqlite3": "^5.1.7",
     "timekeeper": "^2.3.1",
     "ts-node-maintained": "^10.9.5",
     "typescript": "~5.8"