vssh 4.3.0__tar.gz → 4.3.1__tar.gz

{vssh-4.3.0 → vssh-4.3.1}/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## [Unreleased]
 
+- Docs (README/HELP/SECURITY + ko) updated to the key-only model (no shared
+  secret in quickstart, auth via `~/.vssh/authorized_keys`). pip `vssh` 4.3.1
+  fetches the 0.7.38 binary.
+
+### Security/cleanup (2026-06-14) — P4 finish: secret-free daemon, dead HMAC code removed (v0.7.38)
+
+- `vssh server` no longer requires (or reads) a shared secret to start — auth is
+  purely per-node Ed25519 keys. Removed the secret-required startup gate and the
+  `VSSH_INSECURE_ALLOW_EMPTY_SECRET` escape hatch from `cmd/vssh`.
+- Deleted the now-dead HMAC code: `server.ValidateAuthToken`,
+  `server.GenerateAuthToken`, the legacy HMAC-authenticated client transfer
+  functions (`SendFileCompressed/SendFileResume/ParallelDownload/PipeUp/PipeDown/
+  MultiPut/SyncFile` + helpers), and the HMAC token unit tests. The modern
+  `dialAuth`/`Handle*` (VAUTH1) paths are unaffected.
+- `scripts/enroll.sh` is now key-only: it installs the daemon unit WITHOUT
+  `VSSH_SECRET` and verifies via VAUTH1 (no shared secret anywhere in onboarding).
+- `go vet`/`go test` green (incl. `TestServerRejectsLegacyHMACAuth`).
+
+### Security (2026-06-14) — P4: key-only auth (legacy shared-secret HMAC removed)
+
+- The daemon now accepts **only per-node Ed25519 VAUTH1**. The legacy shared-secret
+  (HMAC) authentication path was removed from `internal/server/server.go`: any
+  non-VAUTH1 auth line — including a *valid* HMAC token for the configured secret —
+  is rejected (`AUTH_FAILED`). This removes the entire class of risk where one
+  fleet-wide shared secret, if leaked, grants access, and eliminates the secret
+  that could be hardcoded or re-leaked.
+- `dialAuth` (the canonical client path) has been VAUTH1-only since 0.7.25; the
+  remaining `GenerateAuthToken` callers (`transfer_advanced.go` / `sync.go`) are
+  legacy client functions not wired to any CLI command. The HMAC helpers remain
+  for now but are unreachable by the daemon.
+- New regression test `TestServerRejectsLegacyHMACAuth`; `go vet`/`go test` green.
+- Operational: the live fleet already enforces VAUTH at runtime
+  (`VSSH_REQUIRE_VAUTH=1`, incl. the m1 controller as of 2026-06-14); this makes
+  key-only the built-in default. Rollout (build → d1 canary → deploy_fleet → drop
+  `VSSH_SECRET` from units + retire legacy HMAC helpers) is deferred until all
+  nodes are reachable. **Not yet deployed.**
+
 ### Distribution (2026-06-14) — P1 one-line install pipeline (v0.7.36)
 
 - **Makefile version single-sourced** from `cmd/vssh/main.go` (was hardcoded
@@ -15,14 +52,18 @@
   console-script that downloads the matching Go release binary to `~/.vssh/bin`
   on first use (stdlib-only, checksum-verified, `VSSH_BIN`/`VSSH_VERSION`/`VSSH_HOME`
   overrides, atomic cache write) AND keeps `from vssh import VSSH` importable.
-  Package version single-sourced from `src/vssh/_version.py` (== binary version);
+  Package version (`src/vssh/_version.py:__version__`) stays on PyPI's existing
+  `vssh` 4.x line (4.3.0) so `pip install vssh` resolves to it (highest wins); the
+  launcher downloads the decoupled `BINARY_VERSION` (0.7.36) GitHub release asset.
   `python -m vssh` works.
 - Verified on m1: `go vet`/`go test` green, Python SDK 8/8, `make release`
   4-arch + checksums, wheel/sdist build, fresh-venv install (SDK import +
   console-script exec), and an adversarial download test (happy path +
   tampered-checksum rejection fail-closed + `VSSH_BIN` override).
-- Publishing (GitHub release assets + PyPI upload) prepared but deferred to a
-  credentialed hand-off step; see NEXT_SESSION_PROMPT.
+- PUBLISHED 2026-06-14: pushed `main` + tag `v0.7.36`; GitHub release (CI-built
+  4 binaries + `checksums.txt`, marked Latest); PyPI `vssh` **4.3.0**. Verified
+  live on m1: one-line `install.sh` (checksum-verified -> `vssh 0.7.36`) and
+  `pip install vssh` -> import SDK + `vssh --version` downloads 0.7.36 binary.
 
 ### Tooling (2026-06-13) — P1a one-command node onboarding
 
@@ -314,7 +355,7 @@ new-TLS); fleet `agent_suite` 38/38 GREEN over the new TLS client across
 `d1 g1 c1 v1 macmini` (linux + darwin); `handshake-test --tls` AUTH_OK against
 both a 0.7.26 (d1) and a 0.7.25 (c1) daemon; rolled out to 14 online nodes
 (`deploy_fleet.sh`), `n1 s1 s2` offline/skipped. m1 coordinator binary was on 0.7.25 during rollout, then upgraded to 0.7.26 the
-same day via the safe bootout/bootstrap procedure (see NEXT_SESSION_PROMPT).
+same day via the safe bootout/bootstrap procedure (internal release note).
 
 ## [v0.7.25] - 2026-06-13
 

vssh-4.3.1/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for helping improve `vssh`. This is a Go binary with a small Python SDK.
+
+## Development setup
+
+```bash
+git clone https://github.com/meshpop/vssh && cd vssh
+make build          # build ./vssh
+```
+
+Requires Go 1.25+ (and Python 3.9+ for the SDK tests).
+
+## Before opening a PR
+
+```bash
+go vet ./...
+go build ./...
+go test ./...                 # Go tests
+make test                     # Go tests + Python SDK tests
+bash -n install.sh            # when editing the installer
+```
+
+CI runs the same checks. Please make sure they pass locally.
+
+## Pull requests
+
+- Target `main`.
+- Keep changes focused and describe behavior changes clearly — **especially
+  anything touching authentication, transport, policy, or `vssh server`.**
+- Update `CHANGELOG.md` and bump the version in `cmd/vssh/main.go` for
+  user-visible changes.
+- Add or update tests for new behavior.
+
+## Releasing
+
+Maintainers: see [docs/PUBLISH_HANDOFF.md](docs/PUBLISH_HANDOFF.md) for the
+release process (tag → CI builds the GitHub release → PyPI upload).
+
+## Security
+
+Report vulnerabilities privately via
+[GitHub Security Advisories](https://github.com/meshpop/vssh/security/advisories/new),
+not public issues or PRs.

vssh-4.3.1/HELP.md

@@ -0,0 +1,127 @@
+# vssh — help & usage
+
+`vssh` is an sshd-free, AI-native remote execution daemon for private networks.
+It runs commands, transfers files, and manages jobs on remote nodes over TLS 1.3
+with Ed25519 key authentication, returning structured execution evidence.
+
+- No `sshd` required on the target
+- Built-in PTY, typed RPC, file transfer, and long-running jobs
+- TLS 1.3 + Ed25519 key auth (legacy shared-secret path for bootstrap)
+- Node-name routing over Tailscale, Wire/WireGuard, LAN, or configured addresses
+- A built-in MCP server (`vssh mcp`) for AI agents
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/meshpop/vssh/main/install.sh | bash
+# or
+pip install vssh
+```
+
+## Quick start
+
+```bash
+# On the target node (no shared secret — key-authenticated)
+vssh server                     # listens on :48291
+
+# On the client: print your key, add it to the server's ~/.vssh/authorized_keys
+vssh pubkey
+vssh run web1 "uptime"          # structured result
+vssh web1                       # interactive shell
+vssh doctor --json              # diagnose before AI/MCP use
+```
+
+## Command reference
+
+### Execution
+```bash
+vssh <node>                  # interactive PTY shell
+vssh shell <node>            # interactive PTY shell
+vssh run <node> <command>    # run a command (structured result)
+vssh exec <node> <command>   # alias for run
+vssh run-many <n1,n2> <cmd>  # run across comma-separated nodes
+vssh run-batch <node> ...    # run several commands on one session
+```
+
+### Typed APIs
+```bash
+vssh rpc <node> <method> [json]        # call a typed daemon RPC
+vssh rpc-many <nodes> <method> [json]  # RPC across nodes
+vssh facts <node>                      # typed host facts
+vssh facts-many <nodes>                # facts across nodes
+```
+
+### Jobs (long-running)
+```bash
+vssh job-start <node> <command>   # start a background job
+vssh job-status <node> <id>       # job status
+vssh job-logs <node> <id>         # job logs
+vssh job-cancel <node> <id>       # cancel a job
+vssh artifact-collect <node>      # collect output artifacts
+```
+
+### Files
+```bash
+vssh put <local> <node:path>   # upload
+vssh get <node:path> <local>   # download
+```
+
+### Fleet & ops
+```bash
+vssh                 # dashboard (default)
+vssh status          # dashboard
+vssh list            # list known nodes
+vssh doctor [--json] # diagnose binary, secret, config, peers, MCP readiness
+vssh deploy <node>   # atomic binary install + restart + verify
+vssh server          # run the daemon
+vssh mcp             # run the MCP server (for AI agents)
+vssh setup           # first-run self-configuration
+vssh version         # show version
+vssh help            # full help
+```
+
+## Discovery
+
+`vssh` finds nodes from, in order: a Wire coordinator, Tailscale, the config
+file (`~/.vssh/servers.json`), and a local cache. You can always address a node
+by an explicit IP as well.
+
+## Configuration
+
+### Node inventory — `~/.vssh/servers.json`
+```json
+{
+  "web1": { "ip": "192.0.2.10", "user": "deploy" },
+  "db1":  { "ip": "192.0.2.20", "user": "postgres" }
+}
+```
+
+### Per-host users — `~/.wire/users.json` (root: `/etc/wire/users.json`)
+```json
+{ "web1": "deploy", "db1": "postgres" }
+```
+
+> Keep real inventory, hostnames, VPN IPs, and secrets **out of source control**.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `VSSH_PORT` | Daemon listen port (default **48291**). |
+| `VSSH_REQUIRE_TLS` | `1` = refuse non-TLS connections. |
+| `VSSH_NO_HOSTKEY_VERIFY` | `1` = opt out of host-identity verification (not recommended). |
+| `VSSH_BIN` / `VSSH_VERSION` / `VSSH_HOME` | pip-wrapper/installer overrides (see README). |
+
+## Security
+
+`vssh server` authenticates peers with **TLS 1.3 + Ed25519 keys (VAUTH1)** only —
+no shared secret. Authorize clients via `~/.vssh/authorized_keys`. Commands can be
+gated with optional per-key policy. The VPN encrypts the tunnel but does **not**
+replace vssh authentication. Full details and
+a hardening checklist: [SECURITY.md](SECURITY.md).
+
+## More
+
+- MCP / agent orchestration: [docs/CODEX_ORCHESTRATION.md](docs/CODEX_ORCHESTRATION.md)
+- Python SDK: [docs/PYTHON_SDK.md](docs/PYTHON_SDK.md)
+- Why vssh: [docs/WHY_VSSH.md](docs/WHY_VSSH.md)

vssh-4.3.1/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: vssh
+Version: 4.3.1
+Summary: vssh — AI-native, drop-in ssh replacement (CLI binary + Python SDK)
+Project-URL: Homepage, https://github.com/meshpop/vssh
+Project-URL: Repository, https://github.com/meshpop/vssh
+Author: MeshPop
+License: MIT
+Keywords: ai-agents,mcp,remote-execution,ssh,tailscale,vssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# vssh
+
+**An sshd-free, AI-native remote execution daemon for private networks.**
+
+`vssh` runs commands, transfers files, and manages long-running jobs on remote
+nodes over your private network (Tailscale, WireGuard/Wire, or LAN) — without
+running `sshd` on the target. It speaks a typed protocol over TLS 1.3 with
+Ed25519 key authentication, and every result comes back as structured evidence
+(stdout, stderr, exit code, duration, transport), which makes it a natural
+execution layer for AI agents and automation as well as for humans.
+
+```bash
+# Install (Linux/macOS, amd64/arm64)
+curl -fsSL https://raw.githubusercontent.com/meshpop/vssh/main/install.sh | bash
+# or
+pip install vssh
+```
+
+---
+
+## Why vssh
+
+Use `vssh` when the operator is often an **AI agent or automation runtime**, not
+a person typing into a terminal, and when you want execution that is:
+
+- **sshd-free** — the target runs `vssh server`, not OpenSSH.
+- **typed & auditable** — structured `stdout/stderr/exit/duration` evidence, not a raw text stream.
+- **policy-gated** — classify and block dangerous commands before they run.
+- **durable** — start/poll/cancel long-running jobs and collect artifacts.
+- **name-routed** — address nodes by name and capability, not raw IPs.
+
+If all you need is an interactive human shell on a box that already runs `sshd`,
+use `ssh` directly — `vssh` deliberately does not wrap OpenSSH. See
+[docs/WHY_VSSH.md](docs/WHY_VSSH.md).
+
+**Out of scope:** operating the VPN mesh and fleet dashboards. Use
+[Wire](https://github.com/meshpop/wire) for the network layer and
+[mpop](https://github.com/meshpop/mpop) for monitoring.
+
+---
+
+## Install
+
+### One-line installer (recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/meshpop/vssh/main/install.sh | bash
+```
+
+The installer detects your OS/arch, downloads the matching binary from the
+[latest GitHub release](https://github.com/meshpop/vssh/releases/latest),
+**verifies its SHA-256 against the published `checksums.txt`**, and installs to
+`~/bin`. Options:
+
+```bash
+# Install a specific version
+curl -fsSL .../install.sh | VSSH_VERSION=0.7.36 bash
+# Install to a custom directory
+curl -fsSL .../install.sh | INSTALL_DIR=/usr/local/bin bash
+```
+
+### pip (CLI + Python SDK)
+
+```bash
+pip install vssh
+```
+
+This installs both the `vssh` CLI (the Go binary is fetched and checksum-verified
+for your platform on first run, cached under `~/.vssh/bin`) **and** the Python
+SDK (`from vssh import VSSH`). See [Python SDK](#python-sdk).
+
+### From source
+
+```bash
+git clone https://github.com/meshpop/vssh && cd vssh
+make build          # builds ./vssh
+make install        # installs to /usr/local/bin (sudo)
+```
+
+Requires Go 1.25+.
+
+---
+
+## Quick start
+
+On the **target** node, start the daemon (no shared secret — auth is key-based):
+
+```bash
+vssh server                  # listens on :48291
+```
+
+Authorize a client by adding its public key to the server's
+`~/.vssh/authorized_keys` (run `vssh pubkey` on the client to print it). For a
+fleet, `scripts/enroll.sh <node>` does this from a controller automatically.
+Then, from the client:
+
+```bash
+vssh run web1 "df -h"        # run a command, get structured output
+vssh web1                    # open an interactive shell
+vssh put ./app web1:/tmp/    # upload a file
+vssh get web1:/var/log/x .   # download a file
+vssh                         # fleet dashboard
+vssh doctor --json           # diagnose binary, secret, config, peers, MCP
+```
+
+`vssh run` returns an evidence envelope — exit code, durations, transport, and
+the endpoints it tried — not just raw text.
+
+> For a multi-node fleet, `scripts/enroll.sh <node>` installs the daemon and
+> cross-authorizes keys from a controller. See [Security](#security).
+
+---
+
+## How it works
+
+```text
+vssh client ──TLS 1.3──▶ vssh server ──▶ typed exec / file / job / RPC APIs ──▶ structured evidence
+            (Ed25519 pinned)   (:48291)
+```
+
+1. **Transport** — TLS 1.3 with the daemon's **Ed25519 public key pinned**
+   (raw-key, not a CA). The client is TLS-first; set `VSSH_REQUIRE_TLS=1` to
+   refuse plaintext entirely.
+2. **Host identity** — the client verifies it reached the *intended* host by
+   checking the daemon key against a trusted registry (on by default since
+   0.7.33), so a name can't be silently misrouted to the wrong machine.
+3. **Authentication** — per-node **Ed25519 challenge–response (VAUTH1)** only.
+   There is no shared secret; a client is authorized by listing its public key in
+   the server's `~/.vssh/authorized_keys` (or `/etc/vssh/authorized_keys`).
+4. **Policy** — commands can be classified and gated before execution; per-key
+   allow/deny lists, path scoping, and rate limits are available opt-in.
+
+---
+
+## CLI reference
+
+```
+Execution
+  vssh <node>                 Interactive PTY shell
+  vssh shell <node>           Interactive PTY shell
+  vssh run <node> <cmd>       Run a command (structured result)
+  vssh exec <node> <cmd>      Alias for run
+  vssh run-many <n1,n2> <cmd> Run across comma-separated nodes
+  vssh run-batch <node> ...   Run multiple commands on one session
+
+Typed APIs
+  vssh rpc <node> <method> [json]       Call a typed daemon RPC
+  vssh rpc-many <nodes> <method> [json] RPC across nodes
+  vssh facts <node>                     Typed host facts
+  vssh facts-many <nodes>               Facts across nodes
+
+Jobs (long-running)
+  vssh job-start <node> <cmd>   Start a background job
+  vssh job-status <node> <id>   Job status
+  vssh job-logs <node> <id>     Job logs
+  vssh job-cancel <node> <id>   Cancel a job
+  vssh artifact-collect <node>  Collect output artifacts
+
+Files
+  vssh put <local> <node:path>  Upload
+  vssh get <node:path> <local>  Download
+
+Fleet & ops
+  vssh                Dashboard (default)
+  vssh status         Dashboard
+  vssh list           List known nodes
+  vssh doctor [--json] Diagnose local setup
+  vssh deploy <node>  Atomic binary install + restart + verify
+  vssh server         Run the daemon
+  vssh mcp            Run the MCP server (for AI agents)
+  vssh setup          First-run self-configuration
+  vssh version        Show version
+  vssh help           Full help
+```
+
+---
+
+## MCP server (for AI agents)
+
+The MCP server is built into the binary — no separate install:
+
+```bash
+vssh mcp
+```
+
+It exposes typed tools that return execution evidence, so an agent can route,
+gate, and run work with an audit trail:
+
+| Tool | Purpose |
+|------|---------|
+| `vssh_doctor` | Diagnose binary, secret source, config, peers, MCP readiness |
+| `vssh_hosts_list` | List known hosts (addresses, tags, capabilities, health) for routing |
+| `vssh_route_select` | Pick the best host by capability, tag, and health |
+| `vssh_exec_safe` | Run read-only/diagnostic commands (dangerous ones blocked) |
+| `vssh_exec` | Run with policy checks; `allow_dangerous` after explicit approval |
+| `vssh_exec_routed` | Route first, then execute with policy + evidence |
+| `vssh_policy_check` | Classify a command before running it |
+| `vssh_status`, `vssh_list` | Status and peer inventory |
+
+Commands matching destructive patterns (`rm -rf`, `shutdown`, `reboot`,
+`docker rm`, `kubectl delete`, `systemctl restart`, …) are **blocked** unless the
+caller sets `allow_dangerous: true` after explicit human approval. Every response
+is an evidence envelope with timestamps, the policy decision, target, command,
+and the structured result. See [docs/CODEX_ORCHESTRATION.md](docs/CODEX_ORCHESTRATION.md).
+
+---
+
+## Python SDK
+
+```python
+from vssh import VSSH
+
+client = VSSH(secret="a-long-random-value")
+
+client.exec("web1", "uptime")              # -> ExecResult(stdout, exit_code, ...)
+client.exec_many(["web1", "db1"], "uptime")
+client.facts("web1")                        # typed host facts
+job = client.job_start("web1", "long-task")
+client.job_status("web1", job["job_id"])
+client.doctor()
+```
+
+The SDK is a thin client over the installed `vssh` binary (it does not
+reimplement the protocol), so it inherits the same transport, auth, and policy.
+Full method list: `exec`, `exec_many`, `rpc`, `rpc_many`, `facts`, `facts_many`,
+`job_start`, `job_status`, `job_logs`, `job_cancel`, `artifact_collect`,
+`doctor`. See [docs/PYTHON_SDK.md](docs/PYTHON_SDK.md).
+
+---
+
+## Configuration
+
+### Node inventory — `~/.vssh/servers.json`
+
+```json
+{
+  "web1": { "ip": "192.0.2.10", "user": "deploy", "tags": ["linux", "web"], "capabilities": ["docker"] },
+  "gpu1": { "ip": "192.0.2.20", "user": "ubuntu", "tags": ["gpu"], "capabilities": ["cuda", "ollama"], "monitor_port": 8721 }
+}
+```
+
+Nodes are also discovered automatically from a Wire coordinator, Tailscale, and a
+local cache. **Do not commit a real `servers.json`, hostnames, VPN IPs, or
+secrets** — keep inventory outside the repo and use example values in docs.
+
+### Per-host users — `~/.wire/users.json`
+
+```json
+{ "web1": "deploy", "db1": "postgres" }
+```
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `VSSH_PORT` | Daemon listen port (default **48291**). |
+| `VSSH_REQUIRE_TLS` | `1` = refuse non-TLS connections. |
+| `VSSH_NO_HOSTKEY_VERIFY` | `1` = opt out of host-identity verification (not recommended). |
+| `VSSH_BIN` | (pip wrapper) use this binary instead of downloading. |
+| `VSSH_VERSION` | (pip wrapper / installer) pin the binary release to fetch. |
+| `VSSH_HOME` | Override the `~/.vssh` directory. |
+
+---
+
+## Security
+
+- The native daemon grants authorized peers command execution and file transfer
+  **as the configured user** — treat access as root-equivalent.
+- Authentication is **per-node Ed25519 keys (VAUTH1)** only; authorize clients via
+  `~/.vssh/authorized_keys`. Enforce encryption with `VSSH_REQUIRE_TLS=1`.
+- The VPN (WireGuard/Tailscale) encrypts the tunnel but is **not** a substitute
+  for vssh authentication — always set a strong secret or enroll keys, and
+  firewall the listen port.
+- Report vulnerabilities privately via
+  [GitHub Security Advisories](https://github.com/meshpop/vssh/security/advisories/new).
+
+Full model and hardening steps: [SECURITY.md](SECURITY.md).
+
+---
+
+## Documentation
+
+- [Why vssh](docs/WHY_VSSH.md) — positioning and scope
+- [Python SDK](docs/PYTHON_SDK.md) — SDK reference
+- [Codex / agent orchestration](docs/CODEX_ORCHESTRATION.md) — MCP usage for agents
+- [SECURITY.md](SECURITY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
+- [한국어 README](README.ko.md)
+
+## Building & contributing
+
+```bash
+make build      # build ./vssh
+make test       # go test ./... + Python SDK tests
+make release    # cross-compile linux/darwin × amd64/arm64 into dist/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT