fix(stack): restore runtime null guards in encryption operations

Commit 5b7288b (feat(stack): remove null from Encrypted type) tightened
the public types to disallow null in single-value encrypt/decrypt, and
deleted the matching runtime `if (value === null) return null` guards
across every operation in packages/stack/src/encryption/operations/.

The type narrowing does not survive runtime. Callers that reach an
operation through a cast (e.g. `null as any`), dynamic model field
walking, or JS interop will silently have their null encrypted by
protect-ffi into a real SteVec ciphertext (`{ k: 'sv', v: 2, ... }`),
breaking symmetry with the model-helpers layer where null is treated as
"absent" at the field level. The newly-ported searchable-json `round-
trips null values` test in PR #328 exercises this path directly and
surfaced the regression.

Restored guards mirror the @cipherstash/protect pattern:

- encrypt / EncryptOperationWithLockContext: early return null
- bulkEncrypt / *WithLockContext: filter-null + position-preserving merge
- decrypt / *WithLockContext: early return null
- bulkDecrypt / *WithLockContext: filter-null + position-preserving merge
- encryptQuery / *WithLockContext: return { data: null } for null/undefined
- batchEncryptQuery / *WithLockContext: per-element filter, position-stable

Internal operation field/return types widen to `T | null` so the
restored guards compile. Public bulk types (`BulkEncryptPayload`,
`BulkEncryptedData`, `BulkDecryptPayload`, `BulkDecryptedData`) and
`EncryptedQueryResult` widen to admit null in element positions — these
now honestly reflect runtime behavior and let callers process mixed
nullable arrays without filtering ahead of time. `Encryption.decrypt()`
accepts `Encrypted | null`. `Encryption.encrypt()`'s public signature
stays narrow (`JsPlaintext`); the runtime guard is defense in depth.

Author: coderdan

.changeset/restore-null-guards-in-encryption-ops.md

@@ -0,0 +1,23 @@
+---
+"@cipherstash/stack": patch
+---
+
+Fix: restore runtime null short-circuits in the encryption operation classes.
+
+A prior refactor (`feat(stack): remove null from Encrypted type`) tightened the type signatures to disallow `null` and, alongside that, deleted the `if (value === null) return null` guards from every operation in `packages/stack/src/encryption/operations/`. The type guard does not survive runtime: callers reaching the operation through a cast (e.g. `null as any`), dynamic model walking, or JS interop would then have their null silently encrypted by protect-ffi into a real SteVec ciphertext (`{ k: 'sv', v: 2, ... }`) — which is observable, surprising, and breaks symmetry with the model-helpers layer that does still treat null as "absent" at the field level.
+
+Restored, mirroring the pattern in `@cipherstash/protect`:
+
+- `encrypt` / `encryptWithLockContext`: `if (plaintext === null) return null`.
+- `bulkEncrypt` / `bulkEncryptWithLockContext`: per-element null filter; nulls are preserved in position in the output.
+- `decrypt` / `decryptWithLockContext`: `if (encryptedData === null) return null`.
+- `bulkDecrypt` / `bulkDecryptWithLockContext`: per-element null filter, position-preserving merge.
+- `encryptQuery` / `encryptQueryWithLockContext`: `if (plaintext === null || plaintext === undefined) return { data: null }`.
+- `batchEncryptQuery` / `batchEncryptQueryWithLockContext`: per-element null/undefined filter; null slots in the input array stay null in the result array.
+
+Type adjustments to support the runtime behavior honestly:
+
+- `BulkEncryptPayload['plaintext']`, `BulkEncryptedData['data']`, `BulkDecryptPayload['data']`, and the `T` of `BulkDecryptedData` all widen to `... | null`. Bulk APIs now accept and return mixed nullable arrays without filtering ahead of time.
+- `EncryptedQueryResult` widens to include `null` so the batch query path can return position-stable arrays with null slots.
+- `Encryption.decrypt()` accepts `Encrypted | null` (returns null for null input).
+- `Encryption.encrypt()`'s public signature is unchanged — still `JsPlaintext` (no null). The runtime guard is defense in depth for the cases the type system can't catch.

packages/stack/src/encryption/index.ts

@@ -311,7 +311,7 @@ export class EncryptionClient {
    * @see {@link LockContext}
    * @see {@link DecryptOperation}
    */
-  decrypt(encryptedData: Encrypted): DecryptOperation {
+  decrypt(encryptedData: Encrypted | null): DecryptOperation {
     return new DecryptOperation(this.client, encryptedData)
   }
 

packages/stack/src/encryption/operations/batch-encrypt-query.ts

@@ -6,6 +6,7 @@ import type { Client, EncryptedQueryResult, ScalarQueryTerm } from '@/types'
 import { createRequestLogger } from '@/utils/logger'
 import { type Result, withResult } from '@byteslice/result'
 import {
+  type JsPlaintext,
   type QueryPayload,
   encryptQueryBulk as ffiEncryptQueryBulk,
 } from '@cipherstash/protect-ffi'
@@ -21,6 +22,21 @@ import {
 import { noClientError } from '../index'
 import { EncryptionOperation } from './base-operation'
 
+// Separates null/undefined values from non-null terms in the input array
+// so they bypass the FFI call. Original indices are tracked so the
+// reassembled result preserves position.
+function filterNullTerms(terms: readonly ScalarQueryTerm[]): {
+  nonNullTerms: { term: ScalarQueryTerm; originalIndex: number }[]
+} {
+  const nonNullTerms: { term: ScalarQueryTerm; originalIndex: number }[] = []
+  terms.forEach((term, index) => {
+    if (term.value !== null && term.value !== undefined) {
+      nonNullTerms.push({ term, originalIndex: index })
+    }
+  })
+  return { nonNullTerms }
+}
+
 /**
  * Validates and transforms a single term into a QueryPayload.
  * Throws an error if the value is NaN or Infinity.
@@ -42,7 +58,7 @@ function buildQueryPayload(
   assertValueIndexCompatibility(term.value, indexType, term.column.getName())
 
   const payload: QueryPayload = {
-    plaintext: term.value,
+    plaintext: term.value as JsPlaintext,
     column: term.column.getName(),
     table: term.table.tableName,
     indexType,
@@ -57,15 +73,22 @@ function buildQueryPayload(
 }
 
 /**
- * Maps encrypted values to formatted results based on term.returnType.
+ * Reassembles the result array, slotting null at the original indices of
+ * filtered-out terms and formatting encrypted values for non-null terms.
  */
 function assembleResults(
-  terms: readonly ScalarQueryTerm[],
+  totalLength: number,
   encryptedValues: (CipherStashEncrypted | CipherStashEncryptedQuery)[],
+  nonNullTerms: { term: ScalarQueryTerm; originalIndex: number }[],
 ): EncryptedQueryResult[] {
-  return terms.map((term, i) =>
-    formatEncryptedResult(encryptedValues[i], term.returnType),
-  )
+  const results: EncryptedQueryResult[] = new Array(totalLength).fill(null)
+  nonNullTerms.forEach(({ term, originalIndex }, i) => {
+    results[originalIndex] = formatEncryptedResult(
+      encryptedValues[i],
+      term.returnType,
+    )
+  })
+  return results
 }
 
 /**
@@ -107,13 +130,20 @@ export class BatchEncryptQueryOperation extends EncryptionOperation<
       return { data: [] }
     }
 
+    const { nonNullTerms } = filterNullTerms(this.terms)
+
+    if (nonNullTerms.length === 0) {
+      log.emit()
+      return { data: this.terms.map(() => null) }
+    }
+
     const result = await withResult(
       async () => {
         if (!this.client) throw noClientError()
 
         const { metadata } = this.getAuditData()
 
-        const queries: QueryPayload[] = this.terms.map((term) =>
+        const queries: QueryPayload[] = nonNullTerms.map(({ term }) =>
           buildQueryPayload(term),
         )
 
@@ -122,7 +152,7 @@ export class BatchEncryptQueryOperation extends EncryptionOperation<
           unverifiedContext: metadata,
         })
 
-        return assembleResults(this.terms, encrypted)
+        return assembleResults(this.terms.length, encrypted, nonNullTerms)
       },
       (error: unknown) => {
         log.set({ errorCode: getErrorCode(error) ?? 'unknown' })
@@ -169,6 +199,15 @@ export class BatchEncryptQueryOperationWithLockContext extends EncryptionOperati
       return { data: [] }
     }
 
+    // Check for all-null terms BEFORE fetching lockContext to avoid an
+    // unnecessary network call.
+    const { nonNullTerms } = filterNullTerms(this.terms)
+
+    if (nonNullTerms.length === 0) {
+      log.emit()
+      return { data: this.terms.map(() => null) }
+    }
+
     const lockContextResult = await this.lockContext.getLockContext()
     if (lockContextResult.failure) {
       log.emit()
@@ -183,7 +222,7 @@ export class BatchEncryptQueryOperationWithLockContext extends EncryptionOperati
 
         const { metadata } = this.getAuditData()
 
-        const queries: QueryPayload[] = this.terms.map((term) =>
+        const queries: QueryPayload[] = nonNullTerms.map(({ term }) =>
           buildQueryPayload(term, context),
         )
 
@@ -193,7 +232,7 @@ export class BatchEncryptQueryOperationWithLockContext extends EncryptionOperati
           unverifiedContext: metadata,
         })
 
-        return assembleResults(this.terms, encrypted)
+        return assembleResults(this.terms.length, encrypted, nonNullTerms)
       },
       (error: unknown) => {
         log.set({ errorCode: getErrorCode(error) ?? 'unknown' })

packages/stack/src/encryption/operations/bulk-decrypt.ts

@@ -5,40 +5,53 @@ import type { BulkDecryptPayload, BulkDecryptedData, Client } from '@/types'
 import { createRequestLogger } from '@/utils/logger'
 import { type Result, withResult } from '@byteslice/result'
 import {
+  type Encrypted as CipherStashEncrypted,
   type DecryptResult,
   decryptBulkFallible,
 } from '@cipherstash/protect-ffi'
 import { noClientError } from '../index'
 import { EncryptionOperation } from './base-operation'
 
-// Helper functions for better composability
+// Drops nulls so they don't reach protect-ffi's bulk decrypt. The
+// dropped positions are re-inserted as null in `mapDecryptedDataToResult`.
 const createDecryptPayloads = (
   encryptedPayloads: BulkDecryptPayload,
   lockContext?: Context,
 ) => {
-  return encryptedPayloads.map(({ id, data }) => ({
-    id,
-    ciphertext: data,
-    ...(lockContext && { lockContext }),
-  }))
+  return encryptedPayloads
+    .filter(({ data }) => data !== null)
+    .map(({ id, data }) => ({
+      id,
+      ciphertext: data as CipherStashEncrypted,
+      ...(lockContext && { lockContext }),
+    }))
 }
 
+const createNullResult = (
+  encryptedPayloads: BulkDecryptPayload,
+): BulkDecryptedData =>
+  encryptedPayloads.map(({ id }) => ({ id, data: null }))
+
 const mapDecryptedDataToResult = (
   encryptedPayloads: BulkDecryptPayload,
   decryptedData: DecryptResult[],
 ): BulkDecryptedData => {
-  return decryptedData.map((decryptResult, i) => {
-    if ('error' in decryptResult) {
-      return {
-        id: encryptedPayloads[i].id,
-        error: decryptResult.error,
+  const result: BulkDecryptedData = new Array(encryptedPayloads.length)
+  let decryptedIndex = 0
+  for (let i = 0; i < encryptedPayloads.length; i++) {
+    if (encryptedPayloads[i].data === null) {
+      result[i] = { id: encryptedPayloads[i].id, data: null }
+    } else {
+      const decryptResult = decryptedData[decryptedIndex]
+      if ('error' in decryptResult) {
+        result[i] = { id: encryptedPayloads[i].id, error: decryptResult.error }
+      } else {
+        result[i] = { id: encryptedPayloads[i].id, data: decryptResult.data }
       }
+      decryptedIndex++
     }
-    return {
-      id: encryptedPayloads[i].id,
-      data: decryptResult.data,
-    }
-  })
+  }
+  return result
 }
 
 export class BulkDecryptOperation extends EncryptionOperation<BulkDecryptedData> {
@@ -71,12 +84,16 @@ export class BulkDecryptOperation extends EncryptionOperation<BulkDecryptedData>
         if (!this.encryptedPayloads || this.encryptedPayloads.length === 0)
           return []
 
-        const payloads = createDecryptPayloads(this.encryptedPayloads)
+        const nonNullPayloads = createDecryptPayloads(this.encryptedPayloads)
+
+        if (nonNullPayloads.length === 0) {
+          return createNullResult(this.encryptedPayloads)
+        }
 
         const { metadata } = this.getAuditData()
 
         const decryptedData = await decryptBulkFallible(this.client, {
-          ciphertexts: payloads,
+          ciphertexts: nonNullPayloads,
           unverifiedContext: metadata,
         })
 
@@ -140,15 +157,19 @@ export class BulkDecryptOperationWithLockContext extends EncryptionOperation<Bul
           throw new Error(`[encryption]: ${context.failure.message}`)
         }
 
-        const payloads = createDecryptPayloads(
+        const nonNullPayloads = createDecryptPayloads(
           encryptedPayloads,
           context.data.context,
         )
 
+        if (nonNullPayloads.length === 0) {
+          return createNullResult(encryptedPayloads)
+        }
+
         const { metadata } = this.getAuditData()
 
         const decryptedData = await decryptBulkFallible(client, {
-          ciphertexts: payloads,
+          ciphertexts: nonNullPayloads,
           serviceToken: context.data.ctsToken,
           unverifiedContext: metadata,
         })