@turnkey/crypto - npm Package Compare versions

Comparing version 1.0.0 to 2.0.0

./dist/index.js

@@ -9,3 +9,4 @@ 'use strict';
 exports.compressRawPublicKey = crypto.compressRawPublicKey;
-exports.decryptBundle = crypto.decryptBundle;
+exports.decryptCredentialBundle = crypto.decryptCredentialBundle;
+exports.decryptExportBundle = crypto.decryptExportBundle;
 exports.encryptPrivateKeyToBundle = crypto.encryptPrivateKeyToBundle;
@@ -12,0 +13,0 @@ exports.encryptWalletToBundle = crypto.encryptWalletToBundle;

CHANGELOG.md

 # @turnkey/crypto
 
+## 2.0.0
+
+### Major Changes
+
+- [BREAKING CHANGE] renamed `decryptBundle` to `decryptCredentialBundle` (for decrypting email auth/recovery and oauth credential bundles) in order to distinguish from the new `decryptExportBundle` (for decrypting bundles containing wallet mnemonics or private key material)
+
+### Patch Changes
+
+- Updated dependencies [e5c4fe9]
+  - @turnkey/encoding@0.4.0
+
 ## 1.0.0
@@ -4,0 +15,0 @@

dist/crypto.d.ts

 /// <reference lib="dom" />
+interface DecryptExportBundleParams {
+    exportBundle: string;
+    organizationId: string;
+    embeddedKey: string;
+    dangerouslyOverrideSignerPublicKey?: string;
+    returnMnemonic: boolean;
+}
 interface EncryptPrivateKeyToBundleParams {
@@ -78,11 +85,29 @@ privateKey: string;
 /**
- * Decrypt an encrypted email auth/recovery credential bundle.
+ * Decrypt an encrypted email auth/recovery or oauth credential bundle.
  *
  * @param {string} credentialBundle - The encrypted credential bundle.
  * @param {string} embeddedKey - The private key for decryption.
- * @returns {Uint8Array} - The decrypted data or null if decryption fails.
+ * @returns {string} - The decrypted data or null if decryption fails.
  * @throws {Error} - If unable to decrypt the credential bundle
  */
-export declare const decryptBundle: (credentialBundle: string, embeddedKey: string) => Uint8Array;
+export declare const decryptCredentialBundle: (credentialBundle: string, embeddedKey: string) => string;
 /**
+ * Decrypt an encrypted export bundle (such as a private key or wallet account bundle).
+ *
+ * This function verifies the enclave signature to ensure the authenticity of the encrypted data.
+ * It uses HPKE (Hybrid Public Key Encryption) to decrypt the contents of the bundle and returns
+ * either the decrypted mnemonic or the decrypted data in hexadecimal format, based on the
+ * `returnMnemonic` flag.
+ *
+ * @param {DecryptExportBundleParams} params - An object containing the following properties:
+ *   - exportBundle {string}: The encrypted export bundle in JSON format.
+ *   - organizationId {string}: The expected organization ID to verify against the signed data.
+ *   - embeddedKey {string}: The private key used for decrypting the data.
+ *   - dangerouslyOverrideSignerPublicKey {string} [Optional]: Optionally override the default signer public key used for verifying the signature. This should only be done for testing
+ *   - returnMnemonic {boolean}: If true, returns the decrypted data as a mnemonic string; otherwise, returns it in hexadecimal format.
+ * @returns {Promise<string>} - A promise that resolves to the decrypted mnemonic or decrypted hexadecimal data.
+ * @throws {Error} - If decryption or signature verification fails, throws an error with details.
+ */
+export declare const decryptExportBundle: ({ exportBundle, embeddedKey, organizationId, dangerouslyOverrideSignerPublicKey, returnMnemonic, }: DecryptExportBundleParams) => Promise<string>;
+/**
  * Generate a P-256 key pair. Contains the hexed privateKey, publicKey, and Uncompressed publicKey
@@ -124,3 +149,3 @@ *
  *
- * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes)
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted bundle.
@@ -134,3 +159,3 @@ * @throws {Error} - If enclave signature verification or any other validation fails.
  *
- * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes).
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted wallet bundle.
@@ -137,0 +162,0 @@ * @throws {Error} - If enclave signature verification or any other validation fails.

dist/crypto.js

@@ -181,10 +181,10 @@ 'use strict';
 /**
- * Decrypt an encrypted email auth/recovery credential bundle.
+ * Decrypt an encrypted email auth/recovery or oauth credential bundle.
  *
  * @param {string} credentialBundle - The encrypted credential bundle.
  * @param {string} embeddedKey - The private key for decryption.
- * @returns {Uint8Array} - The decrypted data or null if decryption fails.
+ * @returns {string} - The decrypted data or null if decryption fails.
  * @throws {Error} - If unable to decrypt the credential bundle
  */
-const decryptBundle = (credentialBundle, embeddedKey) => {
+const decryptCredentialBundle = (credentialBundle, embeddedKey) => {
     try {
@@ -203,9 +203,55 @@ const bundleBytes = bs58check.decode(credentialBundle);
         });
-        return decryptedData;
+        return encoding.uint8ArrayToHexString(decryptedData);
     }
     catch (error) {
-        throw new Error(`"Error injecting bundle:", ${error}`);
+        throw new Error(`"Error decrypting bundle:", ${error}`);
     }
 };
 /**
+ * Decrypt an encrypted export bundle (such as a private key or wallet account bundle).
+ *
+ * This function verifies the enclave signature to ensure the authenticity of the encrypted data.
+ * It uses HPKE (Hybrid Public Key Encryption) to decrypt the contents of the bundle and returns
+ * either the decrypted mnemonic or the decrypted data in hexadecimal format, based on the
+ * `returnMnemonic` flag.
+ *
+ * @param {DecryptExportBundleParams} params - An object containing the following properties:
+ *   - exportBundle {string}: The encrypted export bundle in JSON format.
+ *   - organizationId {string}: The expected organization ID to verify against the signed data.
+ *   - embeddedKey {string}: The private key used for decrypting the data.
+ *   - dangerouslyOverrideSignerPublicKey {string} [Optional]: Optionally override the default signer public key used for verifying the signature. This should only be done for testing
+ *   - returnMnemonic {boolean}: If true, returns the decrypted data as a mnemonic string; otherwise, returns it in hexadecimal format.
+ * @returns {Promise<string>} - A promise that resolves to the decrypted mnemonic or decrypted hexadecimal data.
+ * @throws {Error} - If decryption or signature verification fails, throws an error with details.
+ */
+const decryptExportBundle = async ({ exportBundle, embeddedKey, organizationId, dangerouslyOverrideSignerPublicKey, returnMnemonic, }) => {
+    try {
+        const parsedExportBundle = JSON.parse(exportBundle);
+        const verified = await verifyEnclaveSignature(parsedExportBundle.enclaveQuorumPublic, parsedExportBundle.dataSignature, parsedExportBundle.data, dangerouslyOverrideSignerPublicKey);
+        if (!verified) {
+            throw new Error(`failed to verify enclave signature: ${parsedExportBundle}`);
+        }
+        const signedData = JSON.parse(new TextDecoder().decode(encoding.uint8ArrayFromHexString(parsedExportBundle.data)));
+        if (!signedData.organizationId ||
+            signedData.organizationId !== organizationId) {
+            throw new Error(`organization id does not match expected value. Expected: ${organizationId}. Found: ${signedData.organizationId}.`);
+        }
+        if (!signedData.encappedPublic) {
+            throw new Error('missing "encappedPublic" in bundle signed data');
+        }
+        const encappedKeyBuf = encoding.uint8ArrayFromHexString(signedData.encappedPublic);
+        const ciphertextBuf = encoding.uint8ArrayFromHexString(signedData.ciphertext);
+        const decryptedData = hpkeDecrypt({
+            ciphertextBuf,
+            encappedKeyBuf,
+            receiverPriv: embeddedKey,
+        });
+        const decryptedDataHex = encoding.uint8ArrayToHexString(decryptedData);
+        return returnMnemonic ? encoding.hexToAscii(decryptedDataHex) : decryptedDataHex;
+    }
+    catch (error) {
+        throw new Error(`"Error decrypting bundle:", ${error}`);
+    }
+};
+/**
  * Generate a P-256 key pair. Contains the hexed privateKey, publicKey, and Uncompressed publicKey
@@ -493,3 +539,3 @@ *
  *
- * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes)
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted bundle.
@@ -525,3 +571,3 @@ * @throws {Error} - If enclave signature verification or any other validation fails.
  *
- * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes).
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted wallet bundle.
@@ -556,3 +602,4 @@ * @throws {Error} - If enclave signature verification or any other validation fails.
 exports.compressRawPublicKey = compressRawPublicKey;
-exports.decryptBundle = decryptBundle;
+exports.decryptCredentialBundle = decryptCredentialBundle;
+exports.decryptExportBundle = decryptExportBundle;
 exports.encryptPrivateKeyToBundle = encryptPrivateKeyToBundle;
@@ -559,0 +606,0 @@ exports.encryptWalletToBundle = encryptWalletToBundle;

dist/crypto.mjs

@@ -5,3 +5,3 @@ import { p256 } from '@noble/curves/p256';
 import { gcm } from '@noble/ciphers/aes';
-import { uint8ArrayFromHexString, uint8ArrayToHexString, normalizePadding } from '@turnkey/encoding';
+import { uint8ArrayFromHexString, uint8ArrayToHexString, hexToAscii, normalizePadding } from '@turnkey/encoding';
 import bs58check from 'bs58check';
@@ -161,10 +161,10 @@ import { modSqrt, testBit } from './math.mjs';
 /**
- * Decrypt an encrypted email auth/recovery credential bundle.
+ * Decrypt an encrypted email auth/recovery or oauth credential bundle.
  *
  * @param {string} credentialBundle - The encrypted credential bundle.
  * @param {string} embeddedKey - The private key for decryption.
- * @returns {Uint8Array} - The decrypted data or null if decryption fails.
+ * @returns {string} - The decrypted data or null if decryption fails.
  * @throws {Error} - If unable to decrypt the credential bundle
  */
-const decryptBundle = (credentialBundle, embeddedKey) => {
+const decryptCredentialBundle = (credentialBundle, embeddedKey) => {
     try {
@@ -183,9 +183,55 @@ const bundleBytes = bs58check.decode(credentialBundle);
         });
-        return decryptedData;
+        return uint8ArrayToHexString(decryptedData);
     }
     catch (error) {
-        throw new Error(`"Error injecting bundle:", ${error}`);
+        throw new Error(`"Error decrypting bundle:", ${error}`);
     }
 };
 /**
+ * Decrypt an encrypted export bundle (such as a private key or wallet account bundle).
+ *
+ * This function verifies the enclave signature to ensure the authenticity of the encrypted data.
+ * It uses HPKE (Hybrid Public Key Encryption) to decrypt the contents of the bundle and returns
+ * either the decrypted mnemonic or the decrypted data in hexadecimal format, based on the
+ * `returnMnemonic` flag.
+ *
+ * @param {DecryptExportBundleParams} params - An object containing the following properties:
+ *   - exportBundle {string}: The encrypted export bundle in JSON format.
+ *   - organizationId {string}: The expected organization ID to verify against the signed data.
+ *   - embeddedKey {string}: The private key used for decrypting the data.
+ *   - dangerouslyOverrideSignerPublicKey {string} [Optional]: Optionally override the default signer public key used for verifying the signature. This should only be done for testing
+ *   - returnMnemonic {boolean}: If true, returns the decrypted data as a mnemonic string; otherwise, returns it in hexadecimal format.
+ * @returns {Promise<string>} - A promise that resolves to the decrypted mnemonic or decrypted hexadecimal data.
+ * @throws {Error} - If decryption or signature verification fails, throws an error with details.
+ */
+const decryptExportBundle = async ({ exportBundle, embeddedKey, organizationId, dangerouslyOverrideSignerPublicKey, returnMnemonic, }) => {
+    try {
+        const parsedExportBundle = JSON.parse(exportBundle);
+        const verified = await verifyEnclaveSignature(parsedExportBundle.enclaveQuorumPublic, parsedExportBundle.dataSignature, parsedExportBundle.data, dangerouslyOverrideSignerPublicKey);
+        if (!verified) {
+            throw new Error(`failed to verify enclave signature: ${parsedExportBundle}`);
+        }
+        const signedData = JSON.parse(new TextDecoder().decode(uint8ArrayFromHexString(parsedExportBundle.data)));
+        if (!signedData.organizationId ||
+            signedData.organizationId !== organizationId) {
+            throw new Error(`organization id does not match expected value. Expected: ${organizationId}. Found: ${signedData.organizationId}.`);
+        }
+        if (!signedData.encappedPublic) {
+            throw new Error('missing "encappedPublic" in bundle signed data');
+        }
+        const encappedKeyBuf = uint8ArrayFromHexString(signedData.encappedPublic);
+        const ciphertextBuf = uint8ArrayFromHexString(signedData.ciphertext);
+        const decryptedData = hpkeDecrypt({
+            ciphertextBuf,
+            encappedKeyBuf,
+            receiverPriv: embeddedKey,
+        });
+        const decryptedDataHex = uint8ArrayToHexString(decryptedData);
+        return returnMnemonic ? hexToAscii(decryptedDataHex) : decryptedDataHex;
+    }
+    catch (error) {
+        throw new Error(`"Error decrypting bundle:", ${error}`);
+    }
+};
+/**
  * Generate a P-256 key pair. Contains the hexed privateKey, publicKey, and Uncompressed publicKey
@@ -473,3 +519,3 @@ *
  *
- * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptPrivateKeyToBundleParams} params - An object containing the private key, key format, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes)
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted bundle.
@@ -505,3 +551,3 @@ * @throws {Error} - If enclave signature verification or any other validation fails.
  *
- * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key.
+ * @param {EncryptWalletToBundleParams} params - An object containing the mnemonic, bundle, user, and organization details. Optionally, you can override the default signer key (for testing purposes).
  * @returns {Promise<string>} - A promise that resolves to a JSON string representing the encrypted wallet bundle.
@@ -534,3 +580,3 @@ * @throws {Error} - If enclave signature verification or any other validation fails.
 
-export { buildAdditionalAssociatedData, compressRawPublicKey, decryptBundle, encryptPrivateKeyToBundle, encryptWalletToBundle, extractPrivateKeyFromPKCS8Bytes, formatHpkeBuf, generateP256KeyPair, getPublicKey, hpkeAuthEncrypt, hpkeDecrypt, hpkeEncrypt, uncompressRawPublicKey };
+export { buildAdditionalAssociatedData, compressRawPublicKey, decryptCredentialBundle, decryptExportBundle, encryptPrivateKeyToBundle, encryptWalletToBundle, extractPrivateKeyFromPKCS8Bytes, formatHpkeBuf, generateP256KeyPair, getPublicKey, hpkeAuthEncrypt, hpkeDecrypt, hpkeEncrypt, uncompressRawPublicKey };
 //# sourceMappingURL=crypto.mjs.map

dist/index.js

@@ -9,3 +9,4 @@ 'use strict';
 exports.compressRawPublicKey = crypto.compressRawPublicKey;
-exports.decryptBundle = crypto.decryptBundle;
+exports.decryptCredentialBundle = crypto.decryptCredentialBundle;
+exports.decryptExportBundle = crypto.decryptExportBundle;
 exports.encryptPrivateKeyToBundle = crypto.encryptPrivateKeyToBundle;
@@ -12,0 +13,0 @@ exports.encryptWalletToBundle = crypto.encryptWalletToBundle;

dist/index.mjs

@@ -1,2 +0,2 @@
-export { buildAdditionalAssociatedData, compressRawPublicKey, decryptBundle, encryptPrivateKeyToBundle, encryptWalletToBundle, extractPrivateKeyFromPKCS8Bytes, formatHpkeBuf, generateP256KeyPair, getPublicKey, hpkeAuthEncrypt, hpkeDecrypt, hpkeEncrypt, uncompressRawPublicKey } from './crypto.mjs';
+export { buildAdditionalAssociatedData, compressRawPublicKey, decryptCredentialBundle, decryptExportBundle, encryptPrivateKeyToBundle, encryptWalletToBundle, extractPrivateKeyFromPKCS8Bytes, formatHpkeBuf, generateP256KeyPair, getPublicKey, hpkeAuthEncrypt, hpkeDecrypt, hpkeEncrypt, uncompressRawPublicKey } from './crypto.mjs';
 //# sourceMappingURL=index.mjs.map

package.json

 {
   "name": "@turnkey/crypto",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "main": "./dist/index.js",
@@ -46,3 +46,3 @@ "module": "./dist/index.mjs",
     "typescript": "5.0.4",
-    "@turnkey/encoding": "0.3.0"
+    "@turnkey/encoding": "0.4.0"
   },
@@ -52,3 +52,3 @@ "devDependencies": {
     "jest": "29.7.0",
-    "@turnkey/encoding": "0.3.0"
+    "@turnkey/encoding": "0.4.0"
   },
@@ -55,0 +55,0 @@ "scripts": {

No alert changes

Improved metrics

Total package byte prevSize

137929

8.87%

Lines of code

1552

8.38%

Dependency changes

• + Added

  @turnkey/encoding@0.4.0
  (transitive)

• - Removed

  @turnkey/encoding@0.3.0
  (transitive)

• Updated

  @turnkey/encoding@0.4.0