Merge pull request #8 from MaximeMRF/feat/refresh-token

feat(refresh tokens)

Author: MaximeMRF

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

bin/test.ts

@@ -1,11 +1,12 @@
 import { assert } from '@japa/assert'
+import { fileSystem } from '@japa/file-system'
 import { configure, processCLIArgs, run } from '@japa/runner'
 
 processCLIArgs(process.argv.splice(2))
 
 configure({
   files: ['tests/**/*.spec.ts'],
-  plugins: [assert()],
+  plugins: [assert(), fileSystem()],
 })
 
 run()

package.json

@@ -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"

src/define_config.ts

@@ -4,9 +4,11 @@ import { JwtGuardUser, JwtUserProviderContract } from './types.js'
 import { JwtGuard } from './jwt.js'
 import { Secret } from '@adonisjs/core/helpers'
 import type { StringValue } from 'ms'
+import { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens'
 
 export function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>>(config: {
   provider: UserProvider
+  refreshTokenUserProvider?: AccessTokensUserProviderContract<unknown>
   tokenName?: string
   tokenExpiresIn?: number | StringValue
   useCookies?: boolean
@@ -18,6 +20,7 @@ export function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>>(
       const appKey = (app.config.get('app.appKey') as Secret<string>).release()
       const options = {
         secret: config.secret ?? appKey,
+        refreshTokenUserProvider: config.refreshTokenUserProvider,
         tokenName: config.tokenName,
         expiresIn: config.tokenExpiresIn,
         useCookies: config.useCookies,

src/jwt.ts

@@ -3,12 +3,17 @@ import { AuthClientResponse, GuardContract } from '@adonisjs/auth/types'
 import type { HttpContext } from '@adonisjs/core/http'
 import jwt from 'jsonwebtoken'
 import { JwtUserProviderContract, JwtGuardOptions } from './types.js'
+import { Secret } from '@adonisjs/core/helpers'
+import { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens'
 
 export class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>>
   implements GuardContract<UserProvider[typeof symbols.PROVIDER_REAL_USER]>
 {
   #ctx: HttpContext
   #userProvider: UserProvider
+  #refreshTokenUserProvider?: AccessTokensUserProviderContract<
+    UserProvider[typeof symbols.PROVIDER_REAL_USER]
+  >
   #options: JwtGuardOptions<UserProvider[typeof symbols.PROVIDER_REAL_USER]>
   #tokenName: string
 
@@ -20,6 +25,7 @@ export class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>>
     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'
   }
@@ -171,6 +177,92 @@ export class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>>
     return this.getUserOrFail()
   }
 
+  async authenticateWithRefreshToken(): Promise<
+    UserProvider[typeof symbols.PROVIDER_REAL_USER] & { currentToken: string }
+  > {
+    /**
+     * 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() as UserProvider[typeof symbols.PROVIDER_REAL_USER] & {
+      currentToken: string
+    }
+
+    /**
+     * 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
    */

src/types.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
@@ -46,6 +47,7 @@ export type BaseJwtContent = {
 
 export type JwtGuardOptions<RealUser extends any = unknown> = {
   secret: string
+  refreshTokenUserProvider?: AccessTokensUserProviderContract<RealUser>
   tokenName?: string
   expiresIn?: number | StringValue
   useCookies?: boolean