# Worker Secrets

> **Audience:** the person deploying and operating Studio

ZeroPress Studio uses Cloudflare Worker secrets for values that must not be
stored in source control or ordinary plaintext variables. Creating and applying
these bindings remains an operator action; Studio never changes its own Worker
configuration.

## Required format

Every Studio Worker secret uses the same strict format:

- 32–256 characters
- printable ASCII from `!` through `~`
- no spaces or control characters
- a unique value for each secret and each Studio installation

A 64-character lowercase hexadecimal value generated from 32 random bytes is
the recommended form. It carries 256 bits of randomness and can be copied safely
through a shell or the Cloudflare dashboard without whitespace or padding.

Do not use a password, an Argon2 hash, or an Argon2 salt as a Worker secret. A
password-hashing salt has a different purpose and is not expected to remain
secret.

## Secret responsibilities

| Secret | When it is needed | Lifecycle |
| --- | --- | --- |
| `STUDIO_AUTH_SECRET` | Initial installation and every normal Studio start | Keep stable for the lifetime of the installation |
| `STUDIO_INSTALL_TOKEN` | Only while installing an uninstalled D1 database in `initial` mode | Generate separately and remove the binding after installation |
| `STUDIO_OPERATIONS_TOKEN` | Only when Maintenance & Recovery is explicitly enabled | Generate separately, restrict by the operations boundary, and rotate after suspected exposure or emergency recovery |

Never reuse one value across these bindings. `STUDIO_AUTH_SECRET` protects MFA
data, encrypted provider credentials, and temporary authentication information.
Losing or replacing it can make protected data unusable; keep an operator copy
in an appropriate password or secret manager.

## Fastest path from the Studio status screen

When Studio reports that `STUDIO_AUTH_SECRET` is missing or invalid, select
**Generate secure value**.

Studio then:

1. asks the browser Web Crypto API for 32 random bytes;
2. displays those bytes as a 64-character lowercase hexadecimal value;
3. lets you copy the value or generate a different one.

Generation happens only after you select the button. The candidate is not sent
to the Studio API and is not stored by Studio. Copy it before leaving the page,
store it securely, and complete one of the configuration paths below.

The generator only proposes a value. A running Worker cannot add or replace its
own secret binding.

## Configure through the Cloudflare dashboard

1. Open **Workers & Pages** in the Cloudflare dashboard.
2. Select the deployed ZeroPress Studio Worker and open **Settings**.
3. Under **Variables and Secrets**, add a new value with type **Secret**.
4. Enter the exact binding name, such as `STUDIO_AUTH_SECRET`.
5. Paste the generated value and deploy the configuration change.
6. Return to Studio and select **Check again**.

Cloudflare hides a secret value after it is stored, so retain the durable
operator copy before closing the setup flow. See Cloudflare's
[Workers secrets documentation](https://developers.cloudflare.com/workers/configuration/secrets/)
for the current dashboard procedure.

## Configure through Wrangler

Generate a 256-bit value locally:

```sh
openssl rand -hex 32
```

Then start the secret prompt and paste the generated value:

```sh
npx wrangler secret put STUDIO_AUTH_SECRET
```

Repeat with a newly generated value for another secret. Do not paste the same
value into multiple bindings. `wrangler secret put` creates and deploys a new
Worker version, so follow the deployment controls used by your installation.

## Configure local development

For local Worker development, place independently generated values in
`.dev.vars` beside the Wrangler configuration:

```dotenv
STUDIO_AUTH_SECRET="<64-character hexadecimal value>"
STUDIO_INSTALL_TOKEN="<different 64-character hexadecimal value>"
```

Add `STUDIO_OPERATIONS_TOKEN` only when explicitly testing Maintenance &
Recovery. Never commit `.dev.vars`, `.env`, generated values, or copied
Cloudflare configuration to source control.

After installing local D1, remove `STUDIO_INSTALL_TOKEN` from `.dev.vars`, set
`STUDIO_SITE_MODE` to `operational`, and restart the local Worker.

## Rotation and recovery

Do not rotate `STUDIO_AUTH_SECRET` as routine maintenance. Replacing it
invalidates temporary authentication state and can make existing TOTP,
recovery-code, and encrypted provider data unusable. If the value is lost or
suspected to be exposed:

1. keep or return Studio to a non-operational mode;
2. create a reviewed D1 backup;
3. follow the documented [Maintenance & Recovery](../../operations/maintenance-and-recovery/index.md)
   procedure;
4. replace affected MFA or provider credentials after a stable secret is
   restored.

Continue with [Quick Start](../index.md) after all required bindings have been
configured.