Skip to content
Runtime APIs / Secrets Store

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

  1. Bind the secret

    Add the standard Wrangler binding to wrangler.jsonc. Keep your Cloudflare store_id and secret_name: Orange finds the value by binding.

    {
      "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>"
        }
      ]
    }
  2. Set a local value

    Put the value in .dev.vars under the binding name. Keep .dev.vars out of version control.

    API_TOKEN=local-development-value
  3. Read it in your Worker

    env.API_TOKEN is a SecretsStoreSecret object, not the string. Call get() 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>;
  4. 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.

FeatureStatusNotes
secrets_store_secrets bindingSupportedThe same keys as Wrangler. store_id and secret_name must be non-empty strings, and Orange does not use them.
get()SupportedResolves the local value. See Errors for a missing one.
Local valuesPartialOrange reads them from .dev.vars or the process environment by binding name. Wrangler manages a separate local Secrets Store state.
Remote Cloudflare Secrets StoreNot supportedOrange does not read it.
wrangler secrets-store commandsNot supportedorange 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.vars in the project root on the first get(), keeps the parsed values for the life of the runtime, and falls back to the process environment for names absent from that file. .dev.vars takes precedence when both sources contain the binding.
  • It does not read .env for this binding.
  • A .dev.vars entry named after a Secrets Store binding stays that secret’s local value. It does not replace the binding with a plain string.
  • .dev.vars supports plain, single-quoted, and double-quoted assignments, optional export, # comments, and the \n, \r, and \t escapes in double quotes. In an unquoted value, # starts a comment only after whitespace, so value#kept keeps the #.
  • A quoted value can span lines, as in dotenv. Use this for a PEM key.
  • A deployed Worker has no .dev.vars, because orange deploy leaves it out of the image, so get() reads the runner’s environment. orange deploy puts values there with --secret or --secrets-file. No test covers a deployed Secrets Store binding yet.

Errors

MessageCause
Secrets Store binding "API_TOKEN" is not configured locallyNeither .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 invocationget() was called on an object that is not the binding.

Neither successful reads nor failures log a secret value.

Commands

  • orange dev lists the binding as Secrets Store on local.
  • orange doctor checks each binding, as secret:<BINDING>. With a value in .dev.vars or the environment, the check is ok, with the detail env.API_TOKEN · .dev.vars or environment. Without one, it is an action, env.API_TOKEN has no local value, so get() throws, with the hint Set API_TOKEN in .dev.vars.
  • orange migrate does not copy secret values. Its prepare step names each Secrets Store binding in a Not 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 SecretsStoreSecret interface.
  • The bindings/secrets-store differential fixture runs successful and missing get() calls over workerd service-entrypoint RPC and compares them with Orange.
  • packages/runtime-node/src/bindings/secrets-store.test.ts checks the .dev.vars parser, .dev.vars over the environment, the environment fallback, and that errors name the binding without another value.
  • The CLI conformance fixture requires orange types to produce the same self-contained declaration as pinned Wrangler, and proves every generated secret property on Env is exactly the runtime factory’s result type.
  • tests/bindings/bindings.test.ts reads a value from .dev.vars through get() in a Worker on a real orange dev, and checks that the entry does not replace the binding.
  • tests/cli/doctor.test.ts checks the orange doctor action without a value, the ok check with one, and that its output does not contain the value.