Config encryption

How CrossWatch encrypts secret values in config.json, where the master key comes from, and what to back up.

CrossWatch can encrypt secret values before writing them to config.json.

This protects secrets at rest, but it does not protect a compromised host.

Configuration encryption is included starting with v0.9.13 and is enabled by default.

It does not replace normal host security, file permissions, or backup hygiene.

What gets encrypted

Secret fields are encrypted when CrossWatch saves config.json.

Common examples:

• api_key

• access_token

• refresh_token

• client_secret

• account_token

• pms_token

• password

• keys ending in _token

Typical affected providers:

• Plex

• Trakt

• SIMKL

• AniList

• MDBList

• TMDb (Sync)

• Tautulli

What stays plain text

Non-secret settings stay readable.

Examples:

• server URLs

• booleans

• timeouts

• page sizes

• feature toggles

That keeps config.json usable for troubleshooting.

Stored format

Encrypted values are written with an enc:v1: prefix.

Example:

enc:v1:...

If a value does not use that prefix, CrossWatch treats it as plain text.

This lets older plain-text configs continue to load.

Master key source order

CrossWatch checks for the master key in this order:

1. CW_CONFIG_KEY

2. CROSSWATCH_CONFIG_KEY

3. /config/.cw_master_key

If an environment variable is set, it wins.

If not, CrossWatch falls back to /config/.cw_master_key.

Anyone with both the encrypted config and the matching master key can decrypt the secrets.

Protect both.

Save and migration behavior

Existing plain-text secrets are not rewritten immediately.

They are encrypted the next time CrossWatch saves config.json through the normal save path.

That means:

• old installs still load

• encrypted and plain-text values can coexist during transition

• a normal save migrates secret fields to encrypted form

If you still see plain-text secrets after enabling encryption, save the config once.

UI behavior

The browser does not decrypt secrets.

The backend handles decrypt and encrypt operations.

In normal config views:

• the backend reads and decrypts secrets

• the UI receives a redacted version

• secret fields appear masked or empty

That means the browser does not need the master key.

Backup and restore

To restore an encrypted config, you need both:

• config.json

• the matching master key

If you restore config.json without the key, CrossWatch cannot decrypt stored secrets.

Recommended practice:

• back up config and key together

• store the key securely

• avoid casual exports that include secrets or key material

Moving to another machine

When migrating CrossWatch:

1. Move config.json.

2. Move the matching master key, or set the same environment variable.

3. Start CrossWatch.

4. Verify provider authentication still works.

If you move only config.json, encrypted secrets will not load.

Key rotation

If you change the master key, existing secrets must be re-encrypted.

Safe flow:

1. Start with the old key.

2. Decrypt existing values.

3. Switch to the new key.

4. Save config again.

Do not replace the key and expect old encrypted values to keep working.

Troubleshooting

config.json still shows plain-text secrets

Check these first:

• Has the config been saved since encryption was enabled?

• Is another code path writing raw JSON?

Authentication broke after a restore or move

Check these first:

• Is the correct master key present?

• Did the environment variable change?

• Is /config/.cw_master_key missing or different?

UI shows masked values

That usually means a secret is already stored.

It does not mean the real value is literally the mask.

Related pages

• Configuration (config.json)

• Default config values