jackson2w/claude-code-skills / cloudflare-worker-tailscale-shield
cloudflare-worker-tailscale-shield
UnverifiedThis skill should be used when building a Cloudflare Worker that sits in front of a homelab service reachable only via Tailscale Funnel — validating auth/rate-limiting at Cloudflare's edge before forwarding inward, with a Cloudflare Queue for retry-on-failure. Also covers a specific `wrangler secret put` misuse that leaks the secret value as the secret's *name*. Trigger phrases include "cloudflare worker in front of tailscale", "webhook shield worker", "worker forward to tailscale funnel", "workers can't reach tailnet", "wrangler secret put wrong name", "queue retry backoff worker", "workers_dev false no public url".
Cloudflare Worker fronting a Tailscale Funnel service (webhook-shield pattern)
First built 2026-07-18 for n8n-webhook-shield in the homelab repo: a public Worker in front
of n8n's Krisp webhook, validating auth + rate-limiting at Cloudflare's edge before forwarding
to n8n over its existing Tailscale Funnel. Generalizes to any "put a Worker in front of a
Tailscale-exposed homelab service" project.
The core constraint: Workers can't reach tailnet-private addresses
Cloudflare Workers run on Cloudflare's edge network, not inside your tailnet. A Worker can only reach a homelab service via a URL that's actually publicly resolvable and reachable — i.e. the target's Tailscale Funnel URL, never a Serve-only (tailnet-private) one. This means a plain Worker genuinely cannot "take a service off the public internet entirely" while still being able to reach it — that requires a Cloudflare Tunnel connector running inside the homelab instead (a separate, larger project). Confirm this tradeoff with whoever's asking for the shield before building — the "n8n off the public internet" framing in an initial ask may not be fully achievable with a Worker alone, and that's worth surfacing rather than silently building something that doesn't match the stated goal.
What a Worker-in-front does genuinely deliver: the origin's Funnel URL becomes double-gated (edge check + the origin's own existing auth), bad/abusive requests get rejected before ever reaching home bandwidth, and a Cloudflare Queue can retry delivery through a brief origin outage instead of silently dropping the event.
workers_dev defaults matter differently for a public-facing vs. queue-consumer Worker
If templating off a cron-only or queue-only Worker (no real HTTP entry point), don't copy its
"workers_dev": false setting blindly into a new Worker that needs to actually receive public
HTTP traffic — that setting with no custom route configured means the Worker has no public
URL at all. Set "workers_dev": true for anything that needs a reachable *.workers.dev URL
(or configure a custom route/domain instead).
The Worker must forward the origin's own auth header too, not just validate it
If the origin (e.g. n8n's webhook node) has its own independent auth check that's being kept as
a second layer (rather than removed in favor of the edge check), the Worker's forward fetch()
call must include that same auth header — it's easy to write a shield that validates the
inbound header but then constructs the outbound request with only Content-Type, forgetting to
carry the header through. The origin then rejects everything with its own 403/401 regardless
of whether the Worker's own check passed, and — this is the trap — the caller sees no sign of
this at all, because a well-designed shield returns 200 on both "delivered live" and
"queued for retry" (so the initial caller isn't punished for the origin being briefly down).
curl-checking only the shield's own HTTP status will never catch this bug.
Verify with wrangler tail against the Worker actually receiving the origin's response, not
just the status code the shield hands back to its caller. Add explicit logging distinguishing
"forwarded live" vs. "queued for retry" vs. the origin's actual response status/error — cheap to
add, and the only way to see this class of bug without guessing.
Testing the queue/retry/alert path without waiting out the real backoff
If the retry consumer's give-up threshold is high (e.g. 8 attempts with exponential backoff capped at 30 minutes), waiting for a genuine end-to-end exhaustion test takes ~30+ minutes. Temporarily lower the threshold (e.g. to 3) for a test pass, point the shield at a deliberately unreachable path so requests genuinely fail, confirm the alert fires, then restore the real threshold and redeploy before considering the test done. Remember any messages already queued during earlier failed tests (e.g. from a bug fixed mid-session) are independent, already-enqueued messages with their own accumulated attempt counts — they'll keep failing under whatever bug queued them and will each eventually alert-and-purge on their own schedule, which can look like unexplained extra retries/alerts if you've forgotten they're sitting there from an earlier test.
Rate limiting needs a real burst to test, not a quick sequential loop
Cloudflare's Workers ratelimit binding is explicitly documented as "permissive, eventually
consistent, and intentionally designed to not be used as an accurate accounting system" — a
tight sequential loop of even 25-60 requests from one location can all land within the
eventually-consistent window and pass through with no 429 at all, even though the binding is
configured and working correctly. This isn't a bug to chase. To actually observe a 429,
generate real concurrent load (e.g. seq 1 150 | xargs -P 40 -I{} curl ...), not a for-loop.
wrangler secret put misuse can leak the secret as the resource name
wrangler secret put NAME is meant to be run with just the secret's name as the argument,
then the value is entered at the interactive prompt it opens. If it's instead run as
wrangler secret put "<the actual value>" — passing the value where the name goes — the value
itself becomes the name of a new Cloudflare secret, which is then visible via wrangler secret list (and thus can end up printed in a chat transcript, terminal history, screen share,
etc., depending on however that listing gets surfaced). This is a real, easy-to-make mistake,
not just a hypothetical — caught in a real session via routine wrangler secret list output.
If this happens, and the leaked value is a live credential shared with another system (e.g.
the same secret configured in a third-party webhook's auth header), treat it as genuinely
compromised: delete the bad Cloudflare secret entry, rotate the value everywhere it's used
(not just delete-and-recreate the Cloudflare side with the same now-exposed value), and only
then set the new value correctly (wrangler secret put NAME, value at the prompt). When
relaying a freshly rotated value to a human who needs to paste it into multiple UIs (e.g. both
the third-party service's config and the origin's own credential store), write it to a local
file instead of printing it in any tool output, have them view/copy it themselves
(cat <file> in their own terminal), and delete the file once every place that needed it has
been updated — don't print it "just this once" even under time pressure.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |