gateway setup: offer self-signed TLS cert generation (no openssl needed)
CI / Gateway plugin tests (push) Successful in 4m55s
CI / Kotlin tests (android host + desktop) (push) Successful in 6m58s

hermes gateway setup now asks 'Set up TLS now?' when IRIS_HTTP_CERT is
not in .env (default No, Yes for an all-interfaces bind). Accepting
generates a 10-year RSA-2048 self-signed cert with SANs (advertised LAN
IP, hostname, loopback) under ~/.hermes/iris/ via hermes' existing
cryptography dependency, saves IRIS_HTTP_CERT/IRIS_HTTP_KEY, and prints
the SHA-256 fingerprint in openssl format for the app's confirm-and-pin
dialog. The pairing URL/QR printed afterwards already advertise https.

- key created 0600 from the start (no umask window)
- save_env_value inside the best-effort guard (unwritable .env warns)
- leftover cert without env var -> overwrite confirmation (protects the
  app's pinned fingerprint)
- bind wildcards (0.0.0.0 / ::) never become SANs; :: gets the same
  default-Yes as 0.0.0.0 (pairing._unroutable parity)

Tests: 5 new (cert generation incl. openssl fingerprint cross-check,
accept/decline, no re-prompt, default-follows-bind, overwrite prompt).
Docs: install.md Part 2 table + Part 4 Option B.
This commit is contained in:
ARIA committed 2026-08-24 22:46:27 +02:00
1 parent b1c9bac7d8
commit c7a16d51e3
3 files changed
+338 -4

No files matched your search

+10 -4
View File
@@ -72,7 +72,7 @@ Run the interactive setup:
hermes gateway setup
```
It walks you through four things:
It walks you through five things:
| Prompt | What it means | Default |
| --- | --- | --- |
@@ -80,6 +80,7 @@ It walks you through four things:
| **HTTP host** | Which network address the gateway listens on. `127.0.0.1` = only this machine. For a phone on your home network, use the machine's **LAN IP** (e.g. `192.168.1.10`). | `127.0.0.1` |
| **Port** | The port the app connects to. | `8791` |
| **Push backend** | How offline notifications are delivered: `ntfy` (default, stays on your own infrastructure) or `fcm` (Google). See [Part 5](#part-5--push-notifications-optional). | `ntfy` |
| **TLS** | Only asked when no certificate is configured yet: generates a **self-signed** certificate + key under `~/.hermes/iris/` and stores the paths in `.env` (`IRIS_HTTP_CERT` / `IRIS_HTTP_KEY`), so the gateway serves `https://`. The app asks you to confirm the printed SHA-256 fingerprint once (like an SSH host key). | No (Yes if you bound `0.0.0.0`) |
When it finishes it prints two things you need for the app:
@@ -148,10 +149,15 @@ Works out of the box on a trusted home network:
Plain `http://` is fine on a home network you trust, but for remote access
you want the traffic encrypted. The gateway can serve `https://` itself:
1. Create a certificate + key. Two flavors:
1. Create a certificate + key. Three flavors:
- **Generated by setup (easiest)**: `hermes gateway setup` offers to
generate a **self-signed** certificate for you (see the TLS prompt in
[Part 2](#part-2--gateway-setup-one-time)). It writes
`~/.hermes/iris/iris.crt` + `iris.key`, stores the paths in `.env`, and
prints the SHA-256 fingerprint the app will ask you to confirm.
- **CA-signed** (Let's Encrypt, or your own CA): works out of the box.
- **Self-signed** (e.g. `openssl req -x509 -newkey rsa:2048 -nodes
-keyout iris.key -out iris.crt -days 3650 -subj "/CN=iris"
- **Self-signed manually** (e.g. `openssl req -x509 -newkey rsa:2048
-nodes -keyout iris.key -out iris.crt -days 3650 -subj "/CN=iris"
-addext "subjectAltName=DNS:iris.example.com,IP:192.168.1.10"`):
the certificate **must** carry a SAN entry matching the host you'll
type in the app.