@cipherstash/protect-ffi 0.27.0 → 0.29.0

package/lib/index.d.cts

@@ -47,15 +47,20 @@ export declare function decryptBulkFallible(client: Client, opts: DecryptBulkOpt
  * 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.
+ * Under `eqlVersion: 3` this returns an {@link EncryptedV3Query}:
+ *
+ * - Scalar index queries (`unique` / `ore` / `ope` / `match`) produce the
+ *   term-only operand for the column domain's query twin (`{v, i, <terms>}`,
+ *   no `c` ciphertext) — bind with `col = $1::jsonb::eql_v3.query_<name>`.
+ *   The operand always carries ALL the column domain's terms, whichever
+ *   `indexType` was queried.
+ * - JSON containment queries produce the `eql_v3.query_jsonb` needle — bind
+ *   with `doc @> $1::jsonb::eql_v3.query_jsonb`.
+ * - `ste_vec_selector` queries produce the bare selector hash (a string) —
+ *   bind as the `text` argument of `->` / `->>`.
  */
 export declare function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted | EncryptedQuery | EncryptedV3Query>;
-/** Bulk variant of {@link encryptQuery} — same EQL v3 restrictions apply. */
+/** Bulk variant of {@link encryptQuery} — same EQL v3 shapes 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,
@@ -188,7 +193,9 @@ export type EncryptedSteVecSelector = {
  * 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`).
+ * per-element equality / ordering term: `hm` for non-orderable leaves, and for
+ * orderable leaves either `op` (Compat mode, the default) or `oc` (Standard
+ * mode). EQL v3 accepts `hm` XOR `op` and rejects `oc`.
  */
 export type SteVecEntry = {
     /** Hex-encoded tokenized selector — deterministic per (path, key) */
@@ -199,7 +206,9 @@ export type SteVecEntry = {
     a?: boolean;
     /** 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 */
+    /** Per-entry CLLW OPE term for orderable leaves (strings, numbers) — Compat mode, the default */
+    op?: string;
+    /** Per-entry CLLW ORE term for orderable leaves (strings, numbers) — Standard mode, EQL v2 only */
     oc?: string;
 };
 /** @deprecated Use SteVecEntry instead */
@@ -249,9 +258,14 @@ export type ArrayIndexMode = 'all' | 'none' | {
 /**
  * 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.
+ * - `compat`: CLLW-OPE ordering, emits `op` per entry. The default since
+ *   cipherstash-config 0.40.0, and the only mode EQL v3 accepts.
+ * - `standard`: CLLW-ORE ordering, emits `oc` per entry. The pre-0.40.0
+ *   default; EQL v2 only.
+ *
+ * The two orderings are not cross-comparable, so a column cannot change mode
+ * without re-encrypting. Pin `standard` on v2 JSON columns that already hold
+ * rows.
  */
 export type SteVecMode = 'compat' | 'standard';
 export type SteVecIndexOpts = {
@@ -284,25 +298,55 @@ export type NewClientOptions = {
      * `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.
+     * EncryptedV3} payloads for the `eql_v3` per-capability column domains
+     * (`public.eql_v3_text_eq`, `public.eql_v3_integer_ord_ore`,
+     * `public.eql_v3_json`, …), derived
+     * from each column's `cast_as` + indexes, and {@link encryptQuery} /
+     * {@link encryptQueryBulk} return {@link EncryptedV3Query} operands:
+     * term-only scalar operands for the `eql_v3.query_<name>` twins, the
+     * `eql_v3.query_jsonb` containment needle, and bare selector-hash strings
+     * for path queries. {@link decrypt} accepts BOTH formats regardless of
+     * this setting.
      */
     eqlVersion?: 2 | 3;
 };
+/** The token payload the native side ultimately reads. */
+export type TokenResult = {
+    token: string;
+};
+/**
+ * A `@byteslice/result` `Result` envelope, as returned by
+ * `@cipherstash/auth` >= 0.41's `getToken()`.
+ */
+export type TokenResultEnvelope = {
+    data: TokenResult;
+    failure?: undefined;
+} | {
+    failure: {
+        type?: string;
+        error?: Error;
+    };
+    data?: undefined;
+};
 /**
  * Auth strategy shape compatible with `@cipherstash/auth` strategies (e.g.
- * `AccessKeyStrategy`). Only `getToken` is required.
+ * `AccessKeyStrategy`, `OidcFederationStrategy`). Only `getToken` is required.
+ *
+ * `getToken` may resolve either shape — the native and WASM clients accept both
+ * (see `crates/protect-ffi/src/lib.rs` and `crates/protect-ffi/src/wasm.rs`):
+ *
+ * - `{ token }` — the bare payload, used by `@cipherstash/auth` <= 0.40 and by
+ *   custom strategies.
+ * - `{ data: { token } }` / `{ failure }` — the `Result` envelope, used by
+ *   `@cipherstash/auth` >= 0.41. A `failure` is reconstructed into the
+ *   corresponding `AuthError`.
+ *
+ * Both have been accepted at runtime since 0.28.0; this type previously
+ * declared only the bare payload, so a real `@cipherstash/auth` >= 0.41
+ * strategy could not be assigned to it.
  */
 export type AuthStrategy = {
-    getToken: () => Promise<{
-        token: string;
-    }>;
+    getToken: () => Promise<TokenResult | TokenResultEnvelope>;
 };
 /** Options passed to the native `newClient` after vocabulary normalization. */
 type NativeNewClientOptions = {
@@ -325,7 +369,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;

package/lib/normalizeEncryptConfig.d.ts

@@ -24,6 +24,7 @@ export type NativeEncryptConfig = Omit<EncryptConfig, 'tables'> & {
  *   `'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.
+ * library default (`compat` since cipherstash-config 0.40.0). The input
+ * config is never mutated.
  */
 export declare function normalizeEncryptConfig(config: EncryptConfig): NativeEncryptConfig;

package/lib/normalizeEncryptConfig.js

@@ -20,7 +20,8 @@ const CAST_AS_REMAP = {
  *   `'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.
+ * library default (`compat` since cipherstash-config 0.40.0). The input
+ * config is never mutated.
  */
 function normalizeEncryptConfig(config) {
     const tables = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cipherstash/protectjs-ffi.git"
@@ -9,7 +9,7 @@
     "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",
@@ -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.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"
+    "@cipherstash/protect-ffi-darwin-x64": "0.29.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.29.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.29.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.29.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.29.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.29.0"
   }
 }

package/lib/eql-v3-types/OreCllw.d.ts

@@ -1,7 +0,0 @@
-/**
- * CLLW-ORE ordered term — the `oc` wire key of a SteVec entry. Backs entry
- * ordering (`<` `<=` `>` `>=`) and equality on ordered leaves. SQL-side
- * constructor: `eql_v3.ore_cllw`. A SteVec entry carries exactly one of `hm`
- * (equality) XOR `oc` (ordering) — enforced by the SQL domain CHECK.
- */
-export type OreCllw = string;

package/lib/eql-v3-types/OreCllw.js

@@ -1,5 +0,0 @@
-"use strict";
-// @generated — vendored from eql-bindings bindings/v3 (encrypt-query-language).
-// Do not hand-edit. Refresh with scripts/sync-eql-v3-types.sh.
-// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
-Object.defineProperty(exports, "__esModule", { value: true });