@cipherstash/protect-ffi 0.27.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
@@ -91,8 +90,8 @@ Notes:
 - 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` but cannot be produced
-  end-to-end yet: the client does not emit the `op` term (CIP-3280).
+- `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
@@ -104,6 +103,55 @@ Notes:
 > `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.
@@ -151,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).
@@ -175,6 +222,8 @@ protect-ffi/
 |       └── src/
 |           └── lib.rs
 ├── platforms/
+├── docs/
+├── scripts/
 ├── package.json
 └── target/
 ```
@@ -191,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.                                                                                      |
 
@@ -208,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
@@ -249,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.
@@ -260,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;
@@ -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,12 +784,12 @@ export function __wbg_wasmclient_new(arg0) {
     return ret;
 }
 export function __wbindgen_cast_0000000000000001(arg0, arg1) {
-    // Cast intrinsic for `Closure(Closure { dtor_idx: 879, function: Function { arguments: [], shim_idx: 880, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+    // 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: 932, function: Function { arguments: [Externref], shim_idx: 933, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+    // 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;
 }

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

@@ -30,11 +30,11 @@ export const wasm_bindgen__closure__destroy__h94971d029da3e81d: (a: number, b: n
 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_malloc: (a: number, b: number) => number;
-export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 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;