Upgrade @cipherstash/protect-ffi to 0.20.1 and new encryptQuery() API

.changeset/encrypt-query-api.md

@@ -0,0 +1,11 @@
+---
+"@cipherstash/protect": minor
+"@cipherstash/drizzle": patch
+---
+
+Add `encryptQuery` API for encrypting query terms with explicit query type selection.
+
+- New `encryptQuery()` method replaces `createSearchTerms()` with improved query type handling
+- Supports `equality`, `freeTextSearch`, and `orderAndRange` query types
+- Deprecates `createSearchTerms()` - use `encryptQuery()` instead
+- Updates drizzle operators to use correct index selection via `queryType` parameter

examples/dynamo/src/encrypted-key-in-gsi.ts

@@ -66,21 +66,23 @@ const main = async () => {
 
   await dynamoClient.send(putCommand)
 
-  const searchTermsResult = await protectDynamo.createSearchTerms([
-    {
-      value: 'abc@example.com',
-      column: users.email,
-      table: users,
-    },
+  // Use encryptQuery to create the search term for GSI query
+  const encryptedResult = await protectClient.encryptQuery([
+    { value: 'abc@example.com', column: users.email, table: users, queryType: 'equality' },
   ])
 
-  if (searchTermsResult.failure) {
+  if (encryptedResult.failure) {
     throw new Error(
-      `Failed to create search terms: ${searchTermsResult.failure.message}`,
+      `Failed to encrypt query: ${encryptedResult.failure.message}`,
     )
   }
 
-  const [emailHmac] = searchTermsResult.data
+  // Extract the HMAC for DynamoDB key lookup
+  const encryptedEmail = encryptedResult.data[0]
+  if (!encryptedEmail) {
+    throw new Error('Failed to encrypt query: no result returned')
+  }
+  const emailHmac = encryptedEmail.hm
 
   const queryCommand = new QueryCommand({
     TableName: tableName,

examples/dynamo/src/encrypted-partition-key.ts

@@ -49,21 +49,23 @@ const main = async () => {
 
   await docClient.send(putCommand)
 
-  const searchTermsResult = await protectDynamo.createSearchTerms([
-    {
-      value: 'abc@example.com',
-      column: users.email,
-      table: users,
-    },
+  // Use encryptQuery to create the search term for partition key lookup
+  const encryptedResult = await protectClient.encryptQuery([
+    { value: 'abc@example.com', column: users.email, table: users, queryType: 'equality' },
   ])
 
-  if (searchTermsResult.failure) {
+  if (encryptedResult.failure) {
     throw new Error(
-      `Failed to create search terms: ${searchTermsResult.failure.message}`,
+      `Failed to encrypt query: ${encryptedResult.failure.message}`,
     )
   }
 
-  const [emailHmac] = searchTermsResult.data
+  // Extract the HMAC for DynamoDB key lookup
+  const encryptedEmail = encryptedResult.data[0]
+  if (!encryptedEmail) {
+    throw new Error('Failed to encrypt query: no result returned')
+  }
+  const emailHmac = encryptedEmail.hm
 
   const getCommand = new GetCommand({
     TableName: tableName,

examples/dynamo/src/encrypted-sort-key.ts

@@ -58,21 +58,23 @@ const main = async () => {
 
   await docClient.send(putCommand)
 
-  const searchTermsResult = await protectDynamo.createSearchTerms([
-    {
-      value: 'abc@example.com',
-      column: users.email,
-      table: users,
-    },
+  // Use encryptQuery to create the search term for sort key range query
+  const encryptedResult = await protectClient.encryptQuery([
+    { value: 'abc@example.com', column: users.email, table: users, queryType: 'equality' },
   ])
 
-  if (searchTermsResult.failure) {
+  if (encryptedResult.failure) {
     throw new Error(
-      `Failed to create search terms: ${searchTermsResult.failure.message}`,
+      `Failed to encrypt query: ${encryptedResult.failure.message}`,
     )
   }
 
-  const [emailHmac] = searchTermsResult.data
+  // Extract the HMAC for DynamoDB key lookup
+  const encryptedEmail = encryptedResult.data[0]
+  if (!encryptedEmail) {
+    throw new Error('Failed to encrypt query: no result returned')
+  }
+  const emailHmac = encryptedEmail.hm
 
   const getCommand = new GetCommand({
     TableName: tableName,

examples/typeorm/src/helpers/protect-entity.ts

@@ -1,4 +1,7 @@
-import type { ProtectClient } from '@cipherstash/protect'
+import {
+  type ProtectClient,
+  encryptedToPgComposite,
+} from '@cipherstash/protect'
 import type { EntityTarget } from 'typeorm'
 import { AppDataSource } from '../data-source'
 
@@ -199,25 +202,28 @@ export class ProtectEntityHelper {
     // biome-ignore lint/suspicious/noExplicitAny: Required for Protect.js schema types
     fieldConfig: { table: any; column: any },
   ): Promise<T | null> {
-    const searchTermsResult = await this.protectClient.createSearchTerms([
+    // Use encryptQuery instead of deprecated createSearchTerms
+    const encryptedResult = await this.protectClient.encryptQuery([
       {
         value: searchValue,
         column: fieldConfig.column,
         table: fieldConfig.table,
-        returnType: 'composite-literal',
+        queryType: 'equality',
       },
     ])
 
-    if (searchTermsResult.failure) {
+    if (encryptedResult.failure) {
       throw new Error(
-        `Failed to create search terms: ${searchTermsResult.failure.message}`,
+        `Failed to encrypt query: ${encryptedResult.failure.message}`,
       )
     }
 
+    const [encrypted] = encryptedResult.data
+
     const repository = AppDataSource.getRepository(entityClass)
     return repository.findOne({
       where: {
-        [fieldName]: searchTermsResult.data[0],
+        [fieldName]: encryptedToPgComposite(encrypted),
         // biome-ignore lint/suspicious/noExplicitAny: Required for dynamic field access
       } as any,
     })