{"library":"mongodb-client-encryption","title":"MongoDB Client-Side Encryption Module","description":"The `mongodb-client-encryption` package is the official Node.js wrapper for `libmongocrypt`, a core library enabling Client-Side Field Level Encryption (CSFLE) for MongoDB. It is not intended for standalone use by application developers, but rather as an internal dependency of the `mongodb` Node.js driver to provide robust encryption capabilities. The current stable version is v7.0.0, released in November 2025. Releases typically align with major and minor versions of the main `mongodb` driver, with new features and breaking changes often following driver updates. Its key differentiator is providing the native bindings and core encryption logic for CSFLE, integrating seamlessly with the `mongodb` package to allow developers to encrypt sensitive data before it leaves the application, maintaining data privacy without sacrificing queryability.","language":"javascript","status":"active","last_verified":"Thu Apr 23","install":{"commands":["npm install mongodb-client-encryption"],"cli":null},"imports":["import { ClientEncryption } from 'mongodb-client-encryption'","import type { KMSProviders } from 'mongodb-client-encryption'","import type { ClientEncryptionOptions } from 'mongodb-client-encryption'"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import { MongoClient, Binary } from 'mongodb';\nimport { ClientEncryption } from 'mongodb-client-encryption';\nimport * as crypto from 'crypto';\n\nasync function runEncryptionExample() {\n  // Ensure these environment variables are set or provide default values\n  const connectionString = process.env.MONGO_URI ?? 'mongodb://localhost:27017/';\n  const kmsProviderType = process.env.KMS_PROVIDER_TYPE ?? 'local'; // e.g., 'aws', 'azure', 'gcp', 'kmip', 'local'\n  const keyVaultNamespace = process.env.KEY_VAULT_NAMESPACE ?? 'encryption.__keyVault';\n\n  let kmsProviders: any;\n\n  // For a 'local' KMS provider, a 32-byte master key is required.\n  // In a production environment, this key should be securely managed and never hardcoded.\n  if (kmsProviderType === 'local') {\n    const localMasterKey = process.env.LOCAL_MASTER_KEY || crypto.randomBytes(96).toString('base64'); // 96 bytes for CSFLE, per MongoDB documentation\n    kmsProviders = {\n      local: { key: Buffer.from(localMasterKey, 'base64').subarray(0, 32) } // Ensure it's 32 bytes for the ClientEncryptionSettings\n    };\n  } else if (kmsProviderType === 'aws') {\n    // Example for AWS KMS. Replace with actual credentials/configuration.\n    kmsProviders = {\n      aws: {\n        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID',\n        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY',\n        region: process.env.AWS_REGION ?? 'us-east-1'\n      }\n    };\n  } else {\n      console.error(`KMS Provider ${kmsProviderType} not supported in this example.`);\n      return;\n  }\n\n  const client = new MongoClient(connectionString);\n\n  try {\n    await client.connect();\n\n    const encryption = new ClientEncryption(client,\n      {\n        keyVaultNamespace,\n        kmsProviders\n      }\n    );\n\n    // IMPORTANT: In a real application, you would typically create or retrieve a Data Key ID\n    // from your key vault (e.g., using `encryption.createDataKey()`).\n    // For this quickstart, we'll use a placeholder UUID string for demonstration.\n    // Make sure this is a valid UUID (BSON Binary subtype 0x04) of an actual data key in your vault.\n    const dataKeyUuidString = process.env.DATA_KEY_UUID ?? '12345678123456781234567812345678'; // Example 16-byte hex representation for UUID\n    const dataKeyId = new Binary(Buffer.from(dataKeyUuidString.padEnd(32, '0'), 'hex'), Binary.SUBTYPE_UUID);\n\n    const dataToEncrypt = 'my highly sensitive information';\n\n    console.log('Original Data:', dataToEncrypt);\n\n    // Explicitly encrypt a field\n    const encryptedData = await encryption.encrypt(dataToEncrypt, {\n      keyId: dataKeyId,\n      algorithm: 'AEAD_AES256_CBC_HMAC_SHA512-Deterministic' // Or AEAD_AES256_CBC_HMAC_SHA512-Random\n    });\n\n    console.log('Encrypted Data (BSON Binary):', encryptedData);\n\n    // Explicitly decrypt the field\n    const decryptedData = await encryption.decrypt(encryptedData);\n    console.log('Decrypted Data:', decryptedData);\n\n  } finally {\n    await client.close();\n  }\n}\n\nrunEncryptionExample().catch(console.error);\n","lang":"typescript","description":"Demonstrates direct instantiation and use of `ClientEncryption` for explicit encryption and decryption of data. This showcases the core functionality provided by this library, though in most applications, client-side encryption is managed via the `mongodb` driver's `autoEncryption` settings.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}