feat: EXP-1045 Auth -> JwtAuthenticator access to request object (#787)

* EXP-1045 JwtBasedAuthenticator passing request

* EXP-1045 Update name for consistency

* EXP-1045 Fixing tests

* Readme update

* readme issue fix

Author: CarlosGamero

packages/app/auth/README.md

@@ -25,6 +25,12 @@ import {
   type BaseAuthInfo 
 } from '@lokalise/auth'
 
+// Define your JWT payload type
+type MyJwtPayload = {
+  userId: string
+  email: string
+}
+
 // Define your authentication info type
 type MyAuthInfo = BaseAuthInfo<'my-provider'> & {
   userId: string
@@ -33,19 +39,21 @@ type MyAuthInfo = BaseAuthInfo<'my-provider'> & {
 
 // Create a custom authenticator
 class MyAuthenticator extends JwtBasedAuthenticator<MyAuthInfo> {
-  protected internalAuthenticate(reqContext, jwtPayload, rawToken) {
+  protected internalAuthenticate(reqContext, jwt, request) {
+    const payload = jwt.payload as MyJwtPayload
+
     // Validate the JWT payload and extract user information
-    if (!jwtPayload.sub || !jwtPayload.email) {
+    if (!payload.userId || !payload.email) {
       return { success: false, failure: 'INVALID_CREDENTIALS' }
     }
 
     return {
       success: true,
       authInfo: {
         authType: 'my-provider',
-        rawToken,
-        userId: jwtPayload.sub,
-        email: jwtPayload.email
+        token: jwt.token,
+        userId: payload.userId,
+        email: payload.email
       }
     }
   }
@@ -118,7 +126,7 @@ Base interface for authentication information:
 ```typescript
 type BaseAuthInfo<AuthType extends string> = {
   authType: AuthType
-  rawToken: string
+  token: string
 }
 ```
 
@@ -150,13 +158,11 @@ Abstract base class for JWT-based authentication:
 
 ```typescript
 abstract class JwtBasedAuthenticator<AuthInfo extends BaseAuthInfo<string>> {
-  constructor(tokenDecoder: TokenDecoder, tokenHeader?: string)
-  
   // Must be implemented by subclasses
   protected abstract internalAuthenticate(
     reqContext: RequestContext,
-    jwtPayload: object,
-    rawToken: string
+    jwt: ValidatedJwt,
+    request: FastifyRequest
   ): AuthResult<AuthInfo> | Promise<AuthResult<AuthInfo>>
 }
 ```
@@ -165,11 +171,6 @@ abstract class JwtBasedAuthenticator<AuthInfo extends BaseAuthInfo<string>> {
 
 Chains multiple authenticators, trying each until one succeeds:
 
-```typescript
-class AuthenticatorChain<AuthInfo extends BaseAuthInfo<string>> {
-  constructor(authentators: Authenticator<AuthInfo>[])
-}
-```
 
 ### Token Decoders
 

packages/app/auth/src/authenticators/Authenticator.ts

@@ -6,7 +6,7 @@ import type { FastifyRequest } from 'fastify'
 export type BaseAuthInfo<AuthType extends string> = {
   authType: AuthType
   /** The raw authentication token. May be forwarded to downstream services. */
-  rawToken: string
+  token: string
 }
 
 /**

packages/app/auth/src/authenticators/AuthenticatorChain.spec.ts

@@ -34,7 +34,7 @@ describe('AuthenticatorChain', () => {
       // Given
       const authInfo: AuthInfo = {
         authType: 'provider-1',
-        rawToken: 'raw-token',
+        token: 'raw-token',
       }
 
       const firstAuth = new MockAuthenticator({ success: true, authInfo })
@@ -53,7 +53,7 @@ describe('AuthenticatorChain', () => {
       // Given
       const authInfo: AuthInfo = {
         authType: 'provider-2',
-        rawToken: 'raw-token',
+        token: 'raw-token',
       }
 
       const firstAuth = new MockAuthenticator({ success: false, failure: 'INVALID_CREDENTIALS' })

packages/app/auth/src/authenticators/JwtBasedAuthenticator.spec.ts

@@ -1,4 +1,5 @@
 import type { RequestContext } from '@lokalise/fastify-extras'
+import type { FastifyRequest } from 'fastify'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { createMockFastifyRequest } from '../../tests/createMockFastifyRequest.ts'
 import { createToken } from '../../tests/createToken.ts'
@@ -9,7 +10,7 @@ import {
   type TokenValidationError,
 } from '../token-decoders/index.ts'
 import type { AuthFailureReason, AuthResult, BaseAuthInfo } from './Authenticator.ts'
-import { JwtBasedAuthenticator } from './JwtBasedAuthenticator.ts'
+import { JwtBasedAuthenticator, type ValidatedJwt } from './JwtBasedAuthenticator.ts'
 
 type AuthInfo = BaseAuthInfo<'test-provider'>
 
@@ -23,16 +24,18 @@ class TestJwtAuthenticator extends JwtBasedAuthenticator<AuthInfo> {
 
   protected override internalAuthenticate(
     _reqContext: RequestContext,
-    _jwtPayload: object,
-    rawToken: string,
+    jwt: ValidatedJwt,
+    request: FastifyRequest,
   ): AuthResult<AuthInfo> | Promise<AuthResult<AuthInfo>> {
     if (!this.error) {
       return {
         success: true,
-        authInfo: { authType: 'test-provider', rawToken },
+        authInfo: { authType: 'test-provider', token: jwt.token },
       }
     }
 
+    expect(request).toBeDefined()
+
     return { success: false, failure: this.error }
   }
 }
@@ -60,7 +63,7 @@ describe('JwtBasedAuthenticator', () => {
         // Then
         expect(result).toEqual({
           success: true,
-          authInfo: { authType: 'test-provider', rawToken: token },
+          authInfo: { authType: 'test-provider', token: token },
         })
       })
 
@@ -80,7 +83,7 @@ describe('JwtBasedAuthenticator', () => {
         // Then
         expect(result).toEqual({
           success: true,
-          authInfo: { authType: 'test-provider', rawToken: token },
+          authInfo: { authType: 'test-provider', token: token },
         })
       })
     })

packages/app/auth/src/authenticators/JwtBasedAuthenticator.ts

@@ -3,6 +3,11 @@ import type { FastifyRequest } from 'fastify'
 import type { TokenDecoder } from '../token-decoders/index.ts'
 import type { Authenticator, AuthResult, BaseAuthInfo } from './Authenticator.ts'
 
+export type ValidatedJwt = {
+  payload: object
+  token: string
+}
+
 /**
  * Abstract base class for JWT-based authenticators.
  */
@@ -27,7 +32,9 @@ export abstract class JwtBasedAuthenticator<AuthInfo extends BaseAuthInfo<string
     }
 
     return this.tokenDecoder.decode(request.reqContext, token).then(({ result, error }) => {
-      if (result) return this.internalAuthenticate(request.reqContext, result, token)
+      if (result) {
+        return this.internalAuthenticate(request.reqContext, { payload: result, token }, request)
+      }
 
       logger.warn({ origin: this.constructor.name, error }, 'Token validation failed')
       switch (error) {
@@ -50,14 +57,14 @@ export abstract class JwtBasedAuthenticator<AuthInfo extends BaseAuthInfo<string
    * Must be implemented by subclasses to validate the payload and construct the authentication result.
    *
    * @param reqContext - The request context containing request-scoped data and logger.
-   * @param jwtPayload - The decoded JWT payload.
-   * @param rawToken - The original JWT token string.
+   * @param jwt - The validated JWT containing both the decoded payload and the original token string.
+   * @param request - The Fastify request object for accessing additional request data.
    * @returns The authentication result, either success with auth info or failure.
    */
   protected abstract internalAuthenticate(
     reqContext: RequestContext,
-    jwtPayload: object,
-    rawToken: string,
+    jwt: ValidatedJwt,
+    request: FastifyRequest,
   ): AuthResult<AuthInfo> | Promise<AuthResult<AuthInfo>>
 
   private extractBearerToken(request: FastifyRequest): string | null {

packages/app/auth/src/fastify/createAuthenticationPreHandler.spec.ts

@@ -34,7 +34,7 @@ describe('createAuthenticationPreHandler', () => {
       // Given
       const authInfo: AuthInfo = {
         authType: 'test-provider',
-        rawToken: 'test-token',
+        token: 'test-token',
       }
       const authenticator = new MockAuthenticator({ success: true, authInfo })
       const preHandler = createAuthenticationPreHandler(authenticator)