@cipherstash/protect-ffi 0.21.4 → 0.22.0

package/lib/index.cjs

@@ -47,6 +47,7 @@ exports.encryptQueryBulk = encryptQueryBulk;
 exports.ensureKeyset = ensureKeyset;
 const credentials_js_1 = require("./credentials.js");
 const native = __importStar(require("./load.cjs"));
+const normalizeEncryptConfig_js_1 = require("./normalizeEncryptConfig.js");
 var credentials_js_2 = require("./credentials.js");
 Object.defineProperty(exports, "withEnvCredentials", { enumerable: true, get: function () { return credentials_js_2.withEnvCredentials; } });
 class ProtectError extends Error {
@@ -81,9 +82,15 @@ function inferErrorCode(message) {
     if (message.includes(' index configured')) {
         return 'MISSING_INDEX';
     }
-    if (message.includes("ste_vec index requires cast_as: 'json'")) {
+    if (message.includes('requires plaintext_type: json')) {
         return 'STE_VEC_REQUIRES_JSON_CAST_AS';
     }
+    if (message.includes('requires plaintext_type: text')) {
+        return 'MATCH_REQUIRES_TEXT';
+    }
+    if (message.includes('unsupported config version')) {
+        return 'UNSUPPORTED_CONFIG_VERSION';
+    }
     return 'UNKNOWN';
 }
 function normalizeError(err) {
@@ -117,7 +124,7 @@ function wrapSync(fn) {
 }
 function newClient(opts) {
     return wrapAsync(() => native.newClient({
-        ...opts,
+        encryptConfig: (0, normalizeEncryptConfig_js_1.normalizeEncryptConfig)(opts.encryptConfig),
         clientOpts: (0, credentials_js_1.withEnvCredentials)(opts.clientOpts),
     }));
 }

package/lib/index.d.cts

@@ -1,11 +1,12 @@
 import { type CredentialOpts } from './credentials.js';
+import { type NativeEncryptConfig } from './normalizeEncryptConfig.js';
 export { withEnvCredentials, type EnvReader, type CredentialOpts, } from './credentials.js';
 declare const sym: unique symbol;
 export type Client = {
     readonly [sym]: unknown;
 };
 declare module './load.cjs' {
-    function newClient(opts: NewClientOptions): Promise<Client>;
+    function newClient(opts: NativeNewClientOptions): Promise<Client>;
     function encrypt(client: Client, opts: EncryptOptions): Promise<Encrypted>;
     function decrypt(client: Client, opts: DecryptOptions): Promise<JsPlaintext>;
     function isEncrypted(encrypted: Encrypted): boolean;
@@ -16,7 +17,7 @@ declare module './load.cjs' {
     function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
     function ensureKeyset(opts: EnsureKeysetOpts): Promise<EnsureKeysetResult>;
 }
-export type ProtectErrorCode = 'INVARIANT_VIOLATION' | 'UNKNOWN_QUERY_OP' | 'UNKNOWN_COLUMN' | 'MISSING_INDEX' | 'INVALID_QUERY_INPUT' | 'INVALID_JSON_PATH' | 'STE_VEC_REQUIRES_JSON_CAST_AS' | 'UNKNOWN';
+export type ProtectErrorCode = 'INVARIANT_VIOLATION' | 'UNKNOWN_QUERY_OP' | 'UNKNOWN_COLUMN' | 'MISSING_INDEX' | 'INVALID_QUERY_INPUT' | 'INVALID_JSON_PATH' | 'STE_VEC_REQUIRES_JSON_CAST_AS' | 'MATCH_REQUIRES_TEXT' | 'UNSUPPORTED_CONFIG_VERSION' | 'UNKNOWN';
 export declare class ProtectError extends Error {
     code: ProtectErrorCode;
     details?: unknown;
@@ -67,69 +68,99 @@ export type Context = {
     identityClaim: string[];
 };
 /**
- * Represents encrypted data in the EQL format.
+ * Represents an EQL v2.3 payload returned by the FFI.
  *
- * This TypeScript type mirrors the Rust `EqlCiphertext` structure from `cipherstash-client`.
- * The Rust type hierarchy is:
- * - `EqlCiphertext` (identifier + version + body)
- *   - `EqlCiphertextBody` (ciphertext + SEM fields + array flag)
- *     - `EqlSEM` (all searchable encrypted metadata fields)
+ * Discriminated union keyed on `k`. Narrow on `k` before accessing variant-only
+ * fields:
  *
- * In the serialized JSON format, `#[serde(flatten)]` is used in Rust to produce a flat
- * structure where all fields appear at the top level rather than nested.
+ * ```ts
+ * if (payload.k === 'sv') {
+ *   payload.sv?.forEach(...)
+ * }
+ * ```
  *
- * Note: The ciphertext field (c) is serialized in MessagePack Base85 format.
+ * - `k: "ct"` — scalar payload (storage or query for `unique` / `match` / `ore`
+ *   indexes). Storage payloads always carry `c`; query payloads omit `c` and
+ *   carry exactly one of `hm`, `bf`, or `ob`.
+ * - `k: "sv"` — STE-vector payload. The FFI emits this for SteVec storage
+ *   *and* for JSON containment queries (`ste_vec_term`), both of which carry
+ *   per-selector entries in `sv` with the root document ciphertext at
+ *   `sv[0].c`. Selector queries (`ste_vec_selector`) instead carry a single
+ *   tokenized selector `s` and omit `sv`.
  */
-export type Encrypted = {
-    /** The table and column identifier */
+export type Encrypted = EncryptedScalar | EncryptedSteVec;
+/** Scalar EQL v2.3 payload (`k: "ct"`). */
+export type EncryptedScalar = {
+    k: 'ct';
+    /** EQL schema version */
+    v: number;
+    /** Table and column identifier */
     i: {
         t: string;
         c: string;
     };
-    /** The encryption version */
-    v: number;
-    /** The encrypted ciphertext (mp_base85 encoded, optional for query-mode payloads) */
+    /** Encrypted ciphertext (mp_base85). Required on storage payloads; absent on query payloads. */
     c?: string;
-    /** Whether this encrypted value is part of an array */
-    a?: boolean;
-    /** ORE block index for 64-bit integers */
-    ob?: string[];
-    /** Bloom filter for approximate match queries */
-    bf?: number[];
-    /** HMAC-SHA256 hash for exact matches */
+    /** HMAC-SHA256 hash — `unique` index term on storage, or `unique` lookup term on queries. */
     hm?: string;
-    /** Selector value for field selection (SteVec) */
-    s?: string;
-    /** Blake3 hash for exact matches (SteVec) */
-    b3?: string;
-    /** ORE CLLW fixed-width index for 64-bit values (SteVec) */
-    ocf?: string;
-    /** ORE CLLW variable-width index for strings (SteVec) */
-    ocv?: string;
-    /** Structured encryption vector entries (recursive) */
-    sv?: EqlCiphertextBody[];
+    /** Bloom filter (set bit positions) — `match` index term on storage, or `match` lookup term on queries. */
+    bf?: number[];
+    /** Block ORE u64_8_256 term — `ore` index term on storage, or `ore` comparison term on queries. */
+    ob?: string[];
 };
 /**
- * Body of an EQL ciphertext, used recursively in SteVec entries.
+ * STE-vector EQL v2.3 payload (`k: "sv"`). The FFI emits two disjoint shapes:
+ *
+ * - {@link EncryptedSteVecStorage} for storage encryption and JSON containment
+ *   queries — carries a non-empty `sv` with the root ciphertext at `sv[0].c`.
+ * - {@link EncryptedSteVecSelector} for `ste_vec_selector` queries — carries
+ *   only a tokenized selector `s`.
  */
-export type EqlCiphertextBody = {
-    /** The encrypted ciphertext (mp_base85 encoded) */
-    c?: string;
-    /** Whether this entry is part of an array */
+export type EncryptedSteVec = EncryptedSteVecStorage | EncryptedSteVecSelector;
+/** SteVec storage payload (also used for containment queries). */
+export type EncryptedSteVecStorage = {
+    k: 'sv';
+    v: number;
+    i: {
+        t: string;
+        c: string;
+    };
+    /** Per-selector entries; root document ciphertext lives at `sv[0].c`. */
+    sv: [SteVecEntry, ...SteVecEntry[]];
+    s?: never;
+};
+/** SteVec selector query payload (`ste_vec_selector`). */
+export type EncryptedSteVecSelector = {
+    k: 'sv';
+    v: number;
+    i: {
+        t: string;
+        c: string;
+    };
+    /** Tokenized selector for path queries. */
+    s: string;
+    sv?: never;
+};
+/**
+ * One entry inside a SteVec payload (`k: "sv"`).
+ *
+ * Every element carries `s` (selector), `c` (entry ciphertext), and exactly one
+ * per-element equality / ordering term (`hm` or `oc`).
+ */
+export type SteVecEntry = {
+    /** Hex-encoded tokenized selector — deterministic per (path, key) */
+    s: string;
+    /** Per-entry encrypted record (mp_base85 encoded) */
+    c: string;
+    /** Array marker — true when the selector points at a JSON array context */
     a?: boolean;
-    /** Selector value for field selection */
-    s?: string;
-    /** Blake3 hash for exact matches */
-    b3?: string;
-    /** ORE CLLW fixed-width index */
-    ocf?: string;
-    /** ORE CLLW variable-width index */
-    ocv?: string;
-    /** Nested SteVec entries (for deeply nested JSON) */
-    sv?: EqlCiphertextBody[];
-};
-/** @deprecated Use EqlCiphertextBody instead */
-export type SteVecEntry = EqlCiphertextBody;
+    /** Per-entry HMAC term for non-orderable leaves (objects, arrays, booleans, null) */
+    hm?: string;
+    /** Per-entry CLLW ORE term for orderable leaves (strings, numbers) — Standard mode */
+    oc?: string;
+};
+/** @deprecated Use SteVecEntry instead */
+export type EqlCiphertextBody = SteVecEntry;
 export type EncryptConfig = {
     v: number;
     tables: Record<string, Record<string, Column>>;
@@ -170,10 +201,19 @@ export type ArrayIndexMode = 'all' | 'none' | {
     wildcard?: boolean;
     position?: boolean;
 };
+/**
+ * Encoding mode for SteVec indexes.
+ *
+ * - `standard`: standard encoding (default).
+ * - `compat`: backwards-compatible encoding. Set explicitly to preserve the
+ *   pre-0.34.1-alpha.7 behaviour.
+ */
+export type SteVecMode = 'compat' | 'standard';
 export type SteVecIndexOpts = {
     prefix: string;
     term_filters?: TokenFilter[];
     array_index_mode?: ArrayIndexMode;
+    mode?: SteVecMode;
 };
 export type Tokenizer = {
     kind: 'standard';
@@ -188,6 +228,11 @@ export type NewClientOptions = {
     encryptConfig: EncryptConfig;
     clientOpts?: ClientOpts;
 };
+/** Options passed to the native `newClient` after vocabulary normalization. */
+type NativeNewClientOptions = {
+    encryptConfig: NativeEncryptConfig;
+    clientOpts?: ClientOpts;
+};
 export type ClientOpts = CredentialOpts & {
     keyset?: KeysetIdentifier;
 };

package/lib/normalizeEncryptConfig.d.ts

@@ -0,0 +1,29 @@
+import type { Column, EncryptConfig } from './index.cjs';
+/**
+ * The `cast_as` vocabulary the native addon (cipherstash-config's
+ * `CanonicalEncryptionConfig`) accepts. The public `CastAs` union contains
+ * three JS-only members (`string`, `number`, `bigint`) that are remapped to
+ * their canonical equivalents (`text`, `float`, `big_int`) before being
+ * handed to the native side.
+ */
+export type NativeCastAs = 'text' | 'float' | 'big_int' | 'boolean' | 'date' | 'json' | 'timestamp';
+/** A column after normalization — `cast_as` is in the canonical vocabulary. */
+export type NativeColumn = Omit<Column, 'cast_as'> & {
+    cast_as?: NativeCastAs;
+};
+/** An encrypt config in the vocabulary the native addon expects. */
+export type NativeEncryptConfig = Omit<EncryptConfig, 'tables'> & {
+    tables: Record<string, Record<string, NativeColumn>>;
+};
+/**
+ * Translate a public `EncryptConfig` into the vocabulary the native addon
+ * expects:
+ *
+ * - `cast_as` values `string`/`number`/`bigint` become `text`/`float`/`big_int`.
+ * - `ste_vec` indexes without an explicit `array_index_mode` default to
+ *   `'none'` — the library would otherwise default to `'all'`.
+ *
+ * `mode` is intentionally left untouched: an omitted `mode` follows the
+ * library default (`standard`). The input config is never mutated.
+ */
+export declare function normalizeEncryptConfig(config: EncryptConfig): NativeEncryptConfig;

package/lib/normalizeEncryptConfig.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEncryptConfig = normalizeEncryptConfig;
+/**
+ * The native addon uses a different `cast_as` vocabulary than the public JS
+ * API. These three JS values have no direct equivalent and are remapped to
+ * their canonical names.
+ */
+const CAST_AS_REMAP = {
+    string: 'text',
+    number: 'float',
+    bigint: 'big_int',
+};
+/**
+ * Translate a public `EncryptConfig` into the vocabulary the native addon
+ * expects:
+ *
+ * - `cast_as` values `string`/`number`/`bigint` become `text`/`float`/`big_int`.
+ * - `ste_vec` indexes without an explicit `array_index_mode` default to
+ *   `'none'` — the library would otherwise default to `'all'`.
+ *
+ * `mode` is intentionally left untouched: an omitted `mode` follows the
+ * library default (`standard`). The input config is never mutated.
+ */
+function normalizeEncryptConfig(config) {
+    const tables = {};
+    for (const [tableName, columns] of Object.entries(config.tables)) {
+        const normalizedColumns = {};
+        for (const [columnName, column] of Object.entries(columns)) {
+            normalizedColumns[columnName] = normalizeColumn(column);
+        }
+        tables[tableName] = normalizedColumns;
+    }
+    return { ...config, tables };
+}
+function normalizeColumn(column) {
+    const { cast_as, indexes, ...rest } = column;
+    const normalized = { ...rest };
+    if (cast_as !== undefined) {
+        normalized.cast_as = remapCastAs(cast_as);
+    }
+    const steVec = indexes?.ste_vec;
+    if (indexes !== undefined) {
+        normalized.indexes = indexes;
+    }
+    if (steVec !== undefined && steVec.array_index_mode === undefined) {
+        normalized.indexes = {
+            ...indexes,
+            ste_vec: { ...steVec, array_index_mode: 'none' },
+        };
+    }
+    return normalized;
+}
+function remapCastAs(value) {
+    if (value in CAST_AS_REMAP) {
+        return CAST_AS_REMAP[value];
+    }
+    // The remaining `CastAs` members are already canonical `NativeCastAs` values.
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.21.4",
+  "version": "0.22.0",
   "description": "",
   "main": "./lib/index.cjs",
   "scripts": {
@@ -75,11 +75,11 @@
     "vite": "^8.0.5"
   },
   "optionalDependencies": {
-    "@cipherstash/protect-ffi-darwin-x64": "0.21.4",
-    "@cipherstash/protect-ffi-darwin-arm64": "0.21.4",
-    "@cipherstash/protect-ffi-win32-x64-msvc": "0.21.4",
-    "@cipherstash/protect-ffi-linux-x64-gnu": "0.21.4",
-    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.21.4",
-    "@cipherstash/protect-ffi-linux-x64-musl": "0.21.4"
+    "@cipherstash/protect-ffi-darwin-x64": "0.22.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.22.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.22.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.22.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.22.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.22.0"
   }
 }