From adddc6875874fd213b860abd53efa229142f4481 Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Fri, 3 Apr 2026 22:22:44 -0700 Subject: [PATCH] docs: add TLS setup section to README --- README.md | 27 ++++++++++++ muxplex/tests/test_readme.py | 80 ++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) diff --git a/README.md b/README.md index 81a8f75..307197b 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,14 @@ - `muxplex upgrade` — smart version check + auto-update + service restart - `muxplex config` — CLI settings management +### HTTPS / TLS + +- `muxplex setup-tls` — set up TLS certificates for HTTPS (auto-detects best method) +- **Tailscale** *(Phase 2)* — automatic HTTPS via Tailscale funnel +- **mkcert** *(Phase 2)* — locally-trusted development certificates via mkcert +- **Self-signed fallback** — generates a self-signed cert when no other method is available +- **Clipboard API** — HTTPS is required for clipboard access in most browsers + --- ## Prerequisites @@ -140,6 +148,7 @@ muxplex upgrade [--force] Smart update with version check muxplex doctor Check dependencies + config muxplex show-password Show current auth password muxplex reset-secret Regenerate signing secret +muxplex setup-tls [--method auto] Set up TLS certs for HTTPS ``` ### Service management @@ -174,6 +183,22 @@ muxplex --port 9000 muxplex serve --host 0.0.0.0 ``` +### HTTPS / TLS setup + +```bash +# Auto-detect the best TLS method and set up certificates +muxplex setup-tls + +# Use self-signed certificates explicitly +muxplex setup-tls --method selfsigned + +# Override TLS cert/key for a single run (without saving to config) +muxplex serve --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem + +# Check TLS configuration and dependencies +muxplex doctor +``` + --- ## Configuration @@ -197,6 +222,8 @@ All settings are stored in `~/.config/muxplex/settings.json`. | `federation_key` | `""` | Server-to-server authentication key for federation | | `remote_instances` | `[]` | Remote muxplex instances to aggregate | | `multi_device_enabled` | `false` | Enable multi-instance federation | +| `tls_cert` | `""` | Path to TLS certificate file (empty = HTTP) | +| `tls_key` | `""` | Path to TLS private key file (empty = HTTP) | **Priority:** CLI flags > `settings.json` > defaults. diff --git a/muxplex/tests/test_readme.py b/muxplex/tests/test_readme.py index 4e0ff06..096d5b4 100644 --- a/muxplex/tests/test_readme.py +++ b/muxplex/tests/test_readme.py @@ -117,3 +117,83 @@ def test_readme_documents_hover_preview(): assert "hover" in readme_lower and "preview" in readme_lower, ( "README must mention hover preview" ) + + +# ── TLS / HTTPS documentation tests ─────────────────────────────────────────── + + +def test_readme_has_https_tls_feature_subsection(): + """README must have an 'HTTPS / TLS' subsection under Developer Tools.""" + assert "HTTPS / TLS" in README, ( + "README must contain an 'HTTPS / TLS' feature subsection" + ) + + +def test_readme_cli_reference_includes_setup_tls(): + """README CLI Reference block must include the setup-tls command.""" + assert "setup-tls" in README, ( + "README CLI Reference must include 'setup-tls' command" + ) + + +def test_readme_configuration_table_has_tls_cert_row(): + """README Configuration table must document the tls_cert setting.""" + assert "`tls_cert`" in README, ( + "README Configuration table must include tls_cert row" + ) + assert "Path to TLS certificate" in README or "TLS certificate file" in README, ( + "README must describe tls_cert as a TLS certificate path" + ) + + +def test_readme_configuration_table_has_tls_key_row(): + """README Configuration table must document the tls_key setting.""" + assert "`tls_key`" in README, ( + "README Configuration table must include tls_key row" + ) + assert "Path to TLS private key" in README or "TLS private key file" in README, ( + "README must describe tls_key as a TLS private key path" + ) + + +def test_readme_examples_show_tls_commands(): + """README examples must show TLS setup commands.""" + assert "setup-tls" in README, ( + "README must show setup-tls in its examples" + ) + # Check that the examples demonstrate at least the basic setup-tls usage + assert "muxplex setup-tls" in README, ( + "README examples must show 'muxplex setup-tls' command" + ) + + +def test_readme_phase_2_items_noted(): + """README must note Phase 2 items (Tailscale, mkcert) as upcoming.""" + assert "Tailscale" in README, ( + "README must mention Tailscale as a Phase 2 TLS method" + ) + assert "mkcert" in README, ( + "README must mention mkcert as a Phase 2 TLS method" + ) + assert "Phase 2" in README, ( + "README must note Phase 2 items as upcoming" + ) + + +def test_readme_tls_cert_has_empty_default(): + """README must show tls_cert default as empty string.""" + # The config table must show the empty string default for tls_cert + assert "`tls_cert`" in README, "README must document tls_cert" + + +def test_readme_tls_key_has_empty_default(): + """README must show tls_key default as empty string.""" + # The config table must show the empty string default for tls_key + assert "`tls_key`" in README, "README must document tls_key" + + +def test_readme_tls_setup_tls_entry_with_method_flag(): + """README CLI Reference must show setup-tls with --method flag.""" + assert "--method" in README, ( + "README must document the --method flag for setup-tls" + )