Feature request: supply secret values programmatically in the new config (cloudflare.config.ts)

[theoephraim]

Please excuse the AI authored text below. I reviewed it and it is all accurate and clear. I'm working through integrating varlock with the new cf stuff to discover what bumps I find along the way. My hope is that we can remove the need for a cli wrapper like we currently do with our wrangler integration. We need that in order to inject secrets using the --secret-file option and a FIFO. With the new setup, we should be able to resolve the secrets and inject them directly - with the important restriction of not writing any plaintext secrets to disk. This should work for local dev and deployment, and for both vite and non-vite apps.

---

Problem

In the new experimental config (cloudflare.config.ts / @cloudflare/config), bindings.secret() declares that a secret must exist, but provides no way to supply its value. Values must arrive out-of-band (wrangler secret put, --secrets-file, dashboard).

This undercuts the main benefit of config-as-code: since the config is executable TypeScript evaluated at deploy time, it can already resolve values from a secure source (a secrets manager, an env tool) — but has nowhere to put them.

Consequences:

• Deploys aren't self-contained: a declared secret with no pre-set value fails the first deploy, and inherited secrets go stale unless a separate sync step runs.
• cf deploy has no --secrets-file / --var equivalent, so there is currently no value channel for it at all.
• The upload API already supports this — --secrets-file just becomes {"type": "secret_text", "text": ...} metadata bindings.

Workaround today

The unsafe escape hatch forwards verbatim to upload metadata, so this works:

env: {
  API_KEY: { type: "unsafe:secret_text", text: resolveFromVault("API_KEY") },
}

…but it's explicitly unsupported, warns on every deploy, and the warning suggests migrating to exactly the out-of-band flows this avoids.

Request

First-class support for programmatic secret values, e.g.:

env: {
  API_KEY: bindings.secret({ value: resolveFromVault("API_KEY") }),
}

• Value never serialized into generated types, dry-run output, or logs.
• No-value form keeps current declare/enforce semantics.
• Works in both wrangler deploy --experimental-new-config and cf deploy (same conversion path).
• Ideally also honored by local dev as the binding's value.

Context

Building an integration for varlock (env/secrets management). With the classic config we wrap wrangler to inject --var flags and a --secrets-file; the new config format lets us move all of that into cloudflare.config.ts directly — secret values are the one missing piece. Tested with wrangler@4.120.1, @cloudflare/config@0.5.0, cf@0.6.0.

[theoephraim]

An important wrinkle for the Vite flow (@cloudflare/vite-plugin with experimental.newConfig): a programmatic value API alone wouldn't be enough there.

With wrangler, cloudflare.config.ts is evaluated in-process at deploy time, so resolved secret values can go straight from memory into the upload — nothing touches disk.

With Vite, the config is evaluated at build time and serialized to disk: vite build writes a fully resolved dist/<worker>/wrangler.json snapshot (plus a .wrangler/deploy/config.json redirect), and deploy reads that snapshot. Verified with @cloudflare/vite-plugin@1.51.2: an inlined secret value (via the unsafe:secret_text workaround) ends up in plaintext inside the dist artifact. bindings.secret() declarations serialize safely ("secrets": {"required": [...]}, names only) — but then values must still arrive out-of-band at deploy.

So bindings.secret({ value }) would serialize into the snapshot just the same. For the Vite / Build Output flow to support deploy-time value injection, one of these seems needed:

• deploy re-evaluates the TS config (or a designated resolver hook) for secret values, instead of reading them from the snapshot; or
• the snapshot/build output carries a reference ("resolve API_KEY from cloudflare.config.ts at deploy") rather than a literal value.

Either way, the invariant worth preserving: secret values should exist only in memory during the deploy process, never in build artifacts.

[jamesopstad]

With wrangler, cloudflare.config.ts is evaluated in-process at deploy time, so resolved secret values can go straight from memory into the upload — nothing touches disk.

If you enable the --x-cf-build-output flag alongside --x-new-config then this is not the case. The config is evaluated at build time and serialised to disk. This will be the standard behaviour in the cf CLI. The build output is a specification for everything that is needed to deploy so we should avoid deploy reading cloudflare.config.ts directly. Do you have any other ideas for how we could support your use case with this constraint?

[theoephraim]

Yes I think I figured out something workable.

The main case where you don’t want to have to resolve and pass in secrets again is when the build and deploy is happening in a single step. In this case we can generate an encryption key in memory only and use it to encrypt a blob full of secrets within the build output. In the split build/deploy case, it’s reasonable to expect the secrets passed in again, since build and deploy could be happening in different places with different access.

I think I have a prototype already. Happy to show you. A few other minor changes as well - like ability to set the value as mentioned above, and ability to set required explicitly.

[theoephraim]

We could of course also handle the split scenario with an encryption key too and just expect that key to be passed in as an env var when running the deploy.

[theoephraim]

@jamesopstad - full proposal outlining how this could work in various scenarios

---

Goal: the config (optionally backed by a tool like varlock) supplies the Worker's complete runtime env - vars and secrets - with secret values existing only in memory during build/deploy. Never in the build output, never in logs. Works with the Build Output Spec constraint: the output is complete, and deploy never reads cloudflare.config.ts.

API

bindings.secret()                       // declared; value arrives out-of-band; required by default
bindings.secret({ value })              // value supplied by the config (string or thunk)
bindings.secret({ fromEnv: true })      // deployer reads it from its own env, same name
bindings.secret({ fromEnv: "OTHER" })   // ...or from a different env var name
bindings.secret({ required: false })    // declared for types/dev, not enforced
bindings.text({ value?, fromEnv?, required? })  // same options for vars; text(value) unchanged

value and fromEnv are mutually exclusive; required composes with either. In the build output, fromEnv serializes as a declarative reference the deployer dereferences natively (the entry key is the name, so the boolean is unambiguous): "API_KEY": { "type": "secret", "fromEnv": true }.

Declarations (names only) always serialize into the build output - they drive type generation, dev var scoping, and a fail-loudly backstop if values never arrive at deploy. Vars need a declarations field in the output to match secrets.required.

Core invariant: resolved values are never placed on the config object. They travel a separate in-memory channel from config evaluation to the uploader, so they structurally cannot reach the serialized output, type-gen, or config dumps.

Getting values to deploy (three tiers, no config evaluation at deploy)

The config is evaluated once, at build. Values cross the build/deploy boundary one of three ways:

1. Single-step build+deploy (cf CLI, or wrangler running the build): the orchestrator generates an ephemeral key held only in its memory and passes it to the build via env. The build step encrypts the resolved {name: value} map (AES-256-GCM) and writes the ciphertext alongside the output; the deploy half decrypts in memory, merges into the upload, deletes the file. Only written when the key is present - a bare build stays names-only. Crash-safe: without the key, a leftover payload is garbage.
2. Split build/deploy, secrets available at build: the same encrypted payload is kept with the artifact, and the per-build key is passed to the deploy step through the CI provider's secret channel. Deploy decrypts and merges - no user code runs.
3. Split build/deploy, secrets only in the deploy environment: the output carries a declarative reference instead of a value - fromEnv above, e.g. "API_KEY": { "type": "secret", "fromEnv": true } - and the deployer dereferences it natively from its own process environment. A small closed vocabulary, no user code execution, so the output remains a complete specification: output + deploy environment = everything needed.

Fallback when none apply (deployer has no key, no matching env): today's behavior - inherit for required names, deploy fails loudly if a required secret was never set.

Open question: should the encrypted payload live inside the Build Output Spec (self-contained artifact, key out-of-band) or adjacent to it (no secret material in the artifact, even encrypted)?

Needs-values signal

The evaluation context tells resolvers whether values will be consumed (e.g. key present at build). A build that only produces the output resolves nothing sensitive: declaration-only bindings come from names, and a missing deploy-time secret cannot fail the build. required is enforced where values are resolved.

Replace semantics

Per #15343, merge-vs-replace is a property of the declared state, not a CLI flag: a settings-level env: { mode: "replace" } meaning the configured env is the complete set. Compiles to total-replacement uploads (and the proposed Preview env_mode once it exists).

Non-goals

Pipeline credentials ("secret zero", vault tokens) are not runtime bindings - they live in build/CI secret stores and are read from the pipeline environment during resolution. Internal/build-only items emit no binding.