@cipherstash/stack 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/wasm-inline.js

@@ -11,10 +11,134 @@ import {
 import {
   decrypt as wasmDecrypt,
   encrypt as wasmEncrypt,
+  encryptQuery as wasmEncryptQuery,
+  encryptQueryBulk as wasmEncryptQueryBulk,
   isEncrypted as wasmIsEncrypted,
   newClient as wasmNewClient
 } from "@cipherstash/protect-ffi/wasm-inline";
 
+// src/types.ts
+var queryTypeToFfi = {
+  // v3 `_ord` domains carry `ope` instead — `resolveIndexType` swaps this
+  // static default for the ordering index the column actually configures.
+  orderAndRange: "ore",
+  freeTextSearch: "match",
+  equality: "unique",
+  steVecSelector: "ste_vec",
+  steVecTerm: "ste_vec",
+  searchableJson: "ste_vec"
+};
+var queryTypeToQueryOp = {
+  steVecSelector: "ste_vec_selector",
+  steVecTerm: "ste_vec_term"
+};
+
+// src/encryption/helpers/infer-index-type.ts
+function inferIndexType(column) {
+  const config = column.build();
+  const indexes = config.indexes;
+  if (!indexes || Object.keys(indexes).length === 0) {
+    throw new Error(`Column "${column.getName()}" has no indexes configured`);
+  }
+  if (indexes.unique) return "unique";
+  if (indexes.match) return "match";
+  if (indexes.ore) return "ore";
+  if (indexes.ope) return "ope";
+  if (indexes.ste_vec) return "ste_vec";
+  throw new Error(
+    `Column "${column.getName()}" has no suitable index for queries`
+  );
+}
+function inferQueryOpFromPlaintext(plaintext) {
+  if (typeof plaintext === "string") {
+    return "ste_vec_selector";
+  }
+  if (typeof plaintext === "object" || typeof plaintext === "number" || typeof plaintext === "boolean") {
+    return "ste_vec_term";
+  }
+  return "ste_vec_term";
+}
+function validateIndexType(column, indexType) {
+  const config = column.build();
+  const indexes = config.indexes ?? {};
+  const indexMap = {
+    unique: !!indexes.unique,
+    match: !!indexes.match,
+    ore: !!indexes.ore,
+    ope: !!indexes.ope,
+    ste_vec: !!indexes.ste_vec
+  };
+  if (!indexMap[indexType]) {
+    throw new Error(
+      `Index type "${indexType}" is not configured on column "${column.getName()}"`
+    );
+  }
+}
+function equalityOrderingIndex(column) {
+  if (!("getQueryCapabilities" in column)) return null;
+  if (!column.getQueryCapabilities().equality) return null;
+  const indexes = column.build().indexes ?? {};
+  if (indexes.unique) return null;
+  if (indexes.ore) return "ore";
+  if (indexes.ope) return "ope";
+  return null;
+}
+function resolveIndexType(column, queryType, plaintext) {
+  let indexType = queryType ? queryTypeToFfi[queryType] : inferIndexType(column);
+  if (queryType) {
+    if (queryType === "equality") {
+      const ordering = equalityOrderingIndex(column);
+      if (ordering) return { indexType: ordering };
+    }
+    if (queryType === "orderAndRange" && indexType === "ore") {
+      const indexes = column.build().indexes ?? {};
+      if (!indexes.ore && indexes.ope) indexType = "ope";
+    }
+    validateIndexType(column, indexType);
+    if (queryType === "searchableJson") {
+      if (plaintext === void 0 || plaintext === null) {
+        return { indexType };
+      }
+      return { indexType, queryOp: inferQueryOpFromPlaintext(plaintext) };
+    }
+    return { indexType, queryOp: queryTypeToQueryOp[queryType] };
+  }
+  if (indexType === "ste_vec") {
+    if (plaintext === void 0 || plaintext === null) {
+      return { indexType };
+    }
+    return { indexType, queryOp: inferQueryOpFromPlaintext(plaintext) };
+  }
+  return { indexType };
+}
+
+// src/encryption/helpers/validation.ts
+var INT64_MIN = -9223372036854775808n;
+var INT64_MAX = 9223372036854775807n;
+function isBigintOutOfInt64Range(value) {
+  return typeof value === "bigint" && (value < INT64_MIN || value > INT64_MAX);
+}
+function assertValidNumericValue(value) {
+  if (typeof value === "number" && Number.isNaN(value)) {
+    throw new Error("[encryption]: Cannot encrypt NaN value");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error("[encryption]: Cannot encrypt Infinity value");
+  }
+  if (isBigintOutOfInt64Range(value)) {
+    throw new Error(
+      "[encryption]: Cannot encrypt bigint value out of int64 range"
+    );
+  }
+}
+function assertValueIndexCompatibility(value, indexType, columnName) {
+  if ((typeof value === "number" || typeof value === "bigint") && indexType === "match") {
+    throw new Error(
+      `[encryption]: Cannot use 'match' index with numeric value on column "${columnName}". The 'freeTextSearch' index only supports string values. Configure the column with 'orderAndRange()' or 'equality()' for numeric queries.`
+    );
+  }
+}
+
 // src/schema/match-defaults.ts
 function defaultMatchOpts() {
   return {
@@ -4748,6 +4872,134 @@ var WasmEncryptionClient = class {
   isEncrypted(value) {
     return wasmIsEncrypted(value);
   }
+  /**
+   * Encrypt a QUERY TERM (search needle) for a queryable v3 column —
+   * equality, free-text match, ORE range, or JSON containment/selector.
+   *
+   * The returned term is **ciphertext-free**: it is matched against stored
+   * envelopes, never decrypted, so it is safe to log-scrub less aggressively
+   * than storage payloads (though it still derives from the plaintext).
+   * Interpolate it as a parameter and cast to the column's
+   * `eql_v3.query_<domain>` type to reach the indexed operators — the domain
+   * suffix mirrors the storage domain (`eql_v3_text_eq` →
+   * `eql_v3.query_text_eq`; irregular: `eql_v3_json` → `eql_v3.query_jsonb`).
+   *
+   * @example Equality (unique index)
+   * ```ts
+   * const term = await client.encryptQuery("alice@example.com", {
+   *   table: users, column: users.email, queryType: "equality",
+   * })
+   * // postgres-js:
+   * sql`SELECT * FROM users
+   *     WHERE email = ${term}::jsonb::eql_v3.query_text_eq`
+   * ```
+   *
+   * @example Free-text match (bloom index — one-sided, fuzzy)
+   * ```ts
+   * const term = await client.encryptQuery("needle", {
+   *   table: users, column: users.bio, queryType: "freeTextSearch",
+   * })
+   * sql`SELECT * FROM users
+   *     WHERE eql_v3.contains(bio, ${term}::jsonb::eql_v3.query_text_search)`
+   * ```
+   *
+   * @example Range / ORDER BY (ORE index)
+   * ```ts
+   * const term = await client.encryptQuery(42, {
+   *   table: users, column: users.age, queryType: "orderAndRange",
+   * })
+   * sql`SELECT * FROM users
+   *     WHERE eql_v3.gte(age, ${term}::jsonb::eql_v3.query_integer_ord)`
+   * ```
+   *
+   * @example Encrypted JSON — containment and JSONPath selector
+   * ```ts
+   * // Object value → containment needle (a v3 envelope):
+   * const contains = await client.encryptQuery({ role: "admin" }, {
+   *   table: users, column: users.prefs, queryType: "searchableJson",
+   * })
+   * sql`SELECT * FROM users
+   *     WHERE prefs @> ${contains}::jsonb::eql_v3.query_jsonb`
+   *
+   * // String value → JSONPath selector. NOTE: v3 has no encrypted-selector
+   * // envelope — this returns the BARE selector-hash string, bound as the
+   * // text argument of -> / ->>:
+   * const selector = await client.encryptQuery("$.role", {
+   *   table: users, column: users.prefs, queryType: "searchableJson",
+   * })
+   * sql`SELECT prefs -> ${selector} FROM users`
+   * ```
+   *
+   * @param plaintext - The search needle. `null`/`undefined` returns `null`
+   *   without contacting ZeroKMS (nothing to search for), mirroring the
+   *   native client.
+   * @param opts - Table, column, and (optionally) which index to target —
+   *   see {@link WasmEncryptQueryOptions.queryType} for the inference rules.
+   * @returns The v3 query term, or `null` for null plaintext.
+   * @throws When the requested `queryType` isn't configured on the column,
+   *   the column has no indexes at all, the value fails the same pre-flight
+   *   validation the native client runs (NaN / Infinity / out-of-int64
+   *   bigint, or a numeric value against a `freeTextSearch` index), or
+   *   encryption fails. Errors THROW, consistent with this surface's
+   *   `encrypt`/`decrypt` (the native entry's `{ data } | { failure }`
+   *   envelope lives on the Node client only).
+   */
+  async encryptQuery(plaintext, opts) {
+    if (plaintext === null || plaintext === void 0) return null;
+    return await wasmEncryptQuery(
+      // biome-ignore lint/plugin: the FFI handle is an opaque wasm-bindgen pointer with no JS-side type
+      this.client,
+      // biome-ignore lint/plugin: the term crosses the serde boundary, whose shape protect-ffi types as `any`
+      toFfiQueryTerm(plaintext, opts)
+    );
+  }
+  /**
+   * Batch form of {@link encryptQuery} — one ZeroKMS round trip for many
+   * terms, which is the shape query builders want (encrypt every needle in
+   * a WHERE clause together).
+   *
+   * Position-stable: the result array is index-aligned with `terms`, and a
+   * `null`/`undefined` value yields `null` at the same index (an all-null
+   * batch short-circuits without calling ZeroKMS). Terms may mix query
+   * types and columns freely.
+   *
+   * @example
+   * ```ts
+   * const [emailEq, bioMatch] = await client.encryptQueryBulk([
+   *   { value: "alice@example.com", table: users, column: users.email,
+   *     queryType: "equality" },
+   *   { value: "needle", table: users, column: users.bio,
+   *     queryType: "freeTextSearch" },
+   * ])
+   * ```
+   *
+   * @param terms - The needles to encrypt; see {@link WasmQueryTerm}.
+   * @returns Index-aligned array of v3 query terms (or `null` per null value).
+   * @throws As {@link encryptQuery} — the first invalid term aborts the batch.
+   */
+  async encryptQueryBulk(terms) {
+    const live = [];
+    terms.forEach((term, at) => {
+      if (term.value !== null && term.value !== void 0)
+        live.push({ term, at });
+    });
+    const out = terms.map(() => null);
+    if (live.length === 0) return out;
+    const ffiTerms = live.map(({ term }) => toFfiQueryTerm(term.value, term));
+    const encrypted = await wasmEncryptQueryBulk(
+      // biome-ignore lint/plugin: the FFI handle is an opaque wasm-bindgen pointer with no JS-side type
+      this.client,
+      // biome-ignore lint/plugin: the batch crosses the serde boundary, whose shape protect-ffi types as `any`
+      {
+        queries: ffiTerms
+      }
+    );
+    encrypted.forEach((value, i) => {
+      const slot = live[i];
+      if (slot) out[slot.at] = value;
+    });
+    return out;
+  }
 };
 async function Encryption(config) {
   const { schemas, config: clientConfig } = config;
@@ -4806,6 +5058,22 @@ function getColumnName(col) {
     "[encryption]: opts.column must be a column builder exposing getName()"
   );
 }
+function toFfiQueryTerm(value, opts) {
+  assertValidNumericValue(value);
+  const { indexType, queryOp } = resolveIndexType(
+    opts.column,
+    opts.queryType,
+    value
+  );
+  assertValueIndexCompatibility(value, indexType, getColumnName(opts.column));
+  return {
+    plaintext: value,
+    table: opts.table.tableName,
+    column: getColumnName(opts.column),
+    indexType,
+    ...queryOp ? { queryOp } : {}
+  };
+}
 var warnedStrategyDeprecated = false;
 function warnStrategyDeprecated() {
   if (warnedStrategyDeprecated) return;