feat(protect): encrypt and decrpyt audit ffi calls

Author: calvinbrewer

packages/protect/__tests__/audit.test.ts

@@ -0,0 +1,59 @@
+import 'dotenv/config'
+import { describe, expect, it, beforeAll } from 'vitest'
+import { csTable, csColumn } from '@cipherstash/schema'
+import { LockContext, protect } from '../src'
+
+const users = csTable('users', {
+  auditable: csColumn('auditable'),
+})
+
+type User = {
+  id: string
+  auditable?: string | null
+}
+
+let protectClient: Awaited<ReturnType<typeof protect>>
+
+beforeAll(async () => {
+  protectClient = await protect({
+    schemas: [users],
+  })
+})
+
+describe('encryption and decryption', () => {
+  it('should encrypt and decrypt a payload with audit metadata', async () => {
+    const email = 'very_secret_data'
+
+    const ciphertext = await protectClient
+      .encrypt(email, {
+        column: users.auditable,
+        table: users,
+      })
+      .audit({
+        metadata: {
+          sub: 'cj@cjb.io',
+          hello: 'world',
+          foo: 'bar',
+        },
+      })
+
+    if (ciphertext.failure) {
+      throw new Error(`[protect]: ${ciphertext.failure.message}`)
+    }
+
+    // Verify encrypted field
+    expect(ciphertext.data).toHaveProperty('c')
+
+    const plaintext = await protectClient.decrypt(ciphertext.data).audit({
+      metadata: {
+        sub: 'cj@cjb.io',
+        hello: 'world',
+        foo: 'bar',
+      },
+    })
+
+    expect(plaintext).toEqual({
+      data: email,
+    })
+  }, 30000)
+})

packages/protect/package.json

@@ -53,7 +53,7 @@
 	},
 	"dependencies": {
 		"@byteslice/result": "^0.2.0",
-		"@cipherstash/protect-ffi": "0.16.0-0",
+		"@cipherstash/protect-ffi": "0.16.0-1",
 		"@cipherstash/schema": "workspace:*",
 		"zod": "^3.24.2"
 	},

packages/protect/src/ffi/operations/base-operation.ts

@@ -5,6 +5,10 @@ export type AuditConfig = {
   metadata?: Record<string, unknown>
 }
 
+export type AuditData = {
+  metadata?: Record<string, unknown>
+}
+
 export abstract class ProtectOperation<T> {
   protected auditMetadata?: Record<string, unknown>
 
@@ -21,8 +25,10 @@ export abstract class ProtectOperation<T> {
   /**
    * Get the audit metadata for this operation.
    */
-  public getAuditMetadata(): Record<string, unknown> | undefined {
-    return this.auditMetadata
+  public getAuditData(): AuditData {
+    return {
+      metadata: this.auditMetadata,
+    }
   }
 
   /**

packages/protect/src/ffi/operations/decrypt.ts

@@ -21,9 +21,9 @@ export class DecryptOperation extends ProtectOperation<string | null> {
     lockContext: LockContext,
   ): DecryptOperationWithLockContext {
     const opWithLock = new DecryptOperationWithLockContext(this, lockContext)
-    const auditMetadata = this.getAuditMetadata()
-    if (auditMetadata) {
-      opWithLock.audit(auditMetadata)
+    const auditData = this.getAuditData()
+    if (auditData) {
+      opWithLock.audit(auditData)
     }
     return opWithLock
   }
@@ -39,10 +39,19 @@ export class DecryptOperation extends ProtectOperation<string | null> {
           return null
         }
 
+        const { metadata } = this.getAuditData()
+
         logger.debug('Decrypting data WITHOUT a lock context', {
-          auditMetadata: this.getAuditMetadata(),
+          metadata,
         })
-        return await ffiDecrypt(this.client, this.encryptedData.c)
+
+        return await ffiDecrypt(
+          this.client,
+          this.encryptedData.c,
+          undefined,
+          undefined,
+          ...(metadata !== undefined ? [metadata] : []),
+        )
       },
       (error) => ({
         type: ProtectErrorTypes.DecryptionError,
@@ -54,12 +63,12 @@ export class DecryptOperation extends ProtectOperation<string | null> {
   public getOperation(): {
     client: Client
     encryptedData: EncryptedPayload
-    auditMetadata?: Record<string, unknown>
+    auditData?: Record<string, unknown>
   } {
     return {
       client: this.client,
       encryptedData: this.encryptedData,
-      auditMetadata: this.getAuditMetadata(),
+      auditData: this.getAuditData(),
     }
   }
 }
@@ -74,9 +83,9 @@ export class DecryptOperationWithLockContext extends ProtectOperation<
     super()
     this.operation = operation
     this.lockContext = lockContext
-    const auditMetadata = operation.getAuditMetadata()
-    if (auditMetadata) {
-      this.audit(auditMetadata)
+    const auditData = operation.getAuditData()
+    if (auditData) {
+      this.audit(auditData)
     }
   }
 
@@ -93,8 +102,10 @@ export class DecryptOperationWithLockContext extends ProtectOperation<
           return null
         }
 
+        const { metadata } = this.getAuditData()
+
         logger.debug('Decrypting data WITH a lock context', {
-          auditMetadata: this.getAuditMetadata(),
+          metadata,
         })
 
         const context = await this.lockContext.getLockContext()
@@ -108,6 +119,7 @@ export class DecryptOperationWithLockContext extends ProtectOperation<
           encryptedData.c,
           context.data.context,
           context.data.ctsToken,
+          ...(metadata !== undefined ? [metadata] : []),
         )
       },
       (error) => ({

packages/protect/src/ffi/operations/encrypt.ts

@@ -54,11 +54,18 @@ export class EncryptOperation extends ProtectOperation<EncryptedPayload> {
           return null
         }
 
-        return await ffiEncrypt(this.client, {
-          plaintext: this.plaintext,
-          column: this.column.getName(),
-          table: this.table.tableName,
-        })
+        const { metadata } = this.getAuditData()
+
+        return await ffiEncrypt(
+          this.client,
+          {
+            plaintext: this.plaintext,
+            column: this.column.getName(),
+            table: this.table.tableName,
+          },
+          undefined,
+          ...(metadata !== undefined ? [metadata] : []),
+        )
       },
       (error) => ({
         type: ProtectErrorTypes.EncryptionError,