@cipherstash/protect-ffi 0.26.0 → 0.28.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 CipherStash
+Copyright (c) 2024-2026 CipherStash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
-# Protect.js CipherStash Client FFI
+# CipherStash Client FFI (`@cipherstash/protect-ffi`)
 
 > [!IMPORTANT]
-> If you are looking to implement this package into your application please use the official [protect package](https://github.com/cipherstash/protectjs).
+> If you are looking to implement this package into your application please use the official [`@cipherstash/stack` package](https://github.com/cipherstash/stack).
 
 This project provides the JS bindings for the CipherStash Client Rust SDK and is bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon).
 
@@ -19,19 +19,18 @@ This command uses the [@neon-rs/cli](https://www.npmjs.com/package/@neon-rs/cli)
 
 ## Local setup
 
-You can use the `stash` CLI tool to set up your local environment.
-
-You will be prompted to sign in or create an account and follow steps to create a keyset and client key.
+Authenticate the `stash` CLI to set up your local environment. It runs via `npx` — no separate install needed:
 
 ```sh
-brew install cipherstash/tap/stash
-stash setup
+npx stash auth login
 ```
 
+You will be prompted to sign in or create an account.
+
 ## Exploring
 
 After building `protect-ffi`, you can explore its exports at the Node console.
-`CS_CLIENT_ID` and `CS_CLIENT_KEY` must be set in your environment for the call to `newClient()` to succeed.
+Credentials must be available for the call to `newClient()` to succeed — resolved from the CipherStash profile store, from environment variables, or from an explicit `strategy` passed to `newClient()`. For local development the simplest option is `npx stash auth login`, which populates the profile store. Alternatively, set `CS_WORKSPACE_CRN`, `CS_ACCESS_KEY`, and the `CS_CLIENT_ID`/`CS_CLIENT_KEY` keypair in your environment.
 
 ```sh
 $ npm i
@@ -44,6 +43,115 @@ $ node
 > console.log({ciphertext, plaintext});
 ```
 
+## EQL version selection
+
+`newClient` accepts an `eqlVersion` option selecting the wire format that
+`encrypt` / `encryptBulk` / `encryptQuery` emit:
+
+```js
+// EQL v2 (default) — the `eql_v2_encrypted` payload format
+const v2 = await addon.newClient({ encryptConfig })
+
+// EQL v3 — payloads for the per-capability `eql_v3` domains
+const v3 = await addon.newClient({ encryptConfig, eqlVersion: 3 })
+```
+
+With `eqlVersion: 3`, each column's payload targets the `eql_v3` domain
+derived from its `cast_as` and indexes:
+
+| `cast_as` | family | indexes | domain |
+|-----------|--------|---------|--------|
+| `text` | `text` | `unique` + `ore` + `match` | `text_search` |
+| `text` | `text` | `unique` + `ore` | `text_ord_ore` |
+| `text` | `text` | `match` | `text_match` |
+| `text` | `text` | `unique` | `text_eq` |
+| `int` / `small_int` / `bigint` | `integer` / `smallint` / `bigint` | `ore` (with or without `unique`) | `<family>_ord_ore` |
+| `int` / `small_int` / `bigint` | `integer` / `smallint` / `bigint` | `unique` | `<family>_eq` |
+| `number` / `decimal` / `date` / `timestamp` | `double` / `numeric` / `date` / `timestamp` | as above | as above |
+| any scalar | — | none | storage-only domain (`text`, `integer`, …) |
+| `boolean` | `boolean` | none only | `boolean` (storage-only — any index errors) |
+| `json` | `json` | `ste_vec` (required) | `json` |
+
+Notes:
+
+- The richest matching domain wins, and it must cover every configured
+  capability — a combination that would silently drop a term errors instead
+  (e.g. `unique` + `match`, `unique` + `ope` + `match`, or `ore` + `match`
+  on text: no single domain carries those term sets, so add the missing
+  index to reach `text_search`, split the capabilities across columns, or
+  use `eqlVersion: 2`).
+- Exception: dropping a *term* is fine when the *capability* survives.
+  Non-text ordering domains carry only `ob`, so `unique` + `ore` on a
+  numeric column drops `hm` — equality still works via the ORE operators.
+- Ordered text requires a `unique` index (`text_ord_ore`/`text_ord_ope`
+  carry `hm` + `ob`/`op`); `ore`-only text errors.
+- `decrypt` accepts **both** formats regardless of `eqlVersion`, so v2 and
+  v3 data can coexist during a migration.
+- v3 query encryption currently supports JSON containment only; scalar and
+  selector queries throw `EQL_V3_QUERY_UNSUPPORTED` and need an
+  `eqlVersion: 2` client.
+- `ope`-indexed columns map to `<family>_ord_ope` and carry the `op`
+  (CLLW-OPE) term (emitted since cipherstash-client 0.38.1).
+
+> [!NOTE]
+> **Breaking TypeScript change:** `encrypt`/`encryptBulk` now return
+> `EncryptedPayload` (`Encrypted | EncryptedV3`) instead of `Encrypted`.
+> Runtime output is unchanged for v2 clients, but code that accessed `.k`
+> or assigned the result to `Encrypted` must narrow first. v3 scalars carry
+> no `k`, so guard its presence before reading it:
+> `'k' in payload && payload.k === 'ct'` (a v2 scalar), or check
+> `payload.v === 3` to detect the v3 members. (A bare `payload.k === 'ct'`
+> does not compile against the union.)
+
+## BigInt plaintexts
+
+Encrypted `cast_as: 'bigint'` columns store signed 64-bit integers
+(PostgreSQL `bigint`). `encrypt` / `encryptBulk` / `encryptQuery` /
+`encryptQueryBulk` accept the plaintext as either a JS `number` or a JS
+`bigint`:
+
+- `bigint` inputs are exact and bounds-checked against the full i64 range:
+  **-9223372036854775808 to 9223372036854775807** (-2^63 to 2^63 - 1).
+  Values outside that range throw a `RangeError` (a plain `RangeError`, not
+  a `ProtectError`) naming the bounds and the offending direction. Search
+  index terms (`hm`, `ob`, `op`) are derived from the same value, so the
+  boundary check covers index-term generation too.
+- `number` inputs keep the existing exact-integer guard: fractional,
+  non-finite, or out-of-range values error instead of being silently
+  truncated.
+- A `bigint` is only accepted as the top-level plaintext of a scalar
+  column. JSON has no bigint, so bigints nested inside `cast_as: 'json'`
+  documents (or JSON containment query terms) are rejected with a
+  `TypeError` on both Neon and wasm. More generally, plaintexts follow
+  `JSON.stringify` semantics on both platforms: `toJSON` is honored (a
+  `Date` becomes its ISO string), `undefined` properties are dropped, and
+  non-finite numbers become `null`.
+- The internal wire form `{"__protect_ffi_bigint__": "<digits>"}` is
+  reserved: a `cast_as: 'json'` plaintext consisting of exactly that
+  single-key shape (with an in-range i64 decimal string) is read as a
+  bigint at the boundary and rejected for json columns. Nested
+  occurrences of the key inside a larger document are unaffected.
+
+```js
+const ciphertext = await addon.encrypt(client, {
+  plaintext: 9007199254740993n, // beyond Number.MAX_SAFE_INTEGER — stays exact
+  column: 'score',
+  table: 'users',
+})
+const decrypted = await addon.decrypt(client, { ciphertext })
+// decrypted === 9007199254740993n (a JS bigint)
+```
+
+> [!WARNING]
+> **Breaking change:** `decrypt` / `decryptBulk` / `decryptBulkFallible`
+> now ALWAYS return a JS `bigint` for `cast_as: 'bigint'` columns — even
+> for values that fit in a JS number. Previous releases returned a
+> `number`, silently losing precision beyond `Number.MAX_SAFE_INTEGER`
+> (2^53 - 1). Code comparing or doing arithmetic on decrypted bigint
+> columns must be updated (e.g. `decrypted === 123n` instead of
+> `decrypted === 123`, or `Number(decrypted)` when the value is known to
+> be small).
+
 ## Errors
 
 Async API calls throw `ProtectError` with a stable `code` for programmatic handling.
@@ -91,8 +199,7 @@ Initiate a dry run of a patch release of this library via GitHub Actions. This p
 
 #### `npm test`
 
-Formats and lints Rust and TypeScript code.
-Also runs Rust tests.
+Typechecks the TypeScript and runs the unit tests (tsc + vitest), formats and lints Rust and TypeScript code, and runs Rust tests.
 
 Note: `npm test` at project root does not run integration tests.
 For integration tests, see [below](#integration-tests).
@@ -115,6 +222,8 @@ protect-ffi/
 |       └── src/
 |           └── lib.rs
 ├── platforms/
+├── docs/
+├── scripts/
 ├── package.json
 └── target/
 ```
@@ -131,6 +240,8 @@ protect-ffi/
 | `crates/`            | The directory tree containing the Rust source code for the project.                                                                |
 | `lib.rs`             | Entry point for the Rust source code.                                                                                              |
 | `platforms/`         | The directory containing distributions of the binary addon backend for each platform supported by this library.                    |
+| `docs/`              | JSONB integration docs and migration notes.                                                                        |
+| `scripts/`           | Build helper scripts (e.g. WASM inlining).                                                                         |
 | `package.json`       | The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.              |
 | `target/`            | Binary artifacts generated by the Rust build.                                                                                      |
 
@@ -148,9 +259,11 @@ Example environment variables:
 ```
 CS_CLIENT_ID=
 CS_CLIENT_KEY=
+# The integration tests read CS_CLIENT_ACCESS_KEY; the library itself reads CS_ACCESS_KEY
 CS_CLIENT_ACCESS_KEY=
 CS_WORKSPACE_CRN=
-PGPORT=5432
+# Must match the port used by the integration-test setup (mise.toml)
+PGPORT=5436
 PGDATABASE=cipherstash
 PGUSER=cipherstash
 PGPASSWORD=password
@@ -189,7 +302,7 @@ The release workflow is responsible for:
 
 To perform a release:
 
-1. Navigate to the ["Release" workflow page](https://github.com/cipherstash/protect-ffi/actions/workflows/release.yml) in GitHub.
+1. Navigate to the ["Release" workflow page](https://github.com/cipherstash/protectjs-ffi/actions/workflows/release.yml) in GitHub.
 1. Click on "Run workflow".
 1. Select the branch to release from.
    Use the default of `main` unless you want to do a pre-release version or dry run from a branch.
@@ -200,8 +313,11 @@ To perform a release:
    Select "custom" in the dropdown and fill in the "Custom version" text box if you want to use a semver string instead of the shorthand (patch, minor, major, etc.).
 1. Click "Run workflow".
 
-Note that we currently don't have any automation around release notes or a changelog.
-However, you can add release notes after running the workflow by editing the release on GitHub.
+Release notes and the changelog are automated. Add notes for your changes under the
+`[Unreleased]` heading in [`CHANGELOG.md`](./CHANGELOG.md). On release, the `version`
+npm lifecycle hook promotes that section to a dated release entry
+(`scripts/changelog-release.mjs`), and the workflow publishes the promoted section as
+the GitHub release notes (`scripts/changelog-extract.mjs`).
 
 ## Learn More
 

package/dist/wasm/protect_ffi_bg.js

@@ -247,6 +247,10 @@ export function newClient(opts) {
     const ret = wasm.newClient(opts);
     return ret;
 }
+export function __wbg_BigInt_7882274c8d2ac74c() { return handleError(function (arg0) {
+    const ret = BigInt(arg0);
+    return ret;
+}, arguments); }
 export function __wbg_Error_83742b46f01ce22d(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return ret;
@@ -350,6 +354,10 @@ export function __wbg_arrayBuffer_eb8e9ca620af2a19() { return handleError(functi
     const ret = arg0.arrayBuffer();
     return ret;
 }, arguments); }
+export function __wbg_assign_2c1c53ce7e57ea6e(arg0, arg1) {
+    const ret = Object.assign(arg0, arg1);
+    return ret;
+}
 export function __wbg_buffer_60b8043cd926067d(arg0) {
     const ret = arg0.buffer;
     return ret;
@@ -473,6 +481,16 @@ export function __wbg_instanceof_Map_f194b366846aca0c(arg0) {
     const ret = result;
     return ret;
 }
+export function __wbg_instanceof_Object_be1962063fcc0c9f(arg0) {
+    let result;
+    try {
+        result = arg0 instanceof Object;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
 export function __wbg_instanceof_Promise_7c3bdd7805c2c6e6(arg0) {
     let result;
     try {
@@ -551,6 +569,10 @@ export function __wbg_new_ab79df5bd7c26067() {
     const ret = new Object();
     return ret;
 }
+export function __wbg_new_aff07d10ed2fdd7f(arg0, arg1) {
+    const ret = new RangeError(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
 export function __wbg_new_c518c60af666645b() { return handleError(function () {
     const ret = new AbortController();
     return ret;
@@ -570,7 +592,7 @@ export function __wbg_new_typed_aaaeaf29cf802876(arg0, arg1) {
             const a = state0.a;
             state0.a = 0;
             try {
-                return wasm_bindgen__convert__closures_____invoke__h1201fec59d36da32(a, state0.b, arg0, arg1);
+                return wasm_bindgen__convert__closures_____invoke__h0cb80728b35f261e(a, state0.b, arg0, arg1);
             } finally {
                 state0.a = a;
             }
@@ -605,6 +627,10 @@ export function __wbg_node_84ea875411254db1(arg0) {
     const ret = arg0.node;
     return ret;
 }
+export function __wbg_parse_e9eddd2a82c706eb() { return handleError(function (arg0, arg1) {
+    const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
+    return ret;
+}, arguments); }
 export function __wbg_process_44c7a14e11e9f69e(arg0) {
     const ret = arg0.process;
     return ret;
@@ -612,6 +638,10 @@ export function __wbg_process_44c7a14e11e9f69e(arg0) {
 export function __wbg_prototypesetcall_d62e5099504357e6(arg0, arg1, arg2) {
     Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
 }
+export function __wbg_push_e87b0e732085a946(arg0, arg1) {
+    const ret = arg0.push(arg1);
+    return ret;
+}
 export function __wbg_queueMicrotask_0c399741342fb10f(arg0) {
     const ret = arg0.queueMicrotask;
     return ret;
@@ -643,6 +673,10 @@ export function __wbg_set_282384002438957f(arg0, arg1, arg2) {
 export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
     arg0[arg1] = arg2;
 }
+export function __wbg_set_7eaa4f96924fd6b3() { return handleError(function (arg0, arg1, arg2) {
+    const ret = Reflect.set(arg0, arg1, arg2);
+    return ret;
+}, arguments); }
 export function __wbg_set_8c0b3ffcf05d61c2(arg0, arg1, arg2) {
     arg0.set(getArrayU8FromWasm0(arg1, arg2));
 }
@@ -702,6 +736,10 @@ export function __wbg_status_318629ab93a22955(arg0) {
     const ret = arg0.status;
     return ret;
 }
+export function __wbg_stringify_5ae93966a84901ac() { return handleError(function (arg0) {
+    const ret = JSON.stringify(arg0);
+    return ret;
+}, arguments); }
 export function __wbg_subarray_a068d24e39478a8a(arg0, arg1, arg2) {
     const ret = arg0.subarray(arg1 >>> 0, arg2 >>> 0);
     return ret;
@@ -718,6 +756,10 @@ export function __wbg_then_9e335f6dd892bc11(arg0, arg1, arg2) {
     const ret = arg0.then(arg1, arg2);
     return ret;
 }
+export function __wbg_toString_68d455d069f7169a() { return handleError(function (arg0, arg1) {
+    const ret = arg0.toString(arg1);
+    return ret;
+}, arguments); }
 export function __wbg_url_7fefc1820fba4e0c(arg0, arg1) {
     const ret = arg1.url;
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -742,13 +784,13 @@ export function __wbg_wasmclient_new(arg0) {
     return ret;
 }
 export function __wbindgen_cast_0000000000000001(arg0, arg1) {
-    // Cast intrinsic for `Closure(Closure { dtor_idx: 495, function: Function { arguments: [], shim_idx: 496, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-    const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h379cc5f9ba73967b, wasm_bindgen__convert__closures_____invoke__hc060a2339985e908);
+    // Cast intrinsic for `Closure(Closure { dtor_idx: 893, function: Function { arguments: [], shim_idx: 894, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+    const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__hd9dedd770edb0aa1, wasm_bindgen__convert__closures_____invoke__h8b170b34f8b593df);
     return ret;
 }
 export function __wbindgen_cast_0000000000000002(arg0, arg1) {
-    // Cast intrinsic for `Closure(Closure { dtor_idx: 543, function: Function { arguments: [Externref], shim_idx: 544, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-    const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h18e55ed08acd10aa, wasm_bindgen__convert__closures_____invoke__h425499e9ab8a95b4);
+    // Cast intrinsic for `Closure(Closure { dtor_idx: 946, function: Function { arguments: [Externref], shim_idx: 947, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+    const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h94971d029da3e81d, wasm_bindgen__convert__closures_____invoke__hacad64c6c6b78997);
     return ret;
 }
 export function __wbindgen_cast_0000000000000003(arg0) {
@@ -785,19 +827,19 @@ export function __wbindgen_init_externref_table() {
     table.set(offset + 2, true);
     table.set(offset + 3, false);
 }
-function wasm_bindgen__convert__closures_____invoke__hc060a2339985e908(arg0, arg1) {
-    wasm.wasm_bindgen__convert__closures_____invoke__hc060a2339985e908(arg0, arg1);
+function wasm_bindgen__convert__closures_____invoke__h8b170b34f8b593df(arg0, arg1) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h8b170b34f8b593df(arg0, arg1);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h425499e9ab8a95b4(arg0, arg1, arg2) {
-    const ret = wasm.wasm_bindgen__convert__closures_____invoke__h425499e9ab8a95b4(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__hacad64c6c6b78997(arg0, arg1, arg2) {
+    const ret = wasm.wasm_bindgen__convert__closures_____invoke__hacad64c6c6b78997(arg0, arg1, arg2);
     if (ret[1]) {
         throw takeFromExternrefTable0(ret[0]);
     }
 }
 
-function wasm_bindgen__convert__closures_____invoke__h1201fec59d36da32(arg0, arg1, arg2, arg3) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h1201fec59d36da32(arg0, arg1, arg2, arg3);
+function wasm_bindgen__convert__closures_____invoke__h0cb80728b35f261e(arg0, arg1, arg2, arg3) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h0cb80728b35f261e(arg0, arg1, arg2, arg3);
 }
 
 

package/dist/wasm/protect_ffi_bg.wasm.d.ts

@@ -25,16 +25,16 @@ export const intounderlyingbytesource_cancel: (a: number) => void;
 export const intounderlyingbytesource_pull: (a: number, b: any) => any;
 export const intounderlyingbytesource_start: (a: number, b: any) => void;
 export const intounderlyingbytesource_type: (a: number) => number;
-export const wasm_bindgen__closure__destroy__h379cc5f9ba73967b: (a: number, b: number) => void;
-export const wasm_bindgen__closure__destroy__h18e55ed08acd10aa: (a: number, b: number) => void;
-export const wasm_bindgen__convert__closures_____invoke__h425499e9ab8a95b4: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h1201fec59d36da32: (a: number, b: number, c: any, d: any) => void;
-export const wasm_bindgen__convert__closures_____invoke__hc060a2339985e908: (a: number, b: number) => void;
-export const __wbindgen_malloc: (a: number, b: number) => number;
-export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const wasm_bindgen__closure__destroy__hd9dedd770edb0aa1: (a: number, b: number) => void;
+export const wasm_bindgen__closure__destroy__h94971d029da3e81d: (a: number, b: number) => void;
+export const wasm_bindgen__convert__closures_____invoke__hacad64c6c6b78997: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h0cb80728b35f261e: (a: number, b: number, c: any, d: any) => void;
+export const wasm_bindgen__convert__closures_____invoke__h8b170b34f8b593df: (a: number, b: number) => void;
 export const __wbindgen_exn_store: (a: number) => void;
 export const __externref_table_alloc: () => number;
 export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;
 export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_start: () => void;