Edge routing on AWS CloudFront

No page is cached at the edge, so every page request reaches the origin-request Lambda. It reads its configuration out of the origin custom headers (non-secret settings the distribution attaches to every request it sends toward the origin) and deletes them in the same pass. Then it looks at the user agent. An ordinary browser on an ordinary path is returned at once, and so is a traditional search crawler: no lookup, no call to NORG, no call to AWS, just the request handed back for CloudFront to fetch your origin as if we were not installed.

Only a bot-shaped request goes further. On a cold container it makes two lookups before it can decide: the site key from Secrets Manager, read from the replica in the region that ran the function, and then the policy feed, the per-site list of crawler patterns, operator settings and verified address ranges it fetches from NORG. Both are cached afterwards. It classifies, checks the operator is enabled, verifies the source address, and then either returns the request for CloudFront to send to your origin, returns a generated response it built from the mirror, or rewrites the request to point at the NORG content service (the receptionist) when the mirror is too large to inline. The mirror fetch carries one extra header describing the visit, and the content service records it; the router itself sends no telemetry and waits on none.

A request is treated as an ordinary browser only when its user agent is confidently one: a Mozilla/5.0 prefix, a real engine token, none of the words a crawler or scripted client carries, and no Signature-Agent header. Everything else, an absent user agent included, takes the full sequence. The two directions of error are not symmetric: a human wrongly treated as bot-shaped costs one policy lookup on a cold container and is then passed through anyway, while an agent wrongly treated as a browser would be handed your origin with the router never having looked. So the test is deliberately lopsided toward the second case never happening, and the set of requests that go further is a superset of anything the router might divert.

The site id, the NORG API and receptionist URLs, the environment name and the feature flags arrive as origin custom headers on the distribution. readConfig lifts them into a plain object and deletes each one from request.origin.custom.customHeaders in the same pass, whether or not it held a value, so a half-configured install cannot leak through a header nobody recognised as populated.

That deletion is what keeps them off your own web server. The same scrub is applied again to whatever object is about to be returned, including on the error and oversized-response paths, so there is no exit from the function that carries a config header onward.

A health probe arrives as the request header x-norg-edge-check. Its value is compared against the probe token the distribution supplies in the x-norg-probe-token custom header, which authorises reading install status and nothing else. That token is derived from your site key rather than stored, so rotating the key rotates it too. The inbound header is captured and stripped in the same pass as the config headers, so a mistyped probe cannot reach your origin either. Ask us for your site's value; a self-service surface for it is not built yet.

A Cloudflare worker that decides to pass through has to fetch your origin itself, so a bug in that fetch is a bug in your site. The origin-request contract here is different: the function returns either a response or a request, and returning the request means "carry on as you would have without me". CloudFront then applies its own retries, its own origin timeouts and its own shield. The top-level catch returns exactly that.

NORG unreachable or the feed refused: the container keeps its last known-good policy, and an install that has never authenticated does nothing at all. Secrets Manager unreachable: the key resolves to null and the request passes through. Mirror missing, too large, or too thin after stripping: your origin. Watchdog expiry: your origin. Anything thrown anywhere: your origin. There is no path that returns an error page of ours, and the router sends no telemetry of its own, so nothing about analytics can hold or fail a response.

The one failure the code cannot degrade past sits above it: if a region's Lambda@Edge concurrency quota is exhausted, CloudFront answers 503 for every page request in that region until load falls. The cost panel under Distribution shape says how the install surfaces that quota and what bounds it.

MCP paths (the Model Context Protocol endpoints an agent calls, such as /.well-known/mcp.json) first, then dynamic routes, then framework asset prefixes, then static suffixes, then the default. Order matters because CloudFront takes the first match: an asset suffix placed above a dynamic route would swallow it. MCP behaviours are separated so the default behaviour can run with request bodies switched off. Only the MCP paths need a body, and forwarding one everywhere would put your visitors' POST payloads through our function for no reason.

The default behaviour and the MCP behaviours use CloudFront's managed CachingDisabled policy, so nothing they serve is ever stored at the edge, and an origin request policy of allViewerAndWhitelistCloudFront, which is what makes the viewer geography headers available to the router. Dynamic carve-outs use CachingDisabled with AllViewerExceptHostHeader; the asset carve-outs keep a 24-hour default TTL, because an image is the same bytes for everyone.

The distinction in that origin request policy is not cosmetic. The plain AllViewer policy forwards the viewer's Host header to the origin, which breaks any host-routed origin outright: a live checkout path returned 403 until it was corrected. If you are adapting this by hand, that is the mistake to avoid.

The router is an origin-request function, and CloudFront only runs one on a request it cannot answer from its cache. Earlier versions kept human pages cacheable and partitioned the cache by caller so that agents still reached the router; that took two more functions and a custom cache policy, and each was a place to get wrong. A cache policy with a minimum TTL above zero, for instance, overrides private, no-store on CloudFront, which would have let one bot-shaped request pin your origin page in front of every crawler that followed.

Since 0.6.0 there is no page cache at the edge at all. Every page request reaches the router, a human is handed straight through, and your origin answers as it always did. The origin's own Cache-Control still reaches the browser untouched; only CloudFront stops holding a copy. A mirror is written private, no-store and is never stored anywhere on the path. So every agent visit invokes the router and is recorded exactly once, and there is no cache anywhere that could hand an agent page to a person.

Every page request is a Lambda@Edge invocation, search crawlers included, and your origin takes every page request it would have taken without a CDN cache in front of it. For a human request the invocation is a few milliseconds of string matching with no network call, and the asset and framework carve-outs keep the bulk of a page's requests off the function entirely.

The ceiling is the regional Lambda@Edge concurrency quota, which is shared with every other Lambda you run in that region and defaults to 1,000 (often 10 on a new account); each instance serves ten requests a second, so the quota times ten is the page-request rate a region can take before CloudFront answers 503 on every page request there. The install reads the quota in all thirteen Lambda@Edge regions and prints it, and the new-distribution template enables a per-address WAF rate limit by default. A breach is a 503, not a silent fallback; the request cap is the one failure this design cannot degrade past.

The router keeps no copy of any mirror. Every diverted request fetches it from the NORG content service, which holds a per-location cache in front of the mirror store behind its own authentication check, so a repeat crawl of the same page is answered from that cache without a storage read. Because every fetch reaches that service, it is also where the visit is recorded: the router passes the user agent, the classification, what it is about to serve and the viewer's network context as one request header, and the service writes the event through its own deferred-work primitive after it has answered. Nothing about analytics runs in your account or waits in front of your visitors.

One event per agent visit, written by the NORG content service, from the details the router passes in one request header on the mirror fetch. On this platform the origin request policy forwards the viewer headers, so these are populated: ip_country, ip_city, asn, http_protocol, tls_version. These two are always null, because CloudFront publishes no equivalent in request headers and inventing a value would be worse than an absent one: as_organization, colo. When no mirror exists yet, the event records the fallback the router declared, stripped or origin; this platform does not distinguish a strip that was discarded for being too thin. Passthrough events for humans are off unless you turn them on with x-norg-events-verbose, and on this platform they are sent best-effort. No query strings, no cookies, and none of the visitor's own request headers beyond the user agent: the geographic and TLS fields above come from headers CloudFront itself adds, not from the visitor. No IP either: the address is read inside the runtime for source verification and never leaves it.

On this platform a carve-out is a CloudFront cache behaviour with no function association. A request matching one never reaches our code at all, so it is not merely unmodified, it is untouched: nothing is classified, nothing is logged, and no invocation is billed. That is stronger than the in-code fast path other platforms have to rely on, and it is why exclusions are the cost control here as well as the safety one.

CloudFront matches the first behaviour that fits, so order decides outcomes: the carve-outs are created ahead of the default, and a narrower one ahead of a broader one. The install prints the full list before it creates anything, and it refuses rather than overwrite a behaviour you already have on the same path.

The two artifacts are plain JavaScript in the public deploy repository, each built from source in the same repository, and each recorded with its full SHA-256 in a committed DIGESTS.json next to them. Hash the files you are about to deploy and compare. The build refuses to publish a bundle that contains a NORG-internal secret name, and refuses one that requires anything the Lambda runtime does not provide.

One deliberate exception to self-containment: the router requires the AWS SDK's Secrets Manager client from the managed Node runtime rather than vendoring it. Bundling it would add tens of thousands of lines to a file whose value is that you can read it. The scheduled heartbeat exercises the same code path and fails loudly, so a runtime that ever stopped providing the SDK would show up in your CloudWatch metrics within the half-hour rather than degrading quietly.

CloudFormation for a new distribution, or a CLI that attaches to one you already have. The CLI dry-runs by default, prints the exact diff, refuses on a conflicting function association, and detaches with one flag. It replaces the default behaviour's cache policy with CachingDisabled and says so in the dry run, because after the install your HTML is no longer cached at the edge; it also prints the Lambda@Edge concurrency quota in every region. It writes no credential into your distribution. Artifacts are pinned by S3 object version, so a rollback is a stack update naming the previous version.

Propagation is five to fifteen minutes for a distribution update, and the kill switch is an origin custom header, so it inherits that timing. Revoking the site key on our side is slower, not faster: the router only learns of it at its next policy refresh, which is up to an hour away by default, and if the secret in your own account is what changed, the fifteen-minute secret cache applies on top. Use the kill switch to stop quickly; use revocation to stop permanently.

Every artifact and log group here is named us-east-1, which looks alarming if your visitors are not in Virginia. It is an administrative detail, not a routing one.

AWS requires the function resource to be created in us-east-1. That is the only thing that region governs. CloudFront then replicates the published version to its regional edge caches and runs it there, so a request from Sydney is classified in Sydney and a request from Frankfurt in Frankfurt, and the site key is read from the Secrets Manager replica in that same region. Nothing is routed via Virginia, and nothing crosses the Pacific to make a decision.

You can confirm this in your own account rather than take our word for it. The log group is named /aws/lambda/us-east-1.<function>, but it is created per region, and the entries appear in the region nearest the edge that served the request. On our own reference install, streams exist in Sydney, Oregon, Dublin and Tokyo; none of that traffic was executed in Virginia.

The practical consequence: classification adds a few milliseconds in the data centre the request had already reached, not a round trip to another continent.

No verified-bot signal, so source verification is CIDR-only against operator-published ranges. An operator that publishes no ranges is not diverted here, where Cloudflare would fall back to its own signal. That is a capability gap and the direction of the failure is the safe one: it under-serves agents rather than over-serving humans.

Everything the install creates belongs to one CloudFormation stack named norg-edge- followed by the first eight hex characters of your site id, and the stack names its functions, roles, schedule rule and alarm under the same prefix. So the credential that runs install_on_cdn can be confined to norg-edge-* for stacks, Lambda functions, IAM roles, EventBridge rules and CloudWatch alarms: it cannot create, change or delete anything in your account that does not carry that name. This is not the execution role's permission described above; it is the credential that builds and attaches the stack, which the Lambda never holds.

Three things cannot be scoped that way, because AWS gives them ids rather than names: the distribution and policy calls in CloudFront, the log groups, and the quota reads. Those take *, and the actions listed for them are the narrowest set the stack uses.

Secrets Manager is the one statement that widens with the adapter version. The install creates the site-key secret and the stack replicates it, so the credential needs the secret's full lifecycle. Until adapter 0.6.1 CloudFormation names that secret SiteKeySecret-<random>, so the resource has to be secret:*, as shown below. From 0.6.1 it is named <stack-name>-site-key and the statement can be tightened to secret:norg-edge-*.