Config options
| Option | Default | Meaning |
|---|---|---|
registry | {} | Your secrets, keyed by name. Edited by hand — not settable from the command line |
rotationIntervalDays | 30 | How 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.
| Field | Values | Decides |
|---|---|---|
backend | d1, cf-secrets-store | Where the value is stored. A storage decision, not a read-time one |
scope | environment, global | Per environment, or one value everywhere |
valueType | text, json with a schema | What shape it is |
devValue | random, or absent | Whether the kit can mint a dev value |
rotation | local, provider, manual | Who replaces it |
rotateEveryDays | a number | What 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 |
keyed | a flag | A 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
| Binding | Type | Written by |
|---|---|---|
SECRETS | d1 | pithy add |
SECRETS_ENCRYPTION_KEYS | secret | pithy 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
| Command | Needs |
|---|---|
ls | Nothing. Offline, no credentials |
edit | Nothing beyond a project name |
tables | Nothing for dev, which reads the local store. Elsewhere Cloudflare credentials, read over the D1 REST API as pithy migrate reads |
create, update, rm | Cloudflare credentials, and a deployed manager |
rotate | The same. --dry-run needs the credentials and no deployed manager |
provision, deprovision | Credentials 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.