npm package: @nest-auth/cipher
Description: nestjs module with multiple cipher/hashing implementations
Author: Davide Gheri
Latest version: 0.3.0


# Nest auth Cipher

### nestjs module with multiple cipher/hashing implementations

It provides the following ciphers:
* AES-CBC (via [node-forge](https://github.com/digitalbazaar/forge)) (To be replaced with native crypto implementation)

And the following hashing algorithms:

* [farmhash](https://github.com/lovell/farmhash)
* [argon2](https://github.com/ranisalt/node-argon2)
* SHA-256 (via native crypto module)

## Installation

```bash
$ npm install --save @nest-auth/cipher argon2 farmhash node-forge
$ npm install --save-dev @types/node-forge
```
Or
```bash
$ yarn add @nest-auth/cipher argon2 farmhash node-forge
$ yarn add -D @types/node-forge
```

#### Import it in a module

```typescript
import { Module } from '@nestjs/common';
import { CipherModule } from '@nest-auth/cipher';

@Module({
  imports: [
    //...
    CipherModule.forRoot({
      // Required options
      iv: '123456',
      secret: 'somesupersecretstring',
      // Optional argon2 options, these are the defaults
      argon2Options: {
        hashLength: 32,
        timeCost: 3,
        memoryCost: 4096,
        parallelism: 1,
        saltLength: 16,
      }
    }),
    
    // Or with Async configuration
    CipherModule.forRootAsync({
      import: [ConfigModule],
      inject: [ConfigService],
      useFactory: config => config.get('cipher'),
    }),
    //...
  ],
})
export class AppModule {}
```

### Usage

Import the CipherService

```typescript
import { Injectable } from '@nestjs/common';
import { CipherService } from '@nest-auth/cipher';

@Injectable()
export class SomeService {
  constructor(
    private readonly cipher: CipherService,
  ) {}
}
```

### Available ConfigService methods

#### sha256

```typescript
sha256(data: string, digest: import('crypto').HexBase64Latin1Encoding | boolean = 'hex'): strign | Buffer;
```

Return the sha256 hash of the given string, default as `hex`. If digest is `false`, returns a Buffer 

#### encrypt

```typescript
encrypt(data: any, secret?: string, iv?: string): string;
```

Encrypt the given data (transforming it to a string with `JSON.strignify`) using the `AES-CBC` algorithm. Returns as `hex` string. 
If no secret or iv are passed, the values passed on ConfigModule.forRoot(async) are used.

#### decrypt

```typescript
decrypt(hexString: string, secret?. string, iv?: string): any;
```

Decrypt a given `hex` string representing a `AES-CBC` encrypted data.
If no secret or iv are passed, the values passed on ConfigModule.forRoot(async) are used.

#### farmHash

```typescript
farmHash(data: string): number;
```

Hash the given data using the google `farmhash` hashing function, thanks to [lovell/farmhash](https://github.com/lovell/farmhash) 

It uses the 32bit platform independent method `fingerprint32`.

#### farmHashVerify

```typescript
farmHashVerify(value: string, hashed: string | number): boolean
```

Compare the hash of the given data with the given hash to check it they match

#### argonHash

```typescript
argonHash(value: string): Promise<string>;
```

Hash the given string using the argon2 algo

#### argonVerify

```typescript
argonVerify(value: string, hashed: string): Promise<boolean>;
```

Compare the hash of the given value with the given hash to check if they match

### Static methods

#### hashValue

```typescript
function hashValue(value: string, options?: Options): Promise<string>;
```

```typescript
import { hashValue } from '@nest-auth/cipher';
```

Hash the given string using the argon2 algo, accept a second parameter as argon2 options. Default are:
```typescript
const defaultConfig: argon2.Options = {
  type: argon2id,
  hashLength: 32,
  timeCost: 3,
  memoryCost: 4096,
  parallelism: 1,
  saltLength: 16,
};
```

#### verifyValue

```typescript
function verifyValue(value: string, hashed: string, options?: Options): Promise<boolean>;
```

Compare the hash of the given value with the given hash to check if they match
Accept a third parameter as argon2 options. Default values are the same as `hashValue`