- Go 77%
- TypeScript 10%
- Svelte 10%
- Shell 2%
- CSS <1%
- 3 more languages <1%
Jetbridge #
Jetbridge is a cooperative tunneling service, an alternative to Cloudflare Tunnels or Tailscale Funnel, built on frp, coordinated over AT Protocol.
Services you run can dial out to a Jetbridge Provider; then, once your Marque domain points at that Provider, your service is available on the web with no port-forwarding hassle. The Jetbridge Client, a CLI tool and/or Go package, handles all this for you.
Anyone with a (moderately) static IP address can be a Provider. Clients only need to trust that a Provider will remain up: TLS termination happens in the Client, and the automatic DNS management includes a CAA record preventing the Provider from a takeover.
What you need #
- An Atmosphere account and an app password for it
- A domain on Marque;
jetbridge-client upmanages the zone by writingat.marque.dnsrecords on your atproto account - A Jetbridge Provider to use. To run your own see the Provider runbook.
go install tangled.org/byjp.me/jetbridge/cmd/jetbridge-client@latest
Or with Homebrew, on macOS or Linux:
brew tap byjp.me/tools https://tangled.org/byjp.me/homebrew-tools
brew install byjp.me/tools/jetbridge-client
Serve a local service #
export JETBRIDGE_IDENTITY=you.example.com # your handle or DID
export JETBRIDGE_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
# a web app, reverse-proxied
jetbridge-client up app.example.com --provider provider.example --upstream http://127.0.0.1:3000
# anything else, as raw bytes
jetbridge-client up ssh.example.com --provider provider.example --upstream tcp://127.0.0.1:22
jetbridge-client up runs until you interrupt it. It asks you to accept the Provider's policy, if not already accepted, then:
- binds the hostname to you with a
_jetbridge.TXT record holding your DID - pins your domain with a CAA record that only allows certificates from your ACME account
- writes a
link.jetbridge.routerecord to your atproto repo - opens an outbound tunnel to the Provider (some Providers approve use by hand, this may take time)
- points the hostname's A and AAAA records at the Provider
- gets a certificate through the tunnel, in the background
DNS takes about a minute to serve each change, so the first run takes minutes. http:// upstreams get X-Forwarded-* headers and HSTS (--hsts=false to leave it to your app); tcp:// upstreams get the bytes. Visitors who arrive over plain http:// are redirected to https:// by the Provider.
Important
The ACME account key, certificates and accepted policies live in --store (by default jetbridge in your user config directory). Treat the store as secret.
--accept-policyaccepts the Provider's first policy without asking, now and whenever it stops offering the one you accepted;--accept-policy=CID,...accepts only those.--existing-dns replaceletsupreplace DNS records it didn't write at the hostname.- Interrupting
upremoves the A and AAAA records. The TXT and CAA records stay.
jetbridge-client down app.example.com # cleans up A/AAAA records, if needed
jetbridge-client status # lists your routes: provider, policy acceptance, DNS status, tunnel health, and why any isn't running
See jetbridge-client <command> --help for more detail.
Serve several sites #
List them in a file, and run them all from one process:
# sites.toml
provider = "provider.example" # every site's, unless it names its own
fallback = ["backup.example"] # see jetbridge-client up --fallback
on_disagreement = "notify" # see jetbridge-client up --on-disagreement
accept_policy = true # or a list of policy CIDs
existing_dns = "down" # or "replace"; a site can override it
[[site]]
hostname = "app.example.com"
upstream = "http://127.0.0.1:3000"
existing_dns = "replace"
[[site]]
hostname = "ssh.example.com"
upstream = "tcp://127.0.0.1:22"
provider = "other.example"
Then run directly, or via Docker:
# with the CLI
jetbridge-client run --config sites.toml
# with Docker
docker run -d \
--network host --stop-timeout 120 \ # allow time to remove DNS records
-e JETBRIDGE_IDENTITY=you.example.com -e JETBRIDGE_APP_PASSWORD \
-v "$PWD:/etc/jetbridge:ro" \ # contains sites.toml
-v jetbridge:/var/lib/jetbridge \ # where certificates are stored
atcr.io/byjp.me/jetbridge-client
You can send run a SIGHUP to reload.
Bandwidth use and limits #
Providers may specify a traffic caps, and throttle Clients if they exceed them. The Client also tracks throughput, compares its measurements to those the Provider publishes. The Client can choose a different Provider if it believes there is problematic misreporting.
Your Provider publishes the bytes it carried for you once a day. jetbridge-client up counts the same bytes itself, and compares its count for the day before with the Provider's.
jetbridge-client usage app.example.com # the last 30 days: your count, the provider's, the difference
Results can be:
agree(within 10 MB, or 1% if that's more)provider-overprovider-under(noting when the Provider says it lost counts that day, as when it crashed)missing(no record by 06:00Z)incomplete(the Provider stated more than you counted, but your Client crashed or was killed that day, so its count may be short)
When the Provider serving your hostname states more than you counted, you decide what happens with jetbridge-client up --on-disagreement <action>:
notify(the default) only logs itswitchmoves to the first Provider in--fallbackthat worksdownremoves the A and AAAA records and exits
Embed it in your app #
pkg/ingress does everything up does and hands you a listener whose connections are already TLS-terminated for your hostname:
ln, err := ingress.Listen(ctx, ingress.Config{
Hostname: "app.example.com",
Provider: "provider.example",
Identity: ingress.Identity{ID: "you.example.com", AppPassword: os.Getenv("JETBRIDGE_APP_PASSWORD")},
AcceptPolicy: askTheUser, // offered the Provider's policies; nil declines them all
// or AcceptAllPolicies / AcceptedPolicies, and ReplaceDNS, when there's no one to ask
})
if err != nil {
return err
}
defer ln.Close() // removes the A and AAAA records
return http.Serve(ln, handler)
See examples/embed for an example, go doc ./pkg/ingress covers the details: the store, the DNS writer, logging, and the process-wide state that frp forces on the package.
Tip
ingress.Listen blocks for minutes while DNS settles, so give it a context you can cancel.
Beyond HTTP #
The Provider routes TLS by SNI and nothing else, so any protocol works if you wrap it in TLS and connect to port 443.
SSH can work, if the visitor wraps it:
# on the server
jetbridge-client up ssh.example.com --provider provider.example --upstream tcp://127.0.0.1:22
# in the visitor's ~/.ssh/config
Host ssh.example.com
ProxyCommand openssl s_client -quiet -connect %h:443 -servername %h
SSH still authenticates the server by its host key, so the TLS wrapper doesn't have to.
- One hostname per service. Don't share a hostname between HTTP and anything else. Run one
upfor each. - Port 443, TCP only. Don't advertise HTTP/3 (no
Alt-Svc: h3from your app, noh3in an HTTPS DNS record); the Provider doesn't route UDP. - No Encrypted Client Hello. It hides the SNI Providers route on.
- TLS from the first byte. Protocols that start in plaintext and then upgrade (SMTP and IMAP with STARTTLS, classic PostgreSQL) send no SNI at the start, so the Provider can't tell where to send them.
- ALPN: an
http://upstream negotiates onlyh2andhttp/1.1, so a visitor that insists on another ALPN protocol is refused. Atcp://upstream gets whichever protocol the visitor offers, so PostgreSQL's direct TLS (postgresql) works.
Privacy & Trust #
A Provider sees the hostnames you serve, the IP addresses you and your visitors connect from, your machine's name, OS and architecture, and how many bytes flow and when. It publishes your daily byte counts per hostname to their atproto account, where anyone can read them.
It can't read what's inside the TLS, because the key never leaves your machine, and it can't get a certificate for your domain either: your CAA record allows only your own ACME account.
A Provider can cut you off or drop your traffic.
If your PDS can limit an app password's scopes, as Tranquil and vlpds can, the Client needs only these:
repo:link.jetbridge.route?action=create&action=update repo:at.marque.dns?action=create&action=update rpc:link.jetbridge.requestSession?aud=*
Run a Provider #
See the Provider runbook. The design is in docs/plan.md.