privatae-bastion/docs/host-connects.md

# Your Host connects to a server

A Host on your own computer sits behind your home router. A server on the
internet can't open a connection to it, and nothing on your home network
should be opened for it. The server can be reached, though. So for a server
your Host can reach but that can't reach it back, your Host opens the
connections, to one port on the server, and the bastion there runs every lane
over them exactly as it runs them over a connection it opened itself.

Nothing changes but the direction of the TCP connection. Inside it the
bastion is still the TLS client, the Host's CA is still the only root it
trusts, the Host's certificate still names `host.cseries.internal`, and the
bastion still presents its operator certificate, which the Host signed at
pairing. The lanes, the bearer, the heartbeat and every op are the ones in
[lanes.md](lanes.md) and [host-on-this-machine.md](host-on-this-machine.md).

## For the person

On the server:

    privatae-bastion pair --open

It shows a code, good once and for 15 minutes, and the port (8812). On your
Host, choose "Add a server" and give it the server's address and the code.
That is all: the pairing finishes by itself, the server's terminal says so,
and from then on your Host connects to the server whenever it runs. If a Host
is already in charge of the server, the new one waits for it to admit it, as
any other Host does ([approvals.md](approvals.md)).

**Who is in charge.** Run with machine authority (root, or an Administrator
terminal) on a server no Host is in charge of, `pair --open` puts the Host
that pairs through it in charge of the server: it becomes the anchor
([anchor_local.go](../client-go/anchor_local.go)), and the Host counts the
server as the person's own. A local-mode bastion is made networked for it,
unless it already serves another Host the person said yes to. A Host on the
server itself still wins (paired, and not revoked), and an organisation's
policy that names another Host still decides. With a Host in charge, each
terminal and write on the server waits for the person's approval: enrol a
second factor there (`privatae-bastion stepup-enroll`).

**Adding it again.** The same Host pairing the same server again, through a
fresh `pair --open` code, replaces its pairing in place: no `unpair` first.
It is the same Host when its connection presents the CA the pairing already
pins, whatever handle it gives. The pairing gets new credentials and keeps its
state, its grants and, when it is in charge, the anchor (under a new name too,
its pinned key kept). Another Host with the same name is refused.

Right after `unpair`, the running bastion holds the port until it sees the
pairing gone (within 15 seconds); `pair --open` waits for it, up to 25
seconds, and says so.

**Firewall.** The server needs one port open inbound: **TCP 8812** (or the
one given with `--port`). Nothing on your Host's network needs opening, and
nobody has to touch the server's own firewall: while the port is in use (a
pairing whose Host connects here is active, or a pairing window is open), the
bastion keeps a rule of its own that allows it, and removes that rule when the
last such pairing and window are gone, and on `uninstall`. Every 5 minutes the
running bastion also puts its rule back if it went while the port is still in
use (removed by hand, or the firewall reset), unless a rule of the machine's
own now allows the port. Each add and remove is in the audit, and `status` and
`doctor` show the rule.

- Windows: an inbound rule named "Privatae bastion: your Host connects (TCP
  8812)", allowing TCP 8812 to the bastion's own program only, on every
  profile, made with `netsh` from System32.
- Linux with ufw on: `8812/tcp` allowed, with the comment "privatae-bastion:
  your Host connects". With firewalld running: the port added to the default
  zone, now and permanently. The bastion never turns either on or off or
  changes anything else in it, and a rule of the machine's own that already
  allows the port in from anywhere is left alone (and never removed). ufw
  tells the bastion's rule apart by its comment, so a ufw rule without it is
  never removed. firewalld keeps no comment: a port the bastion added and you
  later also add yourself reads as the bastion's, and goes when the door is no
  longer in use. Running as an account that can't change them, it says what
  to run.
- Rules of another kind (nftables or iptables of the machine's own) are not
  changed: `status` and `doctor` say once that TCP 8812 needs allowing there.
- macOS: with the application firewall on, the bastion's program is allowed
  (`socketfilterfw --add`, `--unblockapp`) and removed again after, by the
  path it was allowed for (a bastion that moved removes its old path's
  entry). `--listapps` is read entry by entry: only an entry for the
  program's exact path that allows incoming connections counts. macOS 15
  lists names without paths (`privatae-bastion (state: 1)`), so there the
  program's name is matched. An entry the person set to block, and "Block all
  incoming connections", are the person's settings: they are reported and
  never changed. This has not been run on a Mac yet.
- A cloud provider's firewall or security group is outside the machine: allow
  TCP 8812 there, from anywhere or from your home address.

## What the port answers

The port is open only while the bastion serves a pairing of this kind, or a
pairing window is open on it. Before the Host has proved itself it answers the
TLS handshake and nothing else, and it never forwards a byte anywhere: a
connection it keeps is a lane of a pairing it already serves.

- A connection whose certificate does not verify under the pinned CA of
  exactly one pairing served there, for `host.cseries.internal`, is closed at
  the handshake. So is one that names no protocol, or the pairing protocol
  with no window open.
- At most 256 handshakes run at once, 8 from one address (an IPv6 address
  counts as its /64), each with 10 seconds to finish. 64 of them are kept for
  addresses a Host proved itself from in the last 7 days (its certificate
  verified for a pairing this bastion serves, on this port or another, or it
  paired through the window), so
  that a flood from any number of addresses never holds them and your Host
  gets in at its first try. Every other address is admitted only while fewer
  than 192 are running, and, as OpenSSH's `MaxStartups` does, once 64 are
  running it is refused at random, with a chance of 30% rising evenly to
  certain at 192: a new Host pairing on a quiet port always gets in, and a
  flood fills slowly. Those addresses are kept in memory only, at most 64 of
  them, never written anywhere: a bastion that has just restarted knows none,
  and a Host connecting from an address it has not connected from before
  (a new home address) is admitted as any other until its first connection
  succeeds.
- A wrong pairing code costs a wait of 1, 2, 4 and 8 seconds before the next
  try, during which the window is not offered at all; the fifth closes the
  window.
- The audit (`pairing_audit.jsonl`, and the system log, [audit.md](audit.md))
  records the window opening and closing, each wrong code, each pairing made
  or refused through it, each time a Host connects after having no connection
  and each time its last connection closes, and refused connections (once per
  address per 10 minutes, and at most 256 addresses per 10 minutes, so a scan
  does not fill it).
- A connection offered the window during its handshake starts nothing if,
  by the time the exchange begins, the window was closed at the terminal,
  expired, closed by the fifth wrong code, or is inside a wrong code's wait;
  and the Host is not asked to sign, nor the pairing saved, once the window
  is closed.

## Wire contract (what the Host implements)

Version 1. All JSON is UTF-8, one object per body.

### Connections and roles

The Host opens a TCP connection to the server's address and port, and is the
**TLS server** on it; the bastion is the **TLS client**. TLS 1.3 only. The
bastion sends the server name `host.cseries.internal` and offers, by ALPN:

| ALPN | Offered | The Host chooses it to |
|---|---|---|
| `privatae-lane/1` | by a bastion serving pairings | carry a lane of an existing pairing |
| `privatae-pair/1` | only while a pairing window is open | pair through the window |

The Host chooses exactly one of them; a connection that negotiates neither is
closed by the bastion.

### Pairing (`privatae-pair/1`)

The person gives the Host the server's `host:port` and the code. The Host
normalises the code: upper case, dashes and spaces removed, `O` read as `0`,
`I` and `L` as `1`. It is then 20 characters of
`0123456789ABCDEFGHJKMNPQRSTVWXYZ` (100 bits). That string, as bytes, is the
HMAC key below; the code itself never crosses the wire.

TLS: the Host presents its certificate for `host.cseries.internal` **followed
by its CA certificate** in the chain (the bastion takes the CA from there and
pins it). It does not request a client certificate.

Then, over that one connection, kept open (HTTP/1.1 keep-alive), the bastion
sends three requests and the Host answers each. Host header
`host.cseries.internal`. Let

- `leaf` = SHA-256 of the DER of the Host's certificate as presented on this connection,
- `ca` = SHA-256 of the DER of its CA certificate,
- `proof(role)` = lowercase hex of HMAC-SHA256(key = code, message =
  `"privatae-pair-v1 " + role + "\x00" + leaf + ca + nonce_b + nonce_h`), the
  hashes and nonces as raw bytes.

1. `POST /v1/pair/hello` `{"v":1,"nonce":"<64 hex: nonce_b>"}` → 200
   `{"v":1,"host_handle":"home","host_name":"home.cseries.localhost","nonce":"<64 hex: nonce_h, fresh random>","proof":"<proof(\"host\")>"}`.
   The Host proves first, so a stranger who connects to an open window learns
   nothing to test codes against. A wrong proof counts as a wrong code.
2. `POST /v1/pair/redeem`
   `{"v":1,"proof":"<proof(\"bastion\")>","wg_public_key":"…","operator_csr":"<PEM>","hostname":"<server's hostname>","platform":"linux|windows|darwin","handle":"home"}`.
   The Host checks the proof (constant time) **before signing anything**; a
   wrong one is 403 `{"error":"…"}` and the Host should close the attempt. It
   then answers 200 with the redeem answer of a TCP pairing, with a transport
   of its own and no lane address:
   `{"operator_cert":"<PEM, the CSR signed by its CA for client auth>","ca_cert":"<PEM>","bearer":"…","transport":"host_dials","host_handle":"home","host_name":"home.cseries.localhost"}`.
   `ca_cert` must be the CA it presented; the CSR carries the device
   fingerprint as URI SANs exactly as at a TCP redeem.
3. `POST /v1/pair/done`
   `{"v":1,"state":"active|pending","host_name":"…","admitted_by":"<the Host in charge, when pending>"}`,
   or `{"v":1,"state":"refused","error":"<why, in words for the person>"}` →
   200 `{}`. The Host shows the person what it says. On `refused` it drops the
   credentials it issued; on `pending` it says who admits it and connects
   anyway (the server refuses its lane connections until it is admitted).

Both proofs bind the Host's certificate on this connection: a proof made on
one connection is worth nothing relayed onto another, and a machine the Host
was misdirected to can't pass step 2 without the code, so it never gets a
signed operator certificate. The bastion closes the connection after step 3.

### Lanes (`privatae-lane/1`)

TLS: the Host presents its lane certificate for `host.cseries.internal`
(signed by the CA pinned at pairing) and **requires and verifies** the
bastion's client certificate against its CA, as its lane port does. Then the
Host serves its lane routes on the connection, exactly as on its lane port:
HTTP/1.1, `Host: <the pairing's host name>:8443`, the WebSocket lanes
(`/bastion-harness`, `/bastion-mgmt`, `/bastion-egress`, `/bastion-serve`,
`/bastion-git`) and `/api/network/bastions/…`, every request with the bearer.

The Host sends nothing on a connection until the bastion has spoken on it (a
byte from the Host on an idle connection closes it), and each connection
carries one lane, or a run of requests, for as long as the bastion keeps it.

How many: the Host keeps **4 connections idle** (open, handshake done, no
request yet) at all times, and opens another each time one carries its first
request or closes, up to **64 open** to one server. The bastion holds at most
32 idle per pairing and closes any beyond that. A bastion with every lane
parked holds about 15 (2 harness, 4 session, 2 management, 4 egress and 2
serve workers, and the heartbeat), so a starting bastion draws a burst; a lane
waits up to 20 seconds for the next connection.

Keepalive and reconnect: TCP keepalive every 25 seconds on both sides (a home
router may forget an idle connection after 30). The server never connects to
the Host. When a connection fails to open or its handshake fails, the Host
tries again after 1 second, doubling to at most 30 seconds, with jitter, and
goes back to 1 second after a success. When the bastion restarts every
connection closes and the Host's redials bring the lanes back; when the Host
comes back after being away, the bastion beats at once.

### On the C-Series side

- "Add a server": the address and code fields, the three pairing requests on
  a connection it opens (an `ssl` server context on a connected socket:
  `asyncio`'s `loop.connect_accepted_socket(..., ssl=ctx)` or
  `ctx.wrap_socket(sock, server_side=True)`), and the pairing kept with the
  server's `host:port` and `transport: host_dials`.
- A dialler per such pairing that keeps the pool above, serving the existing
  lane app on each connection as if accepted on the lane port.
- Showing `done`'s words, and the server as connected or not from its
  heartbeat, as for every other bastion.