Runtime APIs
Secrets Store
Configure and use the Cloudflare Secrets Store binding with OpenOrange.
A Secrets Store binding hands your Worker a secret that is not in your code.
On OpenOrange, the value comes from .dev.vars or the process environment,
and your Worker code and Wrangler configuration stay as they are.
Quickstart
-
Bind the secret
Add the standard Wrangler binding to
wrangler.jsonc. Keep your Cloudflarestore_idandsecret_name: Orange finds the value bybinding.{ "name": "secrets-store", "main": "src/index.ts", "compatibility_date": "2026-09-03", "secrets_store_secrets": [ { "binding": "API_TOKEN", "store_id": "<STORE_ID>", "secret_name": "<SECRET_NAME>" } ] } -
Set a local value
Put the value in
.dev.varsunder the binding name. Keep.dev.varsout of version control.API_TOKEN=local-development-value -
Read it in your Worker
env.API_TOKENis aSecretsStoreSecretobject, not the string. Callget()for the value.interface Env { API_TOKEN: SecretsStoreSecret; } export default { async fetch(request, env): Promise<Response> { const token = await env.API_TOKEN.get(); return fetch("https://api.example.com/", { headers: { Authorization: `Bearer ${token}` }, }); }, } satisfies ExportedHandler<Env>; -
Run it
orange dev Binding Resource Runs on env.API_TOKEN Secrets Store local
How it works
get()looks up the binding name in.dev.vars, then in the process environment.- A missing value makes
get()throw an error that names the binding. - Orange never logs a secret value.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
support.json registers secrets_store_secret as implemented. The feature
matrix lists it as partial, because Orange does not call Cloudflare’s Secrets
Store.
| Feature | Status | Notes |
|---|---|---|
secrets_store_secrets binding | Supported | The same keys as Wrangler. store_id and secret_name must be non-empty strings, and Orange does not use them. |
get() | Supported | Resolves the local value. See Errors for a missing one. |
| Local values | Partial | Orange reads them from .dev.vars or the process environment by binding name. Wrangler manages a separate local Secrets Store state. |
| Remote Cloudflare Secrets Store | Not supported | Orange does not read it. |
wrangler secrets-store commands | Not supported | orange secrets-store prints that the command is not implemented. |
Limits
Orange sets no limit on a secret’s size or on the number of bindings.
Local values
- The local source reads
.dev.varsin the project root on the firstget(), keeps the parsed values for the life of the runtime, and falls back to the process environment for names absent from that file..dev.varstakes precedence when both sources contain the binding. - It does not read
.envfor this binding. - A
.dev.varsentry named after a Secrets Store binding stays that secret’s local value. It does not replace the binding with a plain string. .dev.varssupports plain, single-quoted, and double-quoted assignments, optionalexport,#comments, and the\n,\r, and\tescapes in double quotes. In an unquoted value,#starts a comment only after whitespace, sovalue#keptkeeps the#.- A quoted value can span lines, as in dotenv. Use this for a PEM key.
- A deployed Worker has no
.dev.vars, becauseorange deployleaves it out of the image, soget()reads the runner’s environment.orange deployputs values there with--secretor--secrets-file. No test covers a deployed Secrets Store binding yet.
Errors
| Message | Cause |
|---|---|
Secrets Store binding "API_TOKEN" is not configured locally | Neither .dev.vars nor the environment has API_TOKEN. |
Invalid .dev.vars declaration on line <n> | A line of .dev.vars is not a NAME=value assignment. The message leaves out the line’s text. |
Unclosed quoted .dev.vars value on line <n> | A quoted value never closes. |
Illegal invocation | get() was called on an object that is not the binding. |
Neither successful reads nor failures log a secret value.
Commands
orange devlists the binding asSecrets Storeonlocal.orange doctorchecks each binding, assecret:<BINDING>. With a value in.dev.varsor the environment, the check isok, with the detailenv.API_TOKEN · .dev.vars or environment. Without one, it is an action,env.API_TOKEN has no local value, so get() throws, with the hintSet API_TOKEN in .dev.vars.orange migratedoes not copy secret values. Itspreparestep names each Secrets Store binding in aNot moved:line. See Migrate from Cloudflare.
Internals
The source is replaceable so later providers can resolve the same binding without changing Worker code or Wrangler configuration.
Conformance
- Static conformance checks the binding factory result against Cloudflare’s
exact
SecretsStoreSecretinterface. - The
bindings/secrets-storedifferential fixture runs successful and missingget()calls over workerd service-entrypoint RPC and compares them with Orange. packages/runtime-node/src/bindings/secrets-store.test.tschecks the.dev.varsparser,.dev.varsover the environment, the environment fallback, and that errors name the binding without another value.- The CLI conformance fixture requires
orange typesto produce the same self-contained declaration as pinned Wrangler, and proves every generated secret property onEnvis exactly the runtime factory’s result type. tests/bindings/bindings.test.tsreads a value from.dev.varsthroughget()in a Worker on a realorange dev, and checks that the entry does not replace the binding.tests/cli/doctor.test.tschecks theorange doctoraction without a value, theokcheck with one, and that its output does not contain the value.