The proxy

One core is assembled from per-concern modules and imported from one place by all three hosts, so the route table is the same in dev, on a Node server and on Vercel. This page holds the values — paths, ceilings, defaults, codes. Why each fence exists is on ceilings and fences; the variables that feed the options are on environment variables; every code with its cause is on errors.

Before any route runs

Two checks stand in front of every route the proxy claims, and the WebSocket upgrade asks the same two, because it hangs off the bare server where no middleware runs.

• Host. The Host header must name this deployment: a loopback name always does; otherwise an entry in allowedHosts, or the host of an entry in allowedOrigins or of publicUrl. An entry without a port matches any port. A deployment that named none of them and is not bound to loopback is not checked at all. A request that fails is 403 ProxyHostForbidden, and it is asked first, so a request to the wrong name collects no CORS header on its way out.
• Origin. sec-fetch-site: same-origin or none passes on the browser's own word. Otherwise the Origin must be this deployment's own host — host and port, never the scheme, because behind an edge that terminates TLS the socket is plain http — or an entry in allowedOrigins. A request with no Origin and nothing from Fetch Metadata is not a browser request and passes. A request that fails is 403 ProxyOriginForbidden.

A listed cross-origin caller gets access-control-allow-origin: <origin>, access-control-allow-credentials: true and vary: origin. An OPTIONS preflight on a claimed path is answered 204 with GET, POST, PATCH, DELETE, OPTIONS, the request headers authorization, content-type, x-cf-admin, and access-control-max-age: 600. A refused upgrade is answered as plain HTTP 403 Forbidden before any socket exists.

Everything under /chatfuel/admin is served same-origin only, whatever allowedOrigins says. The host check is not narrowed with it: it is a statement about this server, and the server is the same one whichever route was asked for.

The routes

Paths are the defaults; every one of them is an option.

POST /chatfuel/auth/provision and the three bots routes are mounted on the gate and the service-role key; CHATFUEL_WORKSPACE_ID is checked inside the handler, so a deployment missing it gets an answer that names the variable rather than a 404.

The order a GraphQL body is checked in

Every step answers before the next one runs, and the first refusal is the one you get. A subscribe frame on the socket runs the same chain, with the registry first and the rest in this order; there a refusal is an in-band error frame on that subscription's id, not a close.

What comes back is the upstream status and body, with two exceptions: an error entry naming an internal upstream service has that sentence replaced and, when it carried no code of its own, is tagged UpstreamServiceError; and a request that named exactly one bot teaches the resource fence which bot every id in the answer belongs to.

What decides whether a route exists at all

A route that is not mounted is not claimed: the dispatcher returns false, the host answers its own 404, and that 404 is the signal. The app reads a 404 on the publishing routes as "this deployment keeps its queue in the browser" and offers no schedule control. A deployment that never asked for a panel answers 404 on /chatfuel/admin and the app reads that as "no panel".

The one exception is a password that is set but shorter than 16 characters: adminMode becomes misconfigured, ProxyAdminPasswordWeak joins the configuration problems, the routes stay claimed, and they answer 500 — a panel that quietly is not there teaches the operator nothing.

Under /chatfuel/admin

Every path except POST /session requires a signed cf_admin cookie and an x-cf-admin request header — a form posted from another origin can send a cookie but cannot set a header. The cookie is minted from ADMIN_PASSWORD under a per-deployment salt, lasts two hours, is sent with Path=/; HttpOnly; SameSite=Strict and Secure everywhere but plain-http loopback, and is the whole authorization: this module never calls admitRequest, never consults the auth gate and never applies the workspace fence, because the panel's purpose is the account-wide view those exist to withhold. A body over 64 KiB is 413 AdminBodyTooLarge; on /session, which answers before any credential is checked, the ceiling is 4 KiB.

Anything else under the prefix is 404 AdminRouteNotFound.

Under /chatfuel/publishing

The options

createChatfuelProxy(options, env) takes these; each falls back to the env bag, then to a default. A ceiling given as something that is not a positive number is not a ceiling: the default stands.

auth resolved from env has three outcomes: both VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY set is on, neither is off, and exactly one is misconfigured — which fails closed, so every proxied request answers 500. See the auth gate for what the gate then does.

The ceilings

A body past its ceiling is refused at the byte that crosses it: the bytes past it are dropped rather than kept, the stream is paused, the 413 goes out with connection: close, the socket is ended, and 250 ms later it is destroyed if the caller is still sending.

The document registry

The narrowest document check and the first one asked. Pass the app's generated namespaces as operations — src/operationDocs.ts, the barrel the wizard writes with one import * as per module and never export * — and the proxy forwards those documents and no others. All three hosts pass the same object.

The operation allowlist

A name check on an operation's root fields, following a spread into its fragment and ignoring aliases. The list is ALLOWED_ROOT_FIELDS in allowedOperations.ts — 353 fields, generated by scripts/allowed-operations.ts from every module's skill/examples/operations.graphql, and re-derived by the repository's validator, which fails when the two disagree.

The resource fence

Which bot a flow, block, contact, conversation or task id belongs to, learned from the proxy's own answers and checked on the next request that names it.

The startup line

Every host prints the resolved configuration once, from describeAuthMode, and prints each configuration problem before it by variable name — never by value.

The tail is the same for on and off, in this order: the resource fence, operation allowlist: <n> fields or OFF, operations: <n> documents or NO REGISTRY, admin panel mounted or admin panel MISCONFIGURED (ADMIN_PASSWORD too short), and ORIGINS: * (ANY origin may call this proxy) when '*' is in the origin list. A machine that reaches the internet through a proxy appends — outbound via HTTPS_PROXY=… with the credentials masked.

Two shapes are refused before anything binds, with a line starting REFUSING TO SERVE: — open mode on a host that is not loopback without CHATFUEL_OPEN_PROXY=1, and ALLOWED_ORIGINS='*' without a gate. The Node server prints them and never binds; the Vite plugin throws before the middleware mounts; the Vercel function logs them, answers the health route, and answers 503 ProxyRefusedToServe to everything else. An acknowledged open mode on a reachable host prints a WARNING: line beside the listening line instead.

The three hosts

A rewrite straight to panel.chatfuel.com would be cheaper and cannot work: a rewrite forwards the browser's headers and has no way to add one, so the token would have to be sent by the client — the one thing the proxy exists to prevent. The headers block in vercel.json sets response headers, not request ones.

Every response the proxy writes carries the same seven security headers on all three hosts — every proxied answer, the health answer, every static file and 404 on the Node server, and every path on Vercel through vercel.json:

Nothing the client sent is forwarded

Outgoing headers are built from scratch rather than merged, so the browser's Authorization and its cookies are stripped by construction:

• The GraphQL forward sends exactly content-type: application/json and authorization: Bearer <token>, and a body the proxy serialised from what it read — query, operationName, variables — rather than the bytes that arrived, so the request that was fenced and the request that runs are one object. Of the caller's query string only ?op=<name> travels.
• The REST passthrough sends authorization plus the request's content-type when there is one, because a multipart upload needs its boundary. Nothing else, cookies included, travels.
• The WebSocket relay waits for the browser's connection_init, gates it, and then sends its own connection_init {authToken: "Bearer …"} upstream. The browser's payload — the user's session JWT — is consumed by the gate and never leaves the server. Every later frame goes upstream re-serialised from what the relay read, never as it arrived.

Coming back the other way, the upstream status passes through untouched, because a GraphQL refusal arrives as an envelope under HTTP 200 and rewriting it would lose the answer. The body is piped rather than collected, except on the GraphQL route, where an error entry naming an internal upstream service has that sentence replaced before it reaches the browser. The proxy's own refusals are no-store: a cached 403 would keep saying "not your bot" about a bot that has since become the caller's. Which codes those are is on the errors page.