@cipherstash/protect-ffi 0.21.4 → 0.23.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,22 +1,23 @@
 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;
+    function isEncrypted(encrypted: unknown): boolean;
     function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
     function decryptBulk(client: Client, opts: DecryptBulkOptions): Promise<JsPlaintext[]>;
     function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
-    function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted>;
-    function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
+    function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery>;
+    function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery)[]>;
     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;
@@ -37,12 +38,12 @@ export type DecryptResult = {
 export declare function newClient(opts: NewClientOptions): Promise<Client>;
 export declare function encrypt(client: Client, opts: EncryptOptions): Promise<Encrypted>;
 export declare function decrypt(client: Client, opts: DecryptOptions): Promise<JsPlaintext>;
-export declare function isEncrypted(encrypted: Encrypted): boolean;
+export declare function isEncrypted(encrypted: unknown): boolean;
 export declare function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
 export declare function decryptBulk(client: Client, opts: DecryptBulkOptions): Promise<JsPlaintext[]>;
 export declare function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
-export declare function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted>;
-export declare function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
+export declare function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery>;
+export declare function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery)[]>;
 /**
  * Test-only helper: ensures a keyset with the given name exists, creating it if necessary,
  * and grants the current client access. Not safe for concurrent use — intended for
@@ -67,69 +68,126 @@ export type Context = {
     identityClaim: string[];
 };
 /**
- * Represents encrypted data in the EQL format.
+ * EQL v2.3 **storage** payload — the shape persisted in an `eql_v2_encrypted`
+ * column. Returned by {@link encrypt} / {@link encryptBulk}; the only shape
+ * {@link decrypt} accepts.
  *
- * 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 on `k`. A storage payload always carries the ciphertext — `c`
+ * on the scalar variant, or `sv[0].c` on the STE-vector variant. Query payloads
+ * carry no ciphertext and are a separate type — see {@link EncryptedQuery}.
  *
- * 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(...)
+ * }
+ * ```
+ */
+export type Encrypted = EncryptedScalar | EncryptedSteVec;
+/** Scalar EQL v2.3 storage payload (`k: "ct"`). */
+export type EncryptedScalar = {
+    k: 'ct';
+    /** EQL schema version */
+    v: number;
+    /** Table and column identifier */
+    i: {
+        t: string;
+        c: string;
+    };
+    /** Encrypted ciphertext (mp_base85). Always present on a storage payload. */
+    c: string;
+    /** HMAC-SHA256 term — present when a `unique` index is configured. */
+    hm?: string;
+    /** Bloom filter (set bit positions) — present when a `match` index is configured. */
+    bf?: number[];
+    /** Block ORE u64_8_256 term — present when an `ore` index is configured. */
+    ob?: string[];
+};
+/**
+ * STE-vector EQL v2.3 storage payload (`k: "sv"`). Carries the per-selector
+ * entries in `sv`; the root document ciphertext lives at `sv[0].c`.
+ */
+export type EncryptedSteVec = {
+    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;
+};
+/**
+ * EQL v2.3 **query** payload — an encrypted search term. Returned, alongside
+ * {@link Encrypted}, by {@link encryptQuery} / {@link encryptQueryBulk}.
+ *
+ * Unlike a storage payload, a query payload carries no ciphertext (`c`): it is
+ * matched against stored values, never decrypted. It must not be passed to
+ * {@link decrypt}.
  *
- * Note: The ciphertext field (c) is serialized in MessagePack Base85 format.
+ * This covers the query shapes protect-ffi currently emits. cipherstash-client
+ * additionally defines `k: "sv"` hmac / ore / containment query terms; the FFI
+ * does not emit those today — JSON containment queries come back as an
+ * {@link EncryptedSteVec} storage payload.
+ */
+export type EncryptedQuery = EncryptedScalarQuery | EncryptedSteVecSelector;
+/**
+ * Scalar query term (`k: "ct"`, no ciphertext) — a `unique` / `match` / `ore`
+ * lookup term carrying exactly one of `hm`, `bf`, or `ob`.
  */
-export type Encrypted = {
-    /** The table and column identifier */
+export type EncryptedScalarQuery = {
+    k: 'ct';
+    /** EQL schema version */
+    v: number;
+    /** Table and column identifier */
     i: {
         t: string;
         c: string;
     };
-    /** The encryption version */
+    /** Query payloads carry no ciphertext — discriminates against {@link EncryptedScalar}. */
+    c?: never;
+} & ({
+    hm: string;
+} | {
+    bf: number[];
+} | {
+    ob: string[];
+});
+/**
+ * STE-vector selector query payload (`ste_vec_selector`) — a tokenized JSON
+ * path selector, no ciphertext.
+ */
+export type EncryptedSteVecSelector = {
+    k: 'sv';
     v: number;
-    /** The encrypted ciphertext (mp_base85 encoded, optional for query-mode 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 */
-    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[];
+    i: {
+        t: string;
+        c: string;
+    };
+    /** Tokenized selector for path queries. */
+    s: string;
+    sv?: never;
 };
 /**
- * Body of an EQL ciphertext, used recursively in SteVec entries.
+ * 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 EqlCiphertextBody = {
-    /** The encrypted ciphertext (mp_base85 encoded) */
-    c?: string;
-    /** Whether this entry is part of an array */
+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 +228,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 +255,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.23.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.23.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.23.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.23.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.23.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.23.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.23.0"
   }
 }