Skip to content

Latest commit

 

History

History
111 lines (71 loc) · 4.85 KB

configuration.md

File metadata and controls

111 lines (71 loc) · 4.85 KB

Protect.js Configuration

Protect.js is configured with toml files or environment variables, and is used to initialize the client when Protect.js is initialized.

Environment variables will take precedence over configuration files and it's recommented to use them for sensitive values.

Jump to a section

cipherstash.toml

The cipherstash.toml file is the primary (non-sensitive) configuration file. It stores essential identifiers, like client_id and workspace_id, but must not contain sensitive secrets (e.g., client_key, access_key). Those sensitive values should be placed in either:

  • The cipherstash.secret.toml file, or
  • Environment variables (e.g., CS_CLIENT_KEY).

The cipherstash.toml must be stored in the root directory of your project.

Specification

The minimal cipherstash.toml file:

# cipherstash.toml

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

[auth]
workspace_id = "your-workspace-id"

[encrypt] section

  • client_id (required): A UUID that identifies the client or project.
  • default_keyset_id (optional): A UUID referencing the default keyset (used if you have more than one keyset).
  • client_key (not allowed): This is explicitly disallowed and will be rejected at runtime. The client key must be stored in cipherstash.secret.toml or in an environment variable CS_CLIENT_KEY.

[auth] section

  • workspace_id (required): A base-32 encoded 10-byte unique identifier.
  • access_key (not allowed): This is explicitly disallowed and will be rejected at runtime. The access key must be stored in cipherstash.secret.toml or in an environment variable CS_CLIENT_ACCESS_KEY.

cipherstash.secret.toml

cipherstash.secret.toml is used to store sensitive CipherStash credentials that must not appear in cipherstash.toml.

The cipherstash.toml must be stored in the root directory of your project.

Specification

The minimal cipherstash.secret.toml file:

# cipherstash.secret.toml

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

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

[encrypt] section

  • client_key (required): The client key, typically a hex-encoded string generated by CipherStash. This is critical for encrypting/decrypting data.

[auth] section

  • access_key (required): The access key which is used to authenticate and authorize against CipherStash services.

Environment variables

You can also use environment variables to configure Protect.js. The following environment variables are supported:

Variable name Description Required Default
CS_CLIENT_ID The client ID for your CipherStash account. Yes
CS_CLIENT_KEY The client key for your CipherStash account. Yes
CS_WORKSPACE_ID The workspace ID for your CipherStash account. Yes
CS_CLIENT_ACCESS_KEY The access key for your CipherStash account. Yes
CS_ZEROKMS_HOST The host for the ZeroKMS server. No https://ap-southeast-2.aws.viturhosted.net
CS_CONFIG_PATH A temporary path to store the CipherStash client configuration. No /home/{username}/.cipherstash

Deploying to production

Tip

There are some configuration details you should take note of when deploying @cipherstash/protect in your production apps.

Region configuration

If you've created a Workspace in a region other than ap-southeast-2, you will need to set the CS_ZEROKMS_HOST environment variable to the appropriate region.

For example, if you are using ZeroKMS in the eu-central-1 region, you need to set the CS_ZEROKMS_HOST variable to https://eu-central-1.aws.viturhosted.net. This is a known usability issue that will be addressed.

File system write permissions

In most hosting environments, the CS_CONFIG_PATH environment variable will need to be set to a path that the user running the application has permission to write to.

Setting CS_CONFIG_PATH to /tmp/.cipherstash will work in most cases, and has been tested on Vercel, and AWS Lambda.