From 797fc20864f8f82e93587bf0b65a4cd293479c61 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Sat, 15 Aug 2026 00:49:57 +0100 Subject: [PATCH 1/3] [Workers] Document ctx.access limitations --- .../docs/workers/configuration/cloudflare-access.mdx | 12 +++++++++++- .../runtime-apis/bindings/service-bindings/index.mdx | 4 ++++ .../workers/static-assets/routing/worker-script.mdx | 6 ++++++ .../workers/vite-plugin/reference/static-assets.mdx | 6 ++++++ 4 files changed, 27 insertions(+), 1 deletion(-) diff --git a/src/content/docs/workers/configuration/cloudflare-access.mdx b/src/content/docs/workers/configuration/cloudflare-access.mdx index a7e167fd07a..97d9467209c 100644 --- a/src/content/docs/workers/configuration/cloudflare-access.mdx +++ b/src/content/docs/workers/configuration/cloudflare-access.mdx @@ -253,7 +253,7 @@ For advanced policy configuration, such as multiple identity providers, device p ## Read authenticated user identity with ctx.access -Every time Cloudflare Access authenticates a request, your Worker can read the signed-in user's identity — including email, groups, device posture, and [more identity fields](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/#user-identity) — directly through `ctx.access`. No extra configuration or JWT parsing required. +When Cloudflare Access authenticates a request that directly invokes your Worker, the Worker can read the signed-in user's identity — including email, groups, device posture, and [more identity fields](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/#user-identity) — through `ctx.access`. No extra configuration or JWT parsing is required. Use this to personalize responses, enforce fine-grained permissions, or log activity per user. @@ -278,6 +278,16 @@ export default { +### `ctx.access` limitations + +:::note +`ctx.access` applies only to the Worker invocation authenticated by Access. It does not currently propagate through Worker-to-Worker calls. This includes [Service Binding](/workers/runtime-apis/bindings/service-bindings/) HTTP requests and remote procedure call (RPC) invocations. The downstream Worker does not receive the caller's Access context. + +Workers with [Static Assets](/workers/static-assets/) execute behind an internal router Worker. Access still protects the application and its assets. However, the router does not currently pass `ctx.access` to the user Worker. + +Local and deployed behavior can currently differ. The Cloudflare Vite plugin can add `assets` to the generated deployment configuration when the input Wrangler configuration omits it. Frameworks that use the plugin, including TanStack Start, can expose `ctx.access` locally while it is `undefined` after deployment. +::: + ## Test ctx.access locally When developing locally with `wrangler dev` or the Cloudflare Vite Plugin, you can simulate authenticated Cloudflare Access identities without deploying or going through an Access login flow. diff --git a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx index 8d4dc9e714b..3b0a690f206 100644 --- a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx +++ b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx @@ -62,6 +62,10 @@ Worker A that declares a Service binding to Worker B can call Worker B in two di 1. [RPC](/workers/runtime-apis/bindings/service-bindings/rpc) lets you communicate between Workers using function calls that you define. For example, `await env.BINDING_NAME.myMethod(arg1)`. This is recommended for most use cases, and allows you to create your own internal APIs that your Worker makes available to other Workers. 2. [HTTP](/workers/runtime-apis/bindings/service-bindings/http) lets you communicate between Workers by calling the [`fetch()` handler](/workers/runtime-apis/handlers/fetch) from other Workers, sending `Request` objects and receiving `Response` objects back. For example, `env.BINDING_NAME.fetch(request)`. +:::note[Cloudflare Access context] +Cloudflare Access does not currently propagate `ctx.access` from Worker A to Worker B. This applies to HTTP requests and RPC invocations. Do not treat the downstream invocation as authenticated by the caller's Access context. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). +::: + ## Example — build your first Service binding using RPC This example [extends the `WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc/#the-workerentrypoint-class) to support RPC-based Service bindings. diff --git a/src/content/docs/workers/static-assets/routing/worker-script.mdx b/src/content/docs/workers/static-assets/routing/worker-script.mdx index e2a74a4dad1..cd2f0a3068b 100644 --- a/src/content/docs/workers/static-assets/routing/worker-script.mdx +++ b/src/content/docs/workers/static-assets/routing/worker-script.mdx @@ -16,6 +16,12 @@ If an appropriate static asset if not found, Cloudflare will invoke your Worker This allows you to easily combine together these two features to create powerful applications (e.g. a [full-stack application](/workers/static-assets/routing/full-stack-application/), or a [Single Page Application (SPA)](/workers/static-assets/routing/single-page-application/) or [Static Site Generation (SSG) application](/workers/static-assets/routing/static-site-generation/) with an API). +## Cloudflare Access context + +:::note +When a Worker has Static Assets, the internal assets router does not currently pass `ctx.access` to the user Worker. Access still protects the Worker and its assets, but `ctx.access` is unavailable to the user Worker. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). +::: + ## Run your Worker script first You can configure the [`assets.run_worker_first` setting](/workers/static-assets/binding/#run_worker_first) to control when your Worker script runs relative to static asset serving. This gives you more control over exactly how and when those assets are served and can be used to implement "middleware" for requests. diff --git a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx index bee7c641303..81b24f8355a 100644 --- a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx +++ b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx @@ -26,6 +26,12 @@ On running `vite build`, an output `wrangler.json` configuration file is generat The `assets.directory` field in this file is automatically populated with the path to your `client` build output. It is therefore not necessary to provide the `assets.directory` field in your input Worker configuration. +:::note[Cloudflare Access context] +The Vite plugin can add Static Assets to the generated deployment configuration even when the input Wrangler configuration does not include `assets`. Workers with Static Assets cannot currently access `ctx.access` in the user Worker. Local development can currently expose `ctx.access` even though it is `undefined` after deployment. + +This behavior affects frameworks that use the Cloudflare Vite plugin, including TanStack Start. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). +::: + The `assets` configuration should be used, however, if you wish to set [routing configuration](/workers/static-assets/routing/) or enable the [assets binding](/workers/static-assets/binding/#binding). The following example configures the `not_found_handling` for a single-page application so that the fallback will always be the root `index.html` file. From c9c378478d1ba03cd1190caa36634d6e5a1533da Mon Sep 17 00:00:00 2001 From: MattieTK Date: Sat, 15 Aug 2026 01:03:43 +0100 Subject: [PATCH 2/3] [Workers] Correct Vite ctx.access guidance --- src/content/docs/workers/configuration/cloudflare-access.mdx | 2 +- .../docs/workers/vite-plugin/reference/static-assets.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/configuration/cloudflare-access.mdx b/src/content/docs/workers/configuration/cloudflare-access.mdx index 97d9467209c..c874371182c 100644 --- a/src/content/docs/workers/configuration/cloudflare-access.mdx +++ b/src/content/docs/workers/configuration/cloudflare-access.mdx @@ -285,7 +285,7 @@ export default { Workers with [Static Assets](/workers/static-assets/) execute behind an internal router Worker. Access still protects the application and its assets. However, the router does not currently pass `ctx.access` to the user Worker. -Local and deployed behavior can currently differ. The Cloudflare Vite plugin can add `assets` to the generated deployment configuration when the input Wrangler configuration omits it. Frameworks that use the plugin, including TanStack Start, can expose `ctx.access` locally while it is `undefined` after deployment. +The Cloudflare Vite plugin can add `assets` to the generated deployment configuration when the input Wrangler configuration omits it. Frameworks that use the plugin, including TanStack Start, can therefore be affected even when their source configuration does not declare Static Assets. ::: ## Test ctx.access locally diff --git a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx index 81b24f8355a..ecb50a62042 100644 --- a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx +++ b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx @@ -27,7 +27,7 @@ The `assets.directory` field in this file is automatically populated with the pa It is therefore not necessary to provide the `assets.directory` field in your input Worker configuration. :::note[Cloudflare Access context] -The Vite plugin can add Static Assets to the generated deployment configuration even when the input Wrangler configuration does not include `assets`. Workers with Static Assets cannot currently access `ctx.access` in the user Worker. Local development can currently expose `ctx.access` even though it is `undefined` after deployment. +The Vite plugin can add Static Assets to the generated deployment configuration even when the input Wrangler configuration does not include `assets`. Workers with Static Assets cannot currently access `ctx.access` in the user Worker. This behavior affects frameworks that use the Cloudflare Vite plugin, including TanStack Start. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). ::: From 6ee502423650a43ebad5a8e6ca3576196595c068 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Mon, 17 Aug 2026 11:08:08 +0100 Subject: [PATCH 3/3] [Workers] Clarify ctx.access propagation --- .../docs/workers/configuration/cloudflare-access.mdx | 6 ++++-- .../runtime-apis/bindings/service-bindings/index.mdx | 2 +- .../docs/workers/static-assets/routing/worker-script.mdx | 2 +- .../docs/workers/vite-plugin/reference/static-assets.mdx | 2 +- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/workers/configuration/cloudflare-access.mdx b/src/content/docs/workers/configuration/cloudflare-access.mdx index c874371182c..9ef64930498 100644 --- a/src/content/docs/workers/configuration/cloudflare-access.mdx +++ b/src/content/docs/workers/configuration/cloudflare-access.mdx @@ -281,9 +281,11 @@ export default { ### `ctx.access` limitations :::note -`ctx.access` applies only to the Worker invocation authenticated by Access. It does not currently propagate through Worker-to-Worker calls. This includes [Service Binding](/workers/runtime-apis/bindings/service-bindings/) HTTP requests and remote procedure call (RPC) invocations. The downstream Worker does not receive the caller's Access context. +`ctx.access` applies only to the Worker invocation authenticated by Access. Cloudflare Access does not propagate `ctx.access` through [Service Binding](/workers/runtime-apis/bindings/service-bindings/) HTTP requests or remote procedure call (RPC) invocations. The downstream Worker does not receive the caller's Access context. -Workers with [Static Assets](/workers/static-assets/) execute behind an internal router Worker. Access still protects the application and its assets. However, the router does not currently pass `ctx.access` to the user Worker. +If the caller instead sends a `fetch()` subrequest to an Access-protected hostname with valid [service token headers](/cloudflare-one/access-controls/service-credentials/service-tokens/) or a valid [`CF_Authorization` cookie](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/), Access evaluates the new request and creates a `ctx.access` object for the downstream Worker. This is a newly authenticated context, not context propagated from the caller. + +Workers with [Static Assets](/workers/static-assets/) execute behind an internal router Worker. Access still protects the application and its assets. However, the router does not pass `ctx.access` to the user Worker. The Cloudflare Vite plugin can add `assets` to the generated deployment configuration when the input Wrangler configuration omits it. Frameworks that use the plugin, including TanStack Start, can therefore be affected even when their source configuration does not declare Static Assets. ::: diff --git a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx index 3b0a690f206..fb3de364f09 100644 --- a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx +++ b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx @@ -63,7 +63,7 @@ Worker A that declares a Service binding to Worker B can call Worker B in two di 2. [HTTP](/workers/runtime-apis/bindings/service-bindings/http) lets you communicate between Workers by calling the [`fetch()` handler](/workers/runtime-apis/handlers/fetch) from other Workers, sending `Request` objects and receiving `Response` objects back. For example, `env.BINDING_NAME.fetch(request)`. :::note[Cloudflare Access context] -Cloudflare Access does not currently propagate `ctx.access` from Worker A to Worker B. This applies to HTTP requests and RPC invocations. Do not treat the downstream invocation as authenticated by the caller's Access context. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). +Cloudflare Access does not propagate `ctx.access` from Worker A to Worker B. This applies to HTTP requests and RPC invocations. Do not treat the downstream invocation as authenticated by the caller's Access context. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). ::: ## Example — build your first Service binding using RPC diff --git a/src/content/docs/workers/static-assets/routing/worker-script.mdx b/src/content/docs/workers/static-assets/routing/worker-script.mdx index cd2f0a3068b..b847dcdb71c 100644 --- a/src/content/docs/workers/static-assets/routing/worker-script.mdx +++ b/src/content/docs/workers/static-assets/routing/worker-script.mdx @@ -19,7 +19,7 @@ This allows you to easily combine together these two features to create powerful ## Cloudflare Access context :::note -When a Worker has Static Assets, the internal assets router does not currently pass `ctx.access` to the user Worker. Access still protects the Worker and its assets, but `ctx.access` is unavailable to the user Worker. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). +When a Worker has Static Assets, the internal assets router does not pass `ctx.access` to the user Worker. Access still protects the Worker and its assets, but `ctx.access` is unavailable to the user Worker. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). ::: ## Run your Worker script first diff --git a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx index ecb50a62042..cfb3dffb358 100644 --- a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx +++ b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx @@ -27,7 +27,7 @@ The `assets.directory` field in this file is automatically populated with the pa It is therefore not necessary to provide the `assets.directory` field in your input Worker configuration. :::note[Cloudflare Access context] -The Vite plugin can add Static Assets to the generated deployment configuration even when the input Wrangler configuration does not include `assets`. Workers with Static Assets cannot currently access `ctx.access` in the user Worker. +The Vite plugin can add Static Assets to the generated deployment configuration even when the input Wrangler configuration does not include `assets`. Workers with Static Assets do not receive `ctx.access` in the user Worker. This behavior affects frameworks that use the Cloudflare Vite plugin, including TanStack Start. For more information, refer to [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations). :::