@cipherstash/protect-ffi 0.27.0 → 0.28.0

package/lib/bigintWire.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Internal wire encoding for JS `bigint` plaintexts crossing the Neon
+ * boundary.
+ *
+ * The native addon extracts every options object with neon's `Json`
+ * extractor, which runs `JSON.stringify` on the JS side — and
+ * `JSON.stringify` throws a `TypeError` on any `bigint`. So `bigint`
+ * plaintexts are bounds-checked against i64 here (with a clear
+ * `RangeError`) and encoded into the tagged single-key map
+ * `{"__protect_ffi_bigint__": "<decimal string>"}`, which the Rust side
+ * deserializes into `JsPlaintext::BigInt`. The value is a decimal string,
+ * not a number: an i64-magnitude number literal would already have lost
+ * precision beyond 2^53.
+ *
+ * The wasm build performs the equivalent encoding in Rust
+ * (`encode_plaintext` in `crates/protect-ffi/src/wasm.rs`) because
+ * wasm consumers call the wasm-bindgen exports directly, without this
+ * wrapper.
+ *
+ * The decrypt direction needs no decoding: the native addon constructs a
+ * real JS `bigint` (`JsBigInt::from_i64` on Neon, `js_sys::BigInt` on
+ * wasm).
+ */
+/** Must match `BIGINT_WIRE_KEY` in `crates/protect-ffi/src/js_plaintext.rs`. */
+export declare const BIGINT_WIRE_KEY = "__protect_ffi_bigint__";
+/** Smallest value an encrypted bigint column can store (i64::MIN). */
+export declare const BIGINT_MIN: bigint;
+/** Largest value an encrypted bigint column can store (i64::MAX). */
+export declare const BIGINT_MAX: bigint;
+/** The tagged wire form a `bigint` plaintext crosses the boundary in. */
+export type BigIntWire = {
+    [K in typeof BIGINT_WIRE_KEY]: string;
+};
+/**
+ * Encode a `bigint` plaintext into its tagged wire form, throwing a
+ * `RangeError` (naming the i64 bounds and the offending direction) when
+ * the value does not fit a signed 64-bit integer. Non-`bigint` values pass
+ * through untouched. The error deliberately does not echo the value: it is
+ * plaintext being encrypted.
+ */
+export declare function encodeBigIntPlaintext<T>(plaintext: T | bigint): T | BigIntWire;
+/**
+ * Return `opts` with a `bigint` `plaintext` replaced by its tagged wire
+ * form. When the plaintext is not a `bigint`, the original object is
+ * returned unchanged (no clone).
+ */
+export declare function withEncodedPlaintext<T extends {
+    plaintext: unknown;
+}>(opts: T): T;
+/**
+ * Bulk variant of {@link withEncodedPlaintext}: returns the original array
+ * (no clone) when no payload carries a `bigint` plaintext.
+ */
+export declare function withEncodedPlaintexts<T extends {
+    plaintext: unknown;
+}>(payloads: T[]): T[];

package/lib/bigintWire.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Internal wire encoding for JS `bigint` plaintexts crossing the Neon
+ * boundary.
+ *
+ * The native addon extracts every options object with neon's `Json`
+ * extractor, which runs `JSON.stringify` on the JS side — and
+ * `JSON.stringify` throws a `TypeError` on any `bigint`. So `bigint`
+ * plaintexts are bounds-checked against i64 here (with a clear
+ * `RangeError`) and encoded into the tagged single-key map
+ * `{"__protect_ffi_bigint__": "<decimal string>"}`, which the Rust side
+ * deserializes into `JsPlaintext::BigInt`. The value is a decimal string,
+ * not a number: an i64-magnitude number literal would already have lost
+ * precision beyond 2^53.
+ *
+ * The wasm build performs the equivalent encoding in Rust
+ * (`encode_plaintext` in `crates/protect-ffi/src/wasm.rs`) because
+ * wasm consumers call the wasm-bindgen exports directly, without this
+ * wrapper.
+ *
+ * The decrypt direction needs no decoding: the native addon constructs a
+ * real JS `bigint` (`JsBigInt::from_i64` on Neon, `js_sys::BigInt` on
+ * wasm).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BIGINT_MAX = exports.BIGINT_MIN = exports.BIGINT_WIRE_KEY = void 0;
+exports.encodeBigIntPlaintext = encodeBigIntPlaintext;
+exports.withEncodedPlaintext = withEncodedPlaintext;
+exports.withEncodedPlaintexts = withEncodedPlaintexts;
+/** Must match `BIGINT_WIRE_KEY` in `crates/protect-ffi/src/js_plaintext.rs`. */
+exports.BIGINT_WIRE_KEY = '__protect_ffi_bigint__';
+/** Smallest value an encrypted bigint column can store (i64::MIN). */
+exports.BIGINT_MIN = -(2n ** 63n);
+/** Largest value an encrypted bigint column can store (i64::MAX). */
+exports.BIGINT_MAX = 2n ** 63n - 1n;
+const I64_BOUNDS_SUFFIX = 'encrypted bigint values must fit in a signed 64-bit integer ' +
+    '(-9223372036854775808 to 9223372036854775807)';
+/**
+ * Encode a `bigint` plaintext into its tagged wire form, throwing a
+ * `RangeError` (naming the i64 bounds and the offending direction) when
+ * the value does not fit a signed 64-bit integer. Non-`bigint` values pass
+ * through untouched. The error deliberately does not echo the value: it is
+ * plaintext being encrypted.
+ */
+function encodeBigIntPlaintext(plaintext) {
+    if (typeof plaintext !== 'bigint') {
+        return plaintext;
+    }
+    if (plaintext > exports.BIGINT_MAX) {
+        throw new RangeError(`BigInt plaintext is above the maximum supported value: ${I64_BOUNDS_SUFFIX}`);
+    }
+    if (plaintext < exports.BIGINT_MIN) {
+        throw new RangeError(`BigInt plaintext is below the minimum supported value: ${I64_BOUNDS_SUFFIX}`);
+    }
+    return { [exports.BIGINT_WIRE_KEY]: plaintext.toString() };
+}
+/**
+ * Return `opts` with a `bigint` `plaintext` replaced by its tagged wire
+ * form. When the plaintext is not a `bigint`, the original object is
+ * returned unchanged (no clone).
+ */
+function withEncodedPlaintext(opts) {
+    // `opts?.` (matching the detection pass in withEncodedPlaintexts): a
+    // null/undefined element must fall through to native's own validation
+    // error rather than throw a raw property-access TypeError here — the
+    // error a bad element produces must not depend on whether a *sibling*
+    // element happens to carry a bigint.
+    if (typeof opts?.plaintext !== 'bigint') {
+        return opts;
+    }
+    return { ...opts, plaintext: encodeBigIntPlaintext(opts.plaintext) };
+}
+/**
+ * Bulk variant of {@link withEncodedPlaintext}: returns the original array
+ * (no clone) when no payload carries a `bigint` plaintext.
+ */
+function withEncodedPlaintexts(payloads) {
+    if (!Array.isArray(payloads) ||
+        !payloads.some((p) => typeof p?.plaintext === 'bigint')) {
+        return payloads;
+    }
+    return payloads.map(withEncodedPlaintext);
+}

package/lib/index.cjs

@@ -48,6 +48,7 @@ exports.decryptBulkFallible = decryptBulkFallible;
 exports.encryptQuery = encryptQuery;
 exports.encryptQueryBulk = encryptQueryBulk;
 exports.ensureKeyset = ensureKeyset;
+const bigintWire_js_1 = require("./bigintWire.js");
 const credentials_js_1 = require("./credentials.js");
 const native = __importStar(require("./load.cjs"));
 const normalizeEncryptConfig_js_1 = require("./normalizeEncryptConfig.js");
@@ -81,7 +82,7 @@ function newClient(opts) {
     }, opts.strategy));
 }
 function encrypt(client, opts) {
-    return wrapAsync(() => native.encrypt(client, opts));
+    return wrapAsync(() => native.encrypt(client, (0, bigintWire_js_1.withEncodedPlaintext)(opts)));
 }
 function decrypt(client, opts) {
     return wrapAsync(() => native.decrypt(client, opts));
@@ -97,7 +98,10 @@ function isEncrypted(encrypted) {
     return wrapSync(() => native.isEncrypted(encrypted));
 }
 function encryptBulk(client, opts) {
-    return wrapAsync(() => native.encryptBulk(client, opts));
+    return wrapAsync(() => {
+        const plaintexts = (0, bigintWire_js_1.withEncodedPlaintexts)(opts.plaintexts);
+        return native.encryptBulk(client, plaintexts === opts.plaintexts ? opts : { ...opts, plaintexts });
+    });
 }
 function decryptBulk(client, opts) {
     return wrapAsync(() => native.decryptBulk(client, opts));
@@ -125,11 +129,14 @@ async function decryptBulkFallible(client, opts) {
  * shape exists yet, so those queries require an `eqlVersion: 2` client.
  */
 function encryptQuery(client, opts) {
-    return wrapAsync(() => native.encryptQuery(client, opts));
+    return wrapAsync(() => native.encryptQuery(client, (0, bigintWire_js_1.withEncodedPlaintext)(opts)));
 }
 /** Bulk variant of {@link encryptQuery} — same EQL v3 restrictions apply. */
 function encryptQueryBulk(client, opts) {
-    return wrapAsync(() => native.encryptQueryBulk(client, opts));
+    return wrapAsync(() => {
+        const queries = (0, bigintWire_js_1.withEncodedPlaintexts)(opts.queries);
+        return native.encryptQueryBulk(client, queries === opts.queries ? opts : { ...opts, queries });
+    });
 }
 /**
  * Test-only helper: ensures a keyset with the given name exists, creating it if necessary,

package/lib/index.d.cts

@@ -325,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.27.0",
+  "version": "0.28.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.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"
   }
 }