nestjs-cryptography 3.0.0 → 3.1.1

package/wiki/docs/Internals/symmetric-secure-data-encrypt.mdx

@@ -1,161 +0,0 @@
----
-title: Symmetric Secure Data Encrypt
-sidebar_label: Symmetric Secure Data Encrypt
-sidebar_position: 3
-description: Internals of symmetricSecureDataEncrypt
----
-
-In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`symmetricSecureDataEncrypt`][1]
-
-This method securely encrypts input data by first generating a random 32-byte Data Encryption Key (DEK)
-using a cryptographically secure method. It then encrypts the data using AES-256-GCM with the DEK,
-producing an output that includes the initialization vector (IV), salt, authentication tag, and ciphertext.
-After encrypting the data, the method also encrypts the DEK itself using a master key, and finally,
-it concatenates the encrypted DEK and the encrypted data, returning the complete encrypted result for secure storage or transmission.
-
-## **Diagram**
-
-<div style={{ textAlign: 'center' }}>
-  ```mermaid
-  graph TD
-  A[Input: Data] --> ID
-
-  DEK{Generate DEK} --> SG1
-
-  subgraph SG1[Generate DEK]
-  SG1A1[Generate 64 bytes of random data] --> SG1A1A2[Create Secret Key from random data]
-  SG1A1A2 --> SG1A1A3[Generate another 64 bytes of random data]
-  SG1A1A3 --> SG1A1A4[Use HKDF with sha3-256 to derive IV]
-  end
-
-
-  subgraph ED[Encrypt Data]
-  SG1A1A4 --> DEK1[DEK]
-
-  ID(DATA)
-
-  IV1[IV] --> IV1A1{Generate IV}
-  SALT1[SALT] --> SALT1A1{Generate SALT}
-
-  IV1A1 --> SGIV1
-  SALT1A1 --> SGSALT1
-
-  subgraph SGIV1["Generate IV (12 bytes)"]
-  SGIV1A1[Generate 64 bytes of random data] --> SGIV1A1A2[Create Secret Key from random data]
-  SGIV1A1A2 --> SGIV1A1A3[Generate another 64 bytes of random data]
-  SGIV1A1A3 --> SGIV1A1A4[Use HKDF with sha3-256 to derive IV]
-  end
-
-  subgraph SGSALT1["Generate Salt (64 bytes)"]
-  SGSSALT1A1[Generate 64 bytes of random data] --> SGSSALT1A1A2[Create Secret Key from random data]
-  SGSSALT1A1A2 --> SGSSALT1A1A3[Generate another 64 bytes of random data]
-  SGSSALT1A1A3 --> SGSSALT1A1A4[Use HKDF with sha3-256 to derive SALT]
-  end
-
-  DEK1 --> DERIVEDEK[Securely derive DEK using Argon2 + Salt]
-  DERIVEDEK --> EK1(Encryption Key)
-  SGSSALT1A1A4 --> DERIVEDEK
-
-  SGIV1A1A4 --> FIV1(IV)
-  FIV1 ==> FED{Encrypt Data using AES-256-GCM with Encryption Key + IV}
-  EK1 ==> FED
-  ID ==> FED
-
-  FED -.- FFED["Encrypted Data [IV + Salt + AuthTag + CipherText]"]
-  end
-
-
-  subgraph EDEK[Encrypt DEK]
-  SG1A1A4 --> DEK2(DEK)
-
-  IV2[IV] --> IV2A1{Generate IV}
-  SALT2[SALT] --> SALT2A1{Generate SALT}
-
-  IV2A1 --> SGIV2
-  SALT2A1 --> SGSALT2
-
-  subgraph SGIV2["Generate IV (12 bytes)"]
-  SGIV2A1[Generate 64 bytes of random data] --> SGIV2A1A2[Create Secret Key from random data]
-  SGIV2A1A2 --> SGIV2A1A3[Generate another 64 bytes of random data]
-  SGIV2A1A3 --> SGIV2A1A4[Use HKDF with sha3-256 to derive IV]
-  end
-
-  subgraph SGSALT2["Generate Salt (64 bytes)"]
-  SGSSALT2A1[Generate 64 bytes of random data] --> SGSSALT2A1A2[Create Secret Key from random data]
-  SGSSALT2A1A2 --> SGSSALT2A1A3[Generate another 64 bytes of random data]
-  SGSSALT2A1A3 --> SGSSALT2A1A4[Use HKDF with sha3-256 to derive SALT]
-  end
-
-  MK[MASTER KEY] --> DERIVEMK[Securely derive Master Key using Argon2 + Salt]
-  DERIVEMK --> EK2(Encryption Key)
-  SGSSALT2A1A4 --> DERIVEMK
-
-  SGIV2A1A4 --> FIV2(IV)
-
-  EK2 ==> FEDEK{Encrypt DEK using AES-256-GCM with Encryption Key + IV}
-  DEK2 ==> FEDEK
-  FIV2 ==> FEDEK
-
-  FEDEK -.- FFEDEK["Encrypted DEK [IV + Salt + AuthTag + CipherText]"]
-  end
-
-  FFEDEK -.-> FFDD(["Concatenate Encrypted DEK + Encrypted Data"])
-  FFED -.-> FFDD
-
-
-  %% -----------------
-
-  A:::inputDataStyle
-
-  MK:::masterKeyStyle
-
-  DEK:::dekStyle
-
-  SALT1A1:::saltStyle
-  SALT2A1:::saltStyle
-
-  IV1A1:::ivStyle
-  IV2A1:::ivStyle
-
-  FEDEK:::encryptionStyle
-  FED:::encryptionStyle
-
-  FFEDEK:::resultStyle
-  FFED:::resultStyle
-
-  FFDD:::finalResultStyle
-
-  %% Style definitions
-  classDef inputDataStyle fill:#00ff00,stroke:#333,stroke-width:2px;
-  classDef masterKeyStyle fill:#ff0000,stroke:#333,stroke-width:2px;
-  classDef dekStyle fill:#BCD3A3,stroke:#333,stroke-width:2px;
-  classDef ivStyle fill:#ffcc00,stroke:#333,stroke-width:2px;
-  classDef saltStyle fill:#ff6666,stroke:#333,stroke-width:2px;
-  classDef deriveKeyStyle fill:#66ccff,stroke:#333,stroke-width:2px;
-  classDef secureKeyStyle fill:#66ff66,stroke:#333,stroke-width:2px;
-  classDef encryptionStyle fill:#cc99ff,stroke:#333,stroke-width:2px;
-  classDef resultStyle fill:#ff9966,stroke:#333,stroke-width:2px;
-  classDef finalResultStyle fill:#66ffcc,stroke:#333,stroke-width:2px;
-  ```
-</div>
-
-
-## **Explanation of the Diagram**
-1) Generate DEK:
-    - The `createSafeRandomData` method generates a 32-byte **DEK** (Data Encryption Key) using `HKDF(sha3-256 + random_key + random_salt)`.
-2) Encrypt the Input Data:
-    - **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
-    - **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
-    - **Derive Secure Encryption Key**: A secure encryption key is derived using **Argon2** with the DEK and salt.
-    - **Encrypt Data**: The input data is encrypted using **AES-256-GCM** with the derived secure encryption key, producing the encrypted result: _IV + Salt + AuthTag + CipherText_.
-3) Encrypt the DEK:
-    - The DEK itself is encrypted using the master key:
-      - **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
-      - **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
-      - **Derive Master Key**: A secure encryption key is derived using **Argon2** with the [**MasterKey**][2] and salt.
-      - **Encrypt DEK**: The DEK is encrypted using AES-256-GCM, resulting in the encrypted DEK: _IV + Salt + AuthTag + CipherText_.
-4) Concatenate and Return:
-    - The encrypted DEK and the encrypted input data are concatenated to form the final output, which is then returned.
-
-[1]: ../guides/symmetric-encryption#symmetricsecuredataencrypt
-[2]: ../api-reference/settings#masterkey-1

package/wiki/docs/api-reference/_category_.json

@@ -1,7 +0,0 @@
-{
-  "label": "API Reference",
-  "position": 2,
-  "link": {
-    "type": "generated-index",
-  }
-}

package/wiki/docs/api-reference/settings.mdx

@@ -1,199 +0,0 @@
----
-title: Configuration Options
-sidebar_label: Configuration Options
-sidebar_position: 1
-description: Module configuration options
-
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import GenerateHexButton from '@site/src/components/GenerateHexButton';
-
-<details>
-  <summary>👨‍🔧 Let me help you a bit....</summary>
-
-  <div>
-
-    :::info
-
-    If at any point you need to securely generate a secret key for the following configuration, you can do so as follows.
-
-    <Tabs
-      defaultValue="linux"
-      values={[
-        { label: 'Linux / macOS', value: 'linux', },
-        { label: 'Windows / Others', value: 'windows', }
-      ]
-      }>
-      <TabItem value="linux">
-        Type this on the terminal:
-        ```bash
-        openssl rand -hex 32
-        ```
-      </TabItem>
-      <TabItem value="windows">
-        <GenerateHexButton />
-      </TabItem>
-    </Tabs>
-
-
-    :::
-
-  </div>
-</details>
-
-<details>
-  <summary>Example Usage</summary>
-
-  <div>
-
-```typescript title="app.module.ts"
-import { Module } from '@nestjs/common';
-import * as argon2 from 'argon2';
-import {
-  CryptographyModule,
-  CryptographyOptionsInterface,
-} from 'nestjs-cryptography';
-
-@Module({
-imports: [
-  CryptographyModule.registerAsync({
-    imports: [ConfigModule],
-    isGlobal: true,
-    useFactory: (configService: ConfigService) =>
-      ({
-        isGlobal: true,
-        kdf: {
-          timeCost: 32,
-          memoryCost: 131072,
-          argon2Type: argon2.argon2i,
-          outputKeyLength: 32,
-        },
-        hashing: {
-          password: {
-            timeCost: 10,
-            memoryCost: 65536,
-            argon2Type: argon2.argon2id,
-            outputKeyLength: 64,
-          },
-          hmac: {
-            // ‼️ change me please ‼️
-            masterKey: '6c0504d3836ab96a25daeb61c44f6d6345d99a746f6a776290c48d9a5ba8b124',
-          },
-        },
-        encryption: {
-          symmetric: {
-            // ‼️ change me please ‼️
-            masterKey: '1538755db39d3d98115af5be688b1486673910f7d2630fc48dd27c1a1ace2631',
-          },
-        },
-      }) as CryptographyOptionsInterface,
-      inject: [ConfigService],
-  }),
-],
-export class AppModule {}
-```
-
-  </div>
-</details>
-
-## `kdf`
-
-Settings for the Key Derivation Function.
-
-  - ### <u>outputKeyLength</u>
-      > `type: number` | **required**
-
-    The default length (in bytes) of the derived key.
-
-  - ### <u>argon2Type</u>
-      > `type: Argon2Type` | **required**
-
-    The variant of the Argon2 algorithm to use (Argon2d, Argon2i, or Argon2id)
-
-  - ### <u>memoryCost</u>
-      > `type: number` | **required**
-
-    Memory usage (in kilobytes) for the algorithm.
-
-  - ### <u>timeCost</u>
-      > `type: number` | **required**
-
-    Number of iterations to perform.
-
----
-
-## `hashing`
-
-Settings for hashing operations.
-
-### `password`
-
-Configuration for password hashing.
-
-  - ### <u>outputKeyLength</u>
-      > `type: number` | **required**
-
-    The default length (in bytes) of the derived key.
-
-  - ### <u>argon2Type</u>
-      > `type: Argon2Type` | **required**
-
-    The variant of the Argon2 algorithm to use (Argon2d, Argon2i, or Argon2id)
-
-  - ### <u>memoryCost</u>
-      > `type: number` | **required**
-
-    Memory usage (in kilobytes) for the algorithm.
-
-  - ### <u>timeCost</u>
-      > `type: number` | **required**
-
-    Number of iterations to perform.
-
-### `hmac`
-
-Configuration for HMAC (Hash-Based Message Authentication Code).
-
-  - ### <u>masterKey</u>
-      > `type: string` | **required**
-
-    The secret key used for generating HMACs.
-
----
-
-## `encryption`
-
-Settings for encryption operations.
-
-### `symmetric`
-
-Configuration for symmetric encryption.
-
-  - ### <u>masterKey</u>
-      > `type: string` | **required**
-
-    The secret key used for encryption and decryption.
-
-:::danger
-
-Note: Always ensure that secret keys are generated securely and stored safely.
-Do not hard-code them into your source files or expose them in version control systems.
-
-:::
-
-## Additional Information
-
-- **Argon2Type**: An enumeration defining the type of Argon2 algorithm to use.
-The options typically include `Argon2d`, `Argon2i`, and `Argon2id`.
-[Choose the one that best fits your security requirements][3].
-
-- **Security Considerations**: Adjust `memoryCost` and `timeCost`
-according to the desired balance between performance and security.
-Higher values increase security but require more resources.
-You could se more information on [owasp][1] or the [official specs][2]
-
-[1]: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id
-[2]: https://www.password-hashing.net/argon2-specs.pdf#page=15
-[3]: https://en.wikipedia.org/wiki/Argon2

package/wiki/docs/guides/_category_.json

@@ -1,7 +0,0 @@
-{
-  "label": "Guides",
-  "position": 3,
-  "link": {
-    "type": "generated-index"
-  }
-}

package/wiki/docs/guides/generics.mdx

@@ -1,170 +0,0 @@
----
-title: Generics
-sidebar_label: Generics
-sidebar_position: 1
-description: Methods to perform typical operations UUID, randomPassword, ...
----
-
-import RequiredLabel from '@site/src/components/RequiredLabel';
-import Tips from '@site/src/common/tips.mdx'
-
-This section contains some generic methods to perform typical operations
-
-## Generate an UUIDv4
-
-Method to generate a UUID version 4.
-
-### `genUUID`
-
-```tsx
-public genUUID (
-  secure = false
-): string;
-```
-
-**Parameters:**
-
-| Name   | Type    | Default | Description                                                                    |
-|--------|---------|---------|--------------------------------------------------------------------------------|
-| secure | boolean | false   | Decide to use a more secure generation, preventing the use of an entropy cache |
-
-
-**Outputs:**
-
-As output, it will return a string of this format `0E928AD4-4D11-4C7C-A83A-8DD7361FFC01`
-
-
-**Usage:**
-```typescript
-async someAwesomeMethod(): Promise<string> {
-  const newUUID = this.cryptographyService.genUUID(true);
-  ...
-  return newUUID;
-}
-```
-
-
-[//]: #--------------------#
-
-## Generate secure random data
-
-Method to generate a secure random data of the desired length.
-
-### `createSafeRandomData`
-
-```tsx
-public createSafeRandomData (
-  length: number
-): Buffer;
-```
-
-**Parameters:**
-
-| Name                    | Type   | Default | Description                            |
-|-------------------------|--------|---------|----------------------------------------|
-| length <RequiredLabel/> | number |         | The random data output length in bytes |
-
-
-**Outputs:**
-
-As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
-
-
-[//]: #--------------------#
-
-
-## Generate random password
-
-Method to generate a random password with this set of characters: `A-Z a-z 0-9 + = /`.
-
-### `genRandomPassword`
-
-```tsx
-public genRandomPassword (
-  length: number
-): string;
-```
-
-**Parameters:**
-
-| Name                      | Type          | Default | Description                                      |
-|---------------------------|---------------|---------|--------------------------------------------------|
-| length <RequiredLabel/>   | number        |         | The password output length                       |
-
-
-**Outputs:**
-
-As output, it will return a string of this format: `jh2EducrV7yH8tGAc8Jkdcso`
-
-**Usage:**
-```typescript
-async createUserPassword(): Promise<string> {
-  const newPassword = this.cryptographyService.genRandomPassword(24);
-  ...
-  return newPassword;
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Generate symmetric key
-
-Method to generate a cryptographically secure SymmetricKey in [KeyObject][1] format
-to use in subsequent encryption/decryption operations.
-
-### `generateSymmetricKey`
-
-```tsx
-public generateSymmetricKey (
-  length: number = 256
-): KeyObject;
-```
-
-**Parameters:**
-
-| Name   | Type   | Default | Description                     |
-|--------|--------|---------|---------------------------------|
-| length | number | 256     | The symmetric key output length |
-
-
-**Outputs:**
-
-As output, it will return an object of type [KeyObject][1].
-
-:::info
-
- If you want to export this KeyObject to different types, you can access the [`.export` method.][2]
-
-:::
-
-**Usage:**
-```typescript
-async createSymmetricKey(): Promise<void> {
-  const new32KeySize = this.cryptographyService.generateSymmetricKey(32);
-  console.log(new32KeySize.export().toString('hex'));  // f32.....4ee
-
-  const aes128KeySize = this.cryptographyService.generateSymmetricKey(128);
-  console.log(aes128KeySize.export().toString('hex'));  // e89.....41e
-
-  const aes192KeySize = this.cryptographyService.generateSymmetricKey(192);
-  console.log(aes192KeySize.export().toString('base64'));  // 8OI.....ZQ=
-
-  const aes256KeySize = this.cryptographyService.generateSymmetricKey(256);
-  console.log(aes256KeySize.export());  // <Buffer cc 2b.....cd a1 08>
-}
-```
-
-
-[//]: #--------------------#
-
-
-<Tips />
-
-
-[//]: #--------------------#
-
-
-[1]: https://nodejs.org/api/crypto.html#class-keyobject
-[2]: https://nodejs.org/api/crypto.html#keyobjectexportoptions