@cipherstash/stack 0.16.0 → 0.18.0

package/dist/encryption/index.cjs

@@ -20,6 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/encryption/index.ts
 var encryption_exports = {};
 __export(encryption_exports, {
+  BatchEncryptQueryOperation: () => BatchEncryptQueryOperation,
+  BulkDecryptModelsOperation: () => BulkDecryptModelsOperation,
+  BulkDecryptOperation: () => BulkDecryptOperation,
+  BulkEncryptModelsOperation: () => BulkEncryptModelsOperation,
+  BulkEncryptOperation: () => BulkEncryptOperation,
+  DecryptModelOperation: () => DecryptModelOperation,
+  DecryptOperation: () => DecryptOperation,
+  EncryptModelOperation: () => EncryptModelOperation,
+  EncryptOperation: () => EncryptOperation,
+  EncryptQueryOperation: () => EncryptQueryOperation,
   Encryption: () => Encryption,
   EncryptionClient: () => EncryptionClient,
   noClientError: () => noClientError
@@ -103,7 +113,7 @@ var encryptConfigSchema = import_zod.z.object({
 });
 function buildEncryptConfig(...protectTables) {
   const config = {
-    v: 2,
+    v: 1,
     tables: {}
   };
   for (const tb of protectTables) {
@@ -113,7 +123,7 @@ function buildEncryptConfig(...protectTables) {
   return config;
 }
 
-// ../../node_modules/.pnpm/evlog@1.9.0/node_modules/evlog/dist/utils.mjs
+// ../../node_modules/.pnpm/evlog@1.11.0_next@15.5.10_react-dom@19.2.3_react@19.2.3__react@19.2.3__react@19.2.3/node_modules/evlog/dist/utils.mjs
 function formatDuration(ms) {
   if (ms < 1e3) return `${Math.round(ms)}ms`;
   return `${(ms / 1e3).toFixed(2)}s`;
@@ -169,7 +179,7 @@ function matchesPattern(path, pattern) {
   return new RegExp(`^${regexPattern}$`).test(path);
 }
 
-// ../../node_modules/.pnpm/evlog@1.9.0/node_modules/evlog/dist/logger.mjs
+// ../../node_modules/.pnpm/evlog@1.11.0_next@15.5.10_react-dom@19.2.3_react@19.2.3__react@19.2.3__react@19.2.3/node_modules/evlog/dist/logger.mjs
 function isPlainObject(val) {
   return val !== null && typeof val === "object" && !Array.isArray(val);
 }
@@ -673,6 +683,15 @@ var EncryptionOperation = class {
 };
 
 // src/encryption/operations/batch-encrypt-query.ts
+function filterNullTerms(terms) {
+  const nonNullTerms = [];
+  terms.forEach((term, index) => {
+    if (term.value !== null && term.value !== void 0) {
+      nonNullTerms.push({ term, originalIndex: index });
+    }
+  });
+  return { nonNullTerms };
+}
 function buildQueryPayload(term, lockContext) {
   assertValidNumericValue(term.value);
   const { indexType, queryOp } = resolveIndexType(
@@ -693,10 +712,15 @@ function buildQueryPayload(term, lockContext) {
   }
   return payload;
 }
-function assembleResults(terms, encryptedValues) {
-  return terms.map(
-    (term, i) => formatEncryptedResult(encryptedValues[i], term.returnType)
-  );
+function assembleResults(totalLength, encryptedValues, nonNullTerms) {
+  const results = new Array(totalLength).fill(null);
+  nonNullTerms.forEach(({ term, originalIndex }, i) => {
+    results[originalIndex] = formatEncryptedResult(
+      encryptedValues[i],
+      term.returnType
+    );
+  });
+  return results;
 }
 var BatchEncryptQueryOperation = class extends EncryptionOperation {
   constructor(client, terms) {
@@ -704,6 +728,8 @@ var BatchEncryptQueryOperation = class extends EncryptionOperation {
     this.client = client;
     this.terms = terms;
   }
+  client;
+  terms;
   withLockContext(lockContext) {
     return new BatchEncryptQueryOperationWithLockContext(
       this.client,
@@ -723,18 +749,23 @@ var BatchEncryptQueryOperation = class extends EncryptionOperation {
       log.emit();
       return { data: [] };
     }
+    const { nonNullTerms } = filterNullTerms(this.terms);
+    if (nonNullTerms.length === 0) {
+      log.emit();
+      return { data: this.terms.map(() => null) };
+    }
     const result = await (0, import_result.withResult)(
       async () => {
         if (!this.client) throw noClientError();
         const { metadata } = this.getAuditData();
-        const queries = this.terms.map(
-          (term) => buildQueryPayload(term)
+        const queries = nonNullTerms.map(
+          ({ term }) => buildQueryPayload(term)
         );
         const encrypted = await (0, import_protect_ffi2.encryptQueryBulk)(this.client, {
           queries,
           unverifiedContext: metadata
         });
-        return assembleResults(this.terms, encrypted);
+        return assembleResults(this.terms.length, encrypted, nonNullTerms);
       },
       (error) => {
         log.set({ errorCode: getErrorCode(error) ?? "unknown" });
@@ -757,6 +788,9 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
     this.lockContext = lockContext;
     this.auditMetadata = auditMetadata;
   }
+  client;
+  terms;
+  lockContext;
   async execute() {
     const log = createRequestLogger();
     log.set({
@@ -768,6 +802,11 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
       log.emit();
       return { data: [] };
     }
+    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();
@@ -778,15 +817,15 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
       async () => {
         if (!this.client) throw noClientError();
         const { metadata } = this.getAuditData();
-        const queries = this.terms.map(
-          (term) => buildQueryPayload(term, context)
+        const queries = nonNullTerms.map(
+          ({ term }) => buildQueryPayload(term, context)
         );
         const encrypted = await (0, import_protect_ffi2.encryptQueryBulk)(this.client, {
           queries,
           serviceToken: ctsToken,
           unverifiedContext: metadata
         });
-        return assembleResults(this.terms, encrypted);
+        return assembleResults(this.terms.length, encrypted, nonNullTerms);
       },
       (error) => {
         log.set({ errorCode: getErrorCode(error) ?? "unknown" });
@@ -806,25 +845,30 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
 var import_result2 = require("@byteslice/result");
 var import_protect_ffi3 = require("@cipherstash/protect-ffi");
 var createDecryptPayloads = (encryptedPayloads, lockContext) => {
-  return encryptedPayloads.map(({ id, data }) => ({
+  return encryptedPayloads.filter(({ data }) => data !== null).map(({ id, data }) => ({
     id,
     ciphertext: data,
     ...lockContext && { lockContext }
   }));
 };
+var createNullResult = (encryptedPayloads) => encryptedPayloads.map(({ id }) => ({ id, data: null }));
 var mapDecryptedDataToResult = (encryptedPayloads, decryptedData) => {
-  return decryptedData.map((decryptResult, i) => {
-    if ("error" in decryptResult) {
-      return {
-        id: encryptedPayloads[i].id,
-        error: decryptResult.error
-      };
+  const result = 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;
 };
 var BulkDecryptOperation = class extends EncryptionOperation {
   client;
@@ -849,10 +893,13 @@ var BulkDecryptOperation = class extends EncryptionOperation {
         if (!this.client) throw noClientError();
         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 (0, import_protect_ffi3.decryptBulkFallible)(this.client, {
-          ciphertexts: payloads,
+          ciphertexts: nonNullPayloads,
           unverifiedContext: metadata
         });
         return mapDecryptedDataToResult(this.encryptedPayloads, decryptedData);
@@ -904,13 +951,16 @@ var BulkDecryptOperationWithLockContext = class extends EncryptionOperation {
         if (context.failure) {
           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 (0, import_protect_ffi3.decryptBulkFallible)(client, {
-          ciphertexts: payloads,
+          ciphertexts: nonNullPayloads,
           serviceToken: context.data.ctsToken,
           unverifiedContext: metadata
         });
@@ -1549,7 +1599,7 @@ var BulkDecryptModelsOperationWithLockContext = class extends EncryptionOperatio
 var import_result4 = require("@byteslice/result");
 var import_protect_ffi5 = require("@cipherstash/protect-ffi");
 var createEncryptPayloads = (plaintexts, column, table, lockContext) => {
-  return plaintexts.map(({ id, plaintext }) => ({
+  return plaintexts.filter(({ plaintext }) => plaintext !== null).map(({ id, plaintext }) => ({
     id,
     plaintext,
     column: column.getName(),
@@ -1557,6 +1607,20 @@ var createEncryptPayloads = (plaintexts, column, table, lockContext) => {
     ...lockContext && { lockContext }
   }));
 };
+var createNullResult2 = (plaintexts) => plaintexts.map(({ id }) => ({ id, data: null }));
+var mapEncryptedDataToResult = (plaintexts, encryptedData) => {
+  const result = new Array(plaintexts.length);
+  let encryptedIndex = 0;
+  for (let i = 0; i < plaintexts.length; i++) {
+    if (plaintexts[i].plaintext === null) {
+      result[i] = { id: plaintexts[i].id, data: null };
+    } else {
+      result[i] = { id: plaintexts[i].id, data: encryptedData[encryptedIndex] };
+      encryptedIndex++;
+    }
+  }
+  return result;
+};
 var BulkEncryptOperation = class extends EncryptionOperation {
   client;
   plaintexts;
@@ -1589,20 +1653,20 @@ var BulkEncryptOperation = class extends EncryptionOperation {
         if (!this.plaintexts || this.plaintexts.length === 0) {
           return [];
         }
-        const payloads = createEncryptPayloads(
+        const nonNullPayloads = createEncryptPayloads(
           this.plaintexts,
           this.column,
           this.table
         );
+        if (nonNullPayloads.length === 0) {
+          return createNullResult2(this.plaintexts);
+        }
         const { metadata } = this.getAuditData();
         const encryptedData = await (0, import_protect_ffi5.encryptBulk)(this.client, {
-          plaintexts: payloads,
+          plaintexts: nonNullPayloads,
           unverifiedContext: metadata
         });
-        return encryptedData.map((data, i) => ({
-          id: this.plaintexts[i].id,
-          data
-        }));
+        return mapEncryptedDataToResult(this.plaintexts, encryptedData);
       },
       (error) => {
         log.set({ errorCode: getErrorCode(error) ?? "unknown" });
@@ -1659,22 +1723,22 @@ var BulkEncryptOperationWithLockContext = class extends EncryptionOperation {
         if (context.failure) {
           throw new Error(`[encryption]: ${context.failure.message}`);
         }
-        const payloads = createEncryptPayloads(
+        const nonNullPayloads = createEncryptPayloads(
           plaintexts,
           column,
           table,
           context.data.context
         );
+        if (nonNullPayloads.length === 0) {
+          return createNullResult2(plaintexts);
+        }
         const { metadata } = this.getAuditData();
         const encryptedData = await (0, import_protect_ffi5.encryptBulk)(client, {
-          plaintexts: payloads,
+          plaintexts: nonNullPayloads,
           serviceToken: context.data.ctsToken,
           unverifiedContext: metadata
         });
-        return encryptedData.map((data, i) => ({
-          id: plaintexts[i].id,
-          data
-        }));
+        return mapEncryptedDataToResult(plaintexts, encryptedData);
       },
       (error) => {
         log.set({ errorCode: getErrorCode(error) ?? "unknown" });
@@ -1804,6 +1868,10 @@ var import_result6 = require("@byteslice/result");
 var import_protect_ffi6 = require("@cipherstash/protect-ffi");
 var DecryptOperation = class extends EncryptionOperation {
   client;
+  // Internally widened to allow null so the runtime guard below can
+  // short-circuit on legacy / manually-NULLed rows. The public
+  // `Encryption.decrypt()` signature still rejects null at the type
+  // layer; this is defense in depth for direct construction.
   encryptedData;
   constructor(client, encryptedData) {
     super();
@@ -1824,6 +1892,9 @@ var DecryptOperation = class extends EncryptionOperation {
         if (!this.client) {
           throw noClientError();
         }
+        if (this.encryptedData === null) {
+          return null;
+        }
         const { metadata } = this.getAuditData();
         return await (0, import_protect_ffi6.decrypt)(this.client, {
           ciphertext: this.encryptedData,
@@ -1874,6 +1945,9 @@ var DecryptOperationWithLockContext = class extends EncryptionOperation {
         if (!client) {
           throw noClientError();
         }
+        if (encryptedData === null) {
+          return null;
+        }
         const { metadata } = this.getAuditData();
         const context = await this.lockContext.getLockContext();
         if (context.failure) {
@@ -2001,6 +2075,10 @@ var import_result8 = require("@byteslice/result");
 var import_protect_ffi7 = require("@cipherstash/protect-ffi");
 var EncryptOperation = class extends EncryptionOperation {
   client;
+  // Internally widened to allow null so the runtime guard below can
+  // short-circuit. The public `Encryption.encrypt()` signature still
+  // rejects null at the type layer; this is defense in depth for callers
+  // that reach this class through casts or dynamic field walking.
   plaintext;
   column;
   table;
@@ -2027,6 +2105,9 @@ var EncryptOperation = class extends EncryptionOperation {
         if (!this.client) {
           throw noClientError();
         }
+        if (this.plaintext === null) {
+          return null;
+        }
         if (typeof this.plaintext === "number" && Number.isNaN(this.plaintext)) {
           throw new Error("[encryption]: Cannot encrypt NaN value");
         }
@@ -2088,6 +2169,9 @@ var EncryptOperationWithLockContext = class extends EncryptionOperation {
         if (!client) {
           throw noClientError();
         }
+        if (plaintext === null) {
+          return null;
+        }
         const { metadata } = this.getAuditData();
         const context = await this.lockContext.getLockContext();
         if (context.failure) {
@@ -2233,6 +2317,9 @@ var EncryptQueryOperation = class extends EncryptionOperation {
     this.plaintext = plaintext;
     this.opts = opts;
   }
+  client;
+  plaintext;
+  opts;
   withLockContext(lockContext) {
     return new EncryptQueryOperationWithLockContext(
       this.client,
@@ -2251,7 +2338,12 @@ var EncryptQueryOperation = class extends EncryptionOperation {
       queryType: this.opts.queryType,
       lockContext: false
     });
-    const validationError = validateNumericValue(this.plaintext);
+    if (this.plaintext === null || this.plaintext === void 0) {
+      log.emit();
+      return { data: null };
+    }
+    const plaintext = this.plaintext;
+    const validationError = validateNumericValue(plaintext);
     if (validationError?.failure) {
       log.emit();
       return { failure: validationError.failure };
@@ -2263,15 +2355,15 @@ var EncryptQueryOperation = class extends EncryptionOperation {
         const { indexType, queryOp } = resolveIndexType(
           this.opts.column,
           this.opts.queryType,
-          this.plaintext
+          plaintext
         );
         assertValueIndexCompatibility(
-          this.plaintext,
+          plaintext,
           indexType,
           this.opts.column.getName()
         );
         const encrypted = await (0, import_protect_ffi8.encryptQuery)(this.client, {
-          plaintext: this.plaintext,
+          plaintext,
           column: this.opts.column.getName(),
           table: this.opts.table.tableName,
           indexType,
@@ -2305,6 +2397,10 @@ var EncryptQueryOperationWithLockContext = class extends EncryptionOperation {
     this.lockContext = lockContext;
     this.auditMetadata = auditMetadata;
   }
+  client;
+  plaintext;
+  opts;
+  lockContext;
   async execute() {
     const log = createRequestLogger();
     log.set({
@@ -2314,7 +2410,12 @@ var EncryptQueryOperationWithLockContext = class extends EncryptionOperation {
       queryType: this.opts.queryType,
       lockContext: true
     });
-    const validationError = validateNumericValue(this.plaintext);
+    if (this.plaintext === null || this.plaintext === void 0) {
+      log.emit();
+      return { data: null };
+    }
+    const plaintext = this.plaintext;
+    const validationError = validateNumericValue(plaintext);
     if (validationError?.failure) {
       log.emit();
       return { failure: validationError.failure };
@@ -2332,15 +2433,15 @@ var EncryptQueryOperationWithLockContext = class extends EncryptionOperation {
         const { indexType, queryOp } = resolveIndexType(
           this.opts.column,
           this.opts.queryType,
-          this.plaintext
+          plaintext
         );
         assertValueIndexCompatibility(
-          this.plaintext,
+          plaintext,
           indexType,
           this.opts.column.getName()
         );
         const encrypted = await (0, import_protect_ffi8.encryptQuery)(this.client, {
-          plaintext: this.plaintext,
+          plaintext,
           column: this.opts.column.getName(),
           table: this.opts.table.tableName,
           indexType,
@@ -2536,6 +2637,13 @@ var EncryptionClient = class {
    *      .withLockContext(lockContext)
    * ```
    *
+   * @remarks
+   * The public input type rejects null, but at runtime `decrypt` will
+   * short-circuit and return null when given a null ciphertext
+   * (defense in depth for legacy / manually-NULLed DB rows reached via
+   * casts or dynamic field walking). The narrow return type holds for
+   * any caller that respects the input contract.
+   *
    * @see {@link LockContext}
    * @see {@link DecryptOperation}
    */
@@ -2815,6 +2923,16 @@ var Encryption = async (config) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BatchEncryptQueryOperation,
+  BulkDecryptModelsOperation,
+  BulkDecryptOperation,
+  BulkEncryptModelsOperation,
+  BulkEncryptOperation,
+  DecryptModelOperation,
+  DecryptOperation,
+  EncryptModelOperation,
+  EncryptOperation,
+  EncryptQueryOperation,
   Encryption,
   EncryptionClient,
   noClientError