@sicare/auth-guard

A customizable NestJS AuthGuard that authenticates requests by validating tokens via an external endpoint. Designed to work seamlessly with Fastify and Axios.

✨ Features

• 🔐 Token validation via a remote API.

• ✅ Easy integration with NestJS guards.

• 🌍 Supports global module registration.

• ⚠️ Throws proper NestJS HTTP exceptions based on the response.

📦 Installation

npm install @nestjs/axios @nestjs/microservices @sicare/auth-guard

Or using yarn:

yarn add @nestjs/axios @nestjs/microservices @sicare/auth-guard

🚧 Prerequisite: Use Fastify with NestJS

This package is built to work with FastifyAdapter in NestJS. Make sure your main app uses Fastify instead of the default Express:

1. Install Fastify

npm install fastify @nestjs/platform-fastify

Or using yarn:

yarn add fastify @nestjs/platform-fastify

2. Update main.ts

import { NestFactory } from '@nestjs/core';
import {
  FastifyAdapter,
  NestFastifyApplication,
} from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );
  await app.listen(3000);
}
bootstrap();

🚀 Usage

1. Import the AuthGuardModule

In your main app or any feature module:

import { Module } from '@nestjs/common';
import { AuthGuardModule } from '@sicare/auth-guard';

@Module({
  imports: [
    AuthGuardModule.register({
      endpoint: 'https://your-auth-service/validate',
      isGlobal: true, // Optional: make the guard global
    }),
  ],
})
export class AppModule {}

2. Apply the Guard

2.1. External Auth Guard

Use it in your controller or route handler:

import { Controller, Get, UseGuards } from '@nestjs/common';
import { ExternalAuthGuard } from '@sicare/auth-guard';

@Controller('secure')
@UseGuards(ExternalAuthGuard)
export class SecureController {
  @Get()
  getData() {
    return { message: 'You are authenticated!' };
  }
}

2.2. Jwt Auth Guard

Config Jwks endpoint in AuthGuardModule register method.

import { Module } from '@nestjs/common';
import { AuthGuardModule } from '@sicare/auth-guard';

@Module({
  imports: [
    AuthGuardModule.register({
      endpoint: 'https://example.auth0.com/.well-known/jwks.json',
      isGlobal: true, // Optional: make the guard global
    }),
  ],
})
export class AppModule {}

Use JwtAuthGuard in your controller or route handler:

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '@sicare/auth-guard';

@Controller('secure')
@UseGuards(JwtAuthGuard)
export class SecureController {
  @Get()
  getData() {
    return { message: 'You are authenticated!' };
  }
}

🧪 Testing

A basic test is included to verify the guard is defined:

describe('ExternalAuthGuard', () => {
  it('should be defined', () => {
    expect(new ExternalAuthGuard()).toBeDefined();
  });
});

⚙️ Options

| Option | Type | Description | |--------------|----------|-----------------------------------------------------------------------------| | endpoint | string | The URL of the external service to validate the token. |

🛡️ Behavior

• The guard reads the Authorization header.

• Sends the token to the configured endpoint via Axios.

• Injects the result as request.raw.user.

• Responds with:

  • 400 Bad Request if the token is malformed.
  • 401 Unauthorized if the token is missing or invalid.
  • 403 Forbidden if the token is valid but the user is not authorized.
  • 404 Not Found if the endpoint is not reachable.
  • 500 Internal Server Error for any other errors.