feat(protect): init raw bulk interfaces

Author: calvinbrewer

README.md

@@ -528,6 +528,46 @@ const decryptedUsers = decryptedResult.data;
 The model encryption methods provide a higher-level interface that's particularly useful when working with ORMs or when you need to encrypt multiple fields in an object.
 They automatically handle the mapping between your model's structure and the encrypted fields defined in your schema.
 
+#### Bulk encryption operations
+
+For encrypting multiple individual values (rather than entire models), use the `bulkEncrypt` method:
+
+```typescript
+import { protectClient } from "./protect";
+import { users } from "./protect/schema";
+
+// Array of payloads with IDs and plaintext values
+const plaintexts = [
+  { id: "1", plaintext: "user1@example.com" },
+  { id: "2", plaintext: "user2@example.com" },
+  { id: "3", plaintext: null },
+];
+
+// Encrypt multiple values at once
+const encryptedResult = await protectClient.bulkEncrypt(plaintexts, {
+  column: users.email,
+  table: users,
+});
+
+if (encryptedResult.failure) {
+  // Handle the failure
+}
+
+const encryptedData = encryptedResult.data;
+// Returns: [
+//   { id: "1", c: "encrypted_value_1" },
+//   { id: "2", c: "encrypted_value_2" },
+//   { id: "3", c: null }
+// ]
+
+// You can then decrypt individual values using the decrypt method
+const decryptedResult = await protectClient.decrypt(encryptedData[0].c);
+```
+
+The `bulkEncrypt` method is useful when you need to encrypt multiple values for the same column and table, but don't want to encrypt entire model objects. Each encrypted value maintains its own unique key while benefiting from ZeroKMS's bulk operation performance.
+
+The model encryption methods provide a higher-level interface that's particularly useful when working with ORMs or when you need to encrypt multiple fields in an object.
+
 ### Store encrypted data in a database
 
 Encrypted data can be stored in any database that supports JSONB, noting that searchable encryption is only supported in PostgreSQL at the moment.
@@ -719,6 +759,40 @@ const bulkDecryptedResult = await protectClient
   .withLockContext(lockContext);
 ```
 
+### Bulk encryption operations with lock context
+
+Bulk encryption operations also support lock contexts for identity-aware encryption:
+
+```typescript
+import { protectClient } from "./protect";
+import { users } from "./protect/schema";
+
+const plaintexts = [
+  { id: "1", plaintext: "user1@example.com" },
+  { id: "2", plaintext: "user2@example.com" },
+  { id: "3", plaintext: null },
+];
+
+// Bulk encrypt with lock context
+const encryptedResult = await protectClient
+  .bulkEncrypt(plaintexts, {
+    column: users.email,
+    table: users,
+  })
+  .withLockContext(lockContext);
+
+if (encryptedResult.failure) {
+  // Handle the failure
+}
+
+const encryptedData = encryptedResult.data;
+
+// Decrypt individual values with lock context
+const decryptedResult = await protectClient
+  .decrypt(encryptedData[0].c)
+  .withLockContext(lockContext);
+```
+
 ## Supported data types
 
 Protect.js currently supports encrypting and decrypting text.

examples/basic/index.ts

@@ -43,6 +43,32 @@ async function main() {
   console.log('Decrypting the ciphertext...')
   console.log('The plaintext is:', plaintext)
 
+  // Demonstrate bulk encryption
+  console.log('\n--- Bulk Encryption Demo ---')
+
+  const bulkPlaintexts = [
+    { id: '1', plaintext: 'Alice' },
+    { id: '2', plaintext: 'Bob' },
+    { id: '3', plaintext: 'Charlie' },
+    { id: '4', plaintext: null },
+  ]
+
+  console.log(
+    'Bulk encrypting names:',
+    bulkPlaintexts.map((p) => p.plaintext),
+  )
+
+  const bulkEncryptResult = await protectClient.bulkEncrypt(bulkPlaintexts, {
+    column: users.name,
+    table: users,
+  })
+
+  if (bulkEncryptResult.failure) {
+    throw new Error(`[protect]: ${bulkEncryptResult.failure.message}`)
+  }
+
+  console.log('Bulk encrypted data:', bulkEncryptResult.data)
+
   rl.close()
 }
 

packages/protect/__tests__/protect.test.ts

@@ -665,6 +665,96 @@ describe('performance', () => {
   }, 60000)
 })
 
+describe('bulk encryption operations', () => {
+  it('should bulk encrypt payloads with IDs', async () => {
+    const plaintexts = [
+      { id: '1', plaintext: 'hello@example.com' },
+      { id: '2', plaintext: 'world@example.com' },
+      { id: '3', plaintext: null },
+    ]
+
+    const encryptedData = await protectClient.bulkEncrypt(plaintexts, {
+      column: users.email,
+      table: users,
+    })
+
+    if (encryptedData.failure) {
+      throw new Error(`[protect]: ${encryptedData.failure.message}`)
+    }
+
+    // Verify encrypted data structure
+    expect(encryptedData.data).toHaveLength(3)
+    expect(encryptedData.data[0]).toHaveProperty('id', '1')
+    expect(encryptedData.data[0]).toHaveProperty('c')
+    expect(encryptedData.data[1]).toHaveProperty('id', '2')
+    expect(encryptedData.data[1]).toHaveProperty('c')
+    expect(encryptedData.data[2]).toHaveProperty('id', '3')
+    expect(encryptedData.data[2]).toHaveProperty('c', null)
+
+    // Verify encrypted values are different from plaintext
+    expect(encryptedData.data[0].c).not.toBe('hello@example.com')
+    expect(encryptedData.data[1].c).not.toBe('world@example.com')
+  }, 30000)
+
+  it('should bulk encrypt simple arrays', async () => {
+    const plaintexts = ['hello@example.com', 'world@example.com', null]
+
+    const encryptedData = await protectClient.bulkEncrypt(plaintexts, {
+      column: users.email,
+      table: users,
+    })
+
+    if (encryptedData.failure) {
+      throw new Error(`[protect]: ${encryptedData.failure.message}`)
+    }
+
+    // Verify encrypted data structure
+    expect(encryptedData.data).toHaveLength(3)
+    expect(encryptedData.data[0]).toHaveProperty('c')
+    expect(encryptedData.data[1]).toHaveProperty('c')
+    expect(encryptedData.data[2]).toBeNull()
+
+    // Verify encrypted values are different from plaintext
+    expect(encryptedData.data[0]).not.toBe('hello@example.com')
+    expect(encryptedData.data[1]).not.toBe('world@example.com')
+  }, 30000)
+
+  it('should return empty array if plaintexts is empty', async () => {
+    const encryptedData = await protectClient.bulkEncrypt([], {
+      column: users.email,
+      table: users,
+    })
+
+    if (encryptedData.failure) {
+      throw new Error(`[protect]: ${encryptedData.failure.message}`)
+    }
+
+    expect(encryptedData.data).toEqual([])
+  }, 30000)
+
+  it('should handle mixed null and non-null values', async () => {
+    const plaintexts = [
+      { id: '1', plaintext: 'test1' },
+      { id: '2', plaintext: null },
+      { id: '3', plaintext: 'test3' },
+    ]
+
+    const encryptedData = await protectClient.bulkEncrypt(plaintexts, {
+      column: users.email,
+      table: users,
+    })
+
+    if (encryptedData.failure) {
+      throw new Error(`[protect]: ${encryptedData.failure.message}`)
+    }
+
+    expect(encryptedData.data).toHaveLength(3)
+    expect(encryptedData.data[0].c).not.toBeNull()
+    expect(encryptedData.data[1].c).toBeNull()
+    expect(encryptedData.data[2].c).not.toBeNull()
+  }, 30000)
+})
+
 // ------------------------
 // TODO get LockContext working in CI.
 // To manually test locally, uncomment the following lines and provide a valid JWT in the userJwt variable.

packages/protect/src/ffi/index.ts

@@ -18,6 +18,10 @@ import { BulkDecryptModelsOperation } from './operations/bulk-decrypt-models'
 import { EncryptOperation } from './operations/encrypt'
 import { DecryptOperation } from './operations/decrypt'
 import { SearchTermsOperation } from './operations/search-terms'
+import {
+  BulkEncryptOperation,
+  type BulkEncryptPayload,
+} from './operations/bulk-encrypt'
 import {
   type EncryptConfig,
   encryptConfigSchema,
@@ -76,9 +80,9 @@ export class ProtectClient {
         logger.info('Successfully initialized the Protect.js client.')
         return this
       },
-      (error) => ({
+      (error: unknown) => ({
         type: ProtectErrorTypes.ClientInitError,
-        message: error.message,
+        message: (error as Error).message,
       }),
     )
   }
@@ -153,6 +157,19 @@ export class ProtectClient {
     return new BulkDecryptModelsOperation(this.client, input)
   }
 
+  /**
+   * Bulk encryption - returns a thenable object.
+   * Usage:
+   *    await eqlClient.bulkEncrypt(plaintexts, { column, table })
+   *    await eqlClient.bulkEncrypt(plaintexts, { column, table }).withLockContext(lockContext)
+   */
+  bulkEncrypt(
+    plaintexts: BulkEncryptPayload,
+    opts: EncryptOptions,
+  ): BulkEncryptOperation {
+    return new BulkEncryptOperation(this.client, plaintexts, opts)
+  }
+
   /**
    * Create search terms to use in a query searching encrypted data
    * Usage: