Configuration

Local development (recommended)

If you have run npx @cipherstash/cli init, no configuration is needed for local development. The SDK automatically uses device-based authentication to access your workspace and default keyset.

See Getting started for setup instructions.

Production and CI/CD configuration

In production environments where device-based auth is not available, the SDK supports two configuration methods: environment variables and programmatic config. Environment variables take precedence over programmatic config.

Environment variables

Set these in your hosting platform or CI/CD system:

Variable	Description	Required
`CS_WORKSPACE_CRN`	The workspace identifier (CRN format)	Yes
`CS_CLIENT_ID`	The client identifier	Yes
`CS_CLIENT_KEY`	Client key material used with ZeroKMS	Yes
`CS_CLIENT_ACCESS_KEY`	API key for authenticating with the CipherStash API	Yes
`CS_CONFIG_PATH`	Temporary path for client configuration	No (default: `/home/{username}/.cipherstash`)
`STASH_STACK_LOG`	Log level (`debug`, `info`, `error`)	No (default: `error`)

See Going to production for a step-by-step guide to generating production credentials.

Avoid setting CS_* environment variables for local development. Device-based auth provides per-developer identity, no shared secrets, and automatic session management. See Getting started to set up device auth.

Programmatic config

Pass config directly when initializing the client. Use this approach in production 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)

Subpath exports

The SDK provides multiple subpath exports for importing only what you need:

Import path	Provides
`@cipherstash/stack`	`Encryption` function, `Secrets` class, `encryptedTable`, `encryptedColumn`, `encryptedField` (convenience re-exports)
`@cipherstash/stack/schema`	`encryptedTable`, `encryptedColumn`, `encryptedField`, schema types
`@cipherstash/stack/identity`	`LockContext` class and identity types
`@cipherstash/stack/secrets`	`Secrets` class and secrets types
`@cipherstash/stack/drizzle`	`encryptedType`, `extractEncryptionSchema`, `createEncryptionOperators` for Drizzle ORM
`@cipherstash/stack/supabase`	`encryptedSupabase` wrapper for Supabase
`@cipherstash/stack/dynamodb`	`encryptedDynamoDB` helper for DynamoDB
`@cipherstash/stack/encryption`	`EncryptionClient` class, `Encryption` function
`@cipherstash/stack/errors`	`EncryptionErrorTypes`, `StackError`, error subtypes, `getErrorMessage`
`@cipherstash/stack/client`	Client-safe exports: schema builders, schema types, `EncryptionClient` type (no native FFI)
`@cipherstash/stack/types`	All TypeScript types

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: {
    workspaceCrn: "your-workspace-crn",
    accessKey: "your-access-key",
    clientId: "your-client-id",
    clientKey: "your-client-key",
    keyset: { id: "123e4567-e89b-12d3-a456-426614174000" },
  },
})

By name

const client = await Encryption({
  schemas: [users],
  config: {
    workspaceCrn: "your-workspace-crn",
    accessKey: "your-access-key",
    clientId: "your-client-id",
    clientKey: "your-client-key",
    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)

Value	What is logged
`error`	Errors only (default)
`info`	Info and errors
`debug`	Debug, info, and errors

The SDK never logs plaintext data.

Deploying to production

For a complete guide to transitioning from local device-based auth to production environment variables, see Going 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
See Troubleshooting for npm lockfile issues on Linux

Configuration

On this page