@nivinjoseph/n-sec 6.0.3 → 7.0.1

package/dist/crypto/symmetric-encryption.js.map

@@ -1 +1 @@
-{"version":3,"file":"symmetric-encryption.js","sourceRoot":"","sources":["../../src/crypto/symmetric-encryption.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"symmetric-encryption.js","sourceRoot":"","sources":["../../src/crypto/symmetric-encryption.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.json

@@ -1,6 +1,7 @@
 {
     "extends": "../tsconfig.json",
     "compilerOptions": {
+        "rootDir": "../src",
         "outDir": ".",
         "declaration": true,
         "declarationDir": ".",

package/eslint.config.js

@@ -11,7 +11,7 @@ export default defineConfig(
     tsEslint.configs.recommended,
     importPlugin.flatConfigs.recommended,
     {
-        ignores: ["dist/**", "node_modules/**", "**/*.js", "**/*.map", "**/*d.ts"]
+        ignores: ["dist/**", "node_modules/**", "**/*.js", "**/*.map", "**/*.d.ts"]
     },
     {
         files: ["**/*.ts"],
@@ -50,9 +50,9 @@ export default defineConfig(
         files: ["**/*.ts"],
         languageOptions: {
             parserOptions: {
-                project: [
-                    "./tsconfig.json"
-                ],
+                // project: [
+                //     "./tsconfig.json"
+                // ],
                 tsconfigRootDir: import.meta.dirname,
                 projectService: true
             }
@@ -155,7 +155,7 @@ export default defineConfig(
             ],
             "default-param-last": "off",
             "@typescript-eslint/default-param-last": "error",
-            "@typescript-eslint/explicit-function-return-type": "error",
+            "@typescript-eslint/explicit-function-return-type": ["error", { "allowExpressions": true }],
             "@typescript-eslint/explicit-member-accessibility": "error",
             "@typescript-eslint/explicit-module-boundary-types": "error",
             "func-call-spacing": "off",

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "@nivinjoseph/n-sec",
-    "version": "6.0.3",
+    "version": "7.0.1",
     "description": "Security library",
-    "packageManager": "yarn@4.0.2",
+    "packageManager": "yarn@4.14.1",
     "type": "module",
     "exports": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
         "ts-build": "yarn ts-compile && yarn ts-lint",
         "ts-build-dist": "yarn ts-build && tsc -p ./dist",
         "test": "yarn ts-build && node --test --enable-source-maps ./test/**/*.test.js",
-        "publish-package": "yarn ts-build-dist && git add . && git commit -m 'preparing to publish new version' && git push && npm publish --access=public"
+        "publish-package": "yarn ts-build-dist && git add . && git commit -m 'preparing to publish new version' && yarn version patch && git add . && git commit -m 'new version' && git push && npm publish --access=public"
     },
     "repository": {
         "type": "git",
@@ -30,20 +30,20 @@
     },
     "homepage": "https://github.com/nivinjoseph/n-sec#readme",
     "devDependencies": {
-        "@eslint/js": "^9.39.1",
-        "@stylistic/eslint-plugin": "^5.5.0",
-        "@types/node": "^24.10",
-        "eslint": "^9.39.1",
-        "eslint-import-resolver-typescript": "^4.4.4",
-        "eslint-plugin-import": "^2.32.0",
-        "typescript": "^5.9.3",
-        "typescript-eslint": "^8.46.3"
+        "@eslint/js": "10.0.1",
+        "@stylistic/eslint-plugin": "5.10.0",
+        "@types/node": "24.10.0",
+        "eslint": "10.2.1",
+        "eslint-import-resolver-typescript": "4.4.4",
+        "eslint-plugin-import": "2.32.0",
+        "typescript": "6.0.3",
+        "typescript-eslint": "8.59.0"
     },
     "dependencies": {
-        "@nivinjoseph/n-defensive": "^2.0.2",
-        "@nivinjoseph/n-exception": "^2.0.2",
-        "@nivinjoseph/n-ext": "^2.0.2",
-        "@nivinjoseph/n-util": "^3.2.0"
+        "@nivinjoseph/n-defensive": "2.0.3",
+        "@nivinjoseph/n-exception": "2.0.3",
+        "@nivinjoseph/n-ext": "2.0.5",
+        "@nivinjoseph/n-util": "4.0.1"
     },
     "engines": {
         "node": ">=24.10"

package/src/api-security/json-web-token.ts

@@ -1,5 +1,6 @@
 import { given } from "@nivinjoseph/n-defensive";
 import { InvalidOperationException } from "@nivinjoseph/n-exception";
+import { timingSafeEqual } from "node:crypto";
 import { Hmac } from "./../crypto/hmac.js";
 import { AlgType } from "./alg-type.js";
 import { Claim } from "./claim.js";
@@ -14,7 +15,7 @@ export class JsonWebToken
     private readonly _issuer: string;
     private readonly _algType: AlgType;
     private readonly _key: string;
-    private readonly _isfullKey: boolean;
+    private readonly _isFullKey: boolean;
     private readonly _expiry: number;
     private readonly _claims: Array<Claim>;
 
@@ -22,7 +23,7 @@ export class JsonWebToken
     public get issuer(): string { return this._issuer; }
     public get algType(): AlgType { return this._algType; }
     public get key(): string { return this._key; }
-    public get canGenerateToken(): boolean { return this._isfullKey; }
+    public get canGenerateToken(): boolean { return this._isFullKey; }
     public get expiry(): number { return this._expiry; }
     public get isExpired(): boolean { return this._expiry <= Date.now(); }
     public get claims(): ReadonlyArray<Claim> { return this._claims; }
@@ -42,7 +43,7 @@ export class JsonWebToken
         this._issuer = issuer.trim();
         this._algType = algType;
         this._key = key.trim();
-        this._isfullKey = isFullKey;
+        this._isFullKey = isFullKey;
         this._expiry = expiry;
         this._claims = [...claims];
     }
@@ -72,8 +73,26 @@ export class JsonWebToken
         const bodyString = tokenSplitted[1];
         const signature = tokenSplitted[2];
 
-        const header: Header = JsonWebToken._toObject(headerString) as Header;
-        const body: any = JsonWebToken._toObject(bodyString);
+        let parsedHeader: unknown;
+        let parsedBody: unknown;
+        try
+        {
+            parsedHeader = JsonWebToken._toObject(headerString);
+            parsedBody = JsonWebToken._toObject(bodyString);
+        }
+        catch
+        {
+            throw new InvalidTokenException(token, "header or body could not be parsed");
+        }
+
+        if (parsedHeader == null || typeof parsedHeader !== "object" || Array.isArray(parsedHeader))
+            throw new InvalidTokenException(token, "header is not an object");
+
+        if (parsedBody == null || typeof parsedBody !== "object" || Array.isArray(parsedBody))
+            throw new InvalidTokenException(token, "body is not an object");
+
+        const header = parsedHeader as Header;
+        const body = parsedBody as Record<string, unknown>;
 
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (header.iss === undefined || header.iss === null)
@@ -116,26 +135,32 @@ export class JsonWebToken
         // }    
 
         const computedSignature = Hmac.create(key, headerString + "." + bodyString);
-        if (computedSignature !== signature)
+        const expected = Buffer.from(computedSignature, "utf8");
+        const provided = Buffer.from(signature, "utf8");
+        if (expected.length !== provided.length || !timingSafeEqual(expected, provided))
             throw new InvalidTokenException(token, "signature could not be verified");
 
+        const invalidBodyKeys = new Set(["__proto__", "constructor", "prototype"]);
         const claims = new Array<Claim>();
-        for (const item in body)
-            claims.push(new Claim(item, body[item]));
+        for (const [type, value] of Object.entries(body))
+        {
+            if (invalidBodyKeys.has(type))
+                throw new InvalidTokenException(token, `body contains invalid key '${type}'`);
+            claims.push(new Claim(type, value));
+        }
 
         return new JsonWebToken(issuer, algType, key, false, header.exp, claims);
     }
 
-    private static _toObject(hex: string): object
+    private static _toObject(hex: string): unknown
     {
         const json = Buffer.from(hex.toLowerCase(), "hex").toString("utf8");
-        const obj = JSON.parse(json) as object;
-        return obj;
+        return JSON.parse(json);
     }
 
     public generateToken(): string
     {
-        if (!this._isfullKey)
+        if (!this._isFullKey)
             throw new InvalidOperationException("generating token using an instance created from token");
 
         const header: Header = {

package/src/bin.ts

@@ -20,7 +20,7 @@ async function executeCommand(command: SupportedCommands): Promise<void>
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         case SupportedCommands.generateSymmetricKey:
             {
-                const key = await SymmetricEncryption.generateKey();
+                const key = SymmetricEncryption.generateKey();
                 console.log("SYMMETRIC KEY => ", key);
                 break;
             }

package/src/crypto/hash.ts

@@ -1,5 +1,5 @@
 import { given } from "@nivinjoseph/n-defensive";
-import { createHash } from "node:crypto";
+import { createHash, scryptSync, timingSafeEqual } from "node:crypto";
 
 
 // public
@@ -18,6 +18,16 @@ export class Hash
         return hash.digest("hex").toUpperCase();
     }
 
+    /**
+     * @deprecated Unsafe for password storage. Uses a single round of
+     *   SHA-512, which a GPU can compute at billions of hashes/second —
+     *   leaked hashes can be brute-forced rapidly against any wordlist.
+     *   Additionally trims leading/trailing whitespace from both `value`
+     *   and `salt`, so inputs differing only in whitespace collide.
+     *
+     *   For password hashing, use {@link createForPassword} +
+     *   {@link verifyPassword} instead.
+     */
     public static createUsingSalt(value: string, salt: string): string
     {
         given(value, "value").ensureHasValue().ensureIsString();
@@ -43,4 +53,59 @@ export class Hash
 
         return Hash.create(saltedValue);
     }
+
+    /**
+     * Derives a 64-byte hash from `password` and `salt` using scrypt with
+     * parameters N=2^15, r=8, p=1 (RFC 7914 recommended defaults). Suitable
+     * for password storage: slow and memory-hard, so leaked hashes resist
+     * GPU brute-force attacks far better than a plain SHA-512.
+     *
+     * Inputs are NOT trimmed — the exact bytes of `password` and `salt` are
+     * hashed. Two passwords differing only in whitespace produce different
+     * outputs.
+     *
+     * @param password - The password to hash. Hashed as UTF-8.
+     * @param salt - A per-user random value (recommended: ≥16 random bytes,
+     *   e.g. `randomBytes(16).toString("hex")`). Must be stored alongside
+     *   the hash so the same value can be passed on verification.
+     * @returns A 128-character uppercase hex string (64 bytes).
+     */
+    public static createForPassword(password: string, salt: string): string
+    {
+        given(password, "password").ensureHasValue().ensureIsString();
+        given(salt, "salt").ensureHasValue().ensureIsString();
+
+        const derived = scryptSync(password, salt, 64, {
+            N: 1 << 15,
+            r: 8,
+            p: 1,
+            maxmem: 64 * 1024 * 1024
+        });
+        return derived.toString("hex").toUpperCase();
+    }
+
+    /**
+     * Verifies a password against a hash previously produced by
+     * {@link createForPassword}. The comparison is constant-time, so
+     * timing cannot be used to learn how many leading bytes matched.
+     *
+     * @param password - The candidate password to verify. Hashed as UTF-8.
+     * @param salt - The same salt that was passed to
+     *   {@link createForPassword} when the stored hash was created.
+     * @param expectedHash - The previously-stored hash (hex string, any case).
+     * @returns `true` if the candidate matches; `false` if it doesn't,
+     *   if `expectedHash` is not valid hex, or if lengths differ.
+     */
+    public static verifyPassword(password: string, salt: string, expectedHash: string): boolean
+    {
+        given(password, "password").ensureHasValue().ensureIsString();
+        given(salt, "salt").ensureHasValue().ensureIsString();
+        given(expectedHash, "expectedHash").ensureHasValue().ensureIsString();
+
+        const computed = Buffer.from(Hash.createForPassword(password, salt), "hex");
+        const expected = Buffer.from(expectedHash, "hex");
+        if (computed.length !== expected.length)
+            return false;
+        return timingSafeEqual(computed, expected);
+    }
 }

package/src/crypto/symmetric-encryption.ts

@@ -9,74 +9,117 @@ export class SymmetricEncryption
     private constructor() { }
 
 
-    public static generateKey(): Promise<string>
+    /**
+     * Generates a cryptographically random 256-bit key suitable for use with
+     * {@link encrypt} and {@link decrypt}.
+     *
+     * @returns A 64-character uppercase hex string (32 bytes) sourced from the
+     *   platform CSPRNG via Node's `crypto.randomBytes`.
+     */
+    public static generateKey(): string
     {
-        return new Promise<string>((resolve, reject) =>
-        {
-            randomBytes(32, (err, buf) =>
-            {
-                if (err)
-                {
-                    reject(err);
-                    return;
-                }
-
-                resolve(buf.toString("hex").toUpperCase());
-            });
-        });
+        return randomBytes(32).toString("hex").toUpperCase();
     }
 
-    public static encrypt(key: string, value: string): Promise<string>
+    /**
+     * Encrypts a UTF-8 string using AES-256-GCM with a fresh random 96-bit IV.
+     *
+     * The result is an authenticated ciphertext: any bit-flip, truncation, or
+     * substitution will cause {@link decrypt} to throw a {@link CryptoException}.
+     *
+     * @param key - A 64-character hex string (32 bytes) as produced by
+     *   {@link generateKey}. Case-insensitive.
+     * @param value - The plaintext to encrypt. Interpreted as UTF-8.
+     * @param aad - Optional Additional Authenticated Data. When supplied, its
+     *   UTF-8 bytes are bound into the auth tag but not stored in the output;
+     *   the exact same `aad` must be passed to {@link decrypt}, otherwise
+     *   decryption will fail. Use this to bind a ciphertext to its context
+     *   (e.g. `` `user:${userId}` ``) so a valid ciphertext from one record
+     *   cannot be substituted into another.
+     * @returns An uppercase hex string in the form `IV.CIPHERTEXT.TAG`, where
+     *   `IV` is 24 hex chars (12 bytes), `TAG` is 32 hex chars (16 bytes), and
+     *   `CIPHERTEXT` is the encrypted payload.
+     * @throws {CryptoException} If `key` is not exactly 64 hex characters.
+     */
+    public static encrypt(key: string, value: string, aad?: string): string
     {
-        return new Promise<string>((resolve, reject) =>
-        {
-            given(key, "key").ensureHasValue().ensureIsString();
-            given(value, "value").ensureHasValue().ensureIsString();
+        given(key, "key").ensureHasValue().ensureIsString();
+        given(value, "value").ensureHasValue().ensureIsString();
+        if (aad != null)
+            given(aad, "aad").ensureIsString();
 
-            key = key.trim();
-            value = value.trim();
+        const keyBuf = SymmetricEncryption._decodeKey(key);
+        const iv = randomBytes(12);
 
-            randomBytes(16, (err, buf) =>
-            {
-                if (err)
-                {
-                    reject(err);
-                    return;
-                }
+        const cipher = createCipheriv("aes-256-gcm", keyBuf, iv);
+        if (aad != null && aad.length > 0)
+            cipher.setAAD(Buffer.from(aad, "utf8"));
+        const ct = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+        const tag = cipher.getAuthTag();
 
-                try 
-                {
-                    const iv = buf;
-                    const cipher = createCipheriv("AES-256-CBC", Buffer.from(key, "hex"), iv);
-                    let encrypted = cipher.update(value, "utf8", "hex");
-                    encrypted += cipher.final("hex");
-                    const cipherText = `${encrypted}.${iv.toString("hex")}`;
-                    resolve(cipherText.toUpperCase());
-                }
-                catch (error)
-                {
-                    reject(error);
-                }
-            });
-        });
+        return [iv.toString("hex"), ct.toString("hex"), tag.toString("hex")]
+            .join(".").toUpperCase();
     }
 
-    public static decrypt(key: string, value: string): string
+    /**
+     * Decrypts a ciphertext produced by {@link encrypt} and returns the
+     * original UTF-8 plaintext. Integrity is verified via the GCM auth tag
+     * before the plaintext is returned — if verification fails, nothing is
+     * returned.
+     *
+     * @param key - The same 64-character hex key that was used to encrypt.
+     *   Case-insensitive.
+     * @param value - The ciphertext string in `IV.CIPHERTEXT.TAG` form as
+     *   produced by {@link encrypt}.
+     * @param aad - The same Additional Authenticated Data that was supplied
+     *   to {@link encrypt}, or omitted if none was supplied. Any mismatch
+     *   (wrong value, supplied here but not at encrypt, or vice versa) will
+     *   cause the auth tag check to fail.
+     * @returns The original plaintext decoded as UTF-8.
+     * @throws {CryptoException} If `key` is not exactly 64 hex characters,
+     *   if `value` is not in the expected `IV.CIPHERTEXT.TAG` format with
+     *   correct component lengths, or if the auth tag verification fails
+     *   (wrong key, tampered ciphertext, or mismatched `aad`).
+     */
+    public static decrypt(key: string, value: string, aad?: string): string
     {
         given(key, "key").ensureHasValue().ensureIsString();
         given(value, "value").ensureHasValue().ensureIsString();
+        if (aad != null)
+            given(aad, "aad").ensureIsString();
+
+        const keyBuf = SymmetricEncryption._decodeKey(key);
 
-        key = key.trim();
-        value = value.trim();
+        const parts = value.split(".");
+        if (parts.length !== 3)
+            throw new CryptoException("Malformed ciphertext.");
 
-        const splitted = value.split(".");
-        if (splitted.length !== 2)
-            throw new CryptoException("Invalid value.");
+        const iv = Buffer.from(parts[0], "hex");
+        const ct = Buffer.from(parts[1], "hex");
+        const tag = Buffer.from(parts[2], "hex");
 
-        const iv = Buffer.from(splitted[1], "hex");
-        const deCipher = createDecipheriv("AES-256-CBC", Buffer.from(key, "hex"), iv);
-        let decrypted = deCipher.update(splitted[0], "hex", "utf8");
-        decrypted += deCipher.final("utf8");
-        return decrypted;
+        if (iv.length !== 12 || ct.length === 0 || tag.length !== 16)
+            throw new CryptoException("Malformed ciphertext.");
+
+        try
+        {
+            const decipher = createDecipheriv("aes-256-gcm", keyBuf, iv);
+            if (aad != null && aad.length > 0)
+                decipher.setAAD(Buffer.from(aad, "utf8"));
+            decipher.setAuthTag(tag);
+            return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+        }
+        catch
+        {
+            throw new CryptoException("Integrity check failed.");
+        }
+    }
+
+    private static _decodeKey(key: string): Buffer
+    {
+        const buf = Buffer.from(key, "hex");
+        if (buf.length !== 32 || buf.toString("hex").toUpperCase() !== key.toUpperCase())
+            throw new CryptoException("Key must be 64 hex characters (32 bytes).");
+        return buf;
     }
-}
+}

package/test/hash.test.ts

@@ -164,6 +164,95 @@ await describe("Hash", async () =>
 
             Hash.createUsingSalt(password, salt);
         });
+    });
+
+    await describe("createForPassword", async () =>
+    {
+        await test("must return a 128-character uppercase hex string", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            assert.match(hash, /^[0-9A-F]{128}$/);
+        });
+
+        await test("same password and salt must produce the same output", () =>
+        {
+            const hash1 = Hash.createForPassword("password", "some-salt");
+            const hash2 = Hash.createForPassword("password", "some-salt");
+            assert.strictEqual(hash1, hash2);
+        });
+
+        await test("different passwords with the same salt must produce different outputs", () =>
+        {
+            const hash1 = Hash.createForPassword("password1", "some-salt");
+            const hash2 = Hash.createForPassword("password2", "some-salt");
+            assert.notStrictEqual(hash1, hash2);
+        });
+
+        await test("same password with different salts must produce different outputs", () =>
+        {
+            const hash1 = Hash.createForPassword("password", "salt-1");
+            const hash2 = Hash.createForPassword("password", "salt-2");
+            assert.notStrictEqual(hash1, hash2);
+        });
+
+        await test("passwords differing only in trailing whitespace must produce different outputs", () =>
+        {
+            const hash1 = Hash.createForPassword("password", "some-salt");
+            const hash2 = Hash.createForPassword("password ", "some-salt");
+            assert.notStrictEqual(hash1, hash2);
+        });
+
+        await test("passwords differing only in leading whitespace must produce different outputs", () =>
+        {
+            const hash1 = Hash.createForPassword("password", "some-salt");
+            const hash2 = Hash.createForPassword(" password", "some-salt");
+            assert.notStrictEqual(hash1, hash2);
+        });
+    });
+
+    await describe("verifyPassword", async () =>
+    {
+        await test("must return true for the same password and salt that produced the hash", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            assert.strictEqual(Hash.verifyPassword("password", "some-salt", hash), true);
+        });
+
+        await test("must accept the hash in lowercase as well as uppercase", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            assert.strictEqual(Hash.verifyPassword("password", "some-salt", hash.toLowerCase()), true);
+        });
+
+        await test("must return false for a wrong password", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            assert.strictEqual(Hash.verifyPassword("wrong-password", "some-salt", hash), false);
+        });
+
+        await test("must return false for a wrong salt", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            assert.strictEqual(Hash.verifyPassword("password", "different-salt", hash), false);
+        });
+
+        await test("must return false for a tampered hash", () =>
+        {
+            const hash = Hash.createForPassword("password", "some-salt");
+            // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
+            const tampered = (hash[0] === "A" ? "B" : "A") + hash.slice(1);
+            assert.strictEqual(Hash.verifyPassword("password", "some-salt", tampered), false);
+        });
+
+        await test("must return false for a hash of the wrong length", () =>
+        {
+            assert.strictEqual(Hash.verifyPassword("password", "some-salt", "ABCD"), false);
+        });
+
+        await test("must return false for a non-hex hash", () =>
+        {
+            assert.strictEqual(Hash.verifyPassword("password", "some-salt", "Z".repeat(128)), false);
+        });
 
 
 

package/test/hmac.test.ts

@@ -8,9 +8,9 @@ await describe("Hmac", async () =>
 {
     await describe("create", async () =>
     {
-        await test("should return string value that is not null, empty, whitespace or same as the key or input", async () =>
+        await test("should return string value that is not null, empty, whitespace or same as the key or input", () =>
         {
-            const key = await SymmetricEncryption.generateKey();
+            const key = SymmetricEncryption.generateKey();
             const value = "hello world";
             const hmac = Hmac.create(key, value);
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -19,30 +19,30 @@ await describe("Hmac", async () =>
             assert.notStrictEqual(hmac, value);
         });
 
-        await test("multiple invocations with the same key and value must return the same output", async () =>
+        await test("multiple invocations with the same key and value must return the same output", () =>
         {
-            const key = await SymmetricEncryption.generateKey();
+            const key = SymmetricEncryption.generateKey();
             const value = "hello world";
             const hmac1 = Hmac.create(key, value);
             const hmac2 = Hmac.create(key, value);
             assert.strictEqual(hmac1, hmac2);
         });
 
-        await test("multiple invocations with different keys and different values must return different outputs", async () =>
+        await test("multiple invocations with different keys and different values must return different outputs", () =>
         {
-            const key1 = await SymmetricEncryption.generateKey();
+            const key1 = SymmetricEncryption.generateKey();
             const value1 = "hello world";
             const hmac1 = Hmac.create(key1, value1);
 
-            const key2 = await SymmetricEncryption.generateKey();
+            const key2 = SymmetricEncryption.generateKey();
             const value2 = "goodbye world";
             const hmac2 = Hmac.create(key2, value2);
             assert.notStrictEqual(hmac1, hmac2);
         });
 
-        await test("multiple invocations with the same key and different values must return different outputs", async () =>
+        await test("multiple invocations with the same key and different values must return different outputs", () =>
         {
-            const key = await SymmetricEncryption.generateKey();
+            const key = SymmetricEncryption.generateKey();
             const value1 = "hello world";
             const value2 = "goodbye world";
             const hmac1 = Hmac.create(key, value1);
@@ -50,10 +50,10 @@ await describe("Hmac", async () =>
             assert.notStrictEqual(hmac1, hmac2);
         });
 
-        await test("multiple invocations with different keys and the same value must return different outputs", async () =>
+        await test("multiple invocations with different keys and the same value must return different outputs", () =>
         {
-            const key1 = await SymmetricEncryption.generateKey();
-            const key2 = await SymmetricEncryption.generateKey();
+            const key1 = SymmetricEncryption.generateKey();
+            const key2 = SymmetricEncryption.generateKey();
             const value = "hello world";
             const hmac1 = Hmac.create(key1, value);
             const hmac2 = Hmac.create(key2, value);