muxplex/docs/plans/2026-04-03-tls-setup-design.md

HTTPS/TLS Setup Design

Goal

Add HTTPS support to muxplex so the browser Clipboard API works on non-localhost devices, via a muxplex setup-tls command with auto-detection that chooses the best available TLS method.

Background

The browser Clipboard API (navigator.clipboard) requires a secure context — either localhost or HTTPS. When accessing muxplex from another device on the LAN (the common multi-device use case), clipboard operations silently fail because the connection is plain HTTP. This blocks copy/paste workflows that are central to terminal use.

Rather than requiring users to manually configure TLS certificates, muxplex should detect what's available on the system and set up the best option automatically.

Approach

Auto-detection with tiered strategies. A single command — muxplex setup-tls — detects what's available and does the right thing:

1. Tailscale running + MagicDNS → tailscale cert (real Let's Encrypt cert, universally trusted)
2. mkcert installed → local CA cert (trusted on this machine, zero browser warnings)
3. Fallback → self-signed via Python (browser shows warning, but clipboard works)

No new Python package dependencies. ssl is stdlib, subprocess handles mkcert/tailscale CLI calls. uvicorn's built-in SSL support handles the serving side.

Architecture

Settings Integration

Two new keys in settings.py DEFAULT_SETTINGS:

Key	Default	Description
tls_cert	""	Path to TLS certificate file. Empty = HTTP.
tls_key	""	Path to TLS private key file. Empty = HTTP.

In serve(), if both are non-empty and files exist on disk, pass to uvicorn.run(ssl_certfile=tls_cert, ssl_keyfile=tls_key). The server prints https:// in its startup URL instead of http://.

If only one is set, or files don't exist at the configured paths, warn and fall back to HTTP.

CLI Flags

--tls-cert and --tls-key flags on muxplex serve, using the same None-sentinel pattern as --host / --port. These override settings.json values.

muxplex config set tls_cert /path/to/cert.pem also works for persistent configuration.

Detection Flow

muxplex setup-tls [--method=auto|tailscale|mkcert|selfsigned]

Default: --method=auto

1. Is Tailscale running + MagicDNS enabled?
   → YES: Use tailscale cert (real LE cert, universally trusted)
   → NO: continue

2. Is mkcert installed?
   → YES: Use mkcert (local CA, trusted on this machine)
   → NO: continue

3. Fallback: Generate self-signed via Python ssl module
   → Works but browser shows warning
   → Print: "For zero-warning HTTPS, install mkcert or use Tailscale"

---

Components

New Module: muxplex/tls.py

Contains all TLS-related logic: auto-detection, cert generation for each method, cert inspection (expiry, SANs), and status reporting.

muxplex setup-tls Subcommand

What it does:

• Generates cert + key to ~/.config/muxplex/cert.pem and ~/.config/muxplex/key.pem
• Writes tls_cert and tls_key paths to settings.json
• Prints method used, hostname(s) in the cert, and expiry date
• Prints: "Restart service to apply: muxplex service restart"

Tailscale variant:

• Auto-detects MagicDNS hostname via tailscale status --self --json
• Runs tailscale cert --cert-file ~/.config/muxplex/cert.pem --key-file ~/.config/muxplex/key.pem
• Includes the local hostname as a reminder to access via https://spark-1.tail8f3c4e.ts.net:8088
• Notes the 90-day expiry and suggests: "Run muxplex setup-tls again to renew"

mkcert variant:

• Runs mkcert -install (may prompt for sudo/keychain access)
• Generates cert for: $(hostname), $(hostname).local, localhost, 127.0.0.1, ::1
• If Tailscale is detected, also adds the Tailscale IP and MagicDNS name as SANs
• Prints instructions for trusting on other LAN devices: "Copy $(mkcert -CAROOT)/rootCA.pem to other devices"

Self-signed fallback:

• Uses Python ssl or openssl CLI to generate a basic self-signed cert
• Warns: "Browsers will show a security warning. Install mkcert for trusted certs."

muxplex setup-tls --status

Shows current TLS state: method used, cert paths, expiry date, hostnames in the cert. Reuses the same inspection logic as doctor's TLS section.

Settings Changes (muxplex/settings.py)

Add tls_cert and tls_key to DEFAULT_SETTINGS with empty string defaults.

Serve Changes (muxplex/cli.py)

• Add --tls-cert and --tls-key CLI flags to serve subcommand
• In serve(), resolve TLS paths (CLI flag → settings.json → empty)
• If both paths are non-empty and files exist, pass ssl_certfile and ssl_keyfile to uvicorn.run()
• Print https:// URL on startup when TLS is active

Doctor Integration

muxplex doctor shows TLS status:

• TLS enabled: TLS: enabled (cert expires 2036-04-01)
• TLS disabled: TLS: disabled (clipboard requires HTTPS on non-localhost)
• Cert expired: TLS: WARNING — cert expired 5 days ago. Run muxplex setup-tls to renew

---

Service Integration

The service file (systemd/launchd) doesn't need to change — serve() already reads tls_cert and tls_key from settings.json. The service runs muxplex serve with zero extra flags.

URL detection in muxplex service install:

• TLS enabled: Service started → https://spark-1.tail8f3c4e.ts.net:8088
• TLS disabled: Service started → http://0.0.0.0:8088

Tailscale cert renewal (90-day expiry): setup-tls prints renewal instructions. No auto-cron job — users set that up themselves if wanted.

---

Error Handling

Detection Edge Cases

Scenario	Behavior
Tailscale installed but not connected	Skip to mkcert detection
Tailscale connected but HTTPS certs not enabled	Print: "Enable HTTPS Certificates in your Tailscale admin console, then re-run"
mkcert installed but mkcert -install fails (no sudo, no certutil)	Warn and fall back to self-signed
Certs already exist from a previous run	Prompt: "TLS already configured (method: tailscale, expires 2026-07-03). Regenerate? [y/N]"

Runtime Edge Cases

Scenario	Behavior
Cert files in settings but deleted from disk	Warn "TLS cert not found at path, falling back to HTTP" and start without SSL
Cert expired	doctor warns with expiry info and renewal instructions
Port conflict with HTTPS	Existing _kill_stale_port_holder behavior handles it
Only one of cert/key configured	Warn about incomplete TLS config, fall back to HTTP

WebSocket Considerations

• The frontend's connectWebSocket() already auto-detects wss: vs ws: from location.protocol — no change needed
• The federation proxy's websockets.connect() to remote instances already handles both ws:// and wss:// since remote_instances[].url can be either http:// or https://

---

Files to Modify

File	Change
muxplex/settings.py	Add tls_cert, tls_key to DEFAULT_SETTINGS
muxplex/cli.py	Add setup-tls subcommand, --tls-cert/--tls-key flags, SSL pass-through in serve()
muxplex/tls.py	New module: auto-detection, tailscale cert, mkcert, self-signed generation, cert inspection
README.md	Document setup-tls command and TLS configuration

No changes needed to muxplex/main.py — uvicorn handles SSL transparently.

Dependencies

• No new Python package dependencies — ssl is stdlib, subprocess for mkcert/tailscale CLI
• mkcert — optional external tool, detected at runtime
• Tailscale — optional external tool, detected at runtime
• uvicorn SSL — built-in support, already a dependency

Testing Strategy

• Unit tests for detection logic (mock shutil.which, subprocess.run for each tool)
• Unit tests for cert inspection (expiry parsing, SAN extraction)
• Integration tests for serve() with SSL cert/key paths (valid and invalid)
• CLI tests for setup-tls --status output formatting
• Edge case tests: missing files, partial config, expired certs

Effort Estimate

Phase	Work	Time
1	Settings + SSL serve	~2 hours
2	setup-tls + auto-detection + all 3 methods	~4 hours
3	Doctor integration + service URL detection	~1 hour
4	README + tests	~2 hours
Total		~9 hours

Open Questions

None — all sections validated.