vssh 4.1.4__tar.gz → 4.2.1__tar.gz

vssh-4.2.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: vssh client, server, or SSH fallback issue
+labels: bug
+---
+
+## Version
+`vssh version` output:
+
+## Mode
+Native (`vssh server` / `run` / `put`) or SSH/SCP fallback?
+
+## Platform
+
+## What happened
+
+## Expected
+
+## Reproduction / config
+(Redact `VSSH_SECRET`, hostnames if needed.)

vssh-4.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security advisory
+    url: https://github.com/meshpop/vssh/security/advisories/new
+    about: Report vulnerabilities privately.

vssh-4.2.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Build
+        run: go build ./...
+
+      - name: Test
+        run: go test ./...
+
+      - name: Shell script syntax
+        shell: bash
+        run: |
+          while IFS= read -r f; do
+            [[ -z "$f" ]] && continue
+            bash -n "$f"
+          done < <(git ls-files '*.sh')

vssh-4.2.1/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Build release binaries
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          version="${GITHUB_REF_NAME:-dev}"
+          build_time="$(date -u '+%Y-%m-%d_%H:%M:%S')"
+          ldflags="-s -w -X main.version=${version#v} -X main.buildTime=${build_time}"
+
+          for target in \
+            linux/amd64 \
+            linux/arm64 \
+            darwin/amd64 \
+            darwin/arm64
+          do
+            os="${target%/*}"
+            arch="${target#*/}"
+            out="dist/vssh-${os}-${arch}"
+            GOOS="$os" GOARCH="$arch" CGO_ENABLED=0 go build -ldflags "$ldflags" -o "$out" ./cmd/vssh
+          done
+
+          cd dist
+          sha256sum vssh-* > checksums.txt
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/vssh-linux-amd64
+            dist/vssh-linux-arm64
+            dist/vssh-darwin-amd64
+            dist/vssh-darwin-arm64
+            dist/checksums.txt
+          generate_release_notes: true

vssh-4.2.1/.gitignore

@@ -0,0 +1,23 @@
+# Build outputs
+/vssh
+/vssh-*
+!/vssh-*.md
+/dist/
+/build/
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+id_rsa*
+known_hosts
+
+# OS/editor noise
+.DS_Store
+*.swp
+*.tmp

vssh-4.2.1/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## [Unreleased]
+
+## [v0.7.5] - 2026-05-22
+
+### Runtime
+
+- Add `vssh doctor` / `vssh setup-check` for AI-operator setup diagnostics:
+  effective binary, stale binary conflicts, secret source, Wire config, and peer
+  counts.
+- Add MCP `vssh_doctor` so Codex, Claude, Cursor, and other MCP clients can
+  diagnose VSSH before attempting execution or facts calls.
+- Prefer MCP-safe underscore tool names and deduplicate exposed tools.
+- Read native secrets from `/etc/vssh/secret` and `~/.vssh/secret` before
+  falling back to Wire-derived secrets.
+
+### Python SDK
+
+- Add `VSSH.doctor()` to call `vssh doctor --json`.
+
+## [v0.7.4] - 2026-05-16
+
+### Runtime
+
+- Add `vssh.route.select` / `vssh_route_select` for capability, tag, and health-aware host routing.
+- Add `vssh.exec.routed` / `vssh_exec_routed` to route first, then execute with policy and evidence.
+- Return route decisions with selected host, score, reasons, missing capabilities, health, tags, and candidate host records.
+- Keep monitoring separate: `vssh.hosts.list`, `vssh.route.select`, and `vssh.exec.routed` can optionally merge live health from an external MeshClaw/mpop-style monitor endpoint using `monitor_url` or `monitor_port`.
+
+## [v0.7.3] - 2026-05-16
+
+### Runtime
+
+- Enrich `vssh.hosts.list` output with `addresses`, `tags`, `capabilities`, `health`, `stats`, `os`, `arch`, and metadata fields for agent routing.
+- Extend `~/.vssh/servers.json` support with optional `tags`, `capabilities`, `roles`, `os`, `arch`, `public_ip`, `lan_ip`, `port`, and `metadata`.
+- Infer basic capabilities from tags/roles/OS names, including `gpu`, `cuda`, `ollama`, `browser`, `controller`, `mail`, `docker`, `linux`, and `macos`.
+- Add health summaries based on provider online state, `last_seen`, and resource pressure.
+
+## [v0.7.2] - 2026-05-16
+
+### Runtime
+
+- Add agent-facing MCP tool aliases: `vssh.hosts.list`, `vssh.exec`, `vssh.exec.safe`, and `vssh.policy.check`.
+- Add a built-in safety policy that blocks destructive/service-impacting command patterns unless `allow_dangerous` is explicitly set.
+- Wrap MCP execution responses in evidence envelopes with timestamps, policy decision, target, command, timeout, and structured execution result.
+
+### Documentation
+
+- README / README.ko: link to canonical stack snapshot [`meshpop/wire` **docs/CURRENT_STATE.md**](https://github.com/meshpop/wire/blob/main/docs/CURRENT_STATE.md).
+- Document Codex/Runtime MCP usage in English and Korean.
+
+## [v0.7.1] - 2026-05-16
+
+### Runtime
+
+- Preserve MCP `vssh_exec` shell commands as one script instead of splitting with `strings.Fields`.
+- Return structured execution evidence with stdout, stderr, exit code, duration, attempts, transport, fallback, and typed retryable errors.
+- Fix root-run `vsshd` transfer ownership so PUT/PUTZ/RESUME/MPUT/PIPE_UP outputs are usable by the default non-root runtime user.
+
+## [v0.7.0] - 2026-05-14
+
+### Changed
+
+- Remove `mesh-event` dependency; standalone `go build`.
+- Document `internal/adapter` as **discovery-only**; `VSSHAdapter.Exec` remains unimplemented by design until explicitly specified.
+
+### Fixed
+
+- `go vet` cleanups (IPv6 literals) where applicable.
+
+## Earlier releases
+
+See Git tags and GitHub Releases.

vssh-4.2.1/CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# Contributing
+
+- **Branches:** PRs to `main`; describe behavior changes (especially auth / `vssh server`).
+- **Build:** `go vet ./...`, `go build ./...`, `go test ./...` (CI matches).
+- **Shell:** `bash -n install.sh` when editing installers.
+- **Security:** [Security advisories](https://github.com/meshpop/vssh/security/advisories/new) for private reports.

vssh-4.2.1/HELP.md

@@ -0,0 +1,115 @@
+# VSSH
+
+## What is VSSH
+
+VSSH is an AI-native remote execution daemon/protocol for private networks.
+
+- No sshd required on target
+- Built-in PTY, RPC, file transfer, and execution evidence
+- HMAC authentication
+- Node-name routing over Tailscale, VPN, LAN, or configured addresses
+
+## Components
+
+| Binary | Description |
+|--------|-------------|
+| `vssh server` | Server daemon (port 48291) |
+| `vssh` | CLI client |
+
+## Quick Start
+
+```bash
+# Server side
+export VSSH_SECRET=your-secret
+vssh server
+
+# Client side
+export VSSH_SECRET=your-secret
+vssh shell hostname      # Interactive shell
+vssh run hostname "cmd"  # Execute command
+vssh doctor --json       # Diagnose setup before MCP/AI use
+```
+
+## CLI Commands
+
+### Native Protocol
+
+```bash
+vssh <host>                 # Interactive PTY shell
+vssh shell <host>           # Interactive PTY shell
+vssh run <host> <command>   # Execute command
+vssh exec <host> <command>  # Alias for native run
+vssh put <local> <host:path>  # Upload
+vssh get <host:path> <local>  # Download
+```
+
+### Status
+
+```bash
+vssh status        # Show dashboard
+vssh list          # List all peers
+vssh doctor        # Diagnose binary, secret, config, and peers
+vssh version       # Show version
+```
+
+## Data Sources
+
+VSSH discovers peers from multiple sources:
+
+1. Wire VPN coordinator
+2. Tailscale
+3. Config file (~/.vssh/servers.json)
+4. Cache
+
+## Configuration
+
+### Server Config
+
+`~/.vssh/servers.json`:
+
+```json
+{
+  "web1": {"ip": "192.0.2.10", "user": "deploy"},
+  "db1": {"ip": "192.0.2.20", "user": "postgres"}
+}
+```
+
+### User Mapping
+
+Per-host SSH user overrides are read from Wire’s config directory (same as the Wire CLI), not under `~/.vssh/`:
+
+- Non-root: `~/.wire/users.json`
+- Root: `/etc/wire/users.json`
+
+Example (`~/.wire/users.json`):
+
+```json
+{
+  "web1": "deploy",
+  "db1": "postgres"
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VSSH_SECRET` | Primary shared secret for native protocol (set on client and server). |
+| `VSSH_PORT` | Native server listen port (default: **48291**). |
+| `WIRE_SERVER_URL` | If `VSSH_SECRET` is empty, a derived secret can be computed from this URL (and from `server_url` in Wire JSON config). |
+| `VSSH_INSECURE_ALLOW_EMPTY_SECRET` | Set to `1` **only in isolated labs** to allow a native server with no secret (unsafe). |
+
+## Security
+
+- **Native `vssh server`** uses **HMAC** on a shared secret over **plain TCP**. **WireGuard** only encrypts traffic **inside the VPN**; it does **not** replace vssh authentication. Always set a strong secret (or derived secret) and firewall the listen port.
+- VSSH does not expose an OpenSSH wrapper command. Use `ssh` directly for normal sshd-backed shell access.
+- **`internal/adapter`**: discovery / `Probe` only; `Exec` is not implemented. Use native server commands for product execution.
+
+## Architecture
+
+| Package | Purpose |
+|---------|---------|
+| `internal/server` | Native protocol server and client |
+| `internal/ssh` | Discovery helper and legacy internal connector |
+| `internal/adapter` | Config-based node discovery and probing (Exec not implemented) |
+| `internal/agent` | Monitoring agent with event logging |

vssh-4.2.1/Makefile

@@ -0,0 +1,36 @@
+VERSION := 0.7.5
+BUILD_TIME := $(shell date -u '+%Y-%m-%d_%H:%M:%S')
+LDFLAGS := -ldflags "-s -w -X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME)"
+
+.PHONY: all build clean install test test-python release checksums
+
+all: build
+
+build:
+	go build $(LDFLAGS) -o vssh ./cmd/vssh
+
+test:
+	go test ./...
+	PYTHONPATH=src python3 -m unittest discover -s tests
+
+test-python:
+	PYTHONPATH=src python3 -m unittest discover -s tests
+
+clean:
+	rm -rf vssh vssh-* dist
+
+install: build
+	sudo cp vssh /usr/local/bin/
+	@echo "Installed to /usr/local/bin"
+
+release:
+	mkdir -p dist
+	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o dist/vssh-linux-amd64 ./cmd/vssh
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build $(LDFLAGS) -o dist/vssh-linux-arm64 ./cmd/vssh
+	CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o dist/vssh-darwin-amd64 ./cmd/vssh
+	CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o dist/vssh-darwin-arm64 ./cmd/vssh
+	$(MAKE) checksums
+	@ls -la dist
+
+checksums:
+	cd dist && shasum -a 256 vssh-* > checksums.txt