{"id":26005450,"url":"https://github.com/cipherstash/protectjs-ffi","last_synced_at":"2026-04-09T17:15:48.071Z","repository":{"id":279543337,"uuid":"902700496","full_name":"cipherstash/protectjs-ffi","owner":"cipherstash","description":"CipherStash Client Rust bindings for JS. Implemented in @cipherstash/protect","archived":false,"fork":false,"pushed_at":"2026-01-13T04:23:45.000Z","size":777,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-13T05:47:45.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/cipherstash/protectjs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipherstash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-13T05:06:22.000Z","updated_at":"2026-01-13T03:20:24.000Z","dependencies_parsed_at":"2025-02-26T05:32:29.272Z","dependency_job_id":"469052e4-e8aa-4523-90cc-74ac643a665d","html_url":"https://github.com/cipherstash/protectjs-ffi","commit_stats":null,"previous_names":["cipherstash/protectjs-ffi"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/cipherstash/protectjs-ffi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fprotectjs-ffi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fprotectjs-ffi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fprotectjs-ffi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fprotectjs-ffi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipherstash","download_url":"https://codeload.github.com/cipherstash/protectjs-ffi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fprotectjs-ffi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-05T20:57:17.337Z","updated_at":"2026-01-28T06:54:32.699Z","avatar_url":"https://github.com/cipherstash.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Protect.js CipherStash Client FFI\n\n\u003e [!IMPORTANT]\n\u003e If you are looking to implement this package into your application please use the official [protect package](https://github.com/cipherstash/protectjs).\n\nThis project provides the JS bindings for the CipherStash Client Rust SDK and is bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon).\n\n## Building\n\nBuilding requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).\n\nTo run the build, run:\n\n```sh\n$ npm run build\n```\n\nThis 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`.\n\n## Local setup\n\nYou can use the `stash` CLI tool to set up your local environment.\n\nYou will be prompted to sign in or create an account and follow steps to create a keyset and client key.\n\n```sh\nbrew install cipherstash/tap/stash\nstash setup\n```\n\n## Exploring\n\nAfter building `protect-ffi`, you can explore its exports at the Node console.\n`CS_CLIENT_ID` and `CS_CLIENT_KEY` must be set in your environment for the call to `newClient()` to succeed.\n\n```sh\n$ npm i\n$ npm run build\n$ node\n\u003e const addon = require(\".\");\n\u003e const client = await addon.newClient({ encryptConfig: {v: 1, tables: {users: {email: {indexes: {ore: {}, match: {}, unique: {}}}}}} });\n\u003e const ciphertext = await addon.encrypt(client, { plaintext: \"plaintext\", column: \"email\", table: \"users\" });\n\u003e const plaintext = await addon.decrypt(client, { ciphertext });\n\u003e console.log({ciphertext, plaintext});\n```\n\n## Errors\n\nAsync API calls throw `ProtectError` with a stable `code` for programmatic handling.\n\n```typescript\ntry {\n  await addon.encryptQuery(client, opts)\n} catch (err) {\n  if (err?.code === 'INVALID_JSON_PATH') {\n    // handle JSON path mistakes\n  }\n  throw err\n}\n```\n\n## Available Scripts\n\nIn the project directory, you can run:\n\n#### `npm run build`\n\nBuilds the Node addon (`index.node`) from source, generating a release build with `cargo --release`.\n\nAdditional [`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):\n\n```\nnpm run build -- --feature=beetle\n```\n\n#### `npm run debug`\n\nSimilar to `npm run build` but generates a debug build with `cargo`.\n\n#### `npm run cross`\n\nSimilar 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.\n\n#### `npm run release`\n\nInitiate a full build and publication of a new patch release of this library via GitHub Actions.\n\n#### `npm run dryrun`\n\nInitiate 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.\n\n#### `npm test`\n\nFormats and lints Rust and TypeScript code.\nAlso runs Rust tests.\n\nNote: `npm test` at project root does not run integration tests.\nFor integration tests, see [below](#integration-tests).\n\n## Project Layout\n\nThe directory structure of this project is:\n\n```\nprotect-ffi/\n├── Cargo.toml\n├── README.md\n├── integration-tests/\n├── lib/\n├── src/\n|   ├── index.mts\n|   └── index.cts\n├── crates/\n|   └── protect-ffi/\n|       └── src/\n|           └── lib.rs\n├── platforms/\n├── package.json\n└── target/\n```\n\n| Entry                | Purpose                                                                                                                            |\n| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `Cargo.toml`         | The Cargo [manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html), which informs the `cargo` command.             |\n| `README.md`          | This file.                                                                                                                         |\n| `integration-tests/` | The directory containing integration tests.                                              |\n| `lib/`               | The directory containing the generated output from [tsc](https://typescriptlang.org).                                              |\n| `src/`               | The directory containing the TypeScript source files.                                                                              |\n| `index.mts`          | Entry point for when this library is loaded via [ESM `import`](https://nodejs.org/api/esm.html#modules-ecmascript-modules) syntax. |\n| `index.cts`          | Entry point for when this library is loaded via [CJS `require`](https://nodejs.org/api/modules.html#requireid).                    |\n| `crates/`            | The directory tree containing the Rust source code for the project.                                                                |\n| `lib.rs`             | Entry point for the Rust source code.                                                                                              |\n| `platforms/`         | The directory containing distributions of the binary addon backend for each platform supported by this library.                    |\n| `package.json`       | The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.              |\n| `target/`            | Binary artifacts generated by the Rust build.                                                                                      |\n\n## Integration tests\n\nIntegration tests live in the `./integration-tests` directory.\nThese tests use the local build of Rust and JavaScript artifacts to test `@cipherstash/protect-ffi` as API consumers would.\n\nThese tests rely on:\n\n- CipherStash to be configured (via `.toml` config or environment variables), and\n- Environment variables for Postgres to be set\n\nExample environment variables:\n```\nCS_CLIENT_ID=\nCS_CLIENT_KEY=\nCS_CLIENT_ACCESS_KEY=\nCS_WORKSPACE_CRN=\nPGPORT=5432\nPGDATABASE=cipherstash\nPGUSER=cipherstash\nPGPASSWORD=password\nPGHOST=localhost\n```\n\nTo run integration tests:\n```sh\nmise setup\nmise test:integration\n```\n\nYou can also run the integration tests in \"watch\" mode:\n\n```sh\nmise test:integration --watch\n```\n\nBy default lock context tests are not included because invalid lock contexts fire security warnings in ZeroKMS.\nTo include these, run:\n\n```sh\nmise test:integration:all\n```\n\n## Releasing\n\nReleases are handled by GitHub Actions using a `workflow_dispatch` event trigger.\nThe [release workflow](./.github/workflows/release.yml) was generated by [Neon](https://neon-rs.dev/).\n\nThe release workflow is responsible for:\n\n- 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`).\n- Creating the GitHub release.\n- Creating a Git tag for the version.\n\nTo perform a release:\n\n1. Navigate to the [\"Release\" workflow page](https://github.com/cipherstash/protect-ffi/actions/workflows/release.yml) in GitHub.\n1. Click on \"Run workflow\".\n1. Select the branch to release from.\n   Use the default of `main` unless you want to do a pre-release version or dry run from a branch.\n1. Select whether or not to do a dry run.\n   Dry runs are useful for verifying that the build will succeed for all platforms before doing a full run with a publish.\n1. Choose a version to publish.\n   The options are similar to [`npm version`](https://docs.npmjs.com/cli/v11/commands/npm-version).\n   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.).\n1. Click \"Run workflow\".\n\nNote that we currently don't have any automation around release notes or a changelog.\nHowever, you can add release notes after running the workflow by editing the release on GitHub.\n\n## Learn More\n\nLearn more about:\n\n- [Neon](https://neon-bindings.com).\n- [Rust](https://www.rust-lang.org).\n- [Node](https://nodejs.org).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fprotectjs-ffi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipherstash%2Fprotectjs-ffi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fprotectjs-ffi/lists"}