Secrets reference

Config options

OptionDefaultMeaning
registry{}Your secrets, keyed by name. Edited by hand — not settable from the command line
rotationIntervalDays30How often the at-rest key rotates. The manager re-encrypts every stored secret on this cadence

An empty registry here does not mean an empty registry in the Worker: every capability contributes its own slice at runtime.

A registry entry

Declaring one is the walkthrough; writing its value is pithy secrets; a dev value lives in the config directory.

FieldValuesDecides
backendd1, cf-secrets-storeWhere the value is stored. A storage decision, not a read-time one
scopeenvironment, globalPer environment, or one value everywhere
valueTypetext, json with a schemaWhat shape it is
devValuerandom, or absentWhether the kit can mint a dev value
rotationlocal, provider, manualWho replaces it
rotateEveryDaysa numberWhat makes overdue a fact the registry states rather than a number a dashboard invented — and the period the secrets manager rotates it on, when it can
overlap{ days, minimumDays, reencrypt? }How long a replaced version keeps verifying. minimumDays is the floor its owner states; reencrypt names what is sealed under the secret at rest, and retirement waits for each
keyeda flagA keyspace rather than a single name

rotateEveryDays is worth setting whether or not anything can rotate the secret. A local secret is rotated on it every night at 03:00 UTC, and a provider one would be with a rotator attached. A manual secret is reported overdue and nothing more — and a third-party key no automation will ever roll is exactly the one whose drift nothing else would surface. Unattended rotation has what the cron does.

A secret the cron rotates must be able to survive it, and defineSecretRegistry refuses one that cannot, where the author is: a period on a rotatable: false entry, a keyspace or the master key; a period with no overlap; an overlap shorter than its minimumDays, or as long as the period; a local secret minted from a structure the cron cannot produce; and a global secret in d1. An overlap on a rotatable: false entry is refused whether it rotates or not.

Bindings

BindingTypeWritten by
SECRETSd1pithy add
SECRETS_ENCRYPTION_KEYSsecretpithy secrets provision

A secret binding has no array in the wrangler config until an account has been reached — the entry needs a store id and an entry name that do not exist yet. So add reports it rather than writing an entry wrangler would refuse.

Its own database, per environment

Separate from the app database, and one per environment. A feature is an environment here: it gets its own SECRETS database, its own master key and its own manager, and pithy feature destroy deletes all three.

A feature’s manager holds no Cloudflare API token. It hosts no rotation Workflow and runs no cron, so branch code never holds write access to the account’s one Secrets Store, where production’s master key lives. A feature lives for days, so its key never needs rotating. Feature environments has the rest.

Storage format

Every stored value is one envelope carrying its current version and every still-valid one, sealed once.

The secret’s name is bound in as authenticated data — not encrypted, bound. A ciphertext moved between rows does not open.

A row in a declared table uses the same envelope in the same database, under the same master key, and binds its table, its owner and its secret name.

The master key

Lives inside that environment’s manager Worker and never leaves it. Nothing reads it back out.

A stored value therefore cannot be copied between environments. A global secret split across environments cannot be completed by reading one of them.

It rotates on its own axis, inside the manager, on its own cron. It is the one secret nothing replaces in place — replacing it would leave everything sealed under a key nobody holds.

Command requirements

CommandNeeds
lsNothing. Offline, no credentials
editNothing beyond a project name
tablesNothing for dev, which reads the local store. Elsewhere Cloudflare credentials, read over the D1 REST API as pithy migrate reads
create, update, rmCloudflare credentials, and a deployed manager
rotateThe same. --dry-run needs the credentials and no deployed manager
provision, deprovisionCredentials and a recorded store id

--env here is the managed set — every environment the project declares — rather than the three --env takes elsewhere. dev is refused, pointing at the dev server.

--env on a global secret is refused, not ignored, and the re-run is the confirmation.

Exit codes

These commands exit by the kit-wide classes: 2 for a call to fix, 3 for something to set up first, 4 to retry, 5 for a person. 5 is the one that matters here: an issuer rolled a credential and the store write failed, which cannot be undone.

Any other failure means the previous credential is still live, and the command can be re-run. 5 means it is not. A script cannot tell those apart from a message, and the two need opposite reactions. Test for non-zero, then for 5.

pithy secrets verify uses the same code: a finding, or a master key that will not resolve, exits 5, because retrying changes nothing. An environment whose manager did not answer exits 4, which is the one a cron may retry.

Peer capabilities

Required: none. It is the bottom of the graph.

Optional: controlplane — exposes reading the registry and triggering a rotation. audit — records every set, rotation and removal, naming the secret and the environments reached, never the value.

What no surface here can carry

A value. Not on stdout, not in a payload, not in an audit event, not in an error. The rotation result has no field that could hold one, so it is structural rather than a habit.

ESC