deploy: ship the vault dependency, keep it opt-in (#106)

Declaring cryptography nowhere meant the credential vault was impossible
to enable in the bundled Docker image and systemd unit even with
WEBSH_VAULT_ENABLE=1 set — the HAS_CRYPTOGRAPHY gate kept it off. Ship the
dependency (requirements.txt; pip layer in the image, apt/pip step in the
install docs) and pre-provision a writable creds path (Docker /data volume,
systemd StateDirectory=websh — the standard writable-state mechanism under
the unit's ProtectSystem=strict hardening) so enabling the vault is a
one-line opt-in. WEBSH_VAULT_ENABLE stays off by default: turning persistent
server-side credential storage on is an operator's decision, not a
packaging side effect.

Also fixes the manual-install dependency step for PEP 668 (apt install
python3-cryptography) and documents Docker named-volume persistence
(-v websh-data:/data).

Author: gorevds

Dockerfile

@@ -8,12 +8,27 @@ RUN apt-get update && apt-get install -y --no-install-recommends openssh-client
 RUN useradd -r -s /bin/false websh
 
 WORKDIR /app
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
 COPY server.py index.html websh.js ./
 COPY assets/ ./assets/
 
+# Writable home for the encrypted credential vault (websh.creds.json).
+# WORKDIR is root-owned, so point the vault at a dir the websh user owns
+# and expose it as a volume so saved credentials survive a container
+# replacement.
+RUN mkdir -p /data && chown websh:websh /data
+VOLUME /data
+
 USER websh
 
-ENV PORT=8765 HOST=0.0.0.0 SESSION_TIMEOUT=300 MAX_SESSIONS=50
+# The bundled cryptography wheel makes the encrypted credential vault
+# available, but it stays OFF by default. Opt in at run time with
+# `-e WEBSH_VAULT_ENABLE=1` (add `-v websh-data:/data` to persist the
+# store across container replacement). WEBSH_CREDS_PATH points the store
+# at the writable /data volume — the default cwd path is not writable here.
+ENV PORT=8765 HOST=0.0.0.0 SESSION_TIMEOUT=300 MAX_SESSIONS=50 \
+    WEBSH_CREDS_PATH=/data/websh.creds.json
 
 EXPOSE 8765
 

docs/configuration.md

@@ -10,7 +10,7 @@ Environment variables for `server.py`:
 | `MAX_SESSIONS` | `50` | Max concurrent SSH sessions |
 | `MAX_SESSIONS_PER_IP` | `0` | Max concurrent sessions per source IP (`0` disables; counts foreground + background together) |
 | `WEBSH_CONFIG` | *(unset)* | Path to `websh.json`. `server.py` loads a config only when this is set; the PHP proxy computes a default (`../../websh.json`). |
-| `WEBSH_VAULT_ENABLE` | `0` | Set to `1` to enable the encrypted credential vault endpoints and saved-credential UI when `cryptography` is installed. See [`encryption.md`](encryption.md). |
+| `WEBSH_VAULT_ENABLE` | `0` | Set to `1` to enable the encrypted credential vault endpoints and saved-credential UI (requires `cryptography`). The bundled `websh.service` and Docker image ship the dependency and a writable creds path, so enabling the vault there is a one-line opt-in. See [`encryption.md`](encryption.md). |
 | `WEBSH_CREDS_PATH` | *(sibling of `WEBSH_CONFIG`)* | Path to the encrypted credential store `websh.creds.json`. See [`encryption.md`](encryption.md). Created lazily on first user save with mode `0600`. |
 | `WEBSH_REQUIRE_VAULT` | `0` | Set to `1` to make legacy plaintext credentials in `websh.json` a fatal startup error (forces migration to the vault) instead of a warning. See [`encryption.md`](encryption.md). |
 | `TRUSTED_PROXIES` | `127.0.0.1` | Comma-separated IPs to trust `X-Forwarded-For` from |

docs/deployment.md

@@ -80,6 +80,15 @@ docker build -t websh .
 docker run -d -p 127.0.0.1:8765:8765 websh
 ```
 
+The image ships the vault dependency but leaves it **off** by default. To
+enable it, add `-e WEBSH_VAULT_ENABLE=1`; the encrypted store lives under
+the `/data` volume. Mount a named volume to persist it across container
+replacement:
+
+```bash
+docker run -d -p 127.0.0.1:8765:8765 -e WEBSH_VAULT_ENABLE=1 -v websh-data:/data websh
+```
+
 Open `http://localhost:8765/` — the backend serves the frontend directly.
 The container still listens on `0.0.0.0` internally so Docker port
 publishing works, but the command above binds the published host port to
@@ -96,6 +105,14 @@ mkdir -p /opt/websh
 # Copy the backend, the frontend, AND the assets/ dir (the logo lives
 # there; without it index.html 404s on assets/websh-logo.svg).
 cp -r server.py index.html websh.js assets/ /opt/websh/
+
+# Install the one optional dependency so the encrypted credential vault
+# can be enabled (it ships off by default). On Debian/Ubuntu the system
+# Python is externally managed (PEP 668), so use the distro package rather
+# than a system-wide pip; skipping this is non-fatal — the server still
+# runs and the saved-credential UI just stays hidden.
+apt install python3-cryptography   # or: pip install --break-system-packages -r requirements.txt
+
 cp websh.service /etc/systemd/system/
 systemctl enable --now websh
 ```
@@ -117,6 +134,14 @@ systemctl restart websh
 The bundled unit also pins `PORT`/`HOST`; change them there (or via
 `systemctl edit`) rather than relying on the in-code defaults.
 
+The unit pre-provisions a writable `/var/lib/websh` via
+`StateDirectory=websh`, but leaves the encrypted credential vault **off**
+by default. With `cryptography` installed (the optional step above),
+enabling it is one line — add `Environment=WEBSH_VAULT_ENABLE=1` in the
+same `systemctl edit` override; saved credentials then persist (encrypted)
+under `/var/lib/websh/websh.creds.json`. See
+[`encryption.md`](encryption.md).
+
 ## HTTPS via reverse proxy
 
 Put nginx or Caddy in front for TLS termination:

docs/encryption.md

@@ -1,10 +1,12 @@
 # Encrypted credential vault
 
-> **Status:** implemented behind an operator opt-in. Install
-> `cryptography` and set `WEBSH_VAULT_ENABLE=1` to enable the encrypted
-> save UI and vault endpoints. Deployments without that optional
-> dependency or flag continue to run, but saved-credential UI stays
-> hidden and legacy plaintext entries are not migrated automatically.
+> **Status:** implemented, **off by default**. The bundled `websh.service`
+> and Docker image ship the `cryptography` dependency (`requirements.txt`)
+> and a writable creds path, so enabling the vault there is a one-line
+> opt-in (`WEBSH_VAULT_ENABLE=1`); a bare `python3 server.py` additionally
+> needs `cryptography` installed. Either way a deployment missing the
+> dependency or flag still runs — the saved-credential UI just stays
+> hidden, and legacy plaintext entries are not migrated automatically.
 
 Saved SSH credentials are stored as **opaque encrypted blobs** on the
 server. The decryption key lives in the browser's IndexedDB, generated
@@ -27,7 +29,9 @@ the ~50 ms it takes to type it into the SSH PTY.
    Without it, websh keeps working — the saved-credential UI is just
    hidden. With it, the browser's "Save" checkbox enables encrypted
    storage end-to-end.
-2. Opt the vault on explicitly:
+2. Opt the vault on explicitly (the bundled `websh.service` and Docker
+   image already ship the dependency, so this flag is all that's needed
+   there):
    ```bash
    WEBSH_VAULT_ENABLE=1 python3 server.py
    ```

requirements.txt

@@ -0,0 +1,8 @@
+# websh runs on the Python 3 standard library alone. The single optional
+# dependency below ships in the bundled Docker image and systemd unit so
+# the encrypted credential vault can be turned on without chasing a missing
+# wheel. The vault stays OFF by default; opt in with WEBSH_VAULT_ENABLE=1.
+# Without this dependency the server still runs — the saved-credential UI
+# just stays hidden. See docs/encryption.md.
+# 3.4.8 is the documented minimum; modern wheels (>=42) are recommended.
+cryptography>=3.4.8

websh.service

@@ -13,6 +13,17 @@ Environment=HOST=127.0.0.1
 Environment=SESSION_TIMEOUT=300
 Environment=MAX_SESSIONS=50
 
+# The encrypted credential vault is available but OFF by default. To turn
+# it on, `systemctl edit websh` and add `Environment=WEBSH_VAULT_ENABLE=1`
+# (the cryptography wheel from requirements.txt must be installed; without
+# it the server still runs and the saved-credential UI just stays hidden).
+# StateDirectory pre-creates /var/lib/websh owned by the service user and
+# keeps it writable despite ProtectSystem=strict / ProtectHome=read-only,
+# so the lazily created websh.creds.json (mode 0600) has somewhere to live
+# the moment the vault is enabled.
+Environment=WEBSH_CREDS_PATH=/var/lib/websh/websh.creds.json
+StateDirectory=websh
+
 User=websh
 Group=websh