@cipherstash/protect-ffi 0.25.0 → 0.27.0

package/lib/eql-v3.d.ts

@@ -0,0 +1,90 @@
+import type { Bigint } from './eql-v3-types/Bigint.js';
+import type { BigintEq } from './eql-v3-types/BigintEq.js';
+import type { BigintOrd } from './eql-v3-types/BigintOrd.js';
+import type { BigintOrdOpe } from './eql-v3-types/BigintOrdOpe.js';
+import type { BigintOrdOre } from './eql-v3-types/BigintOrdOre.js';
+import type { Boolean as EqlV3Boolean } from './eql-v3-types/Boolean.js';
+import type { Date as EqlV3Date } from './eql-v3-types/Date.js';
+import type { DateEq } from './eql-v3-types/DateEq.js';
+import type { DateOrd } from './eql-v3-types/DateOrd.js';
+import type { DateOrdOpe } from './eql-v3-types/DateOrdOpe.js';
+import type { DateOrdOre } from './eql-v3-types/DateOrdOre.js';
+import type { Double } from './eql-v3-types/Double.js';
+import type { DoubleEq } from './eql-v3-types/DoubleEq.js';
+import type { DoubleOrd } from './eql-v3-types/DoubleOrd.js';
+import type { DoubleOrdOpe } from './eql-v3-types/DoubleOrdOpe.js';
+import type { DoubleOrdOre } from './eql-v3-types/DoubleOrdOre.js';
+import type { Integer } from './eql-v3-types/Integer.js';
+import type { IntegerEq } from './eql-v3-types/IntegerEq.js';
+import type { IntegerOrd } from './eql-v3-types/IntegerOrd.js';
+import type { IntegerOrdOpe } from './eql-v3-types/IntegerOrdOpe.js';
+import type { IntegerOrdOre } from './eql-v3-types/IntegerOrdOre.js';
+import type { Numeric } from './eql-v3-types/Numeric.js';
+import type { NumericEq } from './eql-v3-types/NumericEq.js';
+import type { NumericOrd } from './eql-v3-types/NumericOrd.js';
+import type { NumericOrdOpe } from './eql-v3-types/NumericOrdOpe.js';
+import type { NumericOrdOre } from './eql-v3-types/NumericOrdOre.js';
+import type { Real } from './eql-v3-types/Real.js';
+import type { RealEq } from './eql-v3-types/RealEq.js';
+import type { RealOrd } from './eql-v3-types/RealOrd.js';
+import type { RealOrdOpe } from './eql-v3-types/RealOrdOpe.js';
+import type { RealOrdOre } from './eql-v3-types/RealOrdOre.js';
+import type { Smallint } from './eql-v3-types/Smallint.js';
+import type { SmallintEq } from './eql-v3-types/SmallintEq.js';
+import type { SmallintOrd } from './eql-v3-types/SmallintOrd.js';
+import type { SmallintOrdOpe } from './eql-v3-types/SmallintOrdOpe.js';
+import type { SmallintOrdOre } from './eql-v3-types/SmallintOrdOre.js';
+import type { SteVecDocument } from './eql-v3-types/SteVecDocument.js';
+import type { SteVecQuery } from './eql-v3-types/SteVecQuery.js';
+import type { Text } from './eql-v3-types/Text.js';
+import type { TextEq } from './eql-v3-types/TextEq.js';
+import type { TextMatch } from './eql-v3-types/TextMatch.js';
+import type { TextOrd } from './eql-v3-types/TextOrd.js';
+import type { TextOrdOpe } from './eql-v3-types/TextOrdOpe.js';
+import type { TextOrdOre } from './eql-v3-types/TextOrdOre.js';
+import type { TextSearch } from './eql-v3-types/TextSearch.js';
+import type { Timestamp } from './eql-v3-types/Timestamp.js';
+import type { TimestampEq } from './eql-v3-types/TimestampEq.js';
+import type { TimestampOrd } from './eql-v3-types/TimestampOrd.js';
+import type { TimestampOrdOpe } from './eql-v3-types/TimestampOrdOpe.js';
+import type { TimestampOrdOre } from './eql-v3-types/TimestampOrdOre.js';
+export type { BloomFilter } from './eql-v3-types/BloomFilter.js';
+export type { Ciphertext } from './eql-v3-types/Ciphertext.js';
+export type { Hmac256 } from './eql-v3-types/Hmac256.js';
+export type { Identifier as EqlV3Identifier } from './eql-v3-types/Identifier.js';
+export type { OpeCllw } from './eql-v3-types/OpeCllw.js';
+export type { OreBlock256 } from './eql-v3-types/OreBlock256.js';
+export type { OreCllw } from './eql-v3-types/OreCllw.js';
+export type { SchemaVersion } from './eql-v3-types/SchemaVersion.js';
+export type { Selector } from './eql-v3-types/Selector.js';
+export type { SteVecDocument } from './eql-v3-types/SteVecDocument.js';
+export type { SteVecEntry as EqlV3SteVecEntry } from './eql-v3-types/SteVecEntry.js';
+export type { SteVecForm } from './eql-v3-types/SteVecForm.js';
+export type { SteVecQuery } from './eql-v3-types/SteVecQuery.js';
+export type { SteVecQueryEntry } from './eql-v3-types/SteVecQueryEntry.js';
+export type { SteVecTerm } from './eql-v3-types/SteVecTerm.js';
+export type { Bigint, BigintEq, BigintOrd, BigintOrdOpe, BigintOrdOre, EqlV3Boolean, EqlV3Date, DateEq, DateOrd, DateOrdOpe, DateOrdOre, Double, DoubleEq, DoubleOrd, DoubleOrdOpe, DoubleOrdOre, Integer, IntegerEq, IntegerOrd, IntegerOrdOpe, IntegerOrdOre, Numeric, NumericEq, NumericOrd, NumericOrdOpe, NumericOrdOre, Real, RealEq, RealOrd, RealOrdOpe, RealOrdOre, Smallint, SmallintEq, SmallintOrd, SmallintOrdOpe, SmallintOrdOre, Text, TextEq, TextMatch, TextOrd, TextOrdOpe, TextOrdOre, TextSearch, Timestamp, TimestampEq, TimestampOrd, TimestampOrdOpe, TimestampOrdOre, };
+/**
+ * Every flat scalar EQL v3 storage payload (`{v: 3, i, c, <terms>}`, one
+ * struct per `eql_v3` scalar domain).
+ */
+export type EncryptedV3Scalar = Bigint | BigintEq | BigintOrd | BigintOrdOpe | BigintOrdOre | EqlV3Boolean | EqlV3Date | DateEq | DateOrd | DateOrdOpe | DateOrdOre | Double | DoubleEq | DoubleOrd | DoubleOrdOpe | DoubleOrdOre | Integer | IntegerEq | IntegerOrd | IntegerOrdOpe | IntegerOrdOre | Numeric | NumericEq | NumericOrd | NumericOrdOpe | NumericOrdOre | Real | RealEq | RealOrd | RealOrdOpe | RealOrdOre | Smallint | SmallintEq | SmallintOrd | SmallintOrdOpe | SmallintOrdOre | Text | TextEq | TextMatch | TextOrd | TextOrdOpe | TextOrdOre | TextSearch | Timestamp | TimestampEq | TimestampOrd | TimestampOrdOpe | TimestampOrdOre;
+/**
+ * EQL v3 **storage** payload — returned by `encrypt` / `encryptBulk` when the
+ * client was created with `eqlVersion: 3`.
+ *
+ * Scalars carry no `k` discriminator: they are flat
+ * (`{v: 3, i, c, <terms>}`, terms depending on the column's `eql_v3` domain).
+ * Encrypted JSONB is a {@link SteVecDocument}, which keeps the `k: "sv"`
+ * form discriminator (`{v: 3, k: "sv", i, sv: [...]}`).
+ * The record ciphertext lives at `c` on scalars and at `sv[0].c` on SteVec
+ * documents (`sv[0]` is always the decryption root).
+ */
+export type EncryptedV3 = EncryptedV3Scalar | SteVecDocument;
+/**
+ * EQL v3 **query** payload — returned by `encryptQuery` / `encryptQueryBulk`
+ * under `eqlVersion: 3`. Only JSONB containment queries are supported (the
+ * `eql_v3.jsonb_query` needle); scalar and selector query encryption throws
+ * until a v3 scalar query wire shape exists.
+ */
+export type EncryptedV3Query = SteVecQuery;

package/lib/eql-v3.js

@@ -0,0 +1,6 @@
+"use strict";
+// Hand-written barrel over the vendored (generated) EQL v3 payload types in
+// src/eql-v3-types/. Assembles the public unions and renames the few types
+// whose names would clash with the v2 exports in index.cts (`Identifier`,
+// `SteVecEntry`) or shadow a global (`Boolean`, `Date`).
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/errors.d.ts

@@ -0,0 +1,14 @@
+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' | 'INVALID_EQL_VERSION' | 'EQL_V3_QUERY_UNSUPPORTED' | 'EQL_V3_UNSUPPORTED_COLUMN' | 'EQL_V3_CONVERSION_FAILED' | 'INVALID_CIPHERTEXT' | 'UNKNOWN';
+export declare class ProtectError extends Error {
+    code: ProtectErrorCode;
+    details?: unknown;
+    cause?: unknown;
+    constructor(opts: {
+        code: ProtectErrorCode;
+        message: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+export declare function inferErrorCode(message: string): ProtectErrorCode;
+export declare function normalizeError(err: unknown): unknown;

package/lib/errors.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtectError = void 0;
+exports.inferErrorCode = inferErrorCode;
+exports.normalizeError = normalizeError;
+class ProtectError extends Error {
+    code;
+    details;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ProtectError';
+        this.code = opts.code;
+        this.details = opts.details;
+        this.cause = opts.cause;
+    }
+}
+exports.ProtectError = ProtectError;
+function inferErrorCode(message) {
+    if (message.startsWith('protect-ffi invariant violation:')) {
+        return 'INVARIANT_VIOLATION';
+    }
+    if (message.startsWith('Unknown query operation:')) {
+        return 'UNKNOWN_QUERY_OP';
+    }
+    if (message.startsWith('Invalid query input for')) {
+        return 'INVALID_QUERY_INPUT';
+    }
+    if (message.startsWith('Invalid JSON path')) {
+        return 'INVALID_JSON_PATH';
+    }
+    if (message.includes(' not found in Encrypt config')) {
+        return 'UNKNOWN_COLUMN';
+    }
+    if (message.includes(' index configured')) {
+        return 'MISSING_INDEX';
+    }
+    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';
+    }
+    if (message.startsWith('Invalid eqlVersion')) {
+        return 'INVALID_EQL_VERSION';
+    }
+    if (message.startsWith('EQL v3 scalar query') ||
+        message.startsWith('EQL v3 selector query')) {
+        return 'EQL_V3_QUERY_UNSUPPORTED';
+    }
+    if (message.includes('cannot be represented in EQL v3')) {
+        return 'EQL_V3_UNSUPPORTED_COLUMN';
+    }
+    if (message.startsWith('EQL v3 conversion failed')) {
+        return 'EQL_V3_CONVERSION_FAILED';
+    }
+    if (message.startsWith('Invalid EQL ciphertext:')) {
+        return 'INVALID_CIPHERTEXT';
+    }
+    return 'UNKNOWN';
+}
+function normalizeError(err) {
+    if (err instanceof ProtectError) {
+        return err;
+    }
+    if (err && typeof err === 'object' && 'message' in err) {
+        const message = String(err.message ?? 'Unknown error');
+        const code = inferErrorCode(message);
+        if (code !== 'UNKNOWN') {
+            return new ProtectError({ code, message, cause: err });
+        }
+    }
+    return err;
+}

package/lib/index.cjs

@@ -33,6 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProtectError = exports.withEnvCredentials = void 0;
 exports.newClient = newClient;
@@ -50,68 +53,16 @@ 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 {
-    code;
-    details;
-    cause;
-    constructor(opts) {
-        super(opts.message);
-        this.name = 'ProtectError';
-        this.code = opts.code;
-        this.details = opts.details;
-        this.cause = opts.cause;
-    }
-}
-exports.ProtectError = ProtectError;
-function inferErrorCode(message) {
-    if (message.startsWith('protect-ffi invariant violation:')) {
-        return 'INVARIANT_VIOLATION';
-    }
-    if (message.startsWith('Unknown query operation:')) {
-        return 'UNKNOWN_QUERY_OP';
-    }
-    if (message.startsWith('Invalid query input for')) {
-        return 'INVALID_QUERY_INPUT';
-    }
-    if (message.startsWith('Invalid JSON path')) {
-        return 'INVALID_JSON_PATH';
-    }
-    if (message.includes(' not found in Encrypt config')) {
-        return 'UNKNOWN_COLUMN';
-    }
-    if (message.includes(' index configured')) {
-        return 'MISSING_INDEX';
-    }
-    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) {
-    if (err instanceof ProtectError) {
-        return err;
-    }
-    if (err && typeof err === 'object' && 'message' in err) {
-        const message = String(err.message ?? 'Unknown error');
-        const code = inferErrorCode(message);
-        if (code !== 'UNKNOWN') {
-            return new ProtectError({ code, message, cause: err });
-        }
-    }
-    return err;
-}
+__exportStar(require("./eql-v3.js"), exports);
+const errors_js_1 = require("./errors.js");
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "ProtectError", { enumerable: true, get: function () { return errors_js_2.ProtectError; } });
 async function wrapAsync(fn) {
     try {
         return await fn();
     }
     catch (err) {
-        throw normalizeError(err);
+        throw (0, errors_js_1.normalizeError)(err);
     }
 }
 function wrapSync(fn) {
@@ -119,13 +70,14 @@ function wrapSync(fn) {
         return fn();
     }
     catch (err) {
-        throw normalizeError(err);
+        throw (0, errors_js_1.normalizeError)(err);
     }
 }
 function newClient(opts) {
     return wrapAsync(() => native.newClient({
         encryptConfig: (0, normalizeEncryptConfig_js_1.normalizeEncryptConfig)(opts.encryptConfig),
         clientOpts: (0, credentials_js_1.withEnvCredentials)(opts.clientOpts),
+        eqlVersion: opts.eqlVersion,
     }, opts.strategy));
 }
 function encrypt(client, opts) {
@@ -134,6 +86,13 @@ function encrypt(client, opts) {
 function decrypt(client, opts) {
     return wrapAsync(() => native.decrypt(client, opts));
 }
+/**
+ * True when `encrypted` is a stored EQL payload in EITHER wire format:
+ * an EQL v2.3 payload (`k: "ct"` / `k: "sv"`) or an EQL v3 payload
+ * (`{v: 3, i, c}` scalar or `{v: 3, k: "sv", i, sv}` SteVec document).
+ * Query payloads (including the v3 containment needle) are not stored
+ * payloads and return false.
+ */
 function isEncrypted(encrypted) {
     return wrapSync(() => native.isEncrypted(encrypted));
 }
@@ -147,14 +106,28 @@ async function decryptBulkFallible(client, opts) {
     const results = await wrapAsync(() => native.decryptBulkFallible(client, opts));
     return results.map((item) => {
         if ('error' in item && typeof item.error === 'string') {
-            return { ...item, code: inferErrorCode(item.error) };
+            return { ...item, code: (0, errors_js_1.inferErrorCode)(item.error) };
         }
         return item;
     });
 }
+/**
+ * Encrypt a query term.
+ *
+ * Under `eqlVersion: 2` (default) this returns the v2 shapes ({@link
+ * Encrypted} for JSON containment, {@link EncryptedQuery} otherwise).
+ *
+ * Under `eqlVersion: 3` only JSON containment queries are supported and
+ * return the `eql_v3.jsonb_query` needle ({@link EncryptedV3Query}). Scalar
+ * index queries (`unique` / `ore` / `ope` / `match`) and `ste_vec_selector`
+ * queries
+ * throw `EQL_V3_QUERY_UNSUPPORTED` — no EQL v3 scalar/selector query wire
+ * shape exists yet, so those queries require an `eqlVersion: 2` client.
+ */
 function encryptQuery(client, opts) {
     return wrapAsync(() => native.encryptQuery(client, opts));
 }
+/** Bulk variant of {@link encryptQuery} — same EQL v3 restrictions apply. */
 function encryptQueryBulk(client, opts) {
     return wrapAsync(() => native.encryptQueryBulk(client, opts));
 }

package/lib/index.d.cts

@@ -1,34 +1,26 @@
 import { type CredentialOpts } from './credentials.js';
 import { type NativeEncryptConfig } from './normalizeEncryptConfig.js';
 export { withEnvCredentials, type EnvReader, type CredentialOpts, } from './credentials.js';
+export * from './eql-v3.js';
+import type { EncryptedV3, EncryptedV3Query } from './eql-v3.js';
+import { type ProtectErrorCode } from './errors.js';
+export { ProtectError, type ProtectErrorCode } from './errors.js';
 declare const sym: unique symbol;
 export type Client = {
     readonly [sym]: unknown;
 };
 declare module './load.cjs' {
     function newClient(opts: NativeNewClientOptions, strategy?: AuthStrategy): Promise<Client>;
-    function encrypt(client: Client, opts: EncryptOptions): Promise<Encrypted>;
+    function encrypt(client: Client, opts: EncryptOptions): Promise<EncryptedPayload>;
     function decrypt(client: Client, opts: DecryptOptions): Promise<JsPlaintext>;
     function isEncrypted(encrypted: unknown): boolean;
-    function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
+    function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<EncryptedPayload[]>;
     function decryptBulk(client: Client, opts: DecryptBulkOptions): Promise<JsPlaintext[]>;
     function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
-    function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery>;
-    function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery)[]>;
+    function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery | EncryptedV3Query>;
+    function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery | EncryptedV3Query)[]>;
     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' | 'MATCH_REQUIRES_TEXT' | 'UNSUPPORTED_CONFIG_VERSION' | 'UNKNOWN';
-export declare class ProtectError extends Error {
-    code: ProtectErrorCode;
-    details?: unknown;
-    cause?: unknown;
-    constructor(opts: {
-        code: ProtectErrorCode;
-        message: string;
-        details?: unknown;
-        cause?: unknown;
-    });
-}
 export type DecryptResult = {
     data: JsPlaintext;
 } | {
@@ -36,14 +28,35 @@ export type DecryptResult = {
     code?: ProtectErrorCode;
 };
 export declare function newClient(opts: NewClientOptions): Promise<Client>;
-export declare function encrypt(client: Client, opts: EncryptOptions): Promise<Encrypted>;
+export declare function encrypt(client: Client, opts: EncryptOptions): Promise<EncryptedPayload>;
 export declare function decrypt(client: Client, opts: DecryptOptions): Promise<JsPlaintext>;
+/**
+ * True when `encrypted` is a stored EQL payload in EITHER wire format:
+ * an EQL v2.3 payload (`k: "ct"` / `k: "sv"`) or an EQL v3 payload
+ * (`{v: 3, i, c}` scalar or `{v: 3, k: "sv", i, sv}` SteVec document).
+ * Query payloads (including the v3 containment needle) are not stored
+ * payloads and return false.
+ */
 export declare function isEncrypted(encrypted: unknown): boolean;
-export declare function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
+export declare function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<EncryptedPayload[]>;
 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 | EncryptedQuery>;
-export declare function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery)[]>;
+/**
+ * Encrypt a query term.
+ *
+ * Under `eqlVersion: 2` (default) this returns the v2 shapes ({@link
+ * Encrypted} for JSON containment, {@link EncryptedQuery} otherwise).
+ *
+ * Under `eqlVersion: 3` only JSON containment queries are supported and
+ * return the `eql_v3.jsonb_query` needle ({@link EncryptedV3Query}). Scalar
+ * index queries (`unique` / `ore` / `ope` / `match`) and `ste_vec_selector`
+ * queries
+ * throw `EQL_V3_QUERY_UNSUPPORTED` — no EQL v3 scalar/selector query wire
+ * shape exists yet, so those queries require an `eqlVersion: 2` client.
+ */
+export declare function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery | EncryptedV3Query>;
+/** Bulk variant of {@link encryptQuery} — same EQL v3 restrictions apply. */
+export declare function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<(Encrypted | EncryptedQuery | EncryptedV3Query)[]>;
 /**
  * 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
@@ -57,7 +70,7 @@ export type EncryptPayload = {
     lockContext?: Context;
 };
 export type BulkDecryptPayload = {
-    ciphertext: Encrypted;
+    ciphertext: EncryptedPayload;
     lockContext?: Context;
 };
 export type Context = {
@@ -79,6 +92,13 @@ export type Context = {
  * ```
  */
 export type Encrypted = EncryptedScalar | EncryptedSteVec;
+/**
+ * A stored payload in EITHER wire format: EQL v2.3 ({@link Encrypted}) or
+ * EQL v3 ({@link EncryptedV3}). {@link encrypt} / {@link encryptBulk} return
+ * the format selected by the client's `eqlVersion`; {@link decrypt} accepts
+ * both regardless of `eqlVersion` (data-migration scenarios).
+ */
+export type EncryptedPayload = Encrypted | EncryptedV3;
 /** Scalar EQL v2.3 storage payload (`k: "ct"`). */
 export type EncryptedScalar = {
     k: 'ct';
@@ -192,7 +212,7 @@ export type Column = {
     cast_as?: CastAs;
     indexes?: Indexes;
 };
-export type CastAs = 'bigint' | 'boolean' | 'date' | 'number' | 'string' | 'text' | 'timestamp' | 'json';
+export type CastAs = 'bigint' | 'boolean' | 'date' | 'decimal' | 'int' | 'number' | 'small_int' | 'string' | 'text' | 'timestamp' | 'json';
 type TablesOf<C extends EncryptConfig> = C['tables'];
 export type Identifier<C extends EncryptConfig> = {
     [T in keyof TablesOf<C>]: {
@@ -204,11 +224,13 @@ export type Identifier<C extends EncryptConfig> = {
 }[keyof TablesOf<C>];
 export type Indexes = {
     ore?: OreIndexOpts;
+    ope?: OpeIndexOpts;
     unique?: UniqueIndexOpts;
     match?: MatchIndexOpts;
     ste_vec?: SteVecIndexOpts;
 };
 export type OreIndexOpts = Record<string, never>;
+export type OpeIndexOpts = Record<string, never>;
 export type UniqueIndexOpts = {
     token_filters?: TokenFilter[];
 };
@@ -257,6 +279,21 @@ export type NewClientOptions = {
      * AutoStrategy from env / profile / `clientOpts.creds`.
      */
     strategy?: AuthStrategy;
+    /**
+     * EQL wire version this client emits. Defaults to `2` (the
+     * `eql_v2_encrypted` payload format).
+     *
+     * With `3`, {@link encrypt} / {@link encryptBulk} return {@link
+     * EncryptedV3} payloads for the `eql_v3` per-capability domains
+     * (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …), derived
+     * from each column's `cast_as` + indexes. {@link decrypt} accepts BOTH
+     * formats regardless of this setting.
+     *
+     * v3 limitation: {@link encryptQuery} supports only JSON containment
+     * queries — scalar-index and selector queries throw
+     * `EQL_V3_QUERY_UNSUPPORTED` until a v3 scalar query wire shape exists.
+     */
+    eqlVersion?: 2 | 3;
 };
 /**
  * Auth strategy shape compatible with `@cipherstash/auth` strategies (e.g.
@@ -271,6 +308,7 @@ export type AuthStrategy = {
 type NativeNewClientOptions = {
     encryptConfig: NativeEncryptConfig;
     clientOpts?: ClientOpts;
+    eqlVersion?: 2 | 3;
 };
 export type ClientOpts = CredentialOpts & {
     keyset?: KeysetIdentifier;
@@ -300,7 +338,8 @@ export type EncryptBulkOptions = {
     unverifiedContext?: Record<string, unknown>;
 };
 export type DecryptOptions = {
-    ciphertext: Encrypted;
+    /** A stored payload in either wire format (EQL v2.3 or EQL v3). */
+    ciphertext: EncryptedPayload;
     lockContext?: Context;
     unverifiedContext?: Record<string, unknown>;
 };
@@ -308,7 +347,7 @@ export type DecryptBulkOptions = {
     ciphertexts: BulkDecryptPayload[];
     unverifiedContext?: Record<string, unknown>;
 };
-export type IndexTypeName = 'ste_vec' | 'match' | 'ore' | 'unique';
+export type IndexTypeName = 'ste_vec' | 'match' | 'ore' | 'ope' | 'unique';
 export type QueryOpName = 'default' | 'ste_vec_selector' | 'ste_vec_term';
 export type EncryptQueryOptions = {
     plaintext: JsPlaintext;

package/lib/normalizeEncryptConfig.d.ts

@@ -6,7 +6,7 @@ import type { Column, EncryptConfig } from './index.cjs';
  * 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';
+export type NativeCastAs = 'text' | 'float' | 'big_int' | 'boolean' | 'date' | 'decimal' | 'int' | 'json' | 'small_int' | 'timestamp';
 /** A column after normalization — `cast_as` is in the canonical vocabulary. */
 export type NativeColumn = Omit<Column, 'cast_as'> & {
     cast_as?: NativeCastAs;

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.25.0",
+  "version": "0.27.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cipherstash/protectjs-ffi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cipherstash/protectjs-ffi/issues"
+  },
+  "homepage": "https://github.com/cipherstash/protectjs-ffi#readme",
   "description": "",
   "main": "./lib/index.cjs",
   "scripts": {
     "test": "npm run test:typecheck && npm run test:unit && npm run test:lint && npm run test:format && npm run test:rust",
-    "test:typecheck": "tsc",
+    "test:typecheck": "tsc && tsc -p tsconfig.test.json",
     "test:unit": "vitest run",
     "test:rust": "cargo test",
     "test:lint": "npm run test:lint:ts",
@@ -26,7 +34,7 @@
     "prepack": "tsc &&neon update",
     "version": "neon bump --binaries platforms && git add .",
     "release": "gh workflow run release.yml -f dryrun=false -f version=patch",
-    "dryrun": "gh workflow run publish.yml -f dryrun=true",
+    "dryrun": "gh workflow run release.yml -f dryrun=true -f version=patch",
     "build:wasm": "wasm-pack build crates/protect-ffi --target bundler --out-dir ../../dist/wasm --no-pack",
     "postbuild:wasm": "node scripts/inline-wasm.mjs"
   },
@@ -95,11 +103,11 @@
     "vite": "^8.0.5"
   },
   "optionalDependencies": {
-    "@cipherstash/protect-ffi-darwin-x64": "0.25.0",
-    "@cipherstash/protect-ffi-darwin-arm64": "0.25.0",
-    "@cipherstash/protect-ffi-win32-x64-msvc": "0.25.0",
-    "@cipherstash/protect-ffi-linux-x64-gnu": "0.25.0",
-    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.25.0",
-    "@cipherstash/protect-ffi-linux-x64-musl": "0.25.0"
+    "@cipherstash/protect-ffi-darwin-x64": "0.27.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.27.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.27.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.27.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.27.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.27.0"
   }
 }