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 move to CloudFront's managed CachingDisabled policy, so nothing they serve is ever stored at the edge. Your existing origin request policy is kept: it decides which Host header your origin receives, and the router passes that Host through unchanged. Only a behaviour with no origin request policy gets one, and it is a managed one chosen to keep what your origin already received: AllViewer if you forwarded the visitor's Host, AllViewerExceptHostHeader if you did not. No custom cache, origin request or response-headers policy is written into the distribution — AWS flat-rate plans (Free, Pro, Business, Premium) refuse to associate a custom origin request policy. The asset carve-outs keep a 24-hour default TTL, because an image is the same bytes for everyone.

The install records your cache and origin request settings before it changes anything, and an uninstall puts them back exactly. Changing which Host your origin sees is the one thing it must never do: a WordPress site reached under its public name redirects to itself if it is handed its server's own name, and a host-routed origin answers a Host it does not expect with 403.

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. When your origin request policy forwards CloudFront's viewer location, HTTP and TLS headers (the managed AllViewerExceptHostHeader does; the managed AllViewer does not), these are populated, and null otherwise: 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. The event also records the classification, what the router served, and the user agent. When no mirror exists yet, it 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. 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.

There is no exception: the router does not use the AWS SDK. Its one AWS call, reading the site key from Secrets Manager, is a single HTTPS request it signs itself with the function role's own credentials, in a short file you can read. The scheduled heartbeat makes the same call and fails loudly, so a key it cannot read shows 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-*.

No Lambda@Edge function, so no IAM execution role, no service-linked roles and no regional replicas to wait for on delete. No Secrets Manager secret: the site key never leaves NORG, and the only credential on your distribution is the mirror token on the receptionist origin. No EventBridge schedule and no heartbeat function: the gate stack is one CloudFront Function plus its CloudWatch alarms. Because nothing heartbeats, the site activates on the receptionist's first gate-seen stamp: when it serves the first agent request through the mirror token, it tells NORG, and that flips the site active exactly as a heartbeat would.

The credential that builds and attaches a gate stack needs none of the Lambda, IAM role, Secrets Manager, EventBridge or log-group statements shown in the Lambda policy above. It needs the stack itself, the function (scoped to norg-edge-*), the distribution read and update, the two read-only policy reads the preview uses, and the alarms. Replace <account-id>with your account id.

It can create, update, delete and re-create NORG's CloudFormation stack; manage CloudFront Functions and Lambda@Edge functions named norg-edge-*; read and update your distribution's configuration; create two CloudWatch alarms; write CloudFront access logs to a bucket named norg-edge-logs-* in your account (the files stay with you; NORG reads them for timing reports); and read the installer user's own policies. Created with the template, the user also carries a permissions boundary equal to this grant, and may rewrite its own inline policy within it: that is how NORG scales the grant back later without asking you again, and why it can never widen it. It cannot read your data or your other secrets, touch other IAM users or roles, or change anything not named norg-edge-*.

Download the template below. In the AWS console open CloudFormation, choose Create stack, upload the file, name the stack norg-edge-installer, tick the acknowledgement about IAM resources with custom names, and create it. It makes one IAM user named norg-edge-installer with the policy attached and set as its permissions boundary, creates an access key, and stores the key in Secrets Manager as norg-edge-installer/access-key. Nothing else in the account is touched.

Create an IAM user, attach the JSON below as an inline policy named NorgEdgeInstallerFull with account-id replaced by your account id, and create an access key for it. This document lets NORG read, not rewrite, the user's own policy, so narrowing the grant later needs your admin again; the template avoids that.

Send NORG the access key id and secret through a secure channel, never by email, together with the id of each CloudFront distribution NORG should install on. NORG stores the key encrypted, bound to your workspace, and uses it only for the actions in this policy.

Download norg-edge-installer-user.json and upload it to CloudFormation. It has no placeholders: the account id is resolved when the stack runs.