nestjs-cryptography 2.2.3 → 3.0.0

package/README.md

@@ -1,9 +1,14 @@
 [![codecov](https://codecov.io/github/mjorgegulab/nestjs-cryptography/branch/main/graph/badge.svg?token=I0ZFVZTREB)](https://codecov.io/github/mjorgegulab/nestjs-cryptography)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/d4c33e2a77d64f89ba7f6ba54c6d8cb5)](https://app.codacy.com/gh/mjorgegulab/nestjs-cryptography/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![CodeQL](https://github.com/mjorgegulab/nestjs-cryptography/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/mjorgegulab/nestjs-cryptography/actions/workflows/github-code-scanning/codeql)
+[![Publish Wiki](https://github.com/mjorgegulab/nestjs-cryptography/actions/workflows/deploy-wiki-prod.yaml/badge.svg?branch=main)](https://nestjs-cryptography.thewolfx41.dev)
 
 # NestJS - Cryptography
-## Secure NestJS cryptography module 🔐
+
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
+</p>
+
 
 ## Quick Start
 

package/dist/cryptography.service.d.ts

@@ -1,36 +1,34 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import * as crypto from 'node:crypto';
-import { CryptographyOptionsInterface } from './interfaces';
+import { CryptographyOptionsInterface, GenericOptionsInterface } from './interfaces';
 export declare class CryptographyService {
     private options;
     constructor(options: CryptographyOptionsInterface);
-    private convertDataToBuffer;
+    private convertInputData;
     private extractIV;
     private extractAuthTagFromCypheredData;
     private extractCipheredData;
     private extractSalt;
+    private extractSaltFromHmac;
     private extractCipheredDEK;
     private extractCipheredDataWithDEK;
-    private createSaferRandomData;
-    private generateKeyDEK;
+    private createHmacSecureKey;
+    createSafeRandomData(length: number): Buffer;
     genUUID(secure?: boolean): string;
-    genRandomPassword(length: number, encoding: 'base64' | 'hex'): string;
+    genRandomPassword(length: number): string;
     generateSymmetricKey(length?: number): crypto.KeyObject;
-    deriveMasterKey(masterKey: string | Buffer, salt: Buffer, length: number): Promise<Buffer>;
-    createArgonHashFromPassword(data: string | Buffer): Promise<Buffer>;
-    verifyArgonHashFromPassword(hash: string, data: string | Buffer): Promise<boolean>;
-    createCustomHash(algorithm: string, data: string, outputLength?: number): Buffer;
-    verifyCustomHash(algorithm: string, data: string, oldHash: string | Buffer, outputLength?: number): boolean;
-    createSecureHash(data: string): Buffer;
-    verifySecureHash(data: string, oldHash: string | Buffer): boolean;
-    createCustomHmac(algorithm: string, key: Buffer, data: string): Buffer;
-    verifyCustomHmac(algorithm: string, key: Buffer, data: string, oldHmac: string | Buffer): boolean;
-    createSecureHmac(data: string): Buffer;
-    verifySecureHmac(data: string, oldHmac: Buffer | string): boolean;
-    createInsecureFastHash(data: string): Buffer;
-    private symmetricDataEncrypt;
-    private symmetricDataDecrypt;
-    symmetricSecureDataEncrypt(data: string | Buffer): Promise<Buffer>;
-    symmetricSecureDataDecrypt(data: string | Buffer): Promise<Buffer>;
+    deriveMasterKey(masterKey: string | Buffer, salt: Buffer, length?: number): Promise<Buffer>;
+    createArgon2HashFromPassword(data: string | Buffer): Promise<Buffer>;
+    verifyArgon2HashFromPassword(hash: string, data: string | Buffer): Promise<boolean>;
+    createCustomHash(algorithm: string, data: string | Buffer, options?: GenericOptionsInterface): Buffer;
+    verifyCustomHash(algorithm: string, data: string | Buffer, oldHash: string | Buffer, options?: GenericOptionsInterface): boolean;
+    createSecureHash(data: string | Buffer, options?: GenericOptionsInterface): Buffer;
+    verifySecureHash(data: string | Buffer, oldHash: string | Buffer, options?: GenericOptionsInterface): boolean;
+    createCustomHmac(algorithm: string, key: string | Buffer, data: string | Buffer, options?: GenericOptionsInterface): Buffer;
+    verifyCustomHmac(algorithm: string, key: string | Buffer, data: string | Buffer, oldHmac: string | Buffer, options?: GenericOptionsInterface): boolean;
+    createSecureHmac(data: string | Buffer, options?: GenericOptionsInterface): Buffer;
+    verifySecureHmac(data: string | Buffer, oldHmac: string | Buffer, options?: GenericOptionsInterface): boolean;
+    symmetricDataEncrypt(data: string | Buffer, key: string | Buffer, options?: GenericOptionsInterface): Promise<Buffer>;
+    symmetricDataDecrypt(data: string | Buffer, key: string | Buffer, options?: GenericOptionsInterface): Promise<Buffer>;
+    symmetricSecureDataEncrypt(data: string | Buffer, options?: GenericOptionsInterface): Promise<Buffer>;
+    symmetricSecureDataDecrypt(data: string | Buffer, options?: GenericOptionsInterface): Promise<Buffer>;
 }

package/dist/cryptography.service.js

@@ -44,8 +44,16 @@ let CryptographyService = class CryptographyService {
     constructor(options) {
         this.options = options;
     }
-    convertDataToBuffer(data) {
-        return Buffer.isBuffer(data) ? data : Buffer.from(data, 'hex');
+    convertInputData(data, inputEncoding) {
+        if (Buffer.isBuffer(data)) {
+            return data;
+        }
+        else if (typeof data === 'string') {
+            return Buffer.from(data, inputEncoding ?? 'utf8');
+        }
+        else {
+            throw new Error('Unsupported input type');
+        }
     }
     extractIV(data) {
         return data.subarray(0, 12);
@@ -59,32 +67,35 @@ let CryptographyService = class CryptographyService {
     extractSalt(data) {
         return data.subarray(12, 76);
     }
+    extractSaltFromHmac(data) {
+        return data.subarray(0, 16);
+    }
     extractCipheredDEK(data) {
         return data.subarray(0, 124);
     }
     extractCipheredDataWithDEK(data) {
         return data.subarray(124, data.length);
     }
-    createSaferRandomData(length) {
-        return Buffer.from(crypto.hkdfSync('sha3-256', crypto.createSecretKey(crypto.randomBytes(64)), crypto.randomBytes(64), Buffer.alloc(0), length));
+    createHmacSecureKey(key, salt) {
+        return Buffer.from(crypto.hkdfSync('sha3-256', crypto.createSecretKey(key), salt, Buffer.alloc(0), 64));
     }
-    generateKeyDEK() {
-        return crypto.createSecretKey(this.createSaferRandomData(32));
+    createSafeRandomData(length) {
+        return Buffer.from(crypto.hkdfSync('sha3-256', crypto.createSecretKey(crypto.randomBytes(64)), crypto.randomBytes(64), Buffer.alloc(0), length));
     }
     genUUID(secure = false) {
         return crypto.randomUUID({
             disableEntropyCache: secure,
         });
     }
-    genRandomPassword(length, encoding) {
-        return crypto.randomBytes(length).toString(encoding).slice(0, length);
+    genRandomPassword(length) {
+        return crypto.randomBytes(length).toString('base64').slice(0, length);
     }
     generateSymmetricKey(length = 256) {
         return crypto.generateKeySync('hmac', { length });
     }
     async deriveMasterKey(masterKey, salt, length) {
         return await argon2.hash(masterKey, {
-            hashLength: length ? length : this.options.kdf.defaultOutputKeyLength,
+            hashLength: length ?? this.options.kdf.outputKeyLength,
             salt: salt,
             type: this.options.kdf.argon2Type,
             memoryCost: this.options.kdf.memoryCost,
@@ -92,7 +103,7 @@ let CryptographyService = class CryptographyService {
             raw: true,
         });
     }
-    async createArgonHashFromPassword(data) {
+    async createArgon2HashFromPassword(data) {
         const tmpData = await argon2.hash(data, {
             hashLength: this.options.hashing.password.outputKeyLength,
             type: this.options.hashing.password.argon2Type,
@@ -102,113 +113,102 @@ let CryptographyService = class CryptographyService {
         });
         return Buffer.isBuffer(tmpData) ? tmpData : Buffer.from(tmpData);
     }
-    async verifyArgonHashFromPassword(hash, data) {
+    async verifyArgon2HashFromPassword(hash, data) {
         return await argon2.verify(hash, data);
     }
-    createCustomHash(algorithm, data, outputLength = 0) {
+    createCustomHash(algorithm, data, options) {
+        const inputData = this.convertInputData(data, options?.inputDataEncoding);
         const hash = crypto.createHash(algorithm, {
-            ...(outputLength && { outputLength }),
+            ...(options?.outputLength && { outputLength: options?.outputLength }),
         });
-        hash.update(data);
+        hash.update(inputData);
         return hash.digest();
     }
-    verifyCustomHash(algorithm, data, oldHash, outputLength = 0) {
-        const hash = this.createCustomHash(algorithm, data, outputLength);
-        if (Buffer.isBuffer(oldHash)) {
-            return crypto.timingSafeEqual(hash, oldHash);
-        }
-        else {
-            return crypto.timingSafeEqual(Buffer.from(oldHash, 'hex'), hash);
-        }
+    verifyCustomHash(algorithm, data, oldHash, options) {
+        const inputOldHashData = this.convertInputData(oldHash, options?.inputDataEncoding);
+        const hash = this.createCustomHash(algorithm, data, options);
+        return crypto.timingSafeEqual(hash, inputOldHashData);
     }
-    createSecureHash(data) {
-        return this.createCustomHash('shake256', data, 48);
+    createSecureHash(data, options) {
+        return this.createCustomHash('shake256', data, {
+            ...options,
+            outputLength: 48,
+        });
     }
-    verifySecureHash(data, oldHash) {
-        const hash = this.createCustomHash('shake256', data, 48);
-        const buffOldHash = Buffer.isBuffer(oldHash)
-            ? oldHash
-            : Buffer.from(oldHash, 'hex');
-        return crypto.timingSafeEqual(hash, buffOldHash);
+    verifySecureHash(data, oldHash, options) {
+        return this.verifyCustomHash('shake256', data, oldHash, {
+            ...options,
+            outputLength: 48,
+        });
     }
-    createCustomHmac(algorithm, key, data) {
-        const hmac = crypto.createHmac(algorithm, crypto.createSecretKey(key));
-        hmac.update(data);
+    createCustomHmac(algorithm, key, data, options) {
+        const inputKey = this.convertInputData(key, options?.inputKeyEncoding);
+        const inputData = this.convertInputData(data, options?.inputDataEncoding);
+        const hmac = crypto.createHmac(algorithm, crypto.createSecretKey(inputKey));
+        hmac.update(inputData);
         key = null;
         return hmac.digest();
     }
-    verifyCustomHmac(algorithm, key, data, oldHmac) {
-        const hmac = this.createCustomHmac(algorithm, key, data);
-        if (Buffer.isBuffer(oldHmac)) {
-            return crypto.timingSafeEqual(hmac, oldHmac);
-        }
-        else {
-            return crypto.timingSafeEqual(Buffer.from(oldHmac, 'hex'), hmac);
-        }
+    verifyCustomHmac(algorithm, key, data, oldHmac, options) {
+        const inputOldHmacData = this.convertInputData(oldHmac, options?.inputDataEncoding);
+        const hmac = this.createCustomHmac(algorithm, key, data, options);
+        return crypto.timingSafeEqual(hmac, inputOldHmacData);
     }
-    createSecureHmac(data) {
+    createSecureHmac(data, options) {
         const key = Buffer.from(this.options.hashing.hmac.masterKey, 'hex');
         const salt = crypto.randomBytes(16);
-        const secureKey = Buffer.from(crypto.hkdfSync('sha3-256', crypto.createSecretKey(key), salt, Buffer.alloc(0), 64));
-        const hmac = this.createCustomHmac('sha3-256', secureKey, data);
-        return Buffer.concat([Buffer.from(salt), Buffer.from(hmac)], salt.length + hmac.length);
+        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) {
+    verifySecureHmac(data, oldHmac, options) {
         const key = Buffer.from(this.options.hashing.hmac.masterKey, 'hex');
-        const buffOldHmac = Buffer.isBuffer(oldHmac)
-            ? oldHmac
-            : Buffer.from(oldHmac, 'hex');
-        const saltOldHmac = buffOldHmac.subarray(0, 16);
+        const buffOldHmac = this.convertInputData(oldHmac, options?.inputDataEncoding);
+        const saltOldHmac = this.extractSaltFromHmac(buffOldHmac);
         const hashOldHmac = buffOldHmac.subarray(16, buffOldHmac.length);
-        const secureKey = Buffer.from(crypto.hkdfSync('sha3-256', crypto.createSecretKey(key), saltOldHmac, Buffer.alloc(0), 64));
-        const hmac = this.createCustomHmac('sha3-256', secureKey, data);
+        const secureKey = this.createHmacSecureKey(key, saltOldHmac);
+        const hmac = this.createCustomHmac('sha3-256', secureKey, data, options);
         return crypto.timingSafeEqual(hmac, hashOldHmac);
     }
-    createInsecureFastHash(data) {
-        return crypto.createHash('sha1').update(data).digest();
-    }
-    async symmetricDataEncrypt(data, key) {
-        const iv = this.createSaferRandomData(12);
-        const salt = this.createSaferRandomData(64);
-        const secureEncryptionKey = await this.deriveMasterKey(key, salt, 32);
+    async symmetricDataEncrypt(data, key, options) {
+        const inputData = this.convertInputData(data, options?.inputDataEncoding);
+        const inputKey = this.convertInputData(key, options?.inputKeyEncoding);
+        const iv = this.createSafeRandomData(12);
+        const salt = this.createSafeRandomData(64);
+        const secureEncryptionKey = await this.deriveMasterKey(inputKey, salt, 32);
         const cipher = crypto.createCipheriv('aes-256-gcm', crypto.createSecretKey(secureEncryptionKey), iv, {
             authTagLength: 16,
         });
-        let cipheredData = cipher.update(data);
-        cipheredData = Buffer.concat([
-            Buffer.from(cipheredData),
-            Buffer.from(cipher.final()),
-        ]);
+        let cipheredData = cipher.update(inputData);
+        cipheredData = Buffer.concat([cipheredData, cipher.final()]);
         return Buffer.concat([iv, salt, cipher.getAuthTag(), cipheredData]);
     }
-    async symmetricDataDecrypt(data, key) {
-        data = Buffer.isBuffer(data) ? data : Buffer.from(data, 'hex');
-        const iv = this.extractIV(data);
-        const salt = this.extractSalt(data);
-        const authTag = this.extractAuthTagFromCypheredData(data);
-        const cipheredData = this.extractCipheredData(data);
-        const decryptionKey = await this.deriveMasterKey(key, salt, 32);
+    async symmetricDataDecrypt(data, key, options) {
+        const inputData = this.convertInputData(data, options?.inputDataEncoding);
+        const inputKey = this.convertInputData(key, options?.inputKeyEncoding);
+        const iv = this.extractIV(inputData);
+        const salt = this.extractSalt(inputData);
+        const authTag = this.extractAuthTagFromCypheredData(inputData);
+        const cipheredData = this.extractCipheredData(inputData);
+        const decryptionKey = await this.deriveMasterKey(inputKey, salt, 32);
         const decipher = crypto.createDecipheriv('aes-256-gcm', crypto.createSecretKey(decryptionKey), iv, {
             authTagLength: 16,
         });
         decipher.setAuthTag(authTag);
         let decipheredData = decipher.update(cipheredData);
-        decipheredData = Buffer.concat([
-            Buffer.from(decipheredData),
-            Buffer.from(decipher.final()),
-        ]);
+        decipheredData = Buffer.concat([decipheredData, decipher.final()]);
         return decipheredData;
     }
-    async symmetricSecureDataEncrypt(data) {
-        const dek = this.createSaferRandomData(32);
-        const cipheredData = await this.symmetricDataEncrypt(data, dek);
+    async symmetricSecureDataEncrypt(data, options) {
+        const dek = this.createSafeRandomData(32);
+        const cipheredData = await this.symmetricDataEncrypt(data, dek, options);
         const cipheredDek = await this.symmetricDataEncrypt(dek, this.options.encryption.symmetric.masterKey);
         return Buffer.concat([cipheredDek, cipheredData]);
     }
-    async symmetricSecureDataDecrypt(data) {
-        data = Buffer.isBuffer(data) ? data : Buffer.from(data, 'hex');
-        const cipheredDek = this.extractCipheredDEK(data);
-        const cipheredData = this.extractCipheredDataWithDEK(data);
+    async symmetricSecureDataDecrypt(data, options) {
+        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);
         return await this.symmetricDataDecrypt(cipheredData, decipheredDek);
     }

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

@@ -5,7 +5,7 @@ export declare enum Argon2Type {
 }
 export interface CryptographyOptionsInterface {
     kdf: {
-        defaultOutputKeyLength: number;
+        outputKeyLength: number;
         argon2Type: Argon2Type;
         memoryCost: number;
         timeCost: number;

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

@@ -0,0 +1,5 @@
+export interface GenericOptionsInterface {
+    outputLength?: number;
+    inputDataEncoding?: BufferEncoding;
+    inputKeyEncoding?: BufferEncoding;
+}

package/dist/interfaces/generic-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/index.d.ts

@@ -1 +1,2 @@
 export * from './cryptography-options.interface';
+export * from './generic-options.interface';

package/dist/interfaces/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./cryptography-options.interface"), exports);
+__exportStar(require("./generic-options.interface"), exports);

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "nestjs-cryptography",
-  "version": "2.2.3",
+  "version": "3.0.0",
   "author": {
     "name": "Marc Jorge Gonzalez",
     "url": "https://github.com/mjorgegulab"
   },
   "license": "MIT",
   "description": "Secure NestJS cryptography module 🔐",
-  "publishConfig": {
-    "registry": "https://npm.pkg.github.com/"
-  },
   "homepage": "https://nestjs-cryptography.thewolfx41.dev",
   "repository": {
     "type": "git",
@@ -24,17 +21,18 @@
     "lint": "eslint --fix",
     "publish:npm": "npm publish --access=public",
     "prepublish": "yarn run build",
-    "prepack": "yarn run build"
+    "prepack": "yarn run build",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "all": "yarn format && yarn lint && yarn test && yarn prepack"
   },
   "dependencies": {
     "argon2": "^0.41.1"
   },
   "devDependencies": {
+    "@nestjs/cli": "^10.4.5",
     "@nestjs/common": "^10.4.1",
     "@nestjs/core": "^10.4.1",
-    "@nestjs/cli": "^10.4.5",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1",
     "@nestjs/platform-express": "^10.4.1",
     "@nestjs/schematics": "^10.1.4",
     "@nestjs/testing": "^10.4.1",
@@ -46,17 +44,19 @@
     "@typescript-eslint/parser": "^7.12.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-prettier": "^5.2.1",
     "jest": "29.7.0",
     "prettier": "^3.3.3",
+    "reflect-metadata": "^0.2.2",
+    "rimraf": "^6.0.1",
+    "rxjs": "^7.8.1",
     "source-map-support": "^0.5.21",
     "supertest": "^7.0.0",
     "ts-jest": "29.2.5",
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "4.2.0",
-    "typescript": "^5.4.5",
-    "rimraf": "^5.0.7"
+    "typescript": "^5.6.2"
   },
   "peerDependencies": {
     "@nestjs/common": "^9.0.0 || ^10.0.0",
@@ -68,15 +68,16 @@
       "json",
       "ts"
     ],
-    "rootDir": "src",
-    "testRegex": ".*\\.spec\\.ts$",
+    "rootDir": "./",
+    "testMatch": [
+      "**/test/**/?(*.)+(spec|test).[tj]s?(x)"
+    ],
     "transform": {
       "^.+\\.(t|j)s$": "ts-jest"
     },
     "collectCoverageFrom": [
-      "**/*.(t|j)s"
+      "**/*.service.ts"
     ],
-    "coverageDirectory": "../coverage",
     "testEnvironment": "node"
   }
 }

package/wiki/README.md

@@ -0,0 +1,41 @@
+# 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

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

package/wiki/docs/Internals/_category_.json

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

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

@@ -0,0 +1,41 @@
+---
+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

@@ -0,0 +1,31 @@
+---
+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