nest-phylax
A Nest based security module for authentication and authorization.
**Table of Contents**
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Module Configuration](#module-configuration)
- [Async Configuration](#async-configuration)
- [Security Decorators](#security-decorators)
- [JWT Utilities](#jwt-utilities)
- [API Reference](#api-reference)
- [Dependencies](#dependencies)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Author](#author)
## Features
- JWT Authentication with role-based claims
- Security Decorators for route protection
- Claims extraction from JWT tokens
- Role-based access control
- Public route marking
## Installation
```bash
npm install --save nest-phylax jsonwebtoken @nestjs/passport
```
## Setup
### User Model
Phylax's jwt-auth module requires a user model to be provided. This model must implement the `User` interface. Here are examples for different database implementations:
#### Basic Implementation
```typescript
import { User as NpUser } from 'nest-phylax';
export class User implements NpUser {
id: string;
email: string;
/**
* Get the username of the user
* @returns The username of the user
*
* This method is used to get the username of the user from the user object which is used to find the user in the database
*/
getUsername(): string {
return this.email;
}
}
```
#### Mongoose Implementation
```typescript
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document } from 'mongoose';
import { User as NpUser } from 'nest-phylax';
@Schema()
export class User extends Document implements NpUser {
@Prop({ required: true })
email: string;
@Prop({ required: true })
password: string;
@Prop({ default: 'user' })
role: string;
getUsername(): string {
return this.email;
}
}
export const UserSchema = SchemaFactory.createForClass(User);
UserSchema.methods.getUsername = function () {
return this.email;
};
```
#### TypeORM Implementation
```typescript
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
import { Type } from 'nest-phylax';
@Entity()
export class User implements NpUser {
@PrimaryGeneratedColumn('uuid')
id: string;
@Column({ unique: true })
email: string;
@Column()
password: string;
@Column({ default: 'user' })
role: string;
getUsername(): string {
return this.email;
}
}
```
### User Repository
The user repository is used to find the user in the database. It must implement the `UserRepository` interface. Here are examples for different database implementations:
#### Basic Implementation
```typescript
import { UserRepository } from 'nest-phylax';
export class UserRepository implements UserRepository {
async findOneById(id: string): Promise {
// Logic to find the user by id
}
async getUserRole(user: User): Promise {
// Logic to get the role of the user
}
async getRefreshTokens(user: User): Promise {
// Logic to get the refresh tokens of the user
}
}
```
#### Mongoose Implementation
```typescript
import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';
import { UserRepository } from 'nest-phylax';
import { User } from './user.schema';
@Injectable()
export class UserRepository implements UserRepository {
constructor(
@InjectModel(User.name) private readonly userModel: Model
) {}
async findOneById(id: string): Promise {
return this.userModel.findById(id).exec();
}
}
```
#### TypeORM Implementation
```typescript
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UserRepository as NpUserRepository } from 'nest-phylax';
import { User } from './user.entity';
@Injectable()
export class UserRepository implements NpUserRepository {
constructor(
@InjectRepository(User)
private readonly userRepository: Repository
) {}
/**
* Find a user by their ID
* @param id The ID of the user to find
* @returns The user with the given ID
*/
async findOneById(id: string): Promise {
return this.userRepository.findOne({ where: { id } });
}
/**
* Get the role of a user
* @param user The user to get the role of
* @returns The role of the user
*
* This is added to the user repository to offer flexibility on how user roles are supplied to the jwt auth * guard
*/
async getUserRole(user: User): Promise {
return user.role;
}
/**
* Get the refresh tokens of a user
* @param user The user to get the refresh tokens of
* @returns The refresh tokens of the user
*/
async getRefreshTokens(user: User): Promise {
return user.refreshTokens;
}
}
```
### Password Encoder
The password encoder is used to encode and decode passwords. It must implement the `PasswordEncoder` interface. Here are examples for different password encoder implementations:
#### Basic Implementation
```typescript
import { PasswordEncoder } from 'nest-phylax';
export class PasswordEncoder implements PasswordEncoder {
encode(password: string): Promise {
/**
* Logic to encode the password and return a hash
*/
}
compare(password: string, hash: string): Promise {
/**
* Logic to compare the password with the hash and return a boolean
*/
}
}
```
Import the `JwtAuthModule` into the root `AppModule` and use the `forRoot()` method to configure it:
```typescript
import { Module } from '@nestjs/common';
import { JwtAuthModule } from 'nest-phylax';
import { UserRepository } from './user.repository';
import { PasswordEncoder } from './password.encoder';
@Module({
imports: [
JwtAuthModule.forRoot({
accessTokenConfig: {
secretKey: '{YOUR_SECRET_KEY}',
expiresIn: '1h',
},
userRepositoryProvider: {
useClass: UserRepository,
},
passwordEncoderProvider: {
useClass: PasswordEncoder,
},
}),
],
})
export class AppModule {}
```
## Module Configuration
The `forRoot()` method accepts the following options:
```typescript
interface JwtAuthModuleOptions {
/**
* The configuration for the access token
*/
accessTokenConfig: TokenConfig;
/**
* The provider for the user repository
*/
userRepositoryProvider: Provider;
/**
* The provider for the password encoder
*/
passwordEncoderProvider: Provider;
}
```
#### Token Config
```typescript
interface TokenConfig {
/**
* The secret key for the JWT token
*/
secretKey: string;
/**
* The expiration time for the JWT token
*/
expiresIn: StringValue;
}
type StringValue =
| `${number}`
| `${number}${UnitAnyCase}`
| `${number} ${UnitAnyCase}`;
type UnitAnyCase = Unit | Uppercase | Lowercase;
```
String values can be in the following formats:
- `1h`
- `1d`
- `1w`
- `1m`
- `1y`
etc.
## Security Decorators
### Public Routes
```typescript
import { Public } from 'nest-phylax';
@Controller('api')
export class ApiController {
@Public()
@Get('public')
getPublicData() {
return { message: 'Anyone can see this' };
}
}
```
### Role-Based Access
Nest Phylax offers a `HasRole` decorator to restrict access to specific roles. The roles have to be added to the jwt claims.
```typescript
import { HasRole, Claims } from 'nest-phylax';
@Controller('api')
export class ApiController {
@HasRole('admin')
@Get('admin')
getAdminData(@Claims() claims) {
return {
message: 'Only admins can see this',
user: claims.sub,
};
}
}
```
## JWT Utilities
### Token Generation
Nest phylax provides a wrapper around the `jsonwebtoken` library to generate and verify JWTs.
```typescript
import { JwtUtil, ClaimsDto } from 'nest-phylax';
@Injectable()
export class AuthService {
constructor(private readonly jwtUtil: JwtUtil) {}
generateToken(user: User) {
return this.jwtUtil.generateToken({
user,
claims: new ClaimsDto({ id: user.id, role: user.role }),
});
}
}
```
### Token Verification
```typescript
@Injectable()
export class AuthService {
verifyToken(token: string) {
return this.jwtUtil.verifyJwt(token);
}
}
```
## API Reference
### Decorators
| Decorator | Description |
| --------------------------- | ------------------------------------ |
| `@Public()` | Marks a route as publicly accessible |
| `@Claims()` | Extracts claims from the JWT token |
| `@HasRole(roles: string[])` | Restricts access to specific roles |
### JWT Utilities
```typescript
class JwtUtil {
generateToken({
user,
claims,
secretKey,
signOptions,
}: {
user: User;
claims?: ClaimsDto;
secretKey?: string;
signOptions?: SignOptions;
}): string;
verifyJwt(token: string, secretKey?: string): ClaimsDto;
}
```
## Required Dependencies
- @nestjs/common
- @nestjs/core
- @nestjs/platform-express
- jsonwebtoken
## Development
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
```
## License
This project is released under the terms of the [ISC License](LICENSE).
## Author
Konan