Spec: client access through inbuxa-relay (design note, #484) #489

Open
jcoffey-dev wants to merge 4 commits from spec/client-gateway into main
pull from: spec/client-gateway
+577
View File
@@ -0,0 +1,577 @@
# Feature spec: client access through inbuxa-relay
Status: design note, 2026-11-19, revised 2026-11-21 to cover both modes.
Open questions answered 2026-11-21 (all as recommended). Still a
suggestion: not approved, not planned, not scheduled. inbuxa-server #484
(milestone 27.7), discussed on the forum (t/340). It builds on
`features/relay.md` and doesn't change any of that spec's rules.
## Provenance
inbuxa's own design. No upstream file or snippet was used. Sources:
| Source | Used for |
|---|---|
| `features/relay.md` (RL-1 to RL-36), and the relay code in `crates/relay`, `crates/relay-proto`, `crates/services/src/inbuxa_relay_link.rs` | The link, its identities and hardening, which this reuses |
| RFC 8446 §4.1.2 and RFC 6066 §3 (TLS ClientHello, server_name) | Reading the requested name without decrypting anything |
| HAProxy PROXY protocol, version 2 | Carrying the client's real address to the downstream |
| RFC 8659 (CAA), RFC 8657 (CAA `accounturi`, `validationmethods`) | Keeping a compromised relay from getting a certificate for the client names |
| RFC 9112 §6.3 and §11.2 (message body length, request smuggling) | What a terminating relay refuses before rebuilding a request |
| RFC 7009 (token revocation), as built in #427 | Why sessions in terminating mode are bound to a relay instead of revoked one by one |
| This repository: listener `proxyTrustedNetworks`, `BlockedIps` (`crates/common/src/network/security.rs`), CAA records (`crates/common/src/network/dns/records.rs`), OAuth revocation (`crates/common/src/auth/oauth/revoke.rs`) | What the downstream already has |
| Forum t/340, posts 6 and 8 | The case for terminating mode, stateless relays, and detection and response |
## The question
inbuxa-relay lets a server take mail without opening port 25: the server
dials out to a small relay on a public machine and keeps that link open. A
reader asked for the same for client access (webmail, JMAP, IMAP, CalDAV,
submission), so a server at home or in an office is reachable from outside
with no open port and no VPN.
#484 framed it as JMAP and webmail only, with passkey or token sign-in "so
the gateway never handles a reusable password". The first version of this
note argued for the opposite line, a relay that never decrypts client
traffic. The forum discussion made the case for the other side too, and
both are worth having. This version covers both, chosen per port.
## Two modes
The difference is where client TLS ends, and that decides what a
compromised relay gets and what an attacker on the internet can reach.
**Pass-through.** The relay reads only the unencrypted start of the
handshake to see which name is asked for, and copies the encrypted bytes to
the downstream, which ends TLS with its own certificate, as it does now. The
relay sees client addresses, the names asked for, timing and volume. It
sees no password, token or content, for any protocol. IMAP and submission
are as safe to carry as JMAP.
The cost: the server's IMAP, HTTP and SMTP parsers face the internet
exactly as they would with the ports open. An exploit for one of them
reaches the server, just through a tunnel. What pass-through removes is
the need for the protected network to accept connections at all.
**Terminating.** The relay holds a certificate for the client names, ends
TLS, parses each request completely, and sends the downstream a request it
has rebuilt itself, never the client's bytes. This is what the relay
already does for port 25: it speaks SMTP to the world and hands mail over
the link, so an exploit aimed at its SMTP parser lands on the relay, not
the server. Here the same holds for HTTP. To reach the server an attacker
needs a second exploit, one that works through a well-formed request.
The cost: everything that passes through the relay is in the clear on it.
Whoever takes the relay sees every message read through it, and every
session token, for as long as they hold it. Passwords sent through it are
exposed too, which is why terminating mode refuses them (CG-7).
| | Pass-through | Terminating |
|---|---|---|
| A compromised relay sees | Addresses, names, timing | All of that, plus content and session tokens while it's held |
| A parser exploit lands on | The server | The relay |
| Protocols | 443, 993, 465 (995 with legacy on) | 443 (JMAP, webmail, DAV) at first |
| Sign-in | Anything the server allows, end to end | Passkeys and relay-bound tokens only (CG-7, CG-8) |
| Certificates for client names | Only on the downstream | A short-lived one on the relay, key made there (CG-9) |
| Fits | Few users, or content that matters more than the server | Many users, or a server that matters more than one session |
Neither is wrong. Which one is worth more depends on what is being
protected. For one person on their own server, a taken relay and a taken
server are close to the same loss, and pass-through costs less. For an
office with many accounts, keeping the server out of reach of a single
exploit is worth a box that sees traffic while it's compromised, provided
that box is small, holds nothing, can be cut off at once, and comes back
clean (see "Detection and response").
**Recommendation: both, chosen per port, pass-through by default.**
Pass-through is built first. Terminating comes second, for 443 only at
first, as its own build of the relay (see "Footprint").
## Rules
These hold alongside RL-1 to RL-4. No setting turns them off.
For both modes:
- **CG-2. Implicit TLS only.** The relay carries only ports whose
connections start with TLS: HTTPS 443, IMAPS 993, submissions 465, and
POP3S 995 only where the downstream has legacy protocols on. Never 143,
110 or 587. Their STARTTLS start is in the clear, and passwords sent
there by a misconfigured client would cross the relay readable.
- **CG-3. The downstream picks the target.** A forwarded connection names a
target by id. The node maps the id to an address from its own settings,
never from anything the relay sends. A compromised relay can reach only
what an internet client could reach through it.
- **CG-4. The client's address reaches the downstream.** Each forwarded
connection carries the client's address: a PROXY protocol v2 header in
pass-through, a field in the stream header in terminating mode. Without
it every client would look like the node itself, and the server's
per-address sign-in limits would ban the node.
- **CG-5. Off by default.** Client access is turned on per relay, per port,
from inbuxa-admin, and each port says which mode it uses.
Pass-through:
- **CG-1. A pass-through port never ends client TLS.** The relay reads the
ClientHello's `server_name` to route and filter, and forwards the rest
unread. It holds no certificate for a name it passes through.
Terminating:
- **CG-6. Rebuilt, never forwarded.** The relay sends the downstream only
requests it has parsed in full and written out again in one canonical
form. No byte from the client reaches the downstream unparsed. Anything
it can't parse, or that is ambiguous, is refused at the relay.
- **CG-7. No reusable secret.** A terminating port refuses password
sign-in: HTTP Basic, the OAuth password form, and any other form that
sends a password. Sign-in is by passkey, or with a token already bound to
this relay (CG-8). A passkey assertion is bound to its challenge and
can't be replayed, so a relay that sees one gains nothing lasting.
- **CG-8. Sessions belong to a relay generation.** Every token issued
through a terminating relay carries the relay's id and generation, and
the server accepts it only through that relay and generation. A new
generation (rebuild, rejoin, quarantine) makes all of them useless at
once, with no list of tokens to revoke. A token issued anywhere else is
refused on a terminating port, so tokens from inside the network never
cross the relay.
- **CG-9. The relay's certificate key never leaves it.** The relay makes a
key for the client names on start, keeps it in memory, and sends the
downstream a certificate request over the link. The downstream orders the
certificate by DNS challenge with its own ACME account (so the CAA record
is unchanged, see "Certificates and CAA"), at the shortest lifetime the CA
offers, and pushes back the certificate only. This differs from RL-27,
where the downstream pushes the SMTP certificate's key; that one stays as
it is.
- **CG-10. Nothing kept.** A terminating relay writes nothing about client
traffic to disk: no cache, no log of content or tokens, no session state.
Its image runs with a read-only root. A restart or rebuild loses nothing
that matters, and a compromise doesn't survive one.
- **CG-11. One worker per client connection.** Each client connection is
parsed in its own sandboxed worker process, with no access to other
connections, the link credentials, or the certificate key. The worker
hands rebuilt requests to the relay's main process over a pipe. Breaking
a worker gives an attacker their own connection and nothing else.
- **CG-12. Can be cut off at once.** The downstream can quarantine a relay
in one step, from inbuxa-admin or with an API key that holds only that
permission (see "Detection and response").
## How a connection goes
### Pass-through
```
client ──TLS──▶ relay :443/:993/:465 ──bytes──▶ pooled stream (mTLS, dialed OUT by a node) ──▶ node ──PROXY v2 + bytes──▶ target listener
checks: blocked list, rate, (server listener, or the
name allowed (443) install's front proxy)
```
1. A client connects to the relay on a client port. Before reading
anything, the relay checks the source address against the blocked list
the downstream pushed, and the per-address connection rate and count.
Failing either closes the connection.
2. On 443 the relay reads the ClientHello (one TLS record, at most 16 KB,
within 5 s) and takes `server_name`. A name not in the relay's list of
client names closes the connection. On 993, 465 and 995 there is one
target per port, and the name isn't checked.
3. The relay takes an idle **stream** from its pool. A stream is an mTLS
connection a downstream node dialed to the link port (`GET /stream`,
upgraded), authenticated by the node's link certificate like any link
connection (RL-6), waiting to be used. The relay writes a short header
(mode, target id, client address and port, the relay's address) and
then the bytes it has read so far, and from then on copies both ways.
4. The node reads the header, connects to the target's address from its own
settings, writes a PROXY v2 header with the client's address, and copies
both ways. The target ends TLS as it does now.
5. The node dials a new stream to keep its pool full.
If the pool is empty, the relay asks for more streams over the link's
WebSocket, and holds the client up to 5 s for one before closing.
**Why a pool of connections, not streams inside the WebSocket.** Carrying
many client connections inside the link's one WebSocket needs flow control
per stream, and a large download would hold up the link's own JMAP calls. A
connection per client stream, dialed ahead of time, needs no new framing,
adds no wait on connect, and matches how the link already carries blobs on
separate HTTP/1.1 connections (Decision 10). Each node keeps a few idle
streams (4 by default) and the relay spreads clients across nodes. Idle
streams are pinged like the link (RL-5).
**Long-lived connections.** IMAP IDLE and webmail push hold a connection
for hours. The relay sets no idle timeout of its own on a client stream.
TCP keepalive on both legs finds dead peers.
**HTTP/3.** QUIC is UDP and isn't carried. Clients fall back to TCP. The
target shouldn't advertise HTTP/3 (`Alt-Svc`) for the relayed names, or
clients will try it first and lose a few seconds.
### Terminating
```
client ──TLS──▶ relay :443 ──▶ worker (one per connection, sandboxed) ──rebuilt requests──▶ relay main ──▶ pooled stream ──▶ node ──▶ server HTTP service
ends TLS parses, refuses, rebuilds (CG-6) re-checks canonical form,
(CG-9 cert) relay id + generation (CG-8)
```
1. Steps 1 and 2 above, then the relay ends TLS with its own short-lived
certificate (CG-9) and hands the connection to a fresh worker (CG-11).
2. The worker parses HTTP/1.1 or HTTP/2 from the client and refuses, with
no request sent on: a request with both `Content-Length` and
`Transfer-Encoding`, repeated or malformed length headers, obsolete line
folding, bare CR or LF, a path outside the allowed set (JMAP, its
WebSocket, `.well-known`, webmail, and DAV if turned on), a header
section or body over the limits, and a JMAP body that isn't valid JSON
or is nested deeper than the server accepts. Compressed request bodies
are refused.
3. The worker writes the request out again: method, normalised path,
headers from an allow list with values re-encoded, JSON bodies
re-serialized. The relay sends it on a stream with a header saying it
was terminated, the client's address, and the relay's id and generation.
Responses come back from the downstream and are passed to the client
as they are; they come from the trusted side.
4. The node checks that each request is already in canonical form, so
rebuilding it again would change nothing. A relay sending anything else
has been tampered with, and the node quarantines it (see "Detection and
response"). The node hands the request to its own HTTP service, marked
as coming through that relay and generation, and the service applies
CG-7 and CG-8.
JMAP over WebSocket (RFC 8887) is parsed and rebuilt one message at a time
the same way. Event streams and blob downloads are responses and pass
straight back.
**What the protocol break does and doesn't stop.** It stops anything that
lives in framing and encoding: request smuggling, header tricks, malformed
TLS, HTTP/2 frame floods, oversized or broken JSON. These end at a worker.
It doesn't stop a bug the server has with a well-formed request, since the
relay rebuilds that faithfully. That's the "second exploit" an attacker
still needs.
**IMAP and submission.** Not terminated at first. Doing it means an IMAP
and SMTP submission parser in the relay (the workspace's own `imap-proto`
and `smtp-proto` would do; a bug in the shared parser then fires on the
relay, and the server only sees the rebuilt command). The harder part is
sign-in: IMAP and submission clients send passwords, which CG-7 forbids.
App passwords could stand in, bound to the relay like tokens (CG-8). Listed
as an open question.
## Detection and response
A terminating relay is only as good as how fast a compromised one is cut
off and replaced. Pass-through relays get the same tools, since a taken one
can still drop traffic and forge client addresses.
**Quarantine.** One update on `inbuxa:Relay` (`quarantine: true`), from
inbuxa-admin or through the API with a key holding only
`sysRelayQuarantine`. It:
- drops the relay's link and every stream, and the nodes stop dialing it;
- starts a new generation, so every token bound to the old one is refused
(CG-8);
- asks the CA to revoke the client-name certificates issued for it;
- withdraws its A, AAAA and MX records where the server manages DNS, if
another relay is still serving;
- forgets its link identity, so it can only come back by joining again with
a new token, as a fresh install.
**What can trigger it.**
- An administrator.
- The downstream itself, on things a healthy relay never does: a
terminating stream that isn't in canonical form, a token for another
relay or generation, a request on a port that is off, a link message
outside the protocol.
- A monitor watching the relay's host. The scoped API key is meant for
this. The Cairn OBS agent is the first one to wire up: on a relay host it
can watch for processes that shouldn't run, files changed on a read-only
root, outbound connections other than the link and port 25 delivery, and
the relay binary's hash, and a Cairn OBS alert can call the quarantine.
inbuxa doesn't depend on it; any monitor that can make an HTTP call can
do the same.
**Coming back clean.** Since the relay keeps nothing (CG-10), recovery is a
rebuild from the signed image and a new join. Whatever runs the relay does
the rebuild: Kubernetes, a systemd unit with a fresh image, a VPS restored
from a snapshot. The scoped key can also ask for a join token, so an
orchestrator can rebuild and rejoin with no one at a keyboard. A relay can
also be rebuilt on a schedule, so a compromise nobody noticed still has a
shelf life. CA rate limits cap how often the same names can be issued
(Let's Encrypt allows 5 a week for an identical set), so a scheduled
rebuild defaults to weekly where it's turned on.
**Further out.** Several relays already serve one downstream (RL-25). With
the Kubernetes recipe, terminating relays could run as short-lived pods,
replaced every few hours, with clients spread across them. One relay per
user or per client address goes further still: a compromised one holds
only the attacker's own traffic. That's a lot of machinery for most
installs, and it isn't part of this design, but nothing here rules it out:
CG-11 is the same idea inside one box.
## Targets
The downstream decides where each client port goes:
| Relay port | Mode | Default target | Alternative |
|---|---|---|---|
| 443 | Pass-through | The node's own HTTPS listener | The install's front proxy (webmail, console, server behind one name or several), by address |
| 443 | Terminating | The node's own HTTP service, in process | inbuxa-webmail, once it accepts relay-bound sessions |
| 993 | Pass-through | The node's IMAPS listener | — |
| 465 | Pass-through | The node's submissions listener | — |
| 995 | Pass-through | The node's POP3S listener, only with legacy protocols on | — |
For the node's own listeners, the node's addresses are added to the
listener's PROXY trusted networks automatically. For a front proxy, the
administrator confirms in inbuxa-admin that it takes PROXY v2 from the
nodes. Without that confirmation 443 doesn't turn on (CG-4). A front proxy
can't be the target of a terminating port, since the server must see the
relay's id and generation to apply CG-8.
## The names on 443
The relay forwards only the names it's given, for example `mail.example.com`
and `webmail.example.com`. The console's name is left off the list unless an
administrator adds it, so the console isn't put on the internet just because
webmail is. In terminating mode the console can't be added at all.
A client can ask for one name in the TLS handshake and another in the HTTP
`Host` header. In terminating mode the worker refuses a mismatch itself.
In pass-through, if the target serves the console and webmail on the same
TLS listener, it must refuse a `Host` that doesn't match the TLS name
(answer 421), or a client could reach the console through an allowed name.
The server's own HTTPS listener would gain that check for relayed
connections, as part of this work. For a front proxy it's on the checklist
inbuxa-admin shows before 443 turns on.
## Certificates and CAA
The client names point at the relay's address, so whoever controls the relay
can answer an HTTP or TLS-ALPN challenge for them and get a valid
certificate from a public CA. With that, a compromised pass-through relay
could end TLS after all and read everything (CG-1 broken from outside), and
a compromised terminating relay could keep a certificate past its
quarantine.
The server already publishes, for domains whose certificates it manages, a
CAA record naming its CA and its ACME account (`accounturi`, RFC 8657). A CA
that honours it issues only to that account, so the relay can't get one.
Client access in either mode therefore needs:
- the domain's certificates and DNS both managed by the server, as the
relay's own certificate already needs (RL-27);
- the CAA record in place before 443 turns on. The downstream checks it
in public DNS and refuses to turn 443 on while it's missing;
- the certificates for the client names issued by DNS challenge, since an
HTTP challenge would have to go through the relay. The CAA record then
adds `validationmethods=dns-01` for those names.
In terminating mode the relay's certificate comes from that same account,
on the relay's own key (CG-9). A taken relay holds its current certificate
until it expires or is revoked at quarantine, and can't get another.
A domain whose DNS isn't managed by the server can still use pass-through on
993 and 465, with a warning in inbuxa-admin that an unrestricted CAA leaves
the names open to a certificate from whoever runs the relay's address.
## DNS
The client names need A and AAAA records at the relay's address. For domains
whose DNS the server manages, the downstream publishes them when client
access turns on, and puts them back when it turns off, the way it publishes
MX and SPF for relays (RL-25). It also publishes SRV records for IMAP and
submission (RFC 6186) at the relay's name, so mail apps that look for them
find it.
**Clients on the protected network.** Once the names point at the relay,
clients inside the network also go out to the relay and back, unless local
DNS answers with the server's own address. inbuxa-admin says so when client
access turns on, with the records to add locally. With a terminating 443
this matters more: a token issued inside the network is refused through the
relay (CG-8), so a laptop that moves between the two signs in again.
## What the relay learns from the downstream
Pushed over the link with the other settings:
- `clientAccess`: per port, on or off, the mode, and the target id; the
list of names for 443;
- `clientLimits`: connections per address per minute (60), open connections
per address (50), open client connections in all (2000), and in
terminating mode the request limits (header section 16 KB, body 10 MB
outside uploads, JSON depth);
- `blockedAddresses`: the downstream's blocked list (`BlockedIps`),
changes pushed as they happen. An address the server blocks after failed
sign-ins through the relay is then dropped at the relay, before it reaches
the network;
- in terminating mode, the relay's generation and its certificate.
The relay reports, as `RelayEvent`s: a connection refused for a blocked
address or a limit (counted, not each one), a stream pool that ran dry, and
in terminating mode requests refused by a worker (counted by reason) and
workers that crashed. A run of crashing workers is worth an alert of its
own; it's what probing for a parser bug looks like.
## Footprint
**Pass-through.** No new dependency. In the relay: reading a ClientHello's
`server_name` (a small parser, without rustls), the stream pool, the copy
loop (`tokio::io::copy_bidirectional`), the client listeners, and the limits
and blocked list. In the server: the stream dialer and forwarder in the link
service, the PROXY v2 writer, settings on `inbuxa:Relay`, and a Client
access section on the console's Relays page. Rough size: 1,000 to 1,500
lines in all. RL-3's budgets for binary size and idle memory are unchanged.
Memory per open client connection is two socket buffers, so the 50-session
budget gains a client-connection one: 500 open client connections within
64 MB more.
**Terminating.** An HTTP server, which RL-3 rules out for the relay. So
it's a build feature, `client-gateway`, shipped as its own image and
binaries (`inbuxa-relay-gateway`) from the same tag (RL-31), and the
default relay keeps RL-3's budgets. It adds hyper's HTTP/2 server, the
request rebuilder, the worker sandbox (seccomp and a process per
connection), and certificate requests over the link. In the server: the
canonical-form check, relay-bound tokens, quarantine, and the scoped
permission. Rough size: another 3,000 to 4,000 lines. A worker per
connection costs a process each; at 500 connections that's measured before
it's promised.
## Bandwidth
Every byte a client reads crosses the protected network's uplink and then
the relay's. A mailbox opened from outside costs the downstream's upload
bandwidth, which on a home connection is often a tenth of the download.
inbuxa-admin shows client traffic per relay, so it's visible before it's a
surprise.
## Security considerations
- **A compromised pass-through relay** gets, in addition to what relay.md
lists: client addresses, the names they ask for, and the timing and size
of their traffic. It doesn't get passwords, tokens, or content (CG-1), and
can't get a certificate for the names while the CAA record holds.
- **A compromised terminating relay** gets, while it's held, the content of
every request and response through it, and the relay-bound tokens of
everyone signed in through it. It doesn't get passwords (CG-7), tokens
that work anywhere else (CG-8), anything from before its last rebuild
(CG-10), or a way to keep its access past quarantine. Breaking one worker
gives only that connection (CG-11). This is the price of the mode, and
inbuxa-admin says so when it's turned on.
- **Either kind** can drop or delay connections, and write a false client
address, which could get an innocent address blocked or let one address
get round per-address limits. A relay that can do that can already stop
client access outright, so this adds no new reach.
- **No path in.** Still none. Streams are dialed out by the nodes, and they
reach only the targets the downstream names (CG-3).
- **Exposure.** In pass-through the targets' parsers face the internet as
they would with the ports open; turning it on is the same decision as
opening those ports, and inbuxa-admin says so. In terminating mode the
server's HTTP parser faces only the relay's rebuilt requests.
- **Port 25 and 465.** Port 25 is unchanged. 465 at the relay is the
downstream's own submission listener: sign-in happens there, end to end.
The relay still offers no AUTH of its own (RL-4).
- **The console.** It isn't forwarded unless its name is added (see "The
names on 443"), and never in terminating mode.
- **Sign-in limits.** They work per client address, through CG-4. A target
that ignores the PROXY header would rate-limit the node itself. The
automatic trusted-network setting covers the server's own listeners.
- **The quarantine key.** Whoever holds it can take client access down, but
can't read or change anything else. That's the right trade for a key that
sits on a monitoring system.
## A first step without code
Pass-through can be done by hand today, with a small VPS, WireGuard
(relay.md RL-32) and any TCP proxy that sends the PROXY protocol and routes
by TLS name. A docs page with that recipe would answer the forum question
now, show whether people use it, and give the built version a test to
match. Recommended before any code.
Terminating mode has no by-hand equivalent with the same guarantees. A
reverse proxy on a VPS ends TLS, but sessions aren't bound to it and there
is nothing to cut it off with, so it's the worst case of both modes. The
docs page shouldn't suggest it.
## Acceptance tests (if built)
Pass-through:
- **CG-T1.** A client on 993 signs in to IMAP through the relay. The
server sees the client's address, not the node's, and the bytes the relay
forwards after the ClientHello are the client's TLS records, unchanged.
- **CG-T2.** On 443, a ClientHello for a name not on the list is closed
without a reply. One for an allowed name reaches the target and completes
TLS with the downstream's certificate.
- **CG-T3.** An address the server blocks after failed sign-ins is refused
at the relay within one push.
- **CG-T4.** A connection asking for the webmail name with `Host:` set to
the console's name gets 421 from the server's HTTPS listener.
- **CG-T5.** 443 refuses to turn on, in either mode, while the domain has no
CAA record with `accounturi`.
- **CG-T6.** With the stream pool empty and no node linked, a client is
closed after 5 s. With a node linked, it's served within the link's
round trip.
- **CG-T7.** An IMAP IDLE connection through the relay stays open for 2
hours.
- **CG-T8.** The relay is asked for a target id the node doesn't have. The
node closes the stream, and connects nowhere.
- **CG-T9.** Ports 143, 110 and 587 can't be turned on for client access
(refused by the server and by the relay).
Terminating:
- **CG-T10.** Requests with both `Content-Length` and `Transfer-Encoding`,
with two `Content-Length`s, with a bare LF, and with broken JSON are each
refused at the relay, and the server's HTTP service receives nothing.
- **CG-T11.** A JMAP session through the relay works end to end, and every
request the server receives is byte-identical to rebuilding it again.
- **CG-T12.** A stream from the relay carrying a request that isn't in
canonical form quarantines the relay.
- **CG-T13.** Password sign-in through a terminating port is refused in
every form. Passkey sign-in works and returns a token bound to the relay.
- **CG-T14.** A token bound to relay R generation G is refused through
relay R2, through R after a new generation, and on the server directly. A
token issued inside the network is refused through R.
- **CG-T15.** A quarantine through the scoped API key drops the link and
every stream within 5 s, refuses the old tokens, requests revocation of
the certificate, and the relay can't link again until it rejoins.
- **CG-T16.** The relay's state directory and logs never hold the
certificate key, a token, or request content, after a session that used
all three.
- **CG-T17.** A worker that crashes mid-request takes down only its own
connection, and is reported in a `RelayEvent`.
## Questions
Answered by John on 2026-11-21: all as recommended below. That settles the
shape of the proposal; it doesn't schedule the work, which stays a
suggestion open for discussion on the forum (t/340).
1. **Both modes, chosen per port, pass-through by default?** Recommended:
yes, pass-through built first, terminating second.
2. **Which ports in each mode?** Recommended: pass-through on 443, 993 and
465, 995 only with legacy protocols on, never the STARTTLS ports
(CG-2); terminating on 443 only to start.
3. **IMAP and submission in terminating mode later?** Only with app
passwords bound to the relay, since CG-7 rules out real passwords.
Recommended: decide after terminating 443 has been used for a while.
4. **Passkeys only for sign-in through a terminating port (CG-7)?**
Recommended: yes. Allowing passwords there would hand a compromised
relay credentials that work everywhere.
5. **Terminating mode as its own build and image, so the default relay
keeps RL-3?** Recommended: yes.
6. **A quarantine permission for outside monitors, with Cairn OBS as the
first integration?** Recommended: yes, and kept generic so any monitor
can call it.
7. **Scheduled rebuilds.** Recommended: off by default, weekly when on,
because of CA rate limits.
8. **A worker per connection (CG-11)?** Recommended: yes as the design,
with the cost measured before it's promised.
9. **Sharing 443 with the link.** Both default to 443. Recommended: one
listener, split by TLS name, the link on a name of its own, when they
share an address. When the link runs over WireGuard (RL-32) they're
apart anyway.
10. **The CAA check as a hard stop for 443 (CG-T5)?** Recommended: yes, in
both modes.
11. **Managing the client names' A and AAAA records.** Recommended: yes for
domains whose DNS the server manages, with the inside-network note.
12. **The docs recipe first?** Recommended: yes, for pass-through only, and
decide on building after seeing who uses it.
13. **Milestone.** Recommended: stays in 27.7, unscheduled until 12
has an answer.