Configuration

The SDK supports three configuration methods. Environment variables take precedence over config files.

Environment variables

The simplest approach. Set these in a .env file or your hosting platform:

Sign up at cipherstash.com/signup and follow the onboarding to generate credentials.

TOML config files

For projects that prefer file-based configuration, use two files in your project root:

cipherstash.toml

Non-sensitive configuration. Safe to commit to version control.

[encrypt]
client_id = "your-client-id"

[auth]
workspace_crn = "your-workspace-crn"

cipherstash.secret.toml

Sensitive credentials. Add this file to .gitignore.

[encrypt]
client_key = "your-client-key"

[auth]
access_key = "your-access-key"

Programmatic config

Pass config directly when initializing the client. Useful when loading credentials from a secret manager:

import { Encryption, type EncryptionClientConfig } from "@cipherstash/stack"
import { users } from "./schema"

const config: EncryptionClientConfig = {
  schemas: [users],
  config: {
    workspaceCrn: "your-workspace-crn",
    accessKey: "your-access-key",
    clientId: "your-client-id",
    clientKey: "your-client-key",
  },
}

const client = await Encryption(config)

Keysets

Key Sets are a ZeroKMS primitive for cryptographic isolation. Each Key Set maintains its own set of data encryption keys — data encrypted under one Key Set cannot be decrypted with another. This is the same primitive that powers environment isolation in Secrets.

You can specify a Key Set by ID or by name:

By ID

const client = await Encryption({
  schemas: [users],
  config: {
    keyset: { id: "123e4567-e89b-12d3-a456-426614174000" },
  },
})

By name

const client = await Encryption({
  schemas: [users],
  config: {
    keyset: { name: "Company A" },
  },
})

For full details on creating and managing Key Sets, see the Key Sets reference.

Logging

Control log verbosity with the STASH_STACK_LOG environment variable:

STASH_STACK_LOG=error  # debug | info | error (default: error)

The SDK never logs plaintext data.

Deploying to production

File system write permissions

In most hosting environments, set CS_CONFIG_PATH to a writable directory:

CS_CONFIG_PATH=/tmp/.cipherstash

This has been tested on Vercel and AWS Lambda.

Bundler configuration

@cipherstash/stack includes a native FFI module that must be excluded from bundling:

• Next.js: See Bundling — Next.js
• SST / serverless: See SST setup
• Webpack / esbuild: Add @cipherstash/stack to your externals configuration

Platform requirements

• Node.js >= 18
• Bun is not currently supported due to incomplete Node-API compatibility
• See Troubleshooting for npm lockfile issues on Linux