@cipherstash/protect-ffi 0.5.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# protect-ffi
+
+> [!IMPORTANT]  
+> If you are looking to implement this package into your application please use the official [protect package](https://github.com/cipherstash/protect).
+
+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).
+
+## Building
+
+Building requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
+
+To run the build, run:
+
+```sh
+$ npm run build
+```
+
+This command uses the [@neon-rs/cli](https://www.npmjs.com/package/@neon-rs/cli) utility to assemble the binary Node addon from the output of `cargo`.
+
+## 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.
+
+```sh
+$ npm i
+$ npm run build
+$ node
+> const addon = require(".");
+> const client = await addon.newClient();
+> const ciphertext = await addon.encrypt(client, "plaintext", "column_name");
+> const plaintext = await addon.decrypt(client, ciphertext);
+> console.log({ciphertext, plaintext});
+```
+
+## Available Scripts
+
+In the project directory, you can run:
+
+#### `npm run build`
+
+Builds the Node addon (`index.node`) from source, generating a release build with `cargo --release`.
+
+Additional [`cargo build`](https://doc.rust-lang.org/cargo/commands/cargo-build.html) arguments may be passed to `npm run build` and similar commands. For example, to enable a [cargo feature](https://doc.rust-lang.org/cargo/reference/features.html):
+
+```
+npm run build -- --feature=beetle
+```
+
+#### `npm run debug`
+
+Similar to `npm run build` but generates a debug build with `cargo`.
+
+#### `npm run cross`
+
+Similar to `npm run build` but uses [cross-rs](https://github.com/cross-rs/cross) to cross-compile for another platform. Use the [`CARGO_BUILD_TARGET`](https://doc.rust-lang.org/cargo/reference/config.html#buildtarget) environment variable to select the build target.
+
+#### `npm run release`
+
+Initiate a full build and publication of a new patch release of this library via GitHub Actions.
+
+#### `npm run dryrun`
+
+Initiate a dry run of a patch release of this library via GitHub Actions. This performs a full build but does not publish the final result.
+
+#### `npm test`
+
+Runs the unit tests by calling `cargo test`. You can learn more about [adding tests to your Rust code](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) from the [Rust book](https://doc.rust-lang.org/book/).
+
+## Project Layout
+
+The directory structure of this project is:
+
+```
+protect-ffi/
+├── Cargo.toml
+├── README.md
+├── lib/
+├── src/
+|   ├── index.mts
+|   └── index.cts
+├── crates/
+|   └── protect-ffi/
+|       └── src/
+|           └── lib.rs
+├── platforms/
+├── package.json
+└── target/
+```
+
+| Entry          | Purpose                                                                                                                                  |
+|----------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `Cargo.toml`   | The Cargo [manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html), which informs the `cargo` command.                   |
+| `README.md`    | This file.                                                                                                                               |
+| `lib/`         | The directory containing the generated output from [tsc](https://typescriptlang.org).                                                    |
+| `src/`         | The directory containing the TypeScript source files.                                                                                    |
+| `index.mts`    | Entry point for when this library is loaded via [ESM `import`](https://nodejs.org/api/esm.html#modules-ecmascript-modules) syntax.       |
+| `index.cts`    | Entry point for when this library is loaded via [CJS `require`](https://nodejs.org/api/modules.html#requireid).                          |
+| `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.                          |
+| `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.                                                                                            |
+
+## Releasing
+
+Releases are handled by GitHub Actions using a `workflow_dispatch` event trigger.
+The [release workflow](./.github/workflows/release.yml) was generated by [Neon](https://neon-rs.dev/).
+
+The release workflow is responsible for:
+- Building and publishing the main `@cipherstash/protect-ffi` package as well as the native packages for each platform (e.g. `@cipherstash/protect-ffi-darwin-arm64`).
+- Creating the GitHub release.
+- Creating a Git tag for the version.
+
+To perform a release:
+1. Navigate to the ["Release" workflow page](https://github.com/cipherstash/protect-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.
+1. Select whether or not to do a dry run.
+Dry runs are useful for verifying that the build will succeed for all platforms before doing a full run with a publish.
+1. Choose a version to publish.
+The options are similar to [`npm version`](https://docs.npmjs.com/cli/v11/commands/npm-version).
+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.
+
+## Learn More
+
+Learn more about:
+
+- [Neon](https://neon-bindings.com).
+- [Rust](https://www.rust-lang.org).
+- [Node](https://nodejs.org).

package/lib/index.cjs

@@ -0,0 +1,83 @@
+"use strict";
+// This module is the CJS entry point for the library.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newClient = newClient;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.encryptBulk = encryptBulk;
+exports.decryptBulk = decryptBulk;
+exports.decryptBulkFallible = decryptBulkFallible;
+// The Rust addon.
+const addon = __importStar(require("./load.cjs"));
+function newClient() {
+    return addon.newClient();
+}
+function encrypt(client, plaintext, columnName, lockContext, ctsToken) {
+    if (ctsToken) {
+        return addon.encrypt(client, plaintext, columnName, lockContext, ctsToken);
+    }
+    if (lockContext) {
+        return addon.encrypt(client, plaintext, columnName, lockContext);
+    }
+    return addon.encrypt(client, plaintext, columnName);
+}
+function decrypt(client, ciphertext, lockContext, ctsToken) {
+    if (ctsToken) {
+        return addon.decrypt(client, ciphertext, lockContext, ctsToken);
+    }
+    if (lockContext) {
+        return addon.decrypt(client, ciphertext, lockContext);
+    }
+    return addon.decrypt(client, ciphertext);
+}
+function encryptBulk(client, plaintextTargets, ctsToken) {
+    if (ctsToken) {
+        return addon.encryptBulk(client, plaintextTargets, ctsToken);
+    }
+    return addon.encryptBulk(client, plaintextTargets);
+}
+function decryptBulk(client, ciphertexts, ctsToken) {
+    if (ctsToken) {
+        return addon.decryptBulk(client, ciphertexts, ctsToken);
+    }
+    return addon.decryptBulk(client, ciphertexts);
+}
+function decryptBulkFallible(client, ciphertexts, ctsToken) {
+    if (ctsToken) {
+        return addon.decryptBulkFallible(client, ciphertexts, ctsToken);
+    }
+    return addon.decryptBulkFallible(client, ciphertexts);
+}

package/lib/index.d.cts

@@ -0,0 +1,45 @@
+import * as addon from './load.cjs';
+declare module './load.cjs' {
+    interface Client {
+    }
+    function newClient(): Promise<Client>;
+    function encrypt(client: Client, plaintext: string, columnName: string, context?: Context, ctsToken?: CtsToken): Promise<string>;
+    function decrypt(client: Client, ciphertext: string, context?: Context, ctsToken?: CtsToken): Promise<string>;
+    function encryptBulk(client: Client, plaintextTargets: BulkEncryptPayload[], ctsToken?: CtsToken): Promise<string[]>;
+    function decryptBulk(client: Client, ciphertexts: BulkDecryptPayload[], ctsToken?: CtsToken): Promise<string[]>;
+    function decryptBulkFallible(client: Client, ciphertexts: BulkDecryptPayload[], ctsToken?: CtsToken): Promise<DecryptResult[]>;
+}
+export type DecryptResult = {
+    data: string;
+} | {
+    error: string;
+};
+export declare function newClient(): Promise<addon.Client>;
+export declare function encrypt(client: addon.Client, plaintext: string, columnName: string, lockContext?: Context, ctsToken?: CtsToken): Promise<string>;
+export declare function decrypt(client: addon.Client, ciphertext: string, lockContext?: Context, ctsToken?: CtsToken): Promise<string>;
+export declare function encryptBulk(client: addon.Client, plaintextTargets: BulkEncryptPayload[], ctsToken?: CtsToken): Promise<string[]>;
+export declare function decryptBulk(client: addon.Client, ciphertexts: BulkDecryptPayload[], ctsToken?: CtsToken): Promise<string[]>;
+export declare function decryptBulkFallible(client: addon.Client, ciphertexts: BulkDecryptPayload[], ctsToken?: CtsToken): Promise<DecryptResult[]>;
+export type BulkEncryptPayload = {
+    plaintext: string;
+    column: string;
+    lockContext?: Context;
+};
+export type BulkDecryptPayload = {
+    ciphertext: string;
+    lockContext?: Context;
+};
+export type CtsToken = {
+    accessToken: string;
+    expiry: number;
+};
+export type Context = {
+    identityClaim: string[];
+};
+export type EncryptedEqlPayload = {
+    c: string;
+};
+export type BulkEncryptedEqlPayload = {
+    c: string;
+    id: string;
+}[];

package/lib/index.d.mts

@@ -0,0 +1 @@
+export * from './index.cjs';

package/lib/index.mjs

@@ -0,0 +1,2 @@
+// This module is the ESM entry point for the library.
+export * from './index.cjs';

package/lib/load.cjs

@@ -0,0 +1,18 @@
+"use strict";
+// This module loads the platform-specific build of the addon on
+// the current system. The supported platforms are registered in
+// the `platforms` object below, whose entries can be managed by
+// by the Neon CLI:
+//
+//   https://www.npmjs.com/package/@neon-rs/cli
+Object.defineProperty(exports, "__esModule", { value: true });
+module.exports = require('@neon-rs/load').proxy({
+    platforms: {
+        'win32-x64-msvc': () => require('@cipherstash/protect-ffi-win32-x64-msvc'),
+        'darwin-x64': () => require('@cipherstash/protect-ffi-darwin-x64'),
+        'darwin-arm64': () => require('@cipherstash/protect-ffi-darwin-arm64'),
+        'linux-x64-gnu': () => require('@cipherstash/protect-ffi-linux-x64-gnu'),
+        'linux-arm64-gnu': () => require('@cipherstash/protect-ffi-linux-arm64-gnu'),
+    },
+    debug: () => require('../index.node'),
+});

package/lib/load.d.cts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@cipherstash/protect-ffi",
+  "version": "0.5.4",
+  "description": "",
+  "main": "./lib/index.cjs",
+  "scripts": {
+    "test": "tsc &&cargo test",
+    "cargo-build": "tsc &&cargo build --message-format=json-render-diagnostics > cargo.log",
+    "cross-build": "tsc &&cross build --message-format=json-render-diagnostics > cross.log",
+    "postcargo-build": "neon dist < cargo.log",
+    "postcross-build": "neon dist -m /target < cross.log",
+    "debug": "npm run cargo-build --",
+    "build": "npm run cargo-build -- --release",
+    "cross": "npm run cross-build -- --release",
+    "prepack": "tsc &&neon update",
+    "version": "neon bump --binaries platforms && git add .",
+    "release": "gh workflow run release.yml -f dryrun=false -f version=patch",
+    "dryrun": "gh workflow run publish.yml -f dryrun=true"
+  },
+  "author": "",
+  "license": "ISC",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    }
+  },
+  "types": "./lib/index.d.cts",
+  "files": [
+    "lib/**/*.?({c,m}){t,j}s"
+  ],
+  "neon": {
+    "type": "library",
+    "org": "@cipherstash",
+    "platforms": "common",
+    "load": "./src/load.cts",
+    "prefix": "protect-ffi-"
+  },
+  "devDependencies": {
+    "@neon-rs/cli": "^0.1.82",
+    "@tsconfig/node20": "^20.1.4",
+    "@types/node": "^20.11.16",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@neon-rs/load": "^0.1.82"
+  },
+  "optionalDependencies": {
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.5.4",
+    "@cipherstash/protect-ffi-darwin-x64": "0.5.4",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.5.4",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.5.4",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.5.4"
+  }
+}