Security

Our control plane introduces two machines and checks that the connection is allowed. The traffic itself goes directly between them when their networks permit, and through a relay when they do not.

A connection never falls back to something weaker. If the preferred path is unavailable, pb may choose another path with the same encryption. If authentication, a certificate or an access check fails, the connection ends; it does not try a different route.

You can run the relay and the edge yourself. See self-hosting.

To authorize, route and bill, the control plane needs metadata. It does not need content, and it is not given any.

A relay or an observer on the network can still see that two addresses are talking, when, and roughly how much. Encryption does not hide that.

Each machine creates its own identity keys when it is set up. The private keys stay on that machine, in the operating system's credential store where there is one, or in files only your user can read on a headless server. They are never sent to us and never appear in logs or diagnostic bundles.

Our server registers the public half and issues short-lived certificates that tie a key to your account and that machine. Two machines verify each other's certificates before any traffic flows, so a relay or our own control plane cannot stand in the middle of a session and read it.

Signing in uses a hosted identity provider. When you run pb login, your browser shows a short code and asks you to approve that computer; no token is ever put in a URL. Sessions are short-lived and refreshed, and each refresh replaces the last.

ENV values are encrypted on your device before they are uploaded. The keys are unlocked by a master password, with an optional recovery code. Neither is sent to us, so we cannot decrypt your values and cannot reset your password.

A machine that should receive a value has its own key pair, and gets only the selected values encrypted to it. It never receives your personal or team keys. Unlocked keys are kept in the operating system's credential store; on a headless Linux server they live in memory for 15 minutes and are never written to disk.

Rotating keys after you remove a machine stops it from reading anything new. It cannot make that machine forget values it already had, so change those secrets at their source too.

Every action on a machine is checked against the workspace's policy before it is allowed, by the server and again by the machine that is being reached. Joining a team grants nothing by itself.

Removing a person, a rule or a machine ends the sessions that depended on it within seconds, including open SSH connections. API tokens expire, can be narrowed to single actions, and lose access when their creator does.

If our servers are unreachable, machines that already trust each other keep working with the access they last verified. A revocation that was delivered before the outage stays in force. This is a deliberate trade: an outage on our side should not lock you out of your own machines.

The audit log records who did what, to which machine, and whether it was allowed. It never contains terminal or file contents.

pb updates itself from signed release metadata. It checks the signature, the file's hash and that the version is not older than the one installed before anything is replaced. A new version whose background service fails to start is rolled back.

Updates install at 04:00 local time by default. pb update settings changes the time or turns automatic updates off; pb update check and pb update download let you review a release first.

• A compromised machine. Traffic is decrypted on your machines. Whoever controls one can read what reaches it and use the keys on it. Remove the machine and rotate what it knew.
• Public links. A preview or tunnel without --private is on the internet. Anyone with the address can send it requests, and our edge handles those requests in the clear.
• People you let in. An interactive participant in a shared terminal types with your shell's permissions. A new participant sees recent output.
• Metadata. Timing, sizes and network addresses are visible to relays and to us.

Paperboat has not had a third-party security audit and holds no certification such as SOC 2. When that changes, the report will be linked here.

The source code of the client, the relay, the tunnel edge and the server is public at github.com/pinksaucepasta/paperboat as open source (MIT and AGPL-3.0). The claims on this page can be checked against it; the threat model is in cli/docs/threat-model.md.

Please report privately, not in a public issue. Until a dedicated security address is published on this page, use the contact in the repository's SECURITY.md. Include what you found and how to reproduce it; a person reads every report.