From 1838e385af9d1cddfc394667d69dbc7e9efe87b1 Mon Sep 17 00:00:00 2001
From: KodeStar <kode@audiosilo.app>
Date: Wed, 14 Oct 2026 09:56:41 +0100
Subject: [PATCH 1/5] Plain HTTP at home: how the phone apps reach a
 self-signed server

The apps can't trust the default self-signed certificate, so the server now
answers plain HTTP on its port to home-network devices (tls.home_http).
Remote access explains it (and the Docker gateway trade-off) and no longer
suggests the apps get around the self-signed limit; troubleshooting gains
"The app can't connect, but the browser can"; the connect, mobile apps,
Chromecast, Docker quickstart and admin server pages, the configuration
reference (key, env, setting, Home HTTP section), security notes and the
API reference's home address rule follow.
---
 docs-developers/server/api/reference.md       | 16 ++++++-
 docs-developers/server/auth-and-security.md   |  7 +++
 docs-developers/server/configuration.md       | 45 ++++++++++++++++++-
 docs-developers/server/overview.md            |  4 +-
 docs-users/admin/server.md                    | 13 +++++-
 .../getting-started/quickstart-docker.md      |  2 +-
 docs-users/getting-started/remote-access.md   | 25 ++++++++---
 docs-users/listening/chromecast.md            |  4 +-
 docs-users/listening/connecting.md            |  2 +-
 docs-users/listening/mobile-apps.md           |  2 +
 docs-users/troubleshooting.md                 | 36 +++++++++++++--
 11 files changed, 137 insertions(+), 19 deletions(-)

diff --git a/docs-developers/server/api/reference.md b/docs-developers/server/api/reference.md
index 6dc0bce..c5e3216 100644
--- a/docs-developers/server/api/reference.md
+++ b/docs-developers/server/api/reference.md
@@ -224,7 +224,7 @@ answers, and [`GET /addresses`](#get-apiv1addresses) carry the same object:
 
 | Field | Type | Meaning |
 |---|---|---|
-| `home` | string, optional | The server's address on the household network: the configured [`lan_url`](../configuration.md#home-address-lan_url), else the address **this request** arrived on (scheme + `Host`) when that is a home-network host and the request did not come through a proxy ([the rule](../configuration.md#home-address-lan_url)) |
+| `home` | string, optional | The server's address on the household network: the configured [`lan_url`](../configuration.md#home-address-lan_url), else the address **this request** arrived on (scheme + `Host`) when that is a home-network host and the request did not come through a proxy ([the rule](../configuration.md#home-address-lan_url)). On a self-signed server with [home HTTP](../configuration.md#home-http-tlshome_http) the derived one is always `http://`, on the request's port |
 | `away` | string, optional | The address that works from anywhere: the configured `public_url` |
 
 A `home` equal to the `away` is dropped. On the pairing payloads and the sign-in answers
@@ -242,6 +242,17 @@ https://books.example.com/web/connect?token=…&away=https%3A%2F%2Fbooks.example
 
 Read them by name: the encoder sorts them (`away` before `home`).
 
+On a self-signed server with [home HTTP](../configuration.md#home-http-tlshome_http) (the
+default), the port also answers plain HTTP to home-network clients, and a derived `home`
+is `http://` even when the request came over https: a device pairing at
+`https://192.168.1.20:8080` gets `home` `http://192.168.1.20:8080` (an https request
+without a port gets `http://<host>:443`, the port that answers). `base_url`, `web_url`
+and the `uri`'s `server=` keep the request's own scheme, so a link reads
+`…server=https%3A%2F%2F192.168.1.20%3A8080&token=…&home=http%3A%2F%2F192.168.1.20%3A8080`.
+A native app that can't trust the certificate at `server` exchanges the token at that
+`home` instead, when it has the same host and port; the player's rule is in
+[Connect and home/away addresses](../../frontend/connect-and-addresses.md).
+
 A client must not send a token to a `home` address until a tokenless
 `GET <home>/api/v1/server` there has answered with the same `server_id`: a private
 address can belong to a different machine on another network. The player's rule is in
@@ -6073,6 +6084,7 @@ and `AUDIOSILO_*` variable each one is, and whether it needs a restart (see
   "network": {
     "bind": "0.0.0.0:8080",
     "tls_mode": "selfsigned",
+    "tls_home_http": true,
     "tls_hosts": [],
     "trusted_proxies": ["10.0.0.2/32"],
     "cors_origins": []
@@ -6112,7 +6124,7 @@ and `AUDIOSILO_*` variable each one is, and whether it needs a restart (see
   },
   "locked": { "players.web_dir": "AUDIOSILO_WEB_DIR" },
   "restart_settings": [
-    "network.bind", "network.tls_mode", "network.tls_hosts", "players.web_dir",
+    "network.bind", "network.tls_mode", "network.tls_home_http", "network.tls_hosts", "players.web_dir",
     "metadata.base_url", "metadata.mode", "demo.enabled", "demo.idle_ttl", "backups.dir"
   ],
   "restart_pending": []
diff --git a/docs-developers/server/auth-and-security.md b/docs-developers/server/auth-and-security.md
index fc146a5..3ac295c 100644
--- a/docs-developers/server/auth-and-security.md
+++ b/docs-developers/server/auth-and-security.md
@@ -690,6 +690,13 @@ book's audio and cover as no-cors `<audio>`/`<img>` requests, which `same-site`
 would make the browser block. It reaches one book's media only. **HSTS is set only in `autocert` TLS mode**:
 pinning it with a self-signed cert would make the certificate warning
 impossible to bypass, and behind a reverse proxy (`off`) the proxy owns HSTS.
+That also keeps [home HTTP](configuration.md#home-http-tlshome_http) working: on a
+self-signed server the port answers plain HTTP to clients whose **connection** comes
+from a private, link-local or loopback address (never judged by `X-Forwarded-For`), and
+redirects every other plain HTTP client to https. Sign-ins on the home network then
+travel unencrypted, the documented trade-off for apps that can't trust a self-signed
+certificate; Docker setups that relay every connection from a private gateway address
+make every client count as home (see the caution there).
 
 CORS (`cors` middleware) is a strict allow-list from `cors_origins`; with no
 configured origins, cross-origin browser requests simply get no CORS headers
diff --git a/docs-developers/server/configuration.md b/docs-developers/server/configuration.md
index 9c445ab..78b722e 100644
--- a/docs-developers/server/configuration.md
+++ b/docs-developers/server/configuration.md
@@ -92,7 +92,11 @@ and where it appears: [Home and away addresses](api/reference.md#home-and-away-a
   single-label name. A bare IPv6 host is written in brackets in the address. Never loopback (`127.0.0.0/8`, `::1`, `localhost`): no other device can reach it.
   Never carrier-grade NAT space (`100.64.0.0/10`, which Go's `IsPrivate` leaves out): it
   is the ISP's network, not the household's. The scheme follows the same rule as the
-  pairing `base_url` (`https` on a TLS connection, else `http`), and `X-Forwarded-*` is
+  pairing `base_url` (`https` on a TLS connection, else `http`), except on a server that
+  serves [home HTTP](#home-http-tlshome_http) (`config.ServesHomeHTTP`): there a derived
+  home is always `http://`, even for a request that came over https, and keeps the
+  request's port (`:443` is added when the `Host` has none, since that port is the one
+  answering http, never 80). A configured `lan_url` is used as it is. `X-Forwarded-*` is
   not trusted. A request that came through a reverse proxy (it carries `Forwarded` or
   any `X-Forwarded-*` header) never derives a home address: its `Host` is the proxy's
   upstream, not an address a device can use.
@@ -112,6 +116,7 @@ plain `http` behind TLS). Set `lan_url` to give the apps a home address; a confi
 | `tls.mode` | `off` \| `selfsigned` \| `autocert`, default `selfsigned` | `off` = plain HTTP (use behind a TLS-terminating proxy); `selfsigned` = generate & persist a self-signed cert (LAN default); `autocert` = Let's Encrypt via ACME |
 | `tls.hosts` | []string, `[]` | autocert: hostnames to obtain certificates for. **Required when mode is `autocert`** |
 | `tls.cache_dir` | string, `<data>/certs` | autocert: certificate cache directory (re-defaulted to `<data>/certs` whenever empty) |
+| `tls.home_http` | bool, `true` | selfsigned only: the bind port also answers plain HTTP to home-network clients, see [Home HTTP](#home-http-tlshome_http). Ignored in the other modes |
 | `tls.cert_file` / `tls.key_file` | string, `""` | selfsigned: explicit paths for the persisted cert/key. Empty → `<data>/selfsigned-cert.pem` / `<data>/selfsigned-key.pem` |
 
 Mode-related behaviors worth knowing: HSTS
@@ -121,6 +126,42 @@ bypass), and with `off` the proxy owns HSTS. In `autocert` mode the server
 logs a warning when `bind` is not on port 443, since ACME validation will
 fail otherwise.
 
+#### Home HTTP (`tls.home_http`)
+
+The native apps can't trust a self-signed certificate (there is no "proceed anyway" in
+an app), so in `selfsigned` mode with `tls.home_http` on (the default;
+`AUDIOSILO_TLS_HOME_HTTP`, console `network.tls_home_http`, restart) the bind port
+serves both protocols. `internal/server`:
+
+- `splitListener` accepts each connection and, in its own goroutine (a silent client
+  never blocks the accept loop), reads the first byte under the 10 s header timeout:
+  `0x16` (a TLS handshake record) makes it a `*tls.Conn`, anything else stays plain. A
+  connection that sends nothing in time is closed, and so is one still being read when
+  the server shuts down. One `http.Server` serves both kinds with the usual timeouts
+  (ALPN offers `h2` and `http/1.1`, as `ServeTLS` would).
+- `homeHTTPGate` serves a plain HTTP request only when the **connection's own** remote
+  address (`r.RemoteAddr`; never `X-Forwarded-For`, which the client writes) is
+  `config.HomeNetworkIP` (private RFC 1918 / IPv6 ULA, link-local; not CGNAT
+  `100.64.0.0/10`) or loopback. Any other plain request gets a `308` to the same URL on
+  https (same Host and port), or a `400` when its Host can't make that URL. TLS requests
+  pass untouched.
+
+The server logs at start that plain HTTP is served to home-network clients. The derived
+home address becomes `http://` (see [Home address](#home-address-lan_url)), so a device
+paired over the https QR still learns an address it can use. No HSTS is sent on
+self-signed, and no CSP carries `upgrade-insecure-requests`, so the console and the web
+player also work over http on the LAN (without the secure-context features: the service
+worker, the clipboard API).
+
+:::caution Docker and the source address
+The gate trusts the TCP source address. Docker Desktop (Mac/Windows), rootless Docker and
+Docker's userland proxy (e.g. for IPv6 connections to a published port) relay
+connections from the container network's gateway, such as `172.17.0.1`, a private
+address: every client then counts as home, including internet clients if the port is
+forwarded. Such a setup that is reachable from the internet should turn `home_http` off
+or use autocert / a reverse proxy.
+:::
+
 ### Web player & app links
 
 | Key | Type / default | Meaning |
@@ -414,6 +455,7 @@ by the settings table in `internal/config/settings.go` (`fields`: each entry's
 | `AUDIOSILO_WEB_DIR` | `web_dir` | path |
 | `AUDIOSILO_TLS_MODE` | `tls.mode` | `off` / `selfsigned` / `autocert` |
 | `AUDIOSILO_TLS_HOSTS` | `tls.hosts` | comma-separated list |
+| `AUDIOSILO_TLS_HOME_HTTP` | `tls.home_http` | `strconv.ParseBool` (`false`/`0`/… turns it off) |
 | `AUDIOSILO_TRUSTED_PROXIES` | `trusted_proxies` | comma-separated CIDRs |
 | `AUDIOSILO_CORS_ORIGINS` | `cors_origins` | comma-separated origins |
 | `AUDIOSILO_MAX_UPLOAD_BYTES` | `max_upload_bytes` | integer |
@@ -467,6 +509,7 @@ restart, and whether the console may change it at all:
 | `general.session_days` | `activity.session_days` | `AUDIOSILO_SESSION_DAYS` | at the next daily retention run |
 | `network.bind` | `bind` | `AUDIOSILO_BIND` | restart |
 | `network.tls_mode` | `tls.mode` | `AUDIOSILO_TLS_MODE` | restart |
+| `network.tls_home_http` | `tls.home_http` | `AUDIOSILO_TLS_HOME_HTTP` | restart |
 | `network.tls_hosts` | `tls.hosts` | `AUDIOSILO_TLS_HOSTS` | restart |
 | `network.trusted_proxies` | `trusted_proxies` | `AUDIOSILO_TRUSTED_PROXIES` | at once |
 | `network.cors_origins` | `cors_origins` | `AUDIOSILO_CORS_ORIGINS` | at once |
diff --git a/docs-developers/server/overview.md b/docs-developers/server/overview.md
index bc065c6..6462d54 100644
--- a/docs-developers/server/overview.md
+++ b/docs-developers/server/overview.md
@@ -236,7 +236,9 @@ HTTP transport **only**: routing (`api.go` is the full route table), middleware
 ### `internal/server`
 
 The HTTP(S) server itself: TLS modes (`off` for reverse proxies, `selfsigned`,
-`autocert`/Let's Encrypt) and graceful shutdown. `Certificates` reads the
+`autocert`/Let's Encrypt), home HTTP on the self-signed port (`splitListener` +
+`homeHTTPGate`, see [Home HTTP](configuration.md#home-http-tlshome_http)) and
+graceful shutdown. `Certificates` reads the
 served certificates back from their files for Health > System.
 
 ### `internal/updates`
diff --git a/docs-users/admin/server.md b/docs-users/admin/server.md
index 47f97c6..25d1b99 100644
--- a/docs-users/admin/server.md
+++ b/docs-users/admin/server.md
@@ -128,6 +128,15 @@ apps (the same three choices as [Remote access](../getting-started/remote-access
   ports 80 and 443 open to the internet, and shows **Certificate names**: one
   name per line, like `books.example.com`, each pointing at this server.
 
+With **Self-signed** chosen, the card also shows **Plain HTTP at home**, on out
+of the box. The phone apps can't trust a self-signed certificate, so while it is
+on the server's port also answers plain HTTP to devices on your home network
+(anything else is sent to HTTPS), and that is how the apps connect at home.
+Turn it off and the apps can't connect to a self-signed server. See
+[Plain HTTP at home](../getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect),
+including what it means for Docker setups. `tls.home_http` in `config.yaml` or
+`AUDIOSILO_TLS_HOME_HTTP` sets it too, and then locks it here.
+
 The **Certificate** row says how the certificate the server serves now looks:
 "Valid" with the days left, "Expires in *N* days" (under two weeks), "Expired",
 "Not issued yet" (Let's Encrypt hasn't issued one yet), or "None (plain HTTP)".
@@ -146,8 +155,8 @@ The **Network** card:
   browser, one per line (like `http://localhost:8081`). Usually empty; see
   [Settings you can leave alone](../getting-started/remote-access.md#settings-you-can-leave-alone).
 
-The HTTPS mode, the certificate names and the listen address wait for a
-restart; trusted proxies and allowed origins apply at once.
+The HTTPS mode, plain HTTP at home, the certificate names and the listen
+address wait for a restart; trusted proxies and allowed origins apply at once.
 
 ### Players & app links
 
diff --git a/docs-users/getting-started/quickstart-docker.md b/docs-users/getting-started/quickstart-docker.md
index 2edb608..c923f43 100644
--- a/docs-users/getting-started/quickstart-docker.md
+++ b/docs-users/getting-started/quickstart-docker.md
@@ -80,7 +80,7 @@ By default the server speaks HTTPS with a self-signed certificate, so browse to:
 https://your-server:8080
 ```
 
-Your browser will warn about the certificate the first time - that's expected with the default setup; accept it to continue. [Remote access](./remote-access.md) covers getting a proper certificate or running behind a reverse proxy.
+Your browser will warn about the certificate the first time - that's expected with the default setup; accept it to continue. The phone apps can't accept that warning, so at home they connect over plain HTTP instead, which the server offers to devices on your home network ([plain HTTP at home](./remote-access.md#plain-http-at-home-how-the-phone-apps-connect), including a note on Docker Desktop). [Remote access](./remote-access.md) covers getting a proper certificate or running behind a reverse proxy.
 
 - **`/`** - the connect page, where a listener enters an auth code to pair a device.
 - **`/admin`** - the admin console. Log in as `admin` with the printed password.
diff --git a/docs-users/getting-started/remote-access.md b/docs-users/getting-started/remote-access.md
index 1e81227..2fdcbbf 100644
--- a/docs-users/getting-started/remote-access.md
+++ b/docs-users/getting-started/remote-access.md
@@ -1,13 +1,13 @@
 ---
 title: Remote access
-description: "Listening away from home: TLS modes (self-signed, Let's Encrypt, reverse proxy), ports and firewalls, and why AudioSilo is safe to expose to the internet."
+description: "Listening away from home: TLS modes (self-signed, Let's Encrypt, reverse proxy), plain HTTP for the phone apps at home, ports and firewalls, and why AudioSilo is safe to expose to the internet."
 ---
 
 ## Remote access
 
 AudioSilo is designed from the ground up to be reachable from outside your house - that's the point of self-hosting audiobooks. This page covers the three ways to serve HTTPS, the networking basics, and what the server does to keep an internet-facing setup safe.
 
-All of these are settings in `config.yaml` in the server's data directory (edit and restart), and most can also be set with an environment variable - handy under Docker. Once the server runs, you can also change them in the admin console under [Server > Settings](../admin/server.md#settings): the HTTPS mode, certificate names and listen address on **Network & HTTPS** (they take effect at the next restart), the public address on **General** (at once). An environment variable wins over both, so a setting one sets shows as locked in the console.
+All of these are settings in `config.yaml` in the server's data directory (edit and restart), and most can also be set with an environment variable - handy under Docker. Once the server runs, you can also change them in the admin console under [Server > Settings](../admin/server.md#settings): the HTTPS mode, plain HTTP at home, certificate names and listen address on **Network & HTTPS** (they take effect at the next restart), the public address on **General** (at once). An environment variable wins over both, so a setting one sets shows as locked in the console.
 
 ### The default: self-signed HTTPS
 
@@ -21,11 +21,26 @@ tls:
 Because no public authority issued that certificate, every browser shows a "connection is not private" warning the first time - that's expected, not a sign something is broken. Accept the warning and the connection is encrypted normally. This mode is fine on a home network.
 
 :::note
-One practical limit of a self-signed certificate: "install to home screen" for the web player needs a connection the browser fully trusts (or `localhost`). Streaming in a browser tab works fine; for the installable app experience away from `localhost`, use one of the two options below - or the native [mobile apps](../listening/mobile-apps.md).
+One practical limit of a self-signed certificate: "install to home screen" for the web player needs a connection the browser fully trusts (or `localhost`). Streaming in a browser tab works fine; for the installable app experience away from `localhost`, use one of the two options below. The native [mobile apps](../listening/mobile-apps.md) can't use a self-signed certificate either: at home they connect over plain HTTP instead, as the next section explains.
+:::
+
+#### Plain HTTP at home (how the phone apps connect)
+
+A browser lets you click through the certificate warning; the iPhone and Android apps can't, so they can't connect over a self-signed certificate at all. That's why, in this mode, the server's port also answers **plain HTTP**, but only to devices on your home network: a connection from a private address (like `192.168.1.30` or `10.0.0.12`), a link-local one, or the server's own machine. Any other device that tries plain HTTP is sent to HTTPS.
+
+You don't have to set anything up on the server. Connect the app while your phone is on the same Wi-Fi as the server: scan the pairing QR code or open an invite link, and the app signs in over `http://` on the same address and port, remembering it as the server's [home address](#tell-the-server-its-home-address). To type the address instead, put `http://` in front of it, like `http://192.168.1.20:8080` (without it, the app tries `https://`, which it can't trust here).
+
+**Away from home** the apps still need a certificate they trust: use [autocert](#a-real-certificate-with-autocert-lets-encrypt) or a [reverse proxy](#behind-a-reverse-proxy), and set the [public address](#tell-the-server-its-public-address). The apps then switch between the two by themselves.
+
+To turn plain HTTP off, set `tls.home_http: false` (`AUDIOSILO_TLS_HOME_HTTP=false`, or switch off **Plain HTTP at home** under the console's Server > Settings > Network & HTTPS; it takes effect at the next restart). The phone apps then can't connect to a self-signed server.
+
+:::caution What plain HTTP at home means
+- Plain HTTP isn't encrypted: anyone on your home network who can watch its traffic could see sign-ins and what you listen to. That is the usual trade-off on a trusted home Wi-Fi; on a shared or untrusted network, turn it off and use a trusted certificate instead.
+- The server decides who is "at home" from the address each connection comes from. Some setups hand the server every connection from a private address, whoever made it: Docker Desktop (Mac and Windows), rootless Docker, and Docker's userland proxy (used, for example, for IPv6 connections to a published port) relay connections from the container network's gateway, such as `172.17.0.1`. The server then serves plain HTTP to everyone, including internet visitors if you forward the port. If your server runs like that and is reachable from the internet, turn plain HTTP at home off, or use autocert or a reverse proxy.
 :::
 
 :::note Casting needs a certificate the Cast device trusts
-To [cast](../listening/chromecast.md), your server's address must work for the Cast device, which can't click through a certificate warning. The default self-signed certificate won't work. Use HTTPS with a trusted certificate (one of the two options below), or, from the iPhone and Android apps, plain HTTP on your home network set as the [home address](#tell-the-server-its-home-address): behind a [reverse proxy](#behind-a-reverse-proxy), that's AudioSilo's own port (for example `http://192.168.1.20:8080`), not the proxy's. The web player casts only from an HTTPS page, so it needs the trusted certificate.
+To [cast](../listening/chromecast.md), your server's address must work for the Cast device, which can't click through a certificate warning. The default self-signed certificate won't work. Use HTTPS with a trusted certificate (one of the two options below), or, from the iPhone and Android apps, plain HTTP on your home network as the [home address](#tell-the-server-its-home-address) (the default self-signed setup offers it [by itself](#plain-http-at-home-how-the-phone-apps-connect)): behind a [reverse proxy](#behind-a-reverse-proxy), that's AudioSilo's own port (for example `http://192.168.1.20:8080`), not the proxy's. The web player casts only from an HTTPS page, so it needs the trusted certificate.
 :::
 
 ### A real certificate with autocert (Let's Encrypt)
@@ -87,7 +102,7 @@ lan_url: "http://192.168.1.20:8080"
 
 The apps learn it with the public address when they connect (and from the server each time they start), use it whenever they can reach it, and switch to the public address when you leave home - see [At home and away](../listening/connecting.md#at-home-and-away). It applies the moment you save it.
 
-You can often leave it empty. The server then offers the address a device connected with when that address is a home-network one: a private IP address such as `192.168.1.20` or `10.0.0.5`, or a local name such as `nas.local`, `nas.internal` or `audiosilo`. An IPv6 address is written in square brackets. A device that connected through the public address learns no home address that way, so set it when you want every device to switch.
+You can often leave it empty. The server then offers the address a device connected with when that address is a home-network one: a private IP address such as `192.168.1.20` or `10.0.0.5`, or a local name such as `nas.local`, `nas.internal` or `audiosilo`. An IPv6 address is written in square brackets. With the default self-signed certificate and [plain HTTP at home](#plain-http-at-home-how-the-phone-apps-connect) on, that address is offered as `http://`, even to a device that connected over `https://`, on the same port. A home address you set is offered exactly as you wrote it. A device that connected through the public address learns no home address that way, so set it when you want every device to switch.
 
 :::note Behind a reverse proxy
 A request that reaches AudioSilo through a reverse proxy never gives the server a home address to offer, because the address it sees is the proxy's own internal one. The apps keep using the public address and just never switch to your home network. Set `lan_url` to the server's home address to fix it.
diff --git a/docs-users/listening/chromecast.md b/docs-users/listening/chromecast.md
index 20babfc..554e01c 100644
--- a/docs-users/listening/chromecast.md
+++ b/docs-users/listening/chromecast.md
@@ -26,9 +26,9 @@ On an iPhone, if AudioSilo hasn't asked before, the first tap brings up a reques
 
 - **A Cast device on the same network** as your phone or computer.
 - **A server address the Cast device can reach.** The Cast device fetches the book from your server itself. It uses the address your app is connected through at that moment: in the iPhone and Android apps, your [home address](../getting-started/remote-access.md#tell-the-server-its-home-address) when you're at home; in the web player, the address you opened it at. That address must work for the Cast device too:
-  - **Plain HTTP on your home network** works from the iPhone and Android apps, for example `http://192.168.1.20:8080` (the web player casts only from an HTTPS page, so it needs a trusted certificate). A server [behind a reverse proxy](../getting-started/remote-access.md#behind-a-reverse-proxy) serves plain HTTP on its own port, and its home address can point straight at it.
+  - **Plain HTTP on your home network** works from the iPhone and Android apps, for example `http://192.168.1.20:8080` (the web player casts only from an HTTPS page, so it needs a trusted certificate). A server on the default self-signed certificate offers the apps that plain HTTP address by itself ([plain HTTP at home](../getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect)). A server [behind a reverse proxy](../getting-started/remote-access.md#behind-a-reverse-proxy) serves plain HTTP on its own port, and its home address can point straight at it.
   - **HTTPS with a trusted certificate** works: a [Let's Encrypt certificate](../getting-started/remote-access.md#a-real-certificate-with-autocert-lets-encrypt), or a [reverse proxy](../getting-started/remote-access.md#behind-a-reverse-proxy) with a real certificate.
-  - **A self-signed certificate does not work.** A Cast device can't click through a certificate warning the way you can in a browser, so it won't play from a server on the default self-signed certificate.
+  - **A self-signed certificate does not work.** A Cast device can't click through a certificate warning the way you can in a browser, so it won't play from a server's self-signed `https://` address.
   - **`localhost` doesn't work.** If the app reaches your server at `localhost` (the server runs on the same computer), the Cast device can't. The Cast button explains this instead of casting. Connect to the server by its network address instead.
 
 A downloaded book casts from your server too, since the Cast device can't read the files on your phone. So casting needs the server to be reachable even for a book you've downloaded.
diff --git a/docs-users/listening/connecting.md b/docs-users/listening/connecting.md
index e4255eb..9575cdf 100644
--- a/docs-users/listening/connecting.md
+++ b/docs-users/listening/connecting.md
@@ -51,7 +51,7 @@ When the app (or the web player) isn't connected to anything yet, it opens on th
 
 **In the iOS and Android apps**:
 
-1. Enter the **server address** your admin gave you (e.g. `books.example.com`) and tap **Continue**. Without `https://` or `http://` in front, the app adds `https://`, so type `http://` yourself for a server that only answers plain HTTP. If you don't know the address, ask your admin.
+1. Enter the **server address** your admin gave you (e.g. `books.example.com`) and tap **Continue**. Without `https://` or `http://` in front, the app adds `https://`, so type `http://` yourself for a server that only answers plain HTTP, or for a server on its default self-signed certificate while you're at home (the apps can't trust that certificate, so they use the server's [plain HTTP at home](../getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect)). If you don't know the address, ask your admin.
 2. The app asks the server who it is and says what it found: *"Found Hearthside"*, with the version of AudioSilo it runs, and a note when the address is plain `http://` (*"This server uses an unencrypted connection"*), which is fine at home but not over the internet (see [Remote access](../getting-started/remote-access.md)). Tap **Sign in**.
 3. Choose how to sign in - **Invite code** or **Username and password** - and tap **Sign in**.
 
diff --git a/docs-users/listening/mobile-apps.md b/docs-users/listening/mobile-apps.md
index e20922c..1e443ab 100644
--- a/docs-users/listening/mobile-apps.md
+++ b/docs-users/listening/mobile-apps.md
@@ -29,6 +29,8 @@ Signing the app in is usually a scan, not typing - all the routes are covered in
 - **Tap a link** - an invite link, or an `audiosilo://` link, opens the app and signs it in automatically.
 - **Type it in** - server address plus an invite code or username and password, if you prefer.
 
+A server on its default **self-signed certificate** is one the apps can't trust, so at home they connect to it over plain HTTP, which the server offers to devices on your home network ([plain HTTP at home](../getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect)). A QR code or invite link handles that by itself; when typing the address, put `http://` in front (`http://192.168.1.20:8080`). Away from home, the apps need the server to have a certificate they trust - see [Remote access](../getting-started/remote-access.md).
+
 ## Getting around the app
 
 On a phone, the app uses your phone's own tab bar along the bottom of the screen, with five tabs: **Home**, **Library**, **Search**, **Downloads** and **Me** ([You](you.md): your listening, your year, the Journal, Settings, your household and your account). Each tab keeps its place while you visit the others. See [Getting around](browsing.md#getting-around) for what each one holds.
diff --git a/docs-users/troubleshooting.md b/docs-users/troubleshooting.md
index 7bdcfa7..9836836 100644
--- a/docs-users/troubleshooting.md
+++ b/docs-users/troubleshooting.md
@@ -14,10 +14,11 @@ its own page, the entry links there instead of repeating it.
 Work through these in order:
 
 1. **Are you using `https://`?** Out of the box the server uses a self-signed
-   certificate, which means it speaks **HTTPS** - even on your home network. If
-   you open `http://your-server:8080` against an HTTPS server, the connection
-   simply fails. Try `https://your-server:8080` instead (and see the
-   certificate warning entry below).
+   certificate, which means it speaks **HTTPS**. It also answers plain
+   `http://` on the same port, but only to devices on your home network
+   ([plain HTTP at home](./getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect));
+   from anywhere else, `http://` is sent on to `https://`. If in doubt, try
+   `https://your-server:8080` (and see the certificate warning entry below).
 2. **Is the port right?** The default listen address is `0.0.0.0:8080`. With
    Docker, check that the port is actually published - the example
    `docker-compose.yml` maps `"8080:8080"`. You can change the address and port
@@ -141,6 +142,33 @@ you have no password set, [set one](./listening/account.md#password) so
 you can always get back in on any device without waiting on a fresh invite from
 your admin.
 
+### The app can't connect, but the browser can
+
+The usual cause is the server's default **self-signed certificate**. A browser
+lets you click through its warning; the iPhone and Android apps can't, so they
+can't connect to it over `https://`. On your home network they connect over
+plain HTTP instead, which the server offers there by itself
+([plain HTTP at home](./getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect)).
+Check:
+
+- **Is your phone on the same Wi-Fi as the server?** Plain HTTP is only served
+  to devices on the home network. Away from home, the apps need a certificate
+  they trust: [autocert or a reverse proxy](./getting-started/remote-access.md).
+- **Is the server up to date?** Older servers speak only HTTPS on a
+  self-signed certificate, so the apps can't connect to them at all. Update the
+  server, and the app too.
+- **Is plain HTTP at home switched on?** It's on by default; your admin finds it
+  as **Plain HTTP at home** under
+  [Server > Settings > Network & HTTPS](./admin/server.md#network--https)
+  (`tls.home_http` in `config.yaml`, `AUDIOSILO_TLS_HOME_HTTP`).
+- **Try the address the app should use** in the phone's browser, with
+  `http://` in front: `http://192.168.1.20:8080/web`, say. If the web player
+  loads, the app can connect there too; type that `http://` address into the
+  app.
+- **Is a VPN on in the phone?** The server judges "home" by the address each
+  connection arrives from. Through a VPN the phone's connection can arrive from
+  outside your home network, so the server sends it to HTTPS.
+
 ### The app doesn't use the home address at home
 
 The iOS and Android apps use a server's home address only when the server has

From 7f970a6b93fd7ab23cbf1ca72fd048357e3b2aba Mon Sep 17 00:00:00 2001
From: KodeStar <kode@audiosilo.app>
Date: Wed, 14 Oct 2026 10:13:58 +0100
Subject: [PATCH 2/5] API reference: pairing links and payload carry the
 server's id (sid=, server_id)

The app's fallback to the link's http home address checks GET /server's server_id there against the link's sid before sending the pairing token in cleartext.
---
 docs-developers/server/api/reference.md | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs-developers/server/api/reference.md b/docs-developers/server/api/reference.md
index c5e3216..db3012e 100644
--- a/docs-developers/server/api/reference.md
+++ b/docs-developers/server/api/reference.md
@@ -181,10 +181,11 @@ Response `200` - the pairing payload (`PairingPayload` in `internal/api/qr.go`):
 ```json
 {
   "server_name": "AudioSilo",
+  "server_id": "kx8Qz1c7m2Vw0aB3dEfGh",
   "base_url": "https://books.example.com",
   "pairing_token": "3vJx0eKQm9WZbT5nR8sHc2fLdA7yUqPgVi4oXk1NwsE",
-  "uri": "audiosilo://connect?server=https%3A%2F%2Fbooks.example.com&token=3vJx0eKQ…",
-  "web_url": "https://books.example.com/web/connect?token=3vJx0eKQ…",
+  "uri": "audiosilo://connect?server=https%3A%2F%2Fbooks.example.com&token=3vJx0eKQ…&sid=kx8Qz1c7m2Vw0aB3dEfGh",
+  "web_url": "https://books.example.com/web/connect?token=3vJx0eKQ…&sid=kx8Qz1c7m2Vw0aB3dEfGh",
   "qr_png_data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…",
   "links": {
     "web": "https://books.example.com/web",
@@ -211,7 +212,11 @@ app via Universal/App Links on claimed domains, else the embedded web player);
 `uri` is the custom-scheme equivalent for an explicit "Open in app" action.
 `links.ios`/`links.android` (store links) are omitted until the store apps ship.
 `base_url` honors the configured `public_url`, falling back to the request host.
-`server_name` is the server's display name, as `GET /server`'s `name`.
+`server_name` is the server's display name, as `GET /server`'s `name`, and
+`server_id` its stable id, as `GET /server`'s `server_id`. Both links end with that id as
+`sid=` (after the address params below; absent only on a server without an id, which
+the launcher always mints), so a client can check who answers at an address before
+sending the token there.
 `addresses` is the server's [home and away addresses](#home-and-away-addresses), omitted
 when it has neither; both links then carry them too (below).
 
@@ -236,11 +241,11 @@ The two links carry the same addresses as extra query parameters **after** the e
 ones, only those that are set, so an older client ignores them:
 
 ```text
-audiosilo://connect?server=https%3A%2F%2Fbooks.example.com&token=…&away=https%3A%2F%2Fbooks.example.com&home=http%3A%2F%2F192.168.1.20%3A8080
-https://books.example.com/web/connect?token=…&away=https%3A%2F%2Fbooks.example.com&home=http%3A%2F%2F192.168.1.20%3A8080
+audiosilo://connect?server=https%3A%2F%2Fbooks.example.com&token=…&away=https%3A%2F%2Fbooks.example.com&home=http%3A%2F%2F192.168.1.20%3A8080&sid=kx8Qz1c7m2Vw0aB3dEfGh
+https://books.example.com/web/connect?token=…&away=https%3A%2F%2Fbooks.example.com&home=http%3A%2F%2F192.168.1.20%3A8080&sid=kx8Qz1c7m2Vw0aB3dEfGh
 ```
 
-Read them by name: the encoder sorts them (`away` before `home`).
+Read them by name: the encoder sorts them (`away` before `home`), and `sid` comes last.
 
 On a self-signed server with [home HTTP](../configuration.md#home-http-tlshome_http) (the
 default), the port also answers plain HTTP to home-network clients, and a derived `home`
@@ -248,9 +253,11 @@ is `http://` even when the request came over https: a device pairing at
 `https://192.168.1.20:8080` gets `home` `http://192.168.1.20:8080` (an https request
 without a port gets `http://<host>:443`, the port that answers). `base_url`, `web_url`
 and the `uri`'s `server=` keep the request's own scheme, so a link reads
-`…server=https%3A%2F%2F192.168.1.20%3A8080&token=…&home=http%3A%2F%2F192.168.1.20%3A8080`.
+`…server=https%3A%2F%2F192.168.1.20%3A8080&token=…&home=http%3A%2F%2F192.168.1.20%3A8080&sid=…`.
 A native app that can't trust the certificate at `server` exchanges the token at that
-`home` instead, when it has the same host and port; the player's rule is in
+`home` instead, when it has the same host and port and a tokenless `GET <home>/api/v1/server`
+answers with the link's `sid` (the token then travels in cleartext, so it must reach this
+server and no other box at the same private address); the player's rule is in
 [Connect and home/away addresses](../../frontend/connect-and-addresses.md).
 
 A client must not send a token to a `home` address until a tokenless

From ec0857b88349ea99da0b143a5666d4d72f45d1cf Mon Sep 17 00:00:00 2001
From: KodeStar <kode@audiosilo.app>
Date: Wed, 14 Oct 2026 10:51:38 +0100
Subject: [PATCH 3/5] API reference: pairing links stay https under home HTTP

---
 docs-developers/server/api/reference.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs-developers/server/api/reference.md b/docs-developers/server/api/reference.md
index db3012e..5fd071f 100644
--- a/docs-developers/server/api/reference.md
+++ b/docs-developers/server/api/reference.md
@@ -252,7 +252,8 @@ default), the port also answers plain HTTP to home-network clients, and a derive
 is `http://` even when the request came over https: a device pairing at
 `https://192.168.1.20:8080` gets `home` `http://192.168.1.20:8080` (an https request
 without a port gets `http://<host>:443`, the port that answers). `base_url`, `web_url`
-and the `uri`'s `server=` keep the request's own scheme, so a link reads
+and the `uri`'s `server=` stay https, even for a pairing asked for over plain HTTP
+(the https base on the same port, `:80` for a Host without one), so a link reads
 `…server=https%3A%2F%2F192.168.1.20%3A8080&token=…&home=http%3A%2F%2F192.168.1.20%3A8080&sid=…`.
 A native app that can't trust the certificate at `server` exchanges the token at that
 `home` instead, when it has the same host and port and a tokenless `GET <home>/api/v1/server`

From 72c4dfa6457da26490961601b1d4d6883cbf4502 Mon Sep 17 00:00:00 2001
From: KodeStar <kode@audiosilo.app>
Date: Wed, 14 Oct 2026 11:08:26 +0100
Subject: [PATCH 4/5] Home HTTP: the Host rule, a supplied certificate,
 gateways

---
 docs-developers/server/auth-and-security.md | 10 +++----
 docs-developers/server/configuration.md     | 29 ++++++++++++---------
 docs-users/admin/server.md                  |  3 ++-
 docs-users/getting-started/remote-access.md |  3 ++-
 4 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/docs-developers/server/auth-and-security.md b/docs-developers/server/auth-and-security.md
index 3ac295c..6d4b33b 100644
--- a/docs-developers/server/auth-and-security.md
+++ b/docs-developers/server/auth-and-security.md
@@ -692,11 +692,11 @@ pinning it with a self-signed cert would make the certificate warning
 impossible to bypass, and behind a reverse proxy (`off`) the proxy owns HSTS.
 That also keeps [home HTTP](configuration.md#home-http-tlshome_http) working: on a
 self-signed server the port answers plain HTTP to clients whose **connection** comes
-from a private, link-local or loopback address (never judged by `X-Forwarded-For`), and
-redirects every other plain HTTP client to https. Sign-ins on the home network then
-travel unencrypted, the documented trade-off for apps that can't trust a self-signed
-certificate; Docker setups that relay every connection from a private gateway address
-make every client count as home (see the caution there).
+from loopback, or from a private or link-local address with a home-network Host (never
+judged by `X-Forwarded-For`), and redirects every other plain HTTP client to https.
+Sign-ins on the home network then travel unencrypted, the documented trade-off for apps
+that can't trust a self-signed certificate; the Host check keeps internet clients that a
+NAT or proxy gateway hands over from a private address on https.
 
 CORS (`cors` middleware) is a strict allow-list from `cors_origins`; with no
 configured origins, cross-origin browser requests simply get no CORS headers
diff --git a/docs-developers/server/configuration.md b/docs-developers/server/configuration.md
index 78b722e..1cf29be 100644
--- a/docs-developers/server/configuration.md
+++ b/docs-developers/server/configuration.md
@@ -140,11 +140,16 @@ serves both protocols. `internal/server`:
   the server shuts down. One `http.Server` serves both kinds with the usual timeouts
   (ALPN offers `h2` and `http/1.1`, as `ServeTLS` would).
 - `homeHTTPGate` serves a plain HTTP request only when the **connection's own** remote
-  address (`r.RemoteAddr`; never `X-Forwarded-For`, which the client writes) is
-  `config.HomeNetworkIP` (private RFC 1918 / IPv6 ULA, link-local; not CGNAT
-  `100.64.0.0/10`) or loopback. Any other plain request gets a `308` to the same URL on
-  https (same Host and port), or a `400` when its Host can't make that URL. TLS requests
-  pass untouched.
+  address (`r.RemoteAddr`; never `X-Forwarded-For`, which the client writes) is loopback,
+  or is `config.HomeNetworkIP` (private RFC 1918 / IPv6 ULA, link-local; not CGNAT
+  `100.64.0.0/10`) **and** the request's Host is a home-network host
+  (`config.HomeNetworkHost`: a private IP, a `.local`/`.lan`/`.home.arpa`/`.internal` or
+  single-label name). Any other plain request gets a `308` to the same URL on https (same
+  Host and port, `:80` for a Host without one), or a `400` when its Host can't make that
+  URL. TLS requests pass untouched.
+
+Home HTTP is off, whatever `home_http` says, when `tls.cert_file` is set: a certificate
+the admin supplied may be one the devices trust (a private CA, mkcert), so they keep https.
 
 The server logs at start that plain HTTP is served to home-network clients. The derived
 home address becomes `http://` (see [Home address](#home-address-lan_url)), so a device
@@ -153,13 +158,13 @@ self-signed, and no CSP carries `upgrade-insecure-requests`, so the console and
 player also work over http on the LAN (without the secure-context features: the service
 worker, the clipboard API).
 
-:::caution Docker and the source address
-The gate trusts the TCP source address. Docker Desktop (Mac/Windows), rootless Docker and
-Docker's userland proxy (e.g. for IPv6 connections to a published port) relay
-connections from the container network's gateway, such as `172.17.0.1`, a private
-address: every client then counts as home, including internet clients if the port is
-forwarded. Such a setup that is reachable from the internet should turn `home_http` off
-or use autocert / a reverse proxy.
+:::note Gateways and the source address
+Docker Desktop (Mac/Windows), rootless Docker, Docker's userland proxy (e.g. for IPv6
+connections to a published port) and routers that rewrite a forwarded port's source hand
+the server connections from a private address, such as `172.17.0.1`, whoever made them.
+The Host check is what keeps an internet client on https there: it names the server by
+its public name or address. A client that sends a home-network Host from outside (a
+forged one) only chooses cleartext for itself.
 :::
 
 ### Web player & app links
diff --git a/docs-users/admin/server.md b/docs-users/admin/server.md
index 25d1b99..247ec09 100644
--- a/docs-users/admin/server.md
+++ b/docs-users/admin/server.md
@@ -134,7 +134,8 @@ on the server's port also answers plain HTTP to devices on your home network
 (anything else is sent to HTTPS), and that is how the apps connect at home.
 Turn it off and the apps can't connect to a self-signed server. See
 [Plain HTTP at home](../getting-started/remote-access.md#plain-http-at-home-how-the-phone-apps-connect),
-including what it means for Docker setups. `tls.home_http` in `config.yaml` or
+including what it means for your network. It has no effect when you give the
+server your own certificate (`tls.cert_file`). `tls.home_http` in `config.yaml` or
 `AUDIOSILO_TLS_HOME_HTTP` sets it too, and then locks it here.
 
 The **Certificate** row says how the certificate the server serves now looks:
diff --git a/docs-users/getting-started/remote-access.md b/docs-users/getting-started/remote-access.md
index 2fdcbbf..cb4cdcd 100644
--- a/docs-users/getting-started/remote-access.md
+++ b/docs-users/getting-started/remote-access.md
@@ -36,7 +36,8 @@ To turn plain HTTP off, set `tls.home_http: false` (`AUDIOSILO_TLS_HOME_HTTP=fal
 
 :::caution What plain HTTP at home means
 - Plain HTTP isn't encrypted: anyone on your home network who can watch its traffic could see sign-ins and what you listen to. That is the usual trade-off on a trusted home Wi-Fi; on a shared or untrusted network, turn it off and use a trusted certificate instead.
-- The server decides who is "at home" from the address each connection comes from. Some setups hand the server every connection from a private address, whoever made it: Docker Desktop (Mac and Windows), rootless Docker, and Docker's userland proxy (used, for example, for IPv6 connections to a published port) relay connections from the container network's gateway, such as `172.17.0.1`. The server then serves plain HTTP to everyone, including internet visitors if you forward the port. If your server runs like that and is reachable from the internet, turn plain HTTP at home off, or use autocert or a reverse proxy.
+- The server treats a connection as "at home" when it comes from a home-network address and uses the server's home address (its LAN IP, or a name like `nas.local`). Visitors from the internet use your public name or address, so they are always sent to `https://`, even through setups (Docker Desktop, rootless Docker, some routers) that make every connection look like it comes from inside your network.
+- Plain HTTP at home is off when you give the server your own certificate (`tls.cert_file`): if your devices trust that certificate, they keep using `https://`.
 :::
 
 :::note Casting needs a certificate the Cast device trusts

From 2b8df1c1c7ff22b117f4676af7497c24d4359016 Mon Sep 17 00:00:00 2001
From: KodeStar <kode@audiosilo.app>
Date: Wed, 14 Oct 2026 11:13:08 +0100
Subject: [PATCH 5/5] Connect and addresses: pairing at a self-signed server's
 home HTTP

---
 .../frontend/connect-and-addresses.md         | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs-developers/frontend/connect-and-addresses.md b/docs-developers/frontend/connect-and-addresses.md
index 00ecdc2..9d497e8 100644
--- a/docs-developers/frontend/connect-and-addresses.md
+++ b/docs-developers/frontend/connect-and-addresses.md
@@ -151,6 +151,31 @@ home pick is dropped the moment the device changes network, before anything else
 sent. Any new code path that talks to a home address must keep this order.
 :::
 
+### Pairing at a self-signed server's home HTTP
+
+A server on its own (self-signed) certificate also answers plain HTTP to the home
+network ([Home HTTP](../server/configuration.md#home-http-tlshome_http)), and its pairing
+links carry `home=http://<host:port>` beside an `https://` base, plus the server's id as
+`sid=` (`parsePairingScan` reads it into `PairingScan.serverId`). The app can't trust
+the certificate, so `useLinkPairing` exchanges at the base first and, only when that
+couldn't connect (`withFallback`: never after an `ApiError`, the server's own answer),
+asks `pairingFallback` whether to try the home address once. It says yes only when all
+of these hold: native (an https page can't call http), not a timeout (a host that never
+answered would only time out again), the base is https and the home is plain http on
+the **same host and port** (an absent port is 443 for https, 80 for http), the link
+carries a `sid`, and a tokenless `GET <home>/api/v1/server` answers with exactly that
+id. The exchange's own `server_id` must match too. The connection is stored with the
+https base as `serverUrl` (it fails safely by TLS on another network) and the home as
+its address, and `finishConnect` sets the home pick (`answeredAt`) before the connection
+is stored, so its first requests go home; the address runner then keeps it by the usual
+probe. Android allows cleartext for this (`expo-build-properties`
+`android.usesCleartextTraffic`); iOS's default ATS allows local networking (IP
+addresses, `.local` and single-label names), not a `.lan` or `.home.arpa` name.
+
+When pairing or the address field can't reach an https server at all, the message
+names a self-signed certificate as a likely cause (`selfSignedMayBeWhy`: native, https,
+not a timeout, and no http retry was made).
+
 ### Where the pick lives (`src/api/address-route.ts`)
 
 The pick is **in memory only**: `useAddressRoute` holds `{ [connectionId]: url }`;