byjp.me jetbridge-provider

A Provider relays each visitor's TLS connection, by its SNI, to the client that registered the hostname. It does not decrypt the connection.

0 3 pulls 7 Updated 16h
linux/amd64 linux/arm64 Multi-arch
docker pull atcr.io/byjp.me/jetbridge-provider:latest
Image Size Layers
23.0 MB 14
Pushed 7h
Vulnerabilities
Loading...
Pulls
3 total
Last pull 16h

Run a Jetbridge Provider

A Provider relays each visitor’s TLS connection, by its SNI, to the client that registered the hostname. It does not decrypt the connection.

Before you start

As a Provider you relay other people’s sites so they are available from your IP address. That IP address will be under your name so abuse reports and legal demands about them come to you. You cannot see or remove the content of the sites you are relaying, you can only stop relaying. Get legal advice before you publish an open Provider record, or before admitting clients that you do not know. Privacy & Trust lists what you see about clients and visitors.

You need:

  • a Linux host with a static public IPv4 address, and IPv6 if you have it
  • enough bandwidth, and host terms that let you relay traffic for other people
  • ports 80 and 443, open to the internet
  • a DNS name for the API, with A (and AAAA) records for the host
  • a local, DNSSEC-validating resolver, and an accurate clock

Install and run

The image atcr.io/byjp.me/jetbridge-provider runs as uid 65532:

# Create directories for persistent data
sudo install -d -o 65532 -g 65532 /etc/jetbridge
sudo install -d -o 65532 -g 65532 -m 0700 /var/lib/jetbridge-provider

Write /etc/jetbridge/provider.toml:

operator = "did:plc:your-own-did"

[api]
hostname = "jetbridge.example.com"

[admission]
mode = "closed"

[[policy]]
abuse_contact = "abuse@example.com"
sudo chown 65532:65532 /etc/jetbridge/provider.toml

Your Provider’s identity is did:web:jetbridge.example.com, from api.hostname. Clients name it by that DID or by the hostname. Changing api.hostname gives the Provider a new identity, which clients must switch to.

init creates the Provider’s signing key and repo in /var/lib/jetbridge-provider, and publishes your policies and Provider record there. You must read and respond to what arrives at the abuse contact.

docker run --rm --network host \
  -v /etc/jetbridge:/etc/jetbridge \
  -v /var/lib/jetbridge-provider:/var/lib/jetbridge-provider \
  atcr.io/byjp.me/jetbridge-provider init

Host networking lets init find your API hostname’s addresses through the resolver on 127.0.0.1.

Then start the server with this compose.yaml:

services:
  provider:
    image: atcr.io/byjp.me/jetbridge-provider
    container_name: jetbridge-provider
    command: run
    restart: unless-stopped
    network_mode: host
    volumes:
      - /etc/jetbridge:/etc/jetbridge
      - /var/lib/jetbridge-provider:/var/lib/jetbridge-provider
docker compose up -d
  • Host networking keeps the client addresses in the evidence log correct. It also lets the Provider use the host’s resolver on 127.0.0.1.
  • The logs (docker logs -f jetbridge-provider) name clients and hostnames. run --log-level debug adds client and visitor IP addresses.
  • To upgrade, run docker compose pull && docker compose up -d. To choose when, pin a version tag in image. run publishes the new version in your Provider record.
  • run asks the relays in relays to follow your Provider, so its records reach the atproto network and jetbridge.link can list it. Anyone can then keep copies of its records, approvals and usage included, even after you delete them.

[!TIP]
If you decide to go into the details and manage capabilities directly, keep NET_BIND_SERVICE.

[!IMPORTANT]
Back up /var/lib/jetbridge-provider. Its pds/ directory holds the Provider’s signing key, which is its identity, and its repo, with every approval. Keep backups as private as the key: whoever has it can publish as your Provider.

Reload or restart

docker kill --signal HUP jetbridge-provider   # reload
docker restart jetbridge-provider             # restart

A reload applies operator, admission, limits, new policies and ingress.addresses, finds the API hostname’s addresses again, and disconnects only the clients that they now refuse. Other settings need a restart, which closes all tunnels.

Clients read your Provider record, not your config file. After you edit the file, publish it with init, which writes only what changed. A [[policy]] whose terms or text change is published as a new policy, which clients must accept; the one it replaces, like one you remove, stays accepted for 30 days. Reload after init publishes or retires a policy.

docker exec jetbridge-provider jetbridge-provider init

To change your IP addresses, edit the API hostname’s A and AAAA records. Within five minutes run publishes the new addresses, or at once if you reload. Clients add them, wait a minute, then remove the old ones, so keep the old addresses serving for the record’s TTL plus about 15 minutes. If you set ingress.addresses, edit it and reload instead.

Options

The keys you might set in provider.toml:

Key
ingress.addresses Override what your server’s IP addresses are. Useful for split-horizon DNS.
ingress.https_port, ingress.http_port 443 and 80, unless your router sends them to different ports.
operator The atproto account of whoever runs your Provider, as a DID. It is admitted in all modes, and published in your Provider record for sites such as jetbridge.link to show. Optional. When init writes your first provider.toml, --operator takes a handle as well.
listen_address The one IP to listen on. Empty means all IPs.
api.hostname The home page, the session API and the tunnel, on port 443. run gets a certificate for it from acme.ca by HTTP-01, and does not start without one.
admission.mode closed, approval or open. Start with closed, which admits only your operator and the DIDs in admission.trusted.
admission.trusted DIDs to admit in all modes, besides your operator.
admission.denied_dids, admission.denied_hostnames Refused in all modes.
[[policy]] One table per policy, such as one for each jurisdiction, in your order of preference: each client accepts one. abuse_contact (an email address or URL for abuse reports) is required. Optional: jurisdiction (ISO 3166-1 alpha-2, such as GB), entity (the legal entity operating the Provider), and file, markdown to publish in place of the default text, relative to provider.toml’s directory.
limits.max_hostnames The most hostnames each client may serve. 0 means no limit. An approval can change it.
limits.traffic_cap Caps on each client’s traffic, published in your Provider record. One [[limits.traffic_cap]] table per cap, each with direction (egress is Client to visitors, ingress is visitors to Client), bytes, and timespan, a rolling period: 1s, 1h, 6h, 1d, 7d, 30d or 365d. An approval can override them.
relays The relays that run asks to follow your Provider’s records, so that sites such as jetbridge.link can list it. Bluesky’s and Blacksky’s (["bsky.network", "atproto.africa"]) unless you set it. [] asks none.
resolver The Provider trusts its answers. If it fails for some minutes, the Provider refuses clients. In unbound, set cache-max-negative-ttl: 30. Check that dig @127.0.0.1 dnssec-failed.org gives SERVFAIL.

Day to day

Run these commands in the container: docker exec jetbridge-provider jetbridge-provider <command>. They write the Provider’s repo, which a running Provider serves at once.

approve <did> Publishes a public approval record. Options: --expires, --max-hostnames, and --traffic-cap egress:100GB:30d. Repeat --traffic-cap for more caps; they replace all your default caps for this client, and --traffic-cap none lifts them.
revoke <did> Deletes the approval. In approval mode, the Provider disconnects the client in approximately one minute.
deny, undeny <did|hostname> Edits the deny-list in the config file. Reload to apply it.

To write your own policy text, start from the default, save it in /etc/jetbridge, and name it in file.

The evidence log

The evidence log records who you served. For each session, it keeps the client’s DID, IP address, signed service-auth JWT, DID document and route records. It also records each proxy open and close, and each usage record. It has no visitor addresses or content.

The log is one file for each UTC day, in <data_dir>/evidence/. Each line holds the hash of the line before it. run does not start on a broken chain. If a crash breaks the last line, move that file and all newer files out of the directory. Keep them, and start again.

Choose a retention period with your lawyer, and write it in your policy, because the default policy gives no period. Give backups and logs the same period. As root, delete old files each day, and verify the chain:

find /var/lib/jetbridge-provider/evidence -name '*.jsonl' -mtime +"$RETENTION_DAYS" -delete
docker run --rm -v /var/lib/jetbridge-provider:/var/lib/jetbridge-provider:ro \
  atcr.io/byjp.me/jetbridge-provider evidence verify /var/lib/jetbridge-provider/evidence/*.jsonl

Usage records

Just after midnight UTC each day, the Provider publishes a public link.jetbridge.usage record of each client’s bytes and connections the day before. The Provider deletes records after usage_retention_days. A crash loses only the last few seconds of counts, so your figures for that day may be slightly lower than the Client’s, and its record says countsLost.

Abuse reports

  1. Search the evidence log for the hostname, to find the client’s DID and route record.
  2. deny the hostname or the DID, and reload. In approval mode, also revoke the client.
  3. Tell the client through its atproto account. Tell the reporter what you did.
  4. Write down the report and your decision.

Send legal demands to your lawyer.