G2 Implementation Plan: Cloudflare Tunnel + Access for tilsit.vip¶
History. Done. The tunnel and the Access drift watchdog merged in #225 (2026-10-22), the ingress check in #230 (2026-11-03), and tilsit.vip has gone through the tunnel since 2026-11-03. Task 7 step 3 was amended on 2026-11-04: the cloudflare-ddns daemon stays, for the home VPN hostname (#235). The two open Task 8 items moved to #237; the tunnel /ready watchdog merged in #238. For the current setup see Cloudflare Tunnel and Tunnel security layers.
Date: 2026-10-22
Issues: #209 (gateway, decision G2), #210 (routing, decision R3).
Design: 2026-10-22-tilsit-vip-routing-and-gateway.md.
Supersedes: 2026-04-19-caddy-forms-auth.md (#130, closed).
Decisions already made¶
| Question | Answer |
|---|---|
| Gateway | G2: Cloudflare Tunnel plus Access |
| Routing | R3: tilsit.vip works everywhere; tilsit.local is LAN-only and unchanged |
| Cloudflare terminates TLS for the tunnelled tools | Accepted (it is inherent to G2) |
| Sign-in | Google (personal account, generic Google IdP, not Workspace) |
| QuickConnect links | Stay on the landing page |
Facts this plan depends on (checked 2026-10-22)¶
tilsit.vipis in Cloudflare accountyou@example.com's Account(<account-id>…, Free plan). The Cloudflare MCP connection in Claude Code was authenticated to a different account (nightowlstudio), which has no zones. It must be reconnected to the personal account before Task 1.cloudflare-ddns.shupdates one fixed record ID (CF_RECORD_ID). Once the A record is replaced by the tunnel CNAME, it would fail every cycle, so it is retired at cutover.cloudflared service install <token>on macOS writes the token into/Library/LaunchDaemons/com.cloudflare.cloudflared.plist, which is world-readable. This plan does not useservice install. It follows thecaddy-wrapper.shpattern instead: the token lives in the System keychain and a wrapper exports it asTUNNEL_TOKENbeforeexec.cloudflaredcan require a valid Access JWT before proxying (originRequest.access: {required: true, teamName, audTag}, per Cloudflare's origin-parameters reference).- Google as an IdP needs an OAuth client in Google Cloud Console, with the
Zero Trust team domain as the authorized origin and
https://<team>.cloudflareaccess.com/cdn-cgi/access/callbackas the redirect URI.
Target architecture¶
Browser (anywhere, including LAN)
→ tilsit.vip (proxied CNAME → <tunnel-uuid>.cfargotunnel.com)
→ Cloudflare Access (Google sign-in, allow: you@example.com)
→ Cloudflare Tunnel (outbound connection from TILSIT)
→ cloudflared on TILSIT (rejects requests without a valid Access JWT)
→ Caddy http://127.0.0.1:8080 (tunnel-only site, loopback bind)
→ / landing page, /transmission/ → 127.0.0.1:9091
LAN only, unchanged:
tilsit.local → Caddy :443 (tls internal) → no auth from LAN
Layered checks on the tunnel path¶
- Access policy at the edge (Google identity, one allowed email).
cloudflaredJWT check (access.required). It proves only that the request carries a valid token from this Access application.- It blocks everyone if the application is deleted or replaced, because no valid token for that AUD can then exist.
- It does not help if the policy is widened (for example to "any Google account" or "Everyone"). Then every visitor gets a valid token, and this check passes them.
- Origin email check in Caddy (Task 2b decides whether it ships). The
tunnel site returns 403 unless
Cf-Access-Authenticated-User-Emailis exactly the allowed address. This is the only layer that still holds if the policy is widened. It is safe only if Cloudflare overwrites the header for Access applications, so a client cannot forge it. The docs do not say this, so Task 2b tests it first. - Policy-drift watchdog (Task 8). It reads the Access application and policy through the API and alerts on any change from the expected rule. It does not block, but it shrinks the window from "until noticed" to one check interval.
- Caddy listener bound to
127.0.0.1only. Nothing off-host can reach it.
Deliberately not used: basic_auth on the tunnel listener. An earlier
review suggested it as a second layer, but it brings back the browser
password pop-up after Google sign-in, which is the problem #209 exists to
solve. Layers 3 and 4 cover a widened policy without a second prompt; layer
2 covers a deleted application.
Accepted residual risk if Task 2b fails (the header turns out to be forgeable, so layer 3 is dropped): a widened policy exposes Transmission until the watchdog alerts and the policy is fixed. Transmission has no auth of its own. Andrew must accept this explicitly at Task 2b, or the plan adds a JWT-validating check at the origin instead.
Caddy trap to avoid¶
cloudflared connects from loopback. The existing (common_config) auth
matcher excludes loopback, so importing it on the tunnel site would apply no
auth at all. The tunnel site must not depend on remote_ip for its
security. Its security comes from layers 1–5.
Tasks¶
Every task that changes production says so, and needs Andrew's go-ahead at the time. "Andrew" marks steps only he can do (browser consoles, secrets, routers).
Task 0: Prerequisites (Andrew, about 20 minutes)¶
- Reconnect the Cloudflare MCP to the personal account (
/mcp, sign in asyou@example.com). Claude verifies withwhoamiand a zone lookup fortilsit.vip. - If Zero Trust is not yet set up on that account, open Zero Trust in the dashboard and pick a team name and the Free plan. Claude can then read the team domain from the API.
- In Google Cloud Console, create the OAuth client:
- Consent screen: External; scopes
openid,email,profile. Publish the app (these basic scopes need no Google verification). Do not leave it in Testing. In Testing, Google itself blocks every account that is not a test user. The denial test in Task 6 would then pass without ever reaching the Access policy. - OAuth client type Web application. Origin
https://<team>.cloudflareaccess.com. Redirect URIhttps://<team>.cloudflareaccess.com/cdn-cgi/access/callback. - In Zero Trust → Integrations → Identity providers, add Google, and paste the client ID and secret there. The secret goes only into the dashboard, never into chat or the repo. Store a copy in 1Password.
- Select Test on the Google IdP and confirm the returned identity.
Task 1: Access policy and application (Cloudflare, before any DNS change)¶
Creating these first means the hostname is protected the moment it starts routing through the tunnel.
- Create a reusable Access policy (
/access/policies): action Allow, include emailyou@example.com. Session duration 24 h (adjust later if it prompts too often). - Create a self-hosted Access application for
tilsit.vip(whole host). Attach the policy. Allow only the Google IdP and turn on instant authentication, so users go straight to Google. - Record the application's AUD tag for Task 2.
- Verify that the policy reads back as
reusable: true.
Task 2: Tunnel (Cloudflare + TILSIT keychain)¶
- Create a remotely managed tunnel named
tilsit. - Set its ingress through the API:
tilsit.vip→http://127.0.0.1:8080, withoriginRequest.accessset torequired: true,teamName: <team>, andaudTag: [<AUD>].- Catch-all →
http_status:404. - Read the tunnel configuration back from the API. Confirm that
originRequest.access.requiredistruewith the rightteamNameandaudTag. Cloudflare documentsaccessas config-file YAML, and this readback is what proves it took effect on a remotely managed tunnel. Do not start Task 5 until it passes. - Andrew copies the tunnel token from the dashboard and enters it at a
prompt on TILSIT. Claude must not fetch the token through the API or MCP,
because the value would then land in the session transcript. The command
must also not put the token on the command line, where it would show in
psand shell history. The existingcloudflare-ddns-setup.shpasses-w '<token>'and has exactly that problem, so do not copy it here. - Use
sudo security add-generic-password -s cloudflare-tunnel-token -a tilsit.vip ... -wwith-wgiven no value, sosecurityprompts for the token. Test the exact argument order on a scratch keychain first. If the keychain path comes after a bare-w,securitymay read the path as the password. - Claude then checks only that the item exists (exit status, no
-w). - Production change, keychain only; nothing routes yet.
- Andrew stores a copy in 1Password (Automation vault) for rebuilds.
Task 2b: Test whether the email header can be forged (before cutover)¶
This decides whether layer 3 ships, so it runs before Task 3 builds
anything. The cloudflared daemon does not exist until Task 4, so this test
runs cloudflared by hand in the foreground. It uses a throwaway hostname
and a throwaway Caddy process, so tilsit.vip and production Caddy are
never touched.
- Install
cloudflared(brew install cloudflared, as the admin account). Task 3's setup script will find it already installed. - Create a temporary Access application on
accesstest.tilsit.vipwith a deliberately open policy: Andrew plus a second Google account he owns. Add an ingress ruleaccesstest.tilsit.vip→http://127.0.0.1:18081, before the catch-all, and a proxied DNS record for it. - Start a scratch Caddy on
127.0.0.1:18081(admin off, its config in the session scratchpad). It logs{header.Cf-Access-Authenticated-User-Email}for every request. Startcloudflaredin the foreground in a root shell that reads the token itself, so the token is never in an argument list:
sudo bash -c 'TUNNEL_TOKEN=$(security find-generic-password \
-s cloudflare-tunnel-token -a tilsit.vip -w \
/Library/Keychains/System.keychain) && export TUNNEL_TOKEN \
&& exec /opt/homebrew/bin/cloudflared tunnel --no-autoupdate run'
tilsit.vip has no DNS record pointing at the tunnel yet, so only
accesstest is reachable through it.
3. Sign in as the second account. Send a request that carries a forged
Cf-Access-Authenticated-User-Email: you@example.com header, for
example with curl and the session cookie, or a browser header extension.
4. Read the scratch Caddy log.
- If the logged value is the second account's real email, Cloudflare
overwrote the forged header. Layer 3 is safe, and it ships.
- If the forged value arrives, layer 3 is unsafe. Drop it, and record
Andrew's decision on the residual risk (see "Layered checks").
5. Stop cloudflared (Ctrl-C) and the scratch Caddy. Delete the test
application, its policy, its DNS record, and its ingress rule. Confirm
through the API that each one is gone, and that the tunnel's ingress is
back to the tilsit.vip rule plus the catch-all.
Task 3: Repo changes (branch, tests, PR)¶
app-setup/templates/cloudflared-wrapper.sh: read the token from the System keychain,export TUNNEL_TOKEN, thenexec /opt/homebrew/bin/cloudflared tunnel --no-autoupdate --metrics 127.0.0.1:20241 run. Pick the metrics port at build time after checking it is free.app-setup/templates/com.cloudflare.tunnel.plist: LaunchDaemon (root),KeepAlive,RunAtLoad. Logs go to/Users/__OPERATOR_USERNAME__/.local/state/cloudflared/, as the Caddy daemon's do. launchd does not create missing log directories, so the setup script runsmkdir -pbeforebootstrap. Use a label different fromcom.cloudflare.cloudflared, so a latercloudflared service installcannot collide with it.app-setup/cloudflared-setup.sh:brew install cloudflared(as the admin account). Check the keychain item. Deploy the wrapper and plist, thenbootstrapthe daemon. Followcaddy-setup.sh.Caddyfile: split the routes out of(common_config)into a(site_routes)snippet that holds the landing page,/transmission/, the QuickConnect redirects, and thelogdirective. Leave/mediaout of it.logmoves intosite_routesso that the tunnel site writes the same access log. Without it, the origin keeps no record of tunnel requests, and Task 6's "nothing reached the origin" check has no data.(common_config)keeps the LAN matchers,basic_auth, the/mediahandler, andimport site_routes. Add the tunnel site:
http://:8080 {
bind 127.0.0.1
route {
# Layer 3, only if Task 2b showed the header cannot be forged.
@not_allowed not header Cf-Access-Authenticated-User-Email __ACCESS_ALLOWED_EMAIL__
respond @not_allowed 403
import site_routes
}
}
The route block is what makes the email check run first. Outside a
route, Caddy sorts directives into a fixed order. redir would then
run before respond, and respond before reverse_proxy, which happens
to work today but breaks silently if site_routes gains a handle.
Inside route, directives run in the order written. This was tested on
a scratch Caddy on 2026-10-22. With no header or a wrong email, /,
/romano and /transmission/ all returned 403. With the allowed email,
each request reached its route. Repeat the check with caddy adapt on
the real template at build time. The allowed address is a template
placeholder, following the repo's no-hardcoded-names rule.
/media must not be in site_routes. Through the tunnel every request
comes from loopback, so the /media handler's @not_local guard would
let it through. A respond deny added on the tunnel site would not help
either: Caddy orders handle_path before respond, so the proxy would
run first. Without the handler, /media on the tunnel site falls through
to file_server and returns 404.
5. Tests (tests/caddyfile.bats): the tunnel site binds 127.0.0.1, does
not import common_config, and has no /media handler. site_routes
has none either. If layer 3 ships, the email check is the first
directive inside the tunnel site's route. The existing matcher tests
still pass. Each new test must fail against a known-bad Caddyfile
before it counts. Add BATS for the wrapper (keychain miss → non-zero exit
with a message) using the repo's TEST_RUNNER pattern.
6. Run caddy validate on the rendered template, the full BATS suite,
shellcheck, and shfmt.
7. PR, review, merge-lock, merge.
Task 4: Deploy the origin side (TILSIT, production)¶
- Deploy the Caddyfile change, validate it, then
launchctl kickstart -k system/com.caddyserver.caddy. - Check locally against
http://127.0.0.1:8080: - If layer 3 shipped: with no email header,
/and/transmission/web/return 403. With-H 'Cf-Access-Authenticated-User-Email: <allowed>',/and/transmission/web/return 200 and/media/returns 404. - If layer 3 was dropped: the same paths without the header return 200, 200 and 404.
- In both cases,
192.168.21.10:8080must refuse the connection from another LAN host. - Run
cloudflared-setup.sh. Confirm in the dashboard that the tunnel shows healthy and that/readyon the metrics port returns 200.
Nothing public changes yet: DNS still points at the home IP.
Task 5: Cutover (Cloudflare DNS, production, about 5 minutes)¶
- Stop DDNS so it cannot fight the change, and keep it stopped across a
reboot. Its plist stays in
/Library/LaunchDaemonswithRunAtLoad, sobootoutalone would undo itself at the next boot.sudo launchctl bootout system/com.tilsit.cloudflare-ddns, thensudo launchctl disable system/com.tilsit.cloudflare-ddns. - Record the current A record for rollback: ID, content, TTL, and
proxied(expectedfalse). - Delete the A record. Create a proxied CNAME
tilsit.vip → <tunnel-uuid>.cfargotunnel.com. - Wait for the old A record's TTL (300 s) to expire.
Task 6: Verify¶
- Outside, from the transmission-vpn container's PIA exit:
https://tilsit.vip/redirects to the Access login (302 to<team>.cloudflareaccess.com), not to the home IP. - LAN, from TILSIT:
https://tilsit.vip/now behaves the same way. This is the R3 result: there is no hairpin timeout any more. - Andrew, on the phone over cellular and then on the LAN: Google sign-in,
then the landing page, then
/transmission/works./media/returns 404 throughtilsit.vip; it is a LAN-only tool ontilsit.local. QuickConnect links work. - Test the rule denies the wrong people. Andrew signs in with a second Google account that is not on the list.
- The denial must be Cloudflare's block page, and it must appear in the Access audit log as a policy denial. Google's "Access blocked" page means the OAuth app is still in Testing (Task 0), and the Access policy was never tested.
- The Caddy access log for the tunnel site must show no request in that time window. The request must stop at the edge, not at the origin.
- Test the rule against its own contents. Claude reads the application and policy back through the API and checks them against the expected rule. The check is the same one the drift watchdog will run:
- Action allow, one include rule, email
you@example.com. - No
everyone,email_domain,any_valid_service_tokenor group selectors. - IdP list is Google only.
- The domain is
tilsit.vip. - If layer 3 shipped: from TILSIT, request
http://127.0.0.1:8080/with no email header (expect 403) and with the allowed email (expect 200). This confirms that Caddy enforces the check. - Andrew checks the Access audit log for the allowed and the denied attempts.
tilsit.localon the LAN is unchanged (200, no prompt).
Task 7: Close the inbound port (Andrew, routers)¶
- Remove the WAN 24443 forward on 192.168.0.1 and on 192.168.21.1.
- Claude confirms from the PIA exit that
203.0.113.13:24443times out. - Until a follow-up PR (two weeks after cutover, if nothing went wrong),
keep the
tilsit.vipsite block and its Let's Encrypt config in the Caddyfile as the rollback path. The follow-up then removes the block, thecloudflare-ddnsdaemon and its docs, and decides whetherCF_API_TOKENis still needed.
Amended 2026-11-04: keep the cloudflare-ddns daemon and
CF_API_TOKEN. This plan missed that the home VPN (OpenVPN on ROMANO,
Tunnelblick on the Macs) also connected through tilsit.vip, on port
34443. After the cutover that name resolved to Cloudflare, and the VPN
stopped connecting. The daemon now keeps a DNS-only vpn.tilsit.vip
record current instead. See docs/components/home-vpn.md. The follow-up
still removes the tilsit.vip Caddy site block.
Task 8: Monitoring and docs¶
- Add a tunnel watchdog (LaunchAgent, alert-lib) that alerts when the
metrics
/readyendpoint stops returning 200. Usealert_transition, so it emails on change, not every cycle. BATS tests follow the other watchdogs. - Add an Access policy-drift watchdog, on the same pattern as the Plex
settings drift monitor (
plex-watchdog.sh). - If Task 2b dropped layer 3, build this watchdog before Task 5. It is then the only check against a widened policy, so it must be running before the hostname goes live.
- Every 15 minutes it reads the
tilsit.vipAccess application and policy, using a separate read-only API token (Access: Apps and Policies Read) kept in the System keychain. Andrew enters that token at a prompt, the same way as the tunnel token. - It compares them with the expected rule from Task 6 step 5, and sends
an alert through
alert_transitionon any difference. It also alerts when the application is missing. - It also alerts when the API itself fails several times in a row, so a broken check cannot look like a healthy rule.
- BATS cases use fixture JSON: the expected rule passes; a widened
include (
everyone, a second email, an email domain) fails; a missing application fails; an extra IdP fails; an API error fails. - Live test, once: add a second email to the policy, confirm the alert arrives, then remove it again and confirm the recovery alert. Do this only with Andrew present, because the policy is briefly wider.
- New
docs/apps/cloudflare-tunnel-README.md: architecture, token chain, Access objects (names, AUD), how to revoke a session, rollback. - Add a service section for the tunnel files in
CLAUDE.md. - Update
caddy-README.md(tunnel site) andcloudflare-ddns-README.md(retired, and why).
Rollback¶
Any time before Task 7:
- Delete the CNAME and recreate the A record with the recorded values,
proxied: false. A proxied record cannot carry port 24443, so the old path would not work through it. - The recreated record has a new ID, and
CF_RECORD_IDis a deploy-time placeholder. Re-runcloudflare-ddns-setup.shso the daemon gets the new ID. Thensudo launchctl enable system/com.tilsit.cloudflare-ddnsandbootstrapit. - The old
tilsit.vip:24443path then works again, protected bybasic_authas today.
After Task 7, also re-add the router forwards.
Stopping the tunnel daemon alone makes Cloudflare show an error page for
tilsit.vip. LAN access through tilsit.local does not change.
Revocation¶
- Remove the email from the Access policy, or revoke active sessions in Zero Trust (Users / Access sessions).
- To cut off the origin entirely, delete or rotate the tunnel (new token in the keychain).
Time estimate¶
| Task | Who | Time |
|---|---|---|
| 0 | Andrew | 20 min |
| 1–2 | Claude via MCP, with approvals | 20 min |
| 3 | Claude | 2 h including tests and review |
| 4–6 | Claude + Andrew | 45 min |
| 7 | Andrew | 10 min |
| 8 | Claude | 1 h |
Open items to settle during the build¶
- Session duration (24 h proposed).
- Confirm that the Free Zero Trust plan covers this, at sign-up.
brew upgradebehavior forcloudflared. Decide whether the daemon needs a restart hook, or whether a reboot orKeepAliverestart picking up the new binary is enough.