Bindings: Why Your Worker’s Environment Isn’t Full of Strings

If you have written a Cloudflare Worker that uses Workers KV, you may have noticed something surprising the first time you inspected your environment.

// A simple Worker that always returns the value named "content",
// read from Workers KV storage.
export default {
  async fetch(request, env, ctx) {
    return new Response(await env.MY_KV.get("content"));
  }
}

There is no setup code, no authorization keys, and no client library initialization. The env.MY_KV object is already connected, with a working get() method. On a typical platform, you would expect something far more tedious:

// How would a "typical cloud platform" do it?

// Import KV client library?
import { KV } from "cloudflare:kv";

export default {
  async fetch(request, env, ctx) {
    // Connect to the database?? Using my secret auth key???
    // Which comes from an environment variable????
    let myKv = KV.connect("my-kv-namespace", env.MY_KV_AUTHKEY);

    return new Response(await myKv.get("content"));
  }
}

Service bindings work the same way. When you want a Worker to talk to another Worker, you use a binding directly, as shown here:

// A simple Worker that greets an authenticated user, delegating to a
// separate service to perform authentication.
export default {
  async fetch(request, env, ctx) {
    // Forward headers to auth service to get user info.
    let authResponse = await env.AUTH_SERVICE.fetch(
        "https://auth/getUser",
        {headers: request.headers});
    let userInfo = await authResponse.json();
    return new Response("Hello, " + userInfo.name);
  }
}

The env.AUTH_SERVICE.fetch() call routes the request to the bound service, regardless of the URL hostname. On conventional platforms, this would require a real internal hostname and explicit credentials:

// How would a "typical cloud platform" do it?
export default {
  async fetch(request, env, ctx) {
    // Forward headers to auth service, via some internal hostname?
    // Hostname needs to be configurable, so get it from an env var.
    let authRequest = new Request(
        "https://" + env.AUTH_SERVICE_HOST + "/getUser",
        {headers: request.headers});

    // We also need to prove that our service is allowed to talk to
    // the auth service API. Add a header for that, containing a
    // secret token from our environment.
    authRequest.headers.set("X-Auth-Service-Api-Key",
        env.AUTH_SERVICE_API_KEY);

    // Now we can make the request.
    let authResponse = await fetch(authRequest);
    let userInfo = await authResponse.json();
    return new Response("Hello, " + userInfo.name);
  }
}

This pattern is what Cloudflare calls a binding. It is a named environment variable that points to a specific resource, configured at deploy time. Unlike environment variables elsewhere, bindings are not limited to strings.

Bindings remove boilerplate, but that is the least important part. They are a foundational design choice that reconciles two goals that usually conflict: developer convenience and application security.

SSRF Protection by Design

Bindings eliminate an entire class of Server-Side Request Forgery (SSRF) vulnerabilities. SSRF occurs when an attacker tricks a server into making requests to internal services that should be unreachable from the outside.

A common example: a social media application lets users specify a URL for their avatar image. The server fetches that URL. Nothing seems wrong until a user supplies an address like https://auth-service.internal/status. The server now fetches an internal status page and stores it as the avatar, leaking data the user should never see.

let resp = await fetch(userAvatarUrl);
let data = await resp.arrayBuffer();
await setUserAvatar(data);

With bindings, this attack is impossible. There is no URL an attacker can craft to reach the auth service. The only way to contact it is through the env.AUTH_SERVICE binding.

A legacy caveat: This is not true for every Worker. When Workers launched in 2017, the design followed the Service Workers interface, primarily for CDN middleware. In that model, calling the global fetch() with a URL inside your zone sends the request directly to your origin server, bypassing most Cloudflare logic. That behavior can be abused for SSRF.

Cloudflare is working to close this gap with "origin bindings," where the origin server becomes an explicit env.ORIGIN binding. This would allow the global fetch() to be restricted to the public Internet only. The change requires careful backwards-compatibility handling, so expect more details soon. For Workers without an origin server, or with origins that do not rely on Cloudflare for security, the current global fetch() is already SSRF-safe.

Important reminder: Requests from Workers include a CF-Worker header identifying the owning domain. Use it only for abuse mitigation, not for authorization. Building a private API that trusts this header can reintroduce SSRF risks.

No Keys to Leak

Traditional architectures require API keys for services to access protected resources. Anyone with the key has full access, which creates a constant stream of problems: storing the key securely, avoiding accidental commits to GitHub, and logging it. Even with a managed secrets system, a string-based service can leak keys through careless log statements.

Bindings remove the key entirely. A Workers KV binding, for example, never exposes a key to the code. There is nothing to leak accidentally.

No Certificate Bedlam

Securing internal service-to-service traffic typically requires managing certificates, private keys, and CA trust stores. The operational burden is high, so many teams skip it entirely, relying on a VPC for security.

With bindings, the platform handles transport security behind the scenes. The data crosses a secure channel that the developer never has to configure.

Access Control Without the ACL Headaches

You might wonder: if Cloudflare knows which Worker sent a request, could it handle authentication at the network layer? Imagine this alternative design, where namespaces are opened by name:

// Imagine KV namespaces could be open by name?
let myKv = KV.connect("my-kv-namespace", env.MY_KV_AUTHKEY);

Simplified, it could look like this:

// No authkey, because the system knows whether the Worker has
// permission?
let myKv = KV.connect("my-kv-namespace");

Each namespace would then need its own ACL listing approved Workers. On paper that works, but it creates a familiar dilemma:

  • Maintain complex ACLs for every resource, risking misconfigurations and permissions errors in production.
  • Give up and allow all services to talk to each other.

The core problem is that connecting a service to a resource requires two separate steps:

  1. Configuring the service to point at the resource.
  2. Granting the resource permission to accept requests from that service.

Most developers forget step 2 exists until it causes an outage. Then they face a confusing IAM system with hundreds of roles and no clear path forward.

Bindings collapse these two steps into one. When you configure a binding, the platform understands exactly what you are trying to do and grants the necessary permissions implicitly. There is no separate step 2.

By default, a Worker has access to nothing. Access is granted only through configured bindings, exactly matching what the code needs. This is secure by default.

This design also answers the operational question "Who uses this resource?" directly. Because bindings are declarative, the platform can enumerate every Worker connected to a resource without inspecting code.

Bindings as Developer Tooling

Beyond the security advantages, bindings also simplify the developer experience. Instead of receiving an API key in an environment variable and then having to pass it into a library manually, the environment variable is an initialized client. Setup boilerplate is reduced to zero.

Observability for free

The platform also gains visibility into how Workers actually use resources. Because the system understands the types and targets of all bindings, it can answer questions that would otherwise require manual instrumentation:

  • What resources does a given Worker use? Bindings are typed, not opaque strings, so the system can enumerate them.
  • Which Workers use a particular resource? The deployment system can index bindings and run the reverse query.
  • How often is a given binding used? Calls to binding methods can be logged and metered directly.

Testability through dependency injection

When deploying a test version of a service, you typically want it to operate on test resources while running the same code that will go to production. Resource names therefore cannot be hard-coded. On traditional platforms, that means storing resource identifiers in environment variables — which, in the best case, leaves you managing multiple variables that must stay in sync.

Worse, developers may fail to parameterize resources at all. Code written against a test database can accidentally ship to production. Or a developer may prototype against production resources from day one, and later struggle to retrofit test deployments.

With bindings, this class of problem is structurally impossible. A Worker can only reach a KV namespace through its bindings, so creating a separate deployment that points the same code at a test namespace is always straightforward — for example, through Wrangler Environments. This is dependency injection by default, and it is not just useful for testing. Services whose dependencies are swappable are easier to redeploy into any new environment, including new production environments with different user bases or storage backends.

Prior Art and Capability Security

This pattern is not new. It is how programming languages themselves work: in a memory-safe language, you cannot touch an object unless someone passed you a reference to it. Objects do not have URLs. Workers treats the network as a single computer and extends that language-level convention across it.

The paradigm is known as capability-based security, and bindings are directly inspired by it. They are not yet a complete capability system — notably, a Worker has no mechanism to pass a binding to another Worker. That could change. Imagine calling a Worker through a service binding while simultaneously granting it temporary access to a KV namespace for the duration of the request. A future dynamic binding system could bind different resources per request, with automatic revocation when the request ends.

Even today, bindings share the essential properties of capabilities:

  • A binding both names a resource and grants permission to access it — there is no separate ACL lookup.
  • Bindings live in no global namespace; they are scoped to the env object passed to a specific Worker.
  • To use a binding, code must reference it explicitly and only it — never a URL or global ID of the underlying resource.

Why env Is a Parameter

Passing env into the Worker handler rather than exposing it as a global is a deliberate choice that enables composition. Suppose two Workers — one serving an API and one serving static assets — are to be merged into a single Worker. If each originally used a binding named env.KV but pointed at different namespaces, merging would seem to require renaming in one of them.

It does not. Because env is a parameter, the router Worker that delegates to each can remap the environments before the call:

import apiWorker from "api-worker.js";
import assetWorker from "asset-worker.js";

export default {
  async fetch(req, env, ctx) {
    let url = new URL(req.url);
    if (url.hostname == "api.example.com") {
      let subenv = {KV: env.API_KV};
      return apiWorker.fetch(req, subenv, ctx);
    } else if (url.hostname == "assets.example.com") {
      let subenv = {KV: env.ASSETS_KV};
      return assetWorker.fetch(req, subenv, ctx);
    } else {
      return new Response("Not found", {status: 404});
    }
  }
}

This advantage scales beyond the contrived example. Forcing the environment to be an argument means individual modules within a Worker are also designed for dependency injection. For developers who prefer ambient access, node:async_hooks' AsyncLocalStorage can make the env object available anywhere in the code without passing it around explicitly:

import { AsyncLocalStorage } from 'node:async_hooks';

// Allocate a new AsyncLocalStorage to store the value of `env`.
const ambientEnv = new AsyncLocalStorage();

// We can now define a global function that reads a key from env.MY_KV,
// without having to pass `env` down to it.
function getFromKv(key) {
  // Get the env from AsyncLocalStorage.
  return ambientEnv.getStore().MY_KV.get(key);
}

export default {
  async fetch(req, env, ctx) {
    // Put the env into AsyncLocalStorage while we handle the request,
    // so that calls to getFromKv() work.
    return ambientEnv.run(env, async () => {
      // Handle request, including calling functions that may call
      // getFromKv().

      // ... (code) ...
    });
  }
};

KV Bindings Under the Hood

A KV binding encapsulates a secret key — specifically, the encryption key for the corresponding namespace. That key is distributed to the edge with the Worker's code and configuration, stored in encrypted form. The Worker itself, however, has no way to read the key. Neither does the account owner; the key is never revealed outside Cloudflare's systems, and Cloudflare employees are also prevented from viewing it.

Were the key to leak, it would still be of little use. There is no API to upload a raw key for a KV binding. Instead, the client supplies the public ID of the namespace, and the deployment system verifies that the namespace belongs to the same account as the Worker being uploaded, and that the client is authorized to deploy Workers on that account.

For a full list of binding types and configuration options, see the Cloudflare Workers documentation.