feat (cipher-kit):hashObj added, injected secret key, more tests

WolfieLeader · WolfieLeader · commit 52b5d293a768 · 2025-09-25T21:55:00.000+03:00
diff --git a/packages/cipher-kit/package.json b/packages/cipher-kit/package.json
@@ -1,6 +1,6 @@
 {
   "name": "cipher-kit",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.3",
   "description": "🔐 Secure, Lightweight, and Cross-Platform Encryption, Decryption, and Hashing for Web, Node.js, Deno, Bun, and Cloudflare Workers",
   "homepage": "https://github.com/WolfieLeader/npm/tree/main/packages/cipher-kit#readme",
   "repository": {
diff --git a/packages/cipher-kit/src/__tests__/encrypt.test.ts b/packages/cipher-kit/src/__tests__/encrypt.test.ts
@@ -5,7 +5,7 @@ const secret = 'Secret0123456789Secret0123456789';
 const data = '🦊 secret stuff ~ !@#$%^&*()_+';
 
 describe('Encryption', () => {
-  test('Encrypt Data', async () => {
+  test('Encrypt Data Default', async () => {
     // biome-ignore lint/style/useConst: ignore
     let nodeSecretKey: SecretKey<'node'>;
     const nodeKey = nodeKit.tryCreateSecretKey(secret);
@@ -74,6 +74,89 @@ describe('Encryption', () => {
     expect(decryptedObjWeb.success).toBe(true);
     expect(decryptedObjWeb.result).toEqual(largeObj);
   });
+
+  test('Encrypt Data AES128GCM', async () => {
+    // biome-ignore lint/style/useConst: ignore
+    let nodeSecretKey: SecretKey<'node'>;
+    const nodeKey = nodeKit.tryCreateSecretKey(secret, { algorithm: 'aes128gcm' });
+    expect(nodeKey.success).toBe(true);
+    expect(nodeKey.result).toBeDefined();
+    expect(isSecretKey(nodeKey.result, 'node')).toBe(true);
+    nodeSecretKey = nodeKey.result as SecretKey<'node'>;
+
+    // biome-ignore lint/style/useConst: ignore
+    let webSecretKey: SecretKey<'web'>;
+    const webKey = await webKit.tryCreateSecretKey(secret, { algorithm: 'aes128gcm' });
+    expect(webKey.success).toBe(true);
+    expect(webKey.result).toBeDefined();
+    expect(isSecretKey(webKey.result, 'web')).toBe(true);
+    webSecretKey = webKey.result as SecretKey<'web'>;
+
+    const encryptedNode = nodeKit.tryEncrypt(data, nodeSecretKey, { outputEncoding: 'hex' });
+    expect(encryptedNode.success).toBe(true);
+    expect(encryptedNode.result).toBeDefined();
+    expect(matchPattern(encryptedNode.result as string, 'node')).toBe(true);
+
+    const encryptedWeb = await webKit.tryEncrypt(data, webSecretKey, { outputEncoding: 'hex' });
+    expect(encryptedWeb.success).toBe(true);
+    expect(encryptedWeb.result).toBeDefined();
+    expect(matchPattern(encryptedWeb.result as string, 'web')).toBe(true);
+
+    expect(encryptedNode.result).not.toBe(encryptedWeb.result);
+
+    const decryptedNode = nodeKit.tryDecrypt(encryptedNode.result as string, nodeSecretKey, { inputEncoding: 'hex' });
+    expect(decryptedNode.success).toBe(true);
+    expect(decryptedNode.result).toBe(data);
+
+    const decryptedWeb = await webKit.tryDecrypt(encryptedWeb.result as string, webSecretKey, { inputEncoding: 'hex' });
+    expect(decryptedWeb.success).toBe(true);
+    expect(decryptedWeb.result).toBe(data);
+
+    expect(decryptedNode.result).toBe(decryptedWeb.result);
+
+    const encryptedNode2 = nodeKit.tryEncrypt(data, nodeSecretKey, { outputEncoding: 'hex' });
+    expect(encryptedNode2.success).toBe(true);
+    expect(encryptedNode2.result).toBeDefined();
+    expect(encryptedNode2.result).not.toBe(encryptedNode.result);
+
+    const encryptedWeb2 = await webKit.tryEncrypt(data, webSecretKey, { outputEncoding: 'hex' });
+    expect(encryptedWeb2.success).toBe(true);
+    expect(encryptedWeb2.result).toBeDefined();
+    expect(encryptedWeb2.result).not.toBe(encryptedWeb.result);
+
+    const encryptedObjNode = nodeKit.tryEncryptObj(largeObj, nodeSecretKey, { outputEncoding: 'base64' });
+    expect(encryptedObjNode.success).toBe(true);
+    expect(encryptedObjNode.result).toBeDefined();
+    expect(matchPattern(encryptedObjNode.result as string, 'node')).toBe(true);
+
+    const encryptedObjWeb = await webKit.tryEncryptObj(largeObj, webSecretKey, { outputEncoding: 'base64' });
+    expect(encryptedObjWeb.success).toBe(true);
+    expect(encryptedObjWeb.result).toBeDefined();
+    expect(matchPattern(encryptedObjWeb.result as string, 'web')).toBe(true);
+
+    expect(encryptedObjNode.result).not.toBe(encryptedObjWeb.result);
+
+    const decryptedObjNode = nodeKit.tryDecryptObj<typeof largeObj>(encryptedObjNode.result as string, nodeSecretKey, {
+      inputEncoding: 'base64',
+    });
+    expect(decryptedObjNode.success).toBe(true);
+    expect(decryptedObjNode.result).toEqual(largeObj);
+
+    const decryptedObjWeb = await webKit.tryDecryptObj<typeof largeObj>(
+      encryptedObjWeb.result as string,
+      webSecretKey,
+      { inputEncoding: 'base64' },
+    );
+    expect(decryptedObjWeb.success).toBe(true);
+    expect(decryptedObjWeb.result).toEqual(largeObj);
+  });
+
+  test('Encoding Test', () => {
+    expect(nodeKit.convertEncoding(data, 'utf8', 'base64')).toBe(webKit.convertEncoding(data, 'utf8', 'base64'));
+    expect(nodeKit.convertEncoding(data, 'utf8', 'hex')).toBe(webKit.convertEncoding(data, 'utf8', 'hex'));
+    expect(nodeKit.convertEncoding(data, 'utf8', 'base64url')).toBe(webKit.convertEncoding(data, 'utf8', 'base64url'));
+    expect(nodeKit.convertEncoding(data, 'utf8', 'latin1')).toBe(webKit.convertEncoding(data, 'utf8', 'latin1'));
+  });
 });
 
 const largeObj = {
diff --git a/packages/cipher-kit/src/helpers/consts.ts b/packages/cipher-kit/src/helpers/consts.ts
@@ -7,7 +7,7 @@ export const DIGEST_ALGORITHMS = Object.freeze({
 } as const);
 
 export const ENCRYPTION_ALGORITHMS = Object.freeze({
-  aes256gcm: { name: 'aes256gcm', keyBytes: 32, ivLength: 12, node: 'aes-256-gcm', web: 'AES-GCM' },
-  aes192gcm: { name: 'aes192gcm', keyBytes: 24, ivLength: 12, node: 'aes-192-gcm', web: 'AES-GCM' },
-  aes128gcm: { name: 'aes128gcm', keyBytes: 16, ivLength: 12, node: 'aes-128-gcm', web: 'AES-GCM' },
+  aes256gcm: { keyBytes: 32, ivLength: 12, node: 'aes-256-gcm', web: 'AES-GCM' },
+  aes192gcm: { keyBytes: 24, ivLength: 12, node: 'aes-192-gcm', web: 'AES-GCM' },
+  aes128gcm: { keyBytes: 16, ivLength: 12, node: 'aes-128-gcm', web: 'AES-GCM' },
 } as const);
diff --git a/packages/cipher-kit/src/helpers/types.ts b/packages/cipher-kit/src/helpers/types.ts
@@ -9,10 +9,12 @@ type Brand<T> = { readonly [__brand]: T };
 export type SecretKey<Platform extends 'web' | 'node'> = {
   readonly platform: Platform;
   readonly digest: keyof typeof DIGEST_ALGORITHMS;
-  readonly algo: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];
+  readonly algorithm: keyof typeof ENCRYPTION_ALGORITHMS;
   readonly key: Platform extends 'web' ? webcrypto.CryptoKey : nodeCrypto.KeyObject;
 } & Brand<`secretKey-${Platform}`>;
 
+export type CipherEncoding = Exclude<Encoding, 'utf8' | 'latin1'>;
+
 /** Supported encoding formats */
 export type Encoding = (typeof ENCODINGS)[number];
 
@@ -31,31 +33,31 @@ export interface CreateSecretKeyOptions {
 
 export interface EncryptOptions {
   inputEncoding?: Encoding;
-  outputEncoding?: Encoding;
+  outputEncoding?: CipherEncoding;
 }
 
 export interface DecryptOptions {
-  inputEncoding?: Encoding;
+  inputEncoding?: CipherEncoding;
   outputEncoding?: Encoding;
 }
 
 export interface HashOptions {
   digest?: DigestAlgorithm;
   inputEncoding?: Encoding;
-  outputEncoding?: Encoding;
+  outputEncoding?: CipherEncoding;
 }
 
 export interface HashPasswordOptions {
   digest?: DigestAlgorithm;
-  outputEncoding?: Encoding;
+  outputEncoding?: CipherEncoding;
   saltLength?: number;
   iterations?: number;
   keyLength?: number;
 }
 
 export interface VerifyPasswordOptions {
   digest?: DigestAlgorithm;
-  inputEncoding?: Encoding;
+  inputEncoding?: CipherEncoding;
   iterations?: number;
   keyLength?: number;
 }
diff --git a/packages/cipher-kit/src/helpers/validate.ts b/packages/cipher-kit/src/helpers/validate.ts
@@ -1,5 +1,5 @@
 import nodeCrypto from 'node:crypto';
-import type { EncryptionAlgorithm, SecretKey } from '~/helpers/types';
+import type { SecretKey } from '~/helpers/types';
 import { DIGEST_ALGORITHMS, ENCRYPTION_ALGORITHMS } from './consts';
 
 export function $isStr(x: unknown, min = 1): x is string {
@@ -16,66 +16,69 @@ export function $isLooseObj(x: unknown): x is Record<string, unknown> {
   return typeof x === 'object' && x !== null && x !== undefined;
 }
 
-const expectedKeys = new Set(['platform', 'digest', 'algo', 'key']);
-const expectedAlgoKeys = new Set(['name', 'keyBytes', 'ivLength', 'node', 'web']);
+type InjectedSecretKey<Platform extends 'web' | 'node'> = SecretKey<Platform> & {
+  readonly injected: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];
+};
 
-export function isSecretKey<Platform extends 'node' | 'web'>(x: unknown, platform: Platform): x is SecretKey<Platform> {
-  if (!$isLooseObj(x) || (platform !== 'node' && platform !== 'web') || x.platform !== platform) return false;
-
-  const keys = Object.keys(x);
-  if (keys.length !== expectedKeys.size) return false;
-  for (const key of keys) if (!expectedKeys.has(key)) return false;
-  for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return false;
+const expectedKeys = new Set(['platform', 'digest', 'algorithm', 'key']);
 
-  if (typeof x.digest !== 'string' || !(x.digest in DIGEST_ALGORITHMS)) return false;
-  if (!$isLooseObj(x.algo) || typeof x.algo.name !== 'string' || !(x.algo.name in ENCRYPTION_ALGORITHMS)) return false;
+export function $isSecretKey<Platform extends 'node' | 'web'>(
+  x: unknown,
+  platform: Platform,
+): InjectedSecretKey<Platform> | null {
+  if (!$isLooseObj(x) || (platform !== 'node' && platform !== 'web') || x.platform !== platform) return null;
 
-  const algoKeys = Object.keys(x.algo);
-  if (algoKeys.length !== expectedAlgoKeys.size) return false;
-  for (const key of algoKeys) if (!expectedAlgoKeys.has(key)) return false;
-  for (const key of expectedAlgoKeys) if (!Object.hasOwn(x.algo, key)) return false;
+  const keys = Object.keys(x);
+  if (keys.length !== expectedKeys.size) return null;
+  for (const key of keys) if (!expectedKeys.has(key)) return null;
+  for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return null;
 
-  const algo = ENCRYPTION_ALGORITHMS[x.algo.name as EncryptionAlgorithm];
   if (
-    x.algo.keyBytes !== algo.keyBytes ||
-    x.algo.ivLength !== algo.ivLength ||
-    x.algo.node !== algo.node ||
-    x.algo.web !== algo.web
+    typeof x.digest !== 'string' ||
+    !(x.digest in DIGEST_ALGORITHMS) ||
+    typeof x.algorithm !== 'string' ||
+    !(x.algorithm in ENCRYPTION_ALGORITHMS) ||
+    !$isLooseObj(x.key) ||
+    x.key.type !== 'secret'
   ) {
-    return false;
+    return null;
   }
 
-  if (!$isLooseObj(x.key) || x.key.type !== 'secret') return false;
+  const algorithm = ENCRYPTION_ALGORITHMS[x.algorithm as keyof typeof ENCRYPTION_ALGORITHMS];
 
   if (platform === 'node') {
     if (
       !(x.key instanceof nodeCrypto.KeyObject) ||
-      (typeof x.key.symmetricKeySize === 'number' && x.key.symmetricKeySize !== algo.keyBytes)
+      (typeof x.key.symmetricKeySize === 'number' && x.key.symmetricKeySize !== algorithm.keyBytes)
     ) {
-      return false;
+      return null;
     }
-    return true;
+    return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;
   }
 
   if (
     !$isLooseObj(x.key.algorithm) ||
-    x.key.algorithm.name !== algo.web ||
-    (typeof x.key.algorithm.length === 'number' && x.key.algorithm.length !== algo.keyBytes * 8) ||
+    x.key.algorithm.name !== algorithm.web ||
+    (typeof x.key.algorithm.length === 'number' && x.key.algorithm.length !== algorithm.keyBytes * 8) ||
     typeof x.key.extractable !== 'boolean' ||
     !Array.isArray(x.key.usages) ||
     x.key.usages.length !== 2 ||
     !(x.key.usages.includes('encrypt') && x.key.usages.includes('decrypt'))
   ) {
-    return false;
+    return null;
   }
-  return true;
+  return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;
+}
+
+export function isSecretKey<Platform extends 'node' | 'web'>(x: unknown, platform: Platform): x is SecretKey<Platform> {
+  return $isSecretKey(x, platform) !== null;
 }
 
 /** Regular expressions for encrypted data patterns */
 export const ENCRYPTED_REGEX = Object.freeze({
-  general: /^(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?\.)$/,
-  node: /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.$/,
-  web: /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.$/,
+  node: /^([^.]+)\.([^.]+)\.([^.]+)\.$/,
+  web: /^([^.]+)\.([^.]+)\.$/,
+  general: /^([^.]+)\.([^.]+)(?:\.([^.]+))?\.$/,
 });
 
 /** Checks if the input string matches the specified encrypted data pattern. */
diff --git a/packages/cipher-kit/src/node/kit.ts b/packages/cipher-kit/src/node/kit.ts
@@ -19,6 +19,7 @@ import {
   $encryptObj,
   $generateUuid,
   $hash,
+  $hashObj,
   $hashPassword,
   $verifyPassword,
 } from './node-encrypt';
@@ -227,6 +228,34 @@ export function hash(data: string, options: HashOptions = {}): string {
   return result;
 }
 
+/**
+ * Hashes the input object by first serializing it to a JSON string using stable key ordering,
+ * then hashing the string using SHA-256 and returning the hash in base64url format.
+ *
+ * @param data - The input object to hash.
+ * @returns A Result containing a string representing the SHA-256 hash of the serialized object in base64url format or an error.
+ * */
+export function tryHashObj<T extends object = Record<string, unknown>>(
+  data: T,
+  options: HashOptions = {},
+): Result<string> {
+  return $hashObj(data, options);
+}
+
+/**
+ * Hashes the input object by first serializing it to a JSON string using stable key ordering,
+ * then hashing the string using SHA-256 and returning the hash in base64url format.
+ *
+ * @param data - The input object to hash.
+ * @returns A string representing the SHA-256 hash of the serialized object in base64url format.
+ * @throws {Error} If the input data is invalid or hashing fails.
+ */
+export function hashObj<T extends object = Record<string, unknown>>(data: T, options: HashOptions = {}): string {
+  const { result, error } = $hashObj(data, options);
+  if (error) throw new Error($fmtResultErr(error));
+  return result;
+}
+
 /**
  * Hashes a password using PBKDF2 with SHA-512.
  *
diff --git a/packages/cipher-kit/src/node/node-encrypt.ts b/packages/cipher-kit/src/node/node-encrypt.ts
@@ -12,7 +12,7 @@ import type {
   SecretKey,
   VerifyPasswordOptions,
 } from '~/helpers/types';
-import { $isStr, isSecretKey, matchPattern } from '~/helpers/validate';
+import { $isSecretKey, $isStr, matchPattern } from '~/helpers/validate';
 import { $convertBytesToStr, $convertStrToBytes } from './node-encode';
 
 export function $generateUuid(): Result<string> {
@@ -78,7 +78,7 @@ export function $createSecretKey(
     const secretKey = Object.freeze({
       platform: 'node',
       digest: digest,
-      algo: encryptAlgo,
+      algorithm: algorithm,
       key: key,
     }) as SecretKey<'node'>;
 
@@ -105,7 +105,8 @@ export function $encrypt(data: string, secretKey: SecretKey<'node'>, options: En
     });
   }
 
-  if (!isSecretKey(secretKey, 'node')) {
+  const injectedKey = $isSecretKey(secretKey, 'node');
+  if (!injectedKey) {
     return $err({
       msg: 'Crypto NodeJS API - Encryption: Invalid Secret Key',
       desc: 'Expected a Node SecretKey',
@@ -116,8 +117,8 @@ export function $encrypt(data: string, secretKey: SecretKey<'node'>, options: En
   if (error) return $err(error);
 
   try {
-    const iv = nodeCrypto.randomBytes(secretKey.algo.ivLength);
-    const cipher = nodeCrypto.createCipheriv(secretKey.algo.node, secretKey.key, iv);
+    const iv = nodeCrypto.randomBytes(injectedKey.injected.ivLength);
+    const cipher = nodeCrypto.createCipheriv(injectedKey.injected.node, injectedKey.key, iv);
     const encrypted = Buffer.concat([cipher.update(result), cipher.final()]);
     const tag = cipher.getAuthTag();
 
@@ -167,7 +168,8 @@ export function $decrypt(
     });
   }
 
-  if (!isSecretKey(secretKey, 'node')) {
+  const injectedKey = $isSecretKey(secretKey, 'node');
+  if (!injectedKey) {
     return $err({
       msg: 'Crypto NodeJS API - Decryption: Invalid Secret Key',
       desc: 'Expected a Node SecretKey',
@@ -186,7 +188,7 @@ export function $decrypt(
   }
 
   try {
-    const decipher = nodeCrypto.createDecipheriv(secretKey.algo.node, secretKey.key, ivBytes.result);
+    const decipher = nodeCrypto.createDecipheriv(injectedKey.injected.node, injectedKey.key, ivBytes.result);
     decipher.setAuthTag(tagBytes.result);
     const decrypted = Buffer.concat([decipher.update(cipherBytes.result), decipher.final()]);
 
@@ -252,6 +254,15 @@ export function $hash(data: string, options: HashOptions = {}): Result<string> {
   }
 }
 
+export function $hashObj<T extends object = Record<string, unknown>>(
+  data: T,
+  options: HashOptions = {},
+): Result<string> {
+  const { result, error } = $stringifyObj(data);
+  if (error) return $err(error);
+  return $hash(result, options);
+}
+
 export function $hashPassword(
   password: string,
   options: HashPasswordOptions = {},
diff --git a/packages/cipher-kit/src/web/kit.ts b/packages/cipher-kit/src/web/kit.ts
diff --git a/packages/cipher-kit/src/web/web-encrypt.ts b/packages/cipher-kit/src/web/web-encrypt.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "cipher-kit",`
`3`		`- "version": "2.0.0-beta.2",`
	`3`	`+ "version": "2.0.0-beta.3",`
`4`	`4`	`"description": "🔐 Secure, Lightweight, and Cross-Platform Encryption, Decryption, and Hashing for Web, Node.js, Deno, Bun, and Cloudflare Workers",`
`5`	`5`	`"homepage": "https://github.com/WolfieLeader/npm/tree/main/packages/cipher-kit#readme",`
`6`	`6`	`"repository": {`