Skip to content

vps: connect to servers behind a Cloudflare Tunnel (cloudflared) - #49

Merged
enowdev merged 10 commits into
enowdev:mainfrom
SemutJahat:feat/vps-cloudflared
Nov 14, 2026
Merged

enowdev merged 10 commits into
enowdev:mainfrom
SemutJahat:feat/vps-cloudflared

Conversation

@SemutJahat

@SemutJahat SemutJahat commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Servers that expose SSH only through a Cloudflare Tunnel (port 22 closed, reached with ProxyCommand cloudflared access ssh --hostname %h) can now be added on the VPS page. A saved server gets a Connection setting: Direct SSH (unchanged) or Cloudflare Tunnel (cloudflared). In tunnel mode, Antares opens wss://<hostname>/ itself and runs SSH over binary WebSocket frames. This is the same carrier cloudflared access ssh uses, so the machine running Antares does not need cloudflared installed. Every VPS feature works over it unchanged: Test, metrics, processes, vps_run, and upload/download.

Hostnames protected by Cloudflare Access can use an optional service token (Client ID + Secret, sent as Cf-Access-Client-Id / Cf-Access-Client-Secret). Interactive Access login is not supported, since a background agent cannot complete it.

Design and plan: docs/superpowers/specs/2026-11-14-vps-cloudflared-design.md, docs/superpowers/plans/2026-11-14-vps-cloudflared.md.

Changes

  • Store: migration v4 adds tunnel, cf_client_id and cf_client_secret to vps_hosts. The secret is encrypted at rest like password/key. Existing rows default to direct SSH.
  • internal/vps: new tunnel.go. dialTransport hands dial either a TCP conn or the WebSocket conn, so the SSH handshake, TOFU host-key pinning, keepalive, Run, SFTP and metrics run unchanged.
    • Pasted URLs are normalized (https://, path and user@ are stripped; :port is kept).
    • The upgrade is bounded by a 20s timeout and the caller's context.
    • Refusals are worded by HTTP status: Access (401/403 or an Access login redirect), tunnel offline (502/503/504/530), or hostname not routed to SSH.
    • x/net discards that status, so the upgrade runs over a conn that records the start of the response.
    • A rejected SSH login (both modes) now returns ErrAuthFailed naming the user, the endpoint and whether a password or private key was tried. x/crypto/ssh only reports this as text, so the common cause, a username left at the root default, is now visible.
  • API: tunnel, cf_client_id and cf_client_secret are accepted. The view returns has_cf_secret only, never the secret. A blank secret on edit keeps the stored one, and the Access secret is dropped together with its Client ID.
    • /vps/test tests what the form shows. Stored credentials and the pinned host key are only used while the form still points at the saved address. Once the address changes, only typed credentials are sent and nothing is pinned. This prevents a dashboard session from redirecting a saved host's secrets to another server.
  • Agent tools: stored tunnel hosts map through, and the server list shows "via cloudflared".
  • Dashboard: the add/edit dialog has a Connection select. Tunnel mode hides Port and shows a hostname hint and the optional token fields. The host card shows a "cloudflared" tag and gives the user@host line room below the status badges. Strings are added in en/id/ja/ru/zh.
  • Docs: docs/tools.md covers tunnel hosts.

No new dependencies (golang.org/x/net/websocket was already in go.mod).

Testing

  • go vet ./... and go test ./... pass.
  • New tests:
    • A WebSocket→SSH bridge runs Run/Ping over the tunnel transport, including host-key capture.
    • Access headers are sent only when set.
    • Refusal wording is checked for 401/403/302-to-Access/502/530/404.
    • The context timeout and upgrade timeout are covered.
    • Hostname normalization is covered.
    • Store round-trip checks the secret is encrypted at rest, and a pre-v4 row defaults to direct.
    • API helpers are covered: normalization, secret-keeping rules, no secret in the view, and the Test-address rule.
    • A wrong password against the in-process SSH server yields ErrAuthFailed naming the user.
  • TestLiveCloudflaredBanner is opt-in via ANTARES_LIVE_TUNNEL_HOST. It reads only the SSH banner through a real tunnel and sends no credentials. It passed against a real tunnel.
  • web: bun run typecheck, bun test and bun run build pass.
  • End-to-end on a real server behind a Cloudflare Tunnel (password login, non-root user): Test connects and the card shows live CPU/memory/disk/processes with the "cloudflared" tag.
  • Manual check in an isolated dashboard instance: both dialog modes, hostname normalization on save/test, no secret in GET /api/vps, the card tag, edit → Direct restoring Port 22, and the /api/vps/test address rule exercised with curl.

🤖 Generated with Claude Code

SemutJahat and others added 10 commits November 14, 2026 15:55
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Test pins only for the stored endpoint, Access secret tied to its Client ID,
empty host rejected after normalization, bounded WebSocket upgrade, userinfo
stripped from tunnel host, pre-v4 row test, doc and locale polish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
x/net/websocket reports every refused upgrade as a bare ErrBadStatus, so
an offline tunnel (Cloudflare 502/530) was told to add a service token.
Perform the upgrade over a connection that records the start of the
response and word the error by status class. Every refusal still wraps
ErrTunnelRefused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Testing a saved host at a different address reused its stored password,
key and Access secret with no pinned host key, so a dashboard session could
point a saved host at any server and receive its credentials. Saved
secrets and the pinned key are now used only while the form still points
at the saved endpoint; otherwise only typed credentials are sent, nothing
is pinned, and a blank password/key is refused with a clear message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
x/crypto/ssh reports a refused login as "ssh: handshake failed: ssh:
unable to authenticate, attempted methods [none password], no supported
methods remain", which hides the usual cause: the form's username
defaults to root while the server account is another user. Recognise
that phrase and return ErrAuthFailed naming the user, the endpoint and
whether the password or private key was used.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The line sat 2px under the badge row, so the host's censor bar nearly
touched the Online / cloudflared pills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@enowdev
enowdev merged commit deec2ba into enowdev:main Nov 14, 2026
3 checks passed
@SemutJahat
SemutJahat deleted the feat/vps-cloudflared branch November 14, 2026 12:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants