https://github.com/nhedger/nestjs-encryption
Encryption module for NestJS 🔑
https://github.com/nhedger/nestjs-encryption
encryption nestjs nestjs-module
Last synced: about 1 year ago
JSON representation
Encryption module for NestJS 🔑
- Host: GitHub
- URL: https://github.com/nhedger/nestjs-encryption
- Owner: nhedger
- License: mit
- Created: 2023-08-24T08:19:16.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-08-25T03:50:38.000Z (almost 3 years ago)
- Last Synced: 2024-05-01T17:22:14.724Z (about 2 years ago)
- Topics: encryption, nestjs, nestjs-module
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@hedger/nestjs-encryption
- Size: 62.5 KB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# NestJS Encryption Module
**NestJS Encrytion** is a NestJS 9+ module that provides _plug-and-play_ encryption
and decryption functionality to your NestJS application.
- Uses `aes-256-cbc` by default, but supports [other ciphers](#supported-ciphers) as well.
- Provides a keygen (API and CLI) for generating random and secure encryption keys.
- Thoroughly tested.
## Installation
**NestJS Encryption** can be installed with your favorite package manager.
```bash
# NPM
npm install @hedger/nestjs-encryption
# Yarn
yarn add @hedger/nestjs-encryption
# PNPM
pnpm add @hedger/nestjs-encryption
```
## Setup
Setting up the module inside your NestJS application is a matter of registering
the module within your `AppModule`. The module is registered globally by default
and can be used anywhere in your application.
You may use either the `forRoot` or `forRootAsync` method to register the module in your `AppModule`.
### Using `forRoot`
The `forRoot` method is the simplest way to register the module.
```typescript
import { EncryptionModule, Cipher } from "@hedger/nestjs-encryption";
@Module({
imports: [
EncryptionModule.forRoot({
key: process.env.APP_KEY,
cipher: Cipher.AES_256_CBC,
}),
],
})
export class AppModule {}
```
### Using `forRootAsync`
The `forRootAsync` method allows you to register the module asynchronously,
optionally resolving the encryption key from a configuration service. Here's
an example that uses the `ConfigService` from `@nestjs/config` to resolve the
encryption key from the `APP_KEY` environment variable.
```typescript
import { ConfigModule, ConfigService } from "@nestjs/config";
import { EncryptionModule, Cipher } from "@hedger/nestjs-encryption";
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
}),
EncryptionModule.forRootAsync({
useFactory: (configService: ConfigService) => ({
key: configService.get("APP_KEY"),
}),
inject: [ConfigService],
}),
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}
```
## Usage
Inject the EncryptionService in your service or controller.
```typescript
import { EncryptionService } from "@hedger/nestjs-encryption";
@Injectable()
export class FooService {
constructor(private readonly crypto: EncryptionService) {}
someMethod() {
const encrypted = this.crypto.encrypt("some value");
const decrypted = this.crypto.decrypt(encrypted);
}
}
```
## Encryption key
This package expects the encryption key to be a base64-encoded string of N random
bytes, where N is the key length of the cipher you're using. For example, the
`aes-256-cbc` cipher has a key length of 32 bytes, so the encryption key must
be a base64-encoded string of 32 random bytes.
### Generating a key
This package provides CLI utility for generating random and secure encryption
keys.
```bash
# Generates a random key for the aes-256-cbc cipher (default)
npm exec nestjs-encryption-keygen
```
By default, the keygen generates keys for the `aes-256-cbc` cipher. You may
specify a different cipher by passing the `--cipher` option.
```bash
# Generates a random key for the aes-128-cbc cipher
npm exec nestjs-encryption-keygen --cipher aes-128-cbc
```
See the [Supported ciphers](#supported-ciphers) section for a list of supported
ciphers.
### Generating a key programmatically
Random and secure encryption keys may also be generated programmatically by
calling the `generateKey` method on the `EncryptionService` class.
```typescript
import { Cipher, EncryptionService } from "@hedger/nestjs-encryption";
// Pass the desired cipher as the first argument.
const key = EncryptionService.generateKey(Cipher.AES_256_CBC);
```
## Supported ciphers
The following ciphers are supported by this package.
- `aes-256-cbc` (default)
- `aes-256-gcm`
- `aes-128-cbc`
- `aes-128-gcm`
## License
Copyright © 2023, [Nicolas Hedger](https://github.com/nhedger). Released under the [MIT License](LICENSE.md).