nestjs-cryptography 3.0.0 → 3.1.0

package/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.x     | :white_check_mark: |
+| 2.x     | :x:                |
+
+## Reporting a Vulnerability
+
+Please report security issues to security@thewolfx41.dev

package/dist/constants.d.ts

@@ -1 +1,16 @@
+import { Argon2Type } from './interfaces';
 export declare const CRYPTOGRAPHY_OPTIONS = "CRYPTOGRAPHY_OPTIONS";
+export declare const DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS: {
+    outputKeyLength: number;
+    argon2Type: Argon2Type;
+    memoryCost: number;
+    timeCost: number;
+};
+export declare const DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS: {
+    password: {
+        outputKeyLength: number;
+        argon2Type: Argon2Type;
+        memoryCost: number;
+        timeCost: number;
+    };
+};

package/dist/constants.js

@@ -1,4 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CRYPTOGRAPHY_OPTIONS = void 0;
+exports.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS = exports.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS = exports.CRYPTOGRAPHY_OPTIONS = void 0;
+const interfaces_1 = require("./interfaces");
 exports.CRYPTOGRAPHY_OPTIONS = 'CRYPTOGRAPHY_OPTIONS';
+exports.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS = {
+    outputKeyLength: 32,
+    argon2Type: interfaces_1.Argon2Type.argon2i,
+    memoryCost: 65536,
+    timeCost: 3,
+};
+exports.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS = {
+    password: {
+        outputKeyLength: 64,
+        argon2Type: interfaces_1.Argon2Type.argon2id,
+        memoryCost: 131072,
+        timeCost: 4,
+    },
+};

package/dist/cryptography.service.d.ts

@@ -1,9 +1,10 @@
 import * as crypto from 'node:crypto';
 import { CryptographyOptionsInterface, GenericOptionsInterface } from './interfaces';
 export declare class CryptographyService {
-    private options;
-    constructor(options: CryptographyOptionsInterface);
+    private moduleOptions;
+    constructor(moduleOptions: CryptographyOptionsInterface);
     private convertInputData;
+    private checkModuleOptions;
     private extractIV;
     private extractAuthTagFromCypheredData;
     private extractCipheredData;

package/dist/cryptography.service.js

@@ -40,9 +40,10 @@ const crypto = __importStar(require("node:crypto"));
 const argon2 = __importStar(require("argon2"));
 const common_1 = require("@nestjs/common");
 const cryptography_module_definition_1 = require("./cryptography.module-definition");
+const constants_1 = require("./constants");
 let CryptographyService = class CryptographyService {
-    constructor(options) {
-        this.options = options;
+    constructor(moduleOptions) {
+        this.moduleOptions = moduleOptions;
     }
     convertInputData(data, inputEncoding) {
         if (Buffer.isBuffer(data)) {
@@ -55,6 +56,15 @@ let CryptographyService = class CryptographyService {
             throw new Error('Unsupported input type');
         }
     }
+    checkModuleOptions(parent, options) {
+        for (const option in options) {
+            if (typeof option === 'object')
+                this.checkModuleOptions(parent, option);
+            if (options[option] === undefined || options[option] === null) {
+                throw new Error(`[CryptographyModule] [${parent}] Option ${option} is not defined on the configuration`);
+            }
+        }
+    }
     extractIV(data) {
         return data.subarray(0, 12);
     }
@@ -94,21 +104,69 @@ let CryptographyService = class CryptographyService {
         return crypto.generateKeySync('hmac', { length });
     }
     async deriveMasterKey(masterKey, salt, length) {
+        if (!this.moduleOptions?.useDefaultValues) {
+            this.checkModuleOptions('KDF', {
+                ...(!length && {
+                    outputKeyLength: this.moduleOptions?.kdf?.outputKeyLength,
+                }),
+                argon2Type: this.moduleOptions?.kdf?.argon2Type,
+                memoryCost: this.moduleOptions?.kdf?.memoryCost,
+                timeCost: this.moduleOptions?.kdf?.timeCost,
+            });
+        }
+        else {
+            this.moduleOptions.kdf = {
+                ...this.moduleOptions?.kdf,
+            };
+            this.moduleOptions.kdf.outputKeyLength =
+                constants_1.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS.outputKeyLength;
+            this.moduleOptions.kdf.argon2Type =
+                constants_1.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS.argon2Type;
+            this.moduleOptions.kdf.memoryCost =
+                constants_1.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS.memoryCost;
+            this.moduleOptions.kdf.timeCost =
+                constants_1.DEFAULT_KDF_CRYPTOGRAPHY_OPTIONS.timeCost;
+        }
+        console.log(this.moduleOptions.kdf);
         return await argon2.hash(masterKey, {
-            hashLength: length ?? this.options.kdf.outputKeyLength,
+            hashLength: length ?? this.moduleOptions.kdf.outputKeyLength,
             salt: salt,
-            type: this.options.kdf.argon2Type,
-            memoryCost: this.options.kdf.memoryCost,
-            timeCost: this.options.kdf.timeCost,
+            type: this.moduleOptions.kdf.argon2Type,
+            memoryCost: this.moduleOptions.kdf.memoryCost,
+            timeCost: this.moduleOptions.kdf.timeCost,
             raw: true,
         });
     }
     async createArgon2HashFromPassword(data) {
+        if (!this.moduleOptions?.useDefaultValues) {
+            this.checkModuleOptions('HASHING_PASSWORD', {
+                outputKeyLength: this.moduleOptions?.hashing?.password?.outputKeyLength,
+                argon2Type: this.moduleOptions?.hashing?.password?.argon2Type,
+                memoryCost: this.moduleOptions?.hashing?.password?.memoryCost,
+                timeCost: this.moduleOptions?.hashing?.password?.timeCost,
+            });
+        }
+        else {
+            this.moduleOptions.hashing = {
+                ...this.moduleOptions?.hashing,
+                password: {
+                    ...this.moduleOptions.hashing?.password,
+                },
+            };
+            this.moduleOptions.hashing.password.outputKeyLength =
+                constants_1.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS.password.outputKeyLength;
+            this.moduleOptions.hashing.password.argon2Type =
+                constants_1.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS.password.argon2Type;
+            this.moduleOptions.hashing.password.memoryCost =
+                constants_1.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS.password.memoryCost;
+            this.moduleOptions.hashing.password.timeCost =
+                constants_1.DEFAULT_HASHING_CRYPTOGRAPHY_OPTIONS.password.timeCost;
+        }
         const tmpData = await argon2.hash(data, {
-            hashLength: this.options.hashing.password.outputKeyLength,
-            type: this.options.hashing.password.argon2Type,
-            memoryCost: this.options.hashing.password.memoryCost,
-            timeCost: this.options.hashing.password.timeCost,
+            hashLength: this.moduleOptions.hashing.password.outputKeyLength,
+            type: this.moduleOptions.hashing.password.argon2Type,
+            memoryCost: this.moduleOptions.hashing.password.memoryCost,
+            timeCost: this.moduleOptions.hashing.password.timeCost,
             raw: false,
         });
         return Buffer.isBuffer(tmpData) ? tmpData : Buffer.from(tmpData);
@@ -155,14 +213,20 @@ let CryptographyService = class CryptographyService {
         return crypto.timingSafeEqual(hmac, inputOldHmacData);
     }
     createSecureHmac(data, options) {
-        const key = Buffer.from(this.options.hashing.hmac.masterKey, 'hex');
+        this.checkModuleOptions('HMAC', {
+            masterKey: this.moduleOptions?.hashing?.hmac?.masterKey,
+        });
+        const key = Buffer.from(this.moduleOptions.hashing.hmac.masterKey, 'hex');
         const salt = crypto.randomBytes(16);
         const secureKey = this.createHmacSecureKey(key, salt);
         const hmac = this.createCustomHmac('sha3-256', secureKey, data, options);
         return Buffer.concat([salt, hmac], salt.length + hmac.length);
     }
     verifySecureHmac(data, oldHmac, options) {
-        const key = Buffer.from(this.options.hashing.hmac.masterKey, 'hex');
+        this.checkModuleOptions('HMAC', {
+            masterKey: this.moduleOptions?.hashing?.hmac?.masterKey,
+        });
+        const key = Buffer.from(this.moduleOptions.hashing.hmac.masterKey, 'hex');
         const buffOldHmac = this.convertInputData(oldHmac, options?.inputDataEncoding);
         const saltOldHmac = this.extractSaltFromHmac(buffOldHmac);
         const hashOldHmac = buffOldHmac.subarray(16, buffOldHmac.length);
@@ -200,16 +264,22 @@ let CryptographyService = class CryptographyService {
         return decipheredData;
     }
     async symmetricSecureDataEncrypt(data, options) {
+        this.checkModuleOptions('SYMMETRIC_ENCRYPTION', {
+            masterKey: this.moduleOptions?.encryption?.symmetric?.masterKey,
+        });
         const dek = this.createSafeRandomData(32);
         const cipheredData = await this.symmetricDataEncrypt(data, dek, options);
-        const cipheredDek = await this.symmetricDataEncrypt(dek, this.options.encryption.symmetric.masterKey);
+        const cipheredDek = await this.symmetricDataEncrypt(dek, this.moduleOptions.encryption.symmetric.masterKey);
         return Buffer.concat([cipheredDek, cipheredData]);
     }
     async symmetricSecureDataDecrypt(data, options) {
+        this.checkModuleOptions('SYMMETRIC_ENCRYPTION', {
+            masterKey: this.moduleOptions?.encryption?.symmetric?.masterKey,
+        });
         const inputData = this.convertInputData(data, options?.inputDataEncoding);
         const cipheredDek = this.extractCipheredDEK(inputData);
         const cipheredData = this.extractCipheredDataWithDEK(inputData);
-        const decipheredDek = await this.symmetricDataDecrypt(cipheredDek, this.options.encryption.symmetric.masterKey);
+        const decipheredDek = await this.symmetricDataDecrypt(cipheredDek, this.moduleOptions.encryption.symmetric.masterKey);
         return await this.symmetricDataDecrypt(cipheredData, decipheredDek);
     }
 };

package/dist/interfaces/cryptography-options.interface.d.ts

@@ -3,27 +3,31 @@ export declare enum Argon2Type {
     argon2i = 1,
     argon2id = 2
 }
-export interface CryptographyOptionsInterface {
-    kdf: {
+export interface CryptographyKdfOptions {
+    outputKeyLength: number;
+    argon2Type: Argon2Type;
+    memoryCost: number;
+    timeCost: number;
+}
+export interface CryptographyHashingOptions {
+    password: {
         outputKeyLength: number;
         argon2Type: Argon2Type;
         memoryCost: number;
         timeCost: number;
     };
-    hashing: {
-        password: {
-            outputKeyLength: number;
-            argon2Type: Argon2Type;
-            memoryCost: number;
-            timeCost: number;
-        };
-        hmac: {
-            masterKey: string;
-        };
+    hmac: {
+        masterKey: string;
     };
-    encryption: {
-        symmetric: {
-            masterKey: string;
-        };
+}
+export interface CryptographyEncryptionOptions {
+    symmetric: {
+        masterKey: string;
     };
 }
+export interface CryptographyOptionsInterface {
+    useDefaultValues?: boolean;
+    kdf?: Partial<CryptographyKdfOptions>;
+    hashing?: Partial<CryptographyHashingOptions>;
+    encryption?: Partial<CryptographyEncryptionOptions>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-cryptography",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "author": {
     "name": "Marc Jorge Gonzalez",
     "url": "https://github.com/mjorgegulab"
@@ -31,14 +31,14 @@
   },
   "devDependencies": {
     "@nestjs/cli": "^10.4.5",
-    "@nestjs/common": "^10.4.1",
-    "@nestjs/core": "^10.4.1",
-    "@nestjs/platform-express": "^10.4.1",
+    "@nestjs/common": "^10.4.4",
+    "@nestjs/core": "^10.4.4",
+    "@nestjs/platform-express": "^10.4.4",
     "@nestjs/schematics": "^10.1.4",
-    "@nestjs/testing": "^10.4.1",
+    "@nestjs/testing": "^10.4.4",
     "@types/express": "^4.17.21",
-    "@types/jest": "29.5.12",
-    "@types/node": "22.5.4",
+    "@types/jest": "29.5.13",
+    "@types/node": "22.7.5",
     "@types/supertest": "^6.0.2",
     "@typescript-eslint/eslint-plugin": "^7.12.0",
     "@typescript-eslint/parser": "^7.12.0",
@@ -56,13 +56,20 @@
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "4.2.0",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^9.0.0 || ^10.0.0",
     "@nestjs/core": "^9.0.0 || ^10.0.0"
   },
   "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/wiki/"
+    ],
+    "modulePathIgnorePatterns": [
+      "/wiki/"
+    ],
     "moduleFileExtensions": [
       "js",
       "json",

package/wiki/README.md

@@ -1,41 +0,0 @@
-# Website
-
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
-
-### Installation
-
-```
-$ yarn
-```
-
-### Local Development
-
-```
-$ yarn start
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-
-### Build
-
-```
-$ yarn build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
-
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

package/wiki/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

package/wiki/docs/Internals/_category_.json

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

package/wiki/docs/Internals/create-safe-random-data.mdx

@@ -1,41 +0,0 @@
----
-title: Create Safe Random Data
-sidebar_label: Create Safe Random Data
-sidebar_position: 2
-description: Internals of createSafeRandomData
----
-
-In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`createSafeRandomData`][1]
-
-This method generate a cryptographically secure random bytes of the desired lengths using **HKDF**
-with `sha3-256` digest algorithm using the following params:
- - Generate a random key using the secure random bytes' generator.
- - Generate a salt using the secure random bytes' generator.
-
-
-<div style={{ textAlign: 'center' }}>
-  ```mermaid
-  graph TD
-    A[Key Length: length]
-
-    A --> CRB[Create Random Bytes: 64 bytes]
-    CRB --> CSK[Create Secret Key]
-    CSK ==> SK(SECRET_KEY)
-
-    A --> CRB2[Create Random Bytes: 64 bytes]
-    CRB2 ==> RB[RANDOM_BYTES]
-
-    SK -.-> HKDF["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
-    RB -.-> HKDF --> F([Return Secure Random Bytes])
-
-
-    style CRB fill:#f9f,stroke:#333,stroke-width:2px
-    style CRB2 fill:#f9f,stroke:#333,stroke-width:2px
-    style SK fill:#bbf,stroke:#333,stroke-width:2px
-    style RB fill:#bbf,stroke:#333,stroke-width:2px
-    style HKDF fill:#bfb,stroke:#333,stroke-width:2px
-    style F fill:#00f0f0,stroke:#F0000,stroke-width:2px
-  ```
-</div>
-
-[1]: ../guides/generics#generate-secure-random-data

package/wiki/docs/Internals/create-secure-hmac.mdx

@@ -1,31 +0,0 @@
----
-title: Create Secure HMAC
-sidebar_label: Create Secure HMAC
-sidebar_position: 1
-description: Internals of createSecureHmac
----
-
-In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`createSecureHmac`][1]
-
-This method performs several cryptographic operations, including generating a salt,
-deriving a secure key using HKDF with the sha3-256 hashing algorithm, creating an HMAC,
-and returning the concatenated salt and HMAC result. The diagram will illustrate these steps clearly.
-
-<div style={{ textAlign: 'center' }}>
-  ```mermaid
-  graph TD
-      A[Input Data: data] --> B[Generate Master Key from Options]
-      B --> C[Generate Random Salt: 16 bytes]
-      C --> D[Use HKDF with sha3-256, Master Key, and Salt]
-      D --> E[Generate Secure Key: 64 bytes]
-      E --> F[Create HMAC with sha3-256, Secure Key, and Data]
-      F --> G[Concatenate Salt and HMAC]
-      G --> H[Return Combined Buffer: Salt + HMAC]
-
-      style B fill:#f9f,stroke:#333,stroke-width:2px
-      style D fill:#bbf,stroke:#333,stroke-width:2px
-      style F fill:#bfb,stroke:#333,stroke-width:2px
-  ```
-</div>
-
-[1]: ../guides/hmac#create-a-secure-hmac

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

@@ -1,103 +0,0 @@
----
-title: Symmetric Data Encrypt
-sidebar_label: Symmetric Data Encrypt
-sidebar_position: 4
-description: Internals of symmetricDataEncrypt
----
-
-In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`symmetricDataEncrypt`][1]
-
-This method securely encrypts input data by first generating a 12-byte Initialization Vector **(IV)**
-and a 64-byte **salt** using the `HKDF(sha3-256 + random_key + random_salt)` technique.
-It then derives a secure encryption key from the salt using the **Argon2** algorithm.
-The actual data is encrypted using **AES-256-GCM** with the derived key,
-resulting in an output that includes the IV, salt, authentication tag, and ciphertext.
-This comprehensive approach ensures the integrity and confidentiality of the data during storage or transmission.
-
-## **Diagram**
-
-<div style={{ textAlign: 'center' }}>
-  ```mermaid
-  graph TD
-
-  A[Input: Data] --> ID
-  B[Input: Key] --> IK
-
-  subgraph ED[Encrypt Data]
-
-    ID(DATA)
-    IK(KEY)
-
-    subgraph IVGENERATIONGRAPH["Generate IV (12 bytes)"]
-      IVL[Key Length: length] --> CRB[Create Random Bytes: 64 bytes]
-      CRB --> CSK[Create Secret Key]
-      CSK ==> SK(SECRET_KEY)
-
-      IVL --> CRB2[Create Random Bytes: 64 bytes]
-      CRB2 ==> RB[RANDOM_BYTES]
-
-      SK -.-> HKDF["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
-      RB -.-> HKDF --> F([Return Secure Random Bytes])
-    end
-
-    subgraph SALTGENERATIONGRAPH["Generate Salt (64 bytes)"]
-      IVL2[Key Length: length] --> CRB23[Create Random Bytes: 64 bytes]
-      CRB23 --> CSK2[Create Secret Key]
-      CSK2 ==> SK2(SECRET_KEY)
-
-      IVL2 --> CRB22[Create Random Bytes: 64 bytes]
-      CRB22 ==> RB2[RANDOM_BYTES]
-
-      SK2 -.-> HKDF2["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
-      RB2 -.-> HKDF2 --> F2([Return Secure Random Bytes])
-    end
-
-    F --> FIV(IV)
-
-    F2 --> DERIVEDEK[Securely derive DEK using Argon2 + Salt]
-    DERIVEDEK --> EK1(ENCRYPTION_KEY)
-    IK --> DERIVEDEK
-
-    FIV ==> FED([Encrypt DATA using AES-256-GCM with ENCRYPTION_KEY + IV])
-    EK1 ==> FED
-    ID ==> FED
-
-  end
-
-  FED -.- FFED["Encrypted data [IV + Salt + AuthTag + CipherText]"]
-
-
-  %% Style definitions
-  style ID fill:#BCD3A3,stroke:#333,stroke-width:2px;
-  style FIV fill:#ffcc00,stroke:#333,stroke-width:2px;
-  style EK1 fill:#66ff66,stroke:#333,stroke-width:2px;
-  style FED fill:#cc99ff,stroke:#333,stroke-width:2px;
-  style FFED fill:#ff9966,stroke:#333,stroke-width:2px;
-
-  style CRB fill:#f9f,stroke:#333,stroke-width:2px
-  style CRB2 fill:#f9f,stroke:#333,stroke-width:2px
-  style SK fill:#bbf,stroke:#333,stroke-width:2px
-  style RB fill:#bbf,stroke:#333,stroke-width:2px
-  style HKDF fill:#bfb,stroke:#333,stroke-width:2px
-  style F fill:#00f0f0,stroke:#F0000,stroke-width:2px
-
-  style CRB23 fill:#f9f,stroke:#333,stroke-width:2px
-  style CRB22 fill:#f9f,stroke:#333,stroke-width:2px
-  style SK2 fill:#bbf,stroke:#333,stroke-width:2px
-  style RB2 fill:#bbf,stroke:#333,stroke-width:2px
-  style HKDF2 fill:#bfb,stroke:#333,stroke-width:2px
-  style F2 fill:#00f0f0,stroke:#F0000,stroke-width:2px
-  ```
-</div>
-
-
-## **Explanation of the Diagram**
-1) **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
-2) **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
-3) **Derive Secure Encryption Key**: A secure encryption key is derived using **Argon2** with the _Key_ and **Salt**.
-4) **Encrypt Data**: The _input data_ is encrypted using **AES-256-GCM** with the derived secure encryption key,
-producing the encrypted result in format: `[IV + Salt + AuthTag + CipherText]`.
-
-
-[1]: ../guides/symmetric-encryption#symmetricdataencrypt
-[2]: ../api-reference/settings#masterkey-1