@cipherstash/protect-ffi 0.26.0 → 0.28.0

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;
@@ -287,7 +325,29 @@ export type EnsureKeysetResult = {
     id: string;
     name: string;
 };
-export type JsPlaintext = string | number | boolean | Record<string, unknown> | JsPlaintext[];
+/**
+ * A plaintext value accepted by {@link encrypt} / {@link encryptBulk} /
+ * {@link encryptQuery} and returned by {@link decrypt} / {@link decryptBulk} /
+ * {@link decryptBulkFallible} (in the `data` arm of each result).
+ *
+ * `bigint` support (encrypted `cast_as: 'bigint'` columns store signed
+ * 64-bit integers):
+ *
+ * - **Input**: a top-level `bigint` plaintext is accepted alongside
+ *   `number`. Values outside the i64 range (-2^63 to 2^63 - 1) throw a
+ *   `RangeError` at the boundary — this covers index-term generation too,
+ *   since terms derive from the same value. `number` inputs keep the
+ *   existing exact-integer guard (fractional, non-finite, or beyond-2^53
+ *   inexact values are rejected). `bigint` values nested inside JSON
+ *   objects/arrays are NOT supported (JSON has no bigint) and throw a
+ *   `TypeError` on both Neon and wasm — plaintexts follow
+ *   `JSON.stringify` semantics on both platforms.
+ * - **Output** (BREAKING since the introduction of bigint support):
+ *   decrypting a `cast_as: 'bigint'` column ALWAYS returns a `bigint`,
+ *   even for values that fit in a JS number. Previous releases returned a
+ *   `number`, silently losing precision beyond `Number.MAX_SAFE_INTEGER`.
+ */
+export type JsPlaintext = string | number | boolean | bigint | Record<string, unknown> | JsPlaintext[];
 export type EncryptOptions = {
     plaintext: JsPlaintext;
     column: string;
@@ -300,7 +360,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 +369,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,6 +1,6 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cipherstash/protectjs-ffi.git"
@@ -9,11 +9,11 @@
     "url": "https://github.com/cipherstash/protectjs-ffi/issues"
   },
   "homepage": "https://github.com/cipherstash/protectjs-ffi#readme",
-  "description": "",
+  "description": "Native FFI bindings to the CipherStash Client SDK — powers @cipherstash/stack",
   "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",
@@ -32,14 +32,14 @@
     "cross": "npm run cross-build -- --release",
     "zigbuild": "npm run zig-build -- --release",
     "prepack": "tsc &&neon update",
-    "version": "neon bump --binaries platforms && git add .",
+    "version": "neon bump --binaries platforms && node scripts/changelog-release.mjs && git add .",
     "release": "gh workflow run release.yml -f dryrun=false -f version=patch",
     "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"
   },
-  "author": "",
-  "license": "ISC",
+  "author": "CipherStash <humans@cipherstash.com>",
+  "license": "MIT",
   "exports": {
     ".": {
       "node": {
@@ -103,11 +103,11 @@
     "vite": "^8.0.5"
   },
   "optionalDependencies": {
-    "@cipherstash/protect-ffi-darwin-x64": "0.26.0",
-    "@cipherstash/protect-ffi-darwin-arm64": "0.26.0",
-    "@cipherstash/protect-ffi-win32-x64-msvc": "0.26.0",
-    "@cipherstash/protect-ffi-linux-x64-gnu": "0.26.0",
-    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.26.0",
-    "@cipherstash/protect-ffi-linux-x64-musl": "0.26.0"
+    "@cipherstash/protect-ffi-darwin-x64": "0.28.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.28.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.28.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.28.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.28.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.28.0"
   }
 }