feat: Add sync versions of various operations for Node.js

Also refactor key and message parsing to use regexes.

Author: franky47

src/ciphers/aes-gcm.ts

@@ -18,26 +18,11 @@ export async function encryptAesGcm(
   key: CryptoKey | Uint8Array,
   message: string
 ): Promise<AesCipher> {
-  const buf = utf8.encode(message)
   if (typeof window === 'undefined') {
-    // Node.js - Use native crypto module
-    const iv = nodeCrypto.randomBytes(12)
-    const cipher = nodeCrypto.createCipheriv(
-      'aes-256-gcm',
-      key as Uint8Array,
-      iv
-    )
-    const encrypted = cipher.update(message, 'utf8')
-    cipher.final()
-    const tag = cipher.getAuthTag()
-    return {
-      // Authentication tag is the last 16 bytes
-      // (for compatibility with WebCrypto serialization)
-      text: new Uint8Array(Buffer.concat([encrypted, tag])),
-      iv
-    }
+    return encryptAesGcmSync(key as Uint8Array, message)
   } else {
     // Browser - use WebCrypto
+    const buf = utf8.encode(message)
     const iv = window.crypto.getRandomValues(new Uint8Array(12))
     const cipherText = await window.crypto.subtle.encrypt(
       {
@@ -54,24 +39,32 @@ export async function encryptAesGcm(
   }
 }
 
+/**
+ * Available only for Node.js
+ */
+export function encryptAesGcmSync(key: Uint8Array, message: string): AesCipher {
+  // Node.js - Use native crypto module
+  const iv = nodeCrypto.randomBytes(12)
+  const cipher = nodeCrypto.createCipheriv('aes-256-gcm', key, iv)
+  const encrypted = cipher.update(message, 'utf8')
+  cipher.final()
+  const tag = cipher.getAuthTag()
+  return {
+    // Authentication tag is the last 16 bytes
+    // (for compatibility with WebCrypto serialization)
+    text: new Uint8Array(Buffer.concat([encrypted, tag])),
+    iv
+  }
+}
+
+// --
+
 export async function decryptAesGcm(
   key: CryptoKey | Uint8Array,
   cipher: AesCipher
 ): Promise<string> {
   if (typeof window === 'undefined') {
-    // Node.js - Use native crypto module
-    const decipher = nodeCrypto.createDecipheriv(
-      'aes-256-gcm',
-      key as Uint8Array,
-      cipher.iv
-    )
-    // Authentication tag is the last 16 bytes
-    // (for compatibility with WebCrypto serialization)
-    const tagStart = cipher.text.length - 16
-    const msg = cipher.text.slice(0, tagStart)
-    const tag = cipher.text.slice(tagStart)
-    decipher.setAuthTag(tag)
-    return decipher.update(msg, undefined, 'utf8') + decipher.final('utf8')
+    return decryptAesGcmSync(key as Uint8Array, cipher)
   } else {
     // Browser - use WebCrypto
     const buf = await window.crypto.subtle.decrypt(
@@ -85,3 +78,22 @@ export async function decryptAesGcm(
     return utf8.decode(new Uint8Array(buf))
   }
 }
+
+/**
+ * Available only for Node.js.
+ *
+ * @param key
+ * @param cipher
+ * @returns
+ */
+export function decryptAesGcmSync(key: Uint8Array, cipher: AesCipher): string {
+  // Node.js - Use native crypto module
+  const decipher = nodeCrypto.createDecipheriv('aes-256-gcm', key, cipher.iv)
+  // Authentication tag is the last 16 bytes
+  // (for compatibility with WebCrypto serialization)
+  const tagStart = cipher.text.length - 16
+  const msg = cipher.text.slice(0, tagStart)
+  const tag = cipher.text.slice(tagStart)
+  decipher.setAuthTag(tag)
+  return decipher.update(msg, undefined, 'utf8') + decipher.final('utf8')
+}

src/index.test.ts

@@ -1,10 +1,10 @@
 import 'jest-extended'
 import {
-  generateKey,
-  encryptString,
   decryptString,
-  makeKeychain,
+  encryptString,
   findKeyForMessage,
+  generateKey,
+  makeKeychain,
   parseKey
 } from './index'
 
@@ -31,6 +31,15 @@ describe('v1 format', () => {
     expect(received).toEqual(expected)
   })
 
+  test('Decrypt known message (empty string)', async () => {
+    const key = 'k1.aesgcm256.2itF7YmMYIP4b9NNtKMhIx2axGi6aI50RcwGBiFq-VA='
+    const cipher =
+      'v1.aesgcm256.710bb0e2.9tZkprVBt4L7ZW_U.GDrlM3U_P0UnHf38HvOCgQ=='
+    const expected = ''
+    const received = await decryptString(cipher, key)
+    expect(received).toEqual(expected)
+  })
+
   test('Decrypt known message', async () => {
     const key = 'k1.aesgcm256.2itF7YmMYIP4b9NNtKMhIx2axGi6aI50RcwGBiFq-VA='
     const cipher =

src/index.ts

@@ -1,10 +1,12 @@
 export {
-  generateKey,
+  CloakKey,
+  cloakKeyRegex,
   exportCryptoKey,
+  generateKey,
+  ParsedCloakKey,
   parseKey,
-  serializeKey,
-  CloakKey,
-  ParsedCloakKey
+  parseKeySync,
+  serializeKey
 } from './key'
 export * from './keychain'
 export * from './message'

src/key.ts

@@ -1,4 +1,4 @@
-import { utf8, b64, hex } from '@47ng/codec'
+import { b64, hex, utf8 } from '@47ng/codec'
 import * as NodeCrypto from 'crypto'
 
 let nodeCrypto: typeof NodeCrypto
@@ -9,6 +9,8 @@ if (typeof window === 'undefined') {
 
 export const FINGERPRINT_LENGTH = 8
 
+export const cloakKeyRegex = /^k1\.aesgcm256\.(?<key>[a-zA-Z0-9-_]{43}=?)$/
+
 /**
  * Serialized representation of a Cloak key.
  *
@@ -30,13 +32,26 @@ export function formatKey(raw: Uint8Array) {
   return ['k1', 'aesgcm256', b64.encode(raw)].join('.')
 }
 
-export async function parseKey(key: CloakKey): Promise<ParsedCloakKey> {
+export async function parseKey(
+  key: CloakKey,
+  usage?: 'encrypt' | 'decrypt'
+): Promise<ParsedCloakKey> {
   return {
-    raw: await importKey(key),
+    raw: await importKey(key, usage),
     fingerprint: await getKeyFingerprint(key)
   }
 }
 
+/**
+ * Sync version of parseKey, only available for Node.js
+ */
+export function parseKeySync(key: CloakKey): ParsedCloakKey {
+  return {
+    raw: importKeySync(key),
+    fingerprint: getKeyFingerprintSync(key)
+  }
+}
+
 export async function serializeKey(key: ParsedCloakKey): Promise<CloakKey> {
   return (key.raw as CryptoKey).algorithm
     ? await exportCryptoKey(key.raw as CryptoKey)
@@ -88,14 +103,11 @@ export async function importKey(
   key: CloakKey,
   usage?: 'encrypt' | 'decrypt'
 ): Promise<CryptoKey | Uint8Array> {
-  if (!key.startsWith('k1.')) {
+  const match = key.match(cloakKeyRegex)
+  if (!match) {
     throw new Error('Unknown key format')
   }
-  const [_, algorithm, secret] = key.split('.')
-  if (algorithm !== 'aesgcm256') {
-    throw new Error('Unsupported key type')
-  }
-  const raw = b64.decode(secret)
+  const raw = b64.decode(match.groups!.key)
   if (typeof window === 'undefined') {
     // Node.js
     return raw
@@ -114,6 +126,21 @@ export async function importKey(
   }
 }
 
+/**
+ * Internal method: de-serialize a Cloak key into an Uint8Array.
+ *
+ * Available only on Node.js
+ *
+ * @param key - Serialized Cloak key
+ */
+export function importKeySync(key: CloakKey): Uint8Array {
+  const match = key.match(cloakKeyRegex)
+  if (!match) {
+    throw new Error('Unknown key format')
+  }
+  return b64.decode(match.groups!.key)
+}
+
 /**
  * Internal method: calculate a key fingerprint
  * Fingerprint is the first 8 bytes of the SHA-256 of the
@@ -132,3 +159,15 @@ export async function getKeyFingerprint(key: CloakKey): Promise<string> {
     return hex.encode(new Uint8Array(hash)).slice(0, FINGERPRINT_LENGTH)
   }
 }
+
+/**
+ * Internal method: calculate a key fingerprint
+ * Fingerprint is the first 8 bytes of the SHA-256 of the
+ * serialized key text, represented as an hexadecimal string.
+ */
+export function getKeyFingerprintSync(key: CloakKey): string {
+  const data = utf8.encode(key)
+  const hash = nodeCrypto.createHash('sha256')
+  hash.update(data)
+  return hash.digest('hex').slice(0, FINGERPRINT_LENGTH)
+}

src/keychain.ts

@@ -1,8 +1,17 @@
-import { CloakKey, ParsedCloakKey, parseKey, serializeKey } from './key'
+import {
+  CloakKey,
+  formatKey,
+  ParsedCloakKey,
+  parseKey,
+  parseKeySync,
+  serializeKey
+} from './key'
 import {
   CloakedString,
   decryptString,
+  decryptStringSync,
   encryptString,
+  encryptStringSync,
   getMessageKeyFingerprint
 } from './message'
 
@@ -20,6 +29,13 @@ export type CloakKeychain = {
   [fingerprint: string]: KeychainEntry
 }
 
+/**
+ * Create a keychain holding the given list of keys.
+ *
+ * Runs everywhere (Node.js & browser).
+ *
+ * @param keys a list of keys to include in the keychain
+ */
 export async function makeKeychain(keys: CloakKey[]): Promise<CloakKeychain> {
   const keychain: CloakKeychain = {}
   for (const key of keys) {
@@ -33,7 +49,28 @@ export async function makeKeychain(keys: CloakKey[]): Promise<CloakKeychain> {
 }
 
 /**
- * Decrypt and hydrate the given encrypted keychain
+ * Create a keychain holding the given list of keys.
+ *
+ * Available only for Node.js
+ *
+ * @param keys a list of keys to include in the keychain
+ */
+export function makeKeychainSync(keys: CloakKey[]): CloakKeychain {
+  const keychain: CloakKeychain = {}
+  for (const key of keys) {
+    const parsedKey = parseKeySync(key)
+    keychain[parsedKey.fingerprint] = {
+      key: parsedKey,
+      createdAt: Date.now()
+    }
+  }
+  return keychain
+}
+
+/**
+ * Decrypt and hydrate the given encrypted keychain.
+ *
+ * Runs everywhere (Node.js & browser).
  *
  * @param encryptedKeychain - A keychain as exported by exportKeychain
  * @param masterKey - The key used to encrypt the keychain
@@ -56,15 +93,42 @@ export async function importKeychain(
 }
 
 /**
- * Export a serialized and encrypted version of a keychain
+ * Decrypt and hydrate the given encrypted keychain.
+ *
+ * Available only for Node.js
+ *
+ * @param encryptedKeychain - A keychain as exported by exportKeychain
+ * @param masterKey - The key used to encrypt the keychain
+ */
+export function importKeychainSync(
+  encryptedKeychain: CloakedString,
+  masterKey: CloakKey
+): CloakKeychain {
+  const json = decryptStringSync(encryptedKeychain, masterKey)
+  const keys: SerializedKeychainEntry[] = JSON.parse(json)
+  const keychain: CloakKeychain = {}
+  for (const { key, ...rest } of keys) {
+    const parsedKey = parseKeySync(key)
+    keychain[parsedKey.fingerprint] = {
+      key: parsedKey,
+      ...rest
+    }
+  }
+  return keychain
+}
+
+/**
+ * Export a serialized and encrypted version of a keychain.
+ *
+ * Runs everywhere (Node.js & browser).
  *
  * @param keychain - The keychain to export
  * @param masterKey - The key to use to encrypt the keychain
  * @returns an encrypted keychain string
  */
 export async function exportKeychain(
   keychain: CloakKeychain,
-  masterKey: CloakKey
+  masterKey: CloakKey | ParsedCloakKey
 ): Promise<CloakedString> {
   const rawEntries: KeychainEntry[] = Object.values(keychain)
   const entries: SerializedKeychainEntry[] = []
@@ -77,6 +141,30 @@ export async function exportKeychain(
   return await encryptString(JSON.stringify(entries), masterKey)
 }
 
+/**
+ * Export a serialized and encrypted version of a keychain
+ *
+ * Available only for Node.js
+ *
+ * @param keychain - The keychain to export
+ * @param masterKey - The key to use to encrypt the keychain
+ * @returns an encrypted keychain string
+ */
+export function exportKeychainSync(
+  keychain: CloakKeychain,
+  masterKey: CloakKey | ParsedCloakKey
+): CloakedString {
+  const rawEntries: KeychainEntry[] = Object.values(keychain)
+  const entries: SerializedKeychainEntry[] = []
+  for (const entry of rawEntries) {
+    entries.push({
+      key: formatKey(entry.key.raw as Uint8Array),
+      createdAt: entry.createdAt
+    })
+  }
+  return encryptStringSync(JSON.stringify(entries), masterKey)
+}
+
 export function findKeyForMessage(
   message: CloakedString,
   keychain: CloakKeychain