ssh-server-manager 0.2.0__tar.gz

ssh_server_manager-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: ssh-server-manager
+Version: 0.2.0
+Summary: Local-first SSH host and credential manager for humans and AI agents — OS-keychain vault, loopback web UI, agent-safe by design
+License: MIT
+Project-URL: Homepage, https://xiayh0107.github.io/servers-connect/
+Project-URL: Repository, https://github.com/xiayh0107/servers-connect
+Project-URL: Documentation, https://github.com/xiayh0107/servers-connect/tree/main/ssh-server-manager/docs
+Project-URL: Changelog, https://github.com/xiayh0107/servers-connect/blob/main/ssh-server-manager/CHANGELOG.md
+Keywords: ssh,credentials,keychain,keyring,agent-skill,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: keyring>=25.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: webauthn>=2.2
+Provides-Extra: test
+Requires-Dist: httpx>=0.28; extra == "test"
+Requires-Dist: pytest>=8.0; extra == "test"
+
+# SSH Server Manager
+
+**A local-first SSH host and credential manager for humans and AI agents.**
+One CLI (`serverctl`) and a loopback-only web UI to add, import, test, and
+connect to your servers — with every password and passphrase stored in your
+operating system's native credential vault, never in a plaintext file.
+
+[![test](https://github.com/xiayh0107/servers-connect/actions/workflows/test.yml/badge.svg)](https://github.com/xiayh0107/servers-connect/actions/workflows/test.yml)
+[![release](https://img.shields.io/github/v/release/xiayh0107/servers-connect)](https://github.com/xiayh0107/servers-connect/releases)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](../LICENSE)
+
+[简体中文说明](README.zh-CN.md) · [Documentation](docs/) · [Security model](docs/security.md) · [Website](https://xiayh0107.github.io/servers-connect/)
+
+> 🤖 **Using an AI agent?** The skill deploys to every agent on your machine
+> in one line — dependencies, links, and health check included. See the
+> [agent deployment guide](docs/ai-agents.md).
+
+---
+
+## Why this exists
+
+Most SSH managers make you choose between convenience and custody:
+
+- **Cloud-synced clients** (subscription GUIs) keep your credentials on
+  someone else's infrastructure.
+- **Plain `~/.ssh/config`** keeps you in control but handles no passwords,
+  no vault, and gives AI coding agents an easy way to leak secrets.
+- **`sshpass`-style wrappers** put passwords in files, env vars, or shell
+  history.
+
+SSH Server Manager is different by construction:
+
+| Property | How |
+|---|---|
+| Secrets never touch disk in plaintext | macOS Keychain / Windows Credential Locker / Linux Secret Service via `keyring`; unsafe backends are rejected as a hard error |
+| Your `~/.ssh/config` is never modified | A separate managed config is rendered and included alongside it |
+| The web UI is unreachable from the network | Loopback-only bind, one-time launch token, CSRF + Origin checks, strict CSP |
+| Revealing a stored secret requires re-auth | WebAuthn passkey (Touch ID / Windows Hello) or an Argon2id master password; grants are single-use and expire in 30 s |
+| AI agents can drive it without seeing secrets | Every command has `--json`; SSH authentication happens through AskPass so secrets never appear in argv, env, logs, or model context |
+| Host keys are always verified | `StrictHostKeyChecking` is never weakened, by policy and by code |
+
+## Quick start
+
+```bash
+git clone https://github.com/xiayh0107/servers-connect.git
+cd servers-connect/ssh-server-manager
+./scripts/bootstrap          # Windows: scripts\bootstrap.cmd
+./scripts/serverctl doctor   # verify ssh, vault backend, and dependencies
+```
+
+Add a server and connect:
+
+```bash
+./scripts/serverctl credential add-password work-password   # prompts locally, stores in OS vault
+./scripts/serverctl server add web1 --hostname web1.example.com --username deploy --credential work-password
+./scripts/serverctl server test web1
+./scripts/serverctl connect web1
+```
+
+Or import everything you already have:
+
+```bash
+./scripts/serverctl server import          # preview only
+./scripts/serverctl server import --apply
+```
+
+Prefer a GUI? `./scripts/serverctl ui` opens the local web interface in your
+browser with a one-time tokenized URL.
+
+## Features
+
+- **Connection profiles** — alias, host, port, user, notes, ordered
+  ProxyJump chains (with cycle detection).
+- **Three credential kinds** — vault-backed passwords, private keys with
+  optional vault-backed passphrases, and ssh-agent/OpenSSH defaults.
+  Credentials are reusable across servers and protected against deletion
+  while referenced.
+- **OpenSSH import** — parses your `~/.ssh/config` (following `Include`),
+  resolves each literal alias with `ssh -G`, previews before applying.
+- **Managed config rendering** — atomic, user-only-permission writes to
+  `~/.ssh/ssh-server-manager.conf`; your original config always loads last
+  so unrelated defaults keep working.
+- **Connection testing** — `server test` reports latency and a classified
+  error code (`authentication-failed`, `host-key-untrusted`, `timeout`,
+  `dns-failed`, …) and records history.
+- **Remote execution** — `serverctl exec alias -- cmd args`, with `--shell`
+  for pipelines, `--stdin`/`--stdin-binary` for streaming files, `--reuse N`
+  for ControlMaster connection sharing (macOS/Linux), and `--json` for
+  machine-readable results.
+- **Local web UI** — manage servers and credentials, test connections,
+  import config, and reveal a stored secret after passkey or master-password
+  re-authentication.
+- **Diagnostics** — `serverctl doctor` checks ssh availability and version,
+  vault backend safety, database and config paths, and Python dependencies.
+
+## Platform support
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| CLI + web UI | ✅ | ✅ | ✅ |
+| Credential vault | Keychain | Secret Service (gnome-keyring / KWallet / KeePassXC) | Credential Locker |
+| Secret reveal re-auth | Touch ID passkey or master password | passkey or master password | Windows Hello passkey or master password |
+| Connection reuse (`--reuse`) | ✅ | ✅ | — (OpenSSH ControlMaster needs Unix sockets; a warning is printed) |
+
+Details and headless-server notes: [docs/platforms.md](docs/platforms.md).
+CI runs the full test suite on all three platforms.
+
+## For AI agents
+
+This project ships as an Agent Skill ([SKILL.md](SKILL.md)) so Claude Code,
+Codex, and other agents can manage servers safely: agents get structured
+JSON output and connection error classification, while the AskPass
+architecture keeps secrets out of the model's context by design.
+
+Deploy the skill with one line:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xiayh0107/servers-connect/main/install.sh | sh
+```
+
+It links the skill into every detected agent (`~/.claude/skills`,
+`~/.codex/skills`, …), installs dependencies, and runs `doctor`. Windows
+uses `install.ps1`. See [docs/ai-agents.md](docs/ai-agents.md).
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [docs/installation.md](docs/installation.md) | Per-platform install, requirements, bootstrap |
+| [docs/quickstart.md](docs/quickstart.md) | First 10 minutes, common workflows |
+| [docs/cli.md](docs/cli.md) | Complete `serverctl` reference |
+| [docs/web-ui.md](docs/web-ui.md) | Web UI walkthrough and its security gates |
+| [docs/security.md](docs/security.md) | Threat model and security invariants |
+| [docs/platforms.md](docs/platforms.md) | Platform-specific behavior, headless Linux |
+| [docs/ai-agents.md](docs/ai-agents.md) | Using with Claude Code / Codex / MCP |
+| [docs/faq.md](docs/faq.md) | Troubleshooting and common questions |
+
+## License
+
+[MIT](../LICENSE)

ssh_server_manager-0.2.0/README.md

@@ -0,0 +1,140 @@
+# SSH Server Manager
+
+**A local-first SSH host and credential manager for humans and AI agents.**
+One CLI (`serverctl`) and a loopback-only web UI to add, import, test, and
+connect to your servers — with every password and passphrase stored in your
+operating system's native credential vault, never in a plaintext file.
+
+[![test](https://github.com/xiayh0107/servers-connect/actions/workflows/test.yml/badge.svg)](https://github.com/xiayh0107/servers-connect/actions/workflows/test.yml)
+[![release](https://img.shields.io/github/v/release/xiayh0107/servers-connect)](https://github.com/xiayh0107/servers-connect/releases)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](../LICENSE)
+
+[简体中文说明](README.zh-CN.md) · [Documentation](docs/) · [Security model](docs/security.md) · [Website](https://xiayh0107.github.io/servers-connect/)
+
+> 🤖 **Using an AI agent?** The skill deploys to every agent on your machine
+> in one line — dependencies, links, and health check included. See the
+> [agent deployment guide](docs/ai-agents.md).
+
+---
+
+## Why this exists
+
+Most SSH managers make you choose between convenience and custody:
+
+- **Cloud-synced clients** (subscription GUIs) keep your credentials on
+  someone else's infrastructure.
+- **Plain `~/.ssh/config`** keeps you in control but handles no passwords,
+  no vault, and gives AI coding agents an easy way to leak secrets.
+- **`sshpass`-style wrappers** put passwords in files, env vars, or shell
+  history.
+
+SSH Server Manager is different by construction:
+
+| Property | How |
+|---|---|
+| Secrets never touch disk in plaintext | macOS Keychain / Windows Credential Locker / Linux Secret Service via `keyring`; unsafe backends are rejected as a hard error |
+| Your `~/.ssh/config` is never modified | A separate managed config is rendered and included alongside it |
+| The web UI is unreachable from the network | Loopback-only bind, one-time launch token, CSRF + Origin checks, strict CSP |
+| Revealing a stored secret requires re-auth | WebAuthn passkey (Touch ID / Windows Hello) or an Argon2id master password; grants are single-use and expire in 30 s |
+| AI agents can drive it without seeing secrets | Every command has `--json`; SSH authentication happens through AskPass so secrets never appear in argv, env, logs, or model context |
+| Host keys are always verified | `StrictHostKeyChecking` is never weakened, by policy and by code |
+
+## Quick start
+
+```bash
+git clone https://github.com/xiayh0107/servers-connect.git
+cd servers-connect/ssh-server-manager
+./scripts/bootstrap          # Windows: scripts\bootstrap.cmd
+./scripts/serverctl doctor   # verify ssh, vault backend, and dependencies
+```
+
+Add a server and connect:
+
+```bash
+./scripts/serverctl credential add-password work-password   # prompts locally, stores in OS vault
+./scripts/serverctl server add web1 --hostname web1.example.com --username deploy --credential work-password
+./scripts/serverctl server test web1
+./scripts/serverctl connect web1
+```
+
+Or import everything you already have:
+
+```bash
+./scripts/serverctl server import          # preview only
+./scripts/serverctl server import --apply
+```
+
+Prefer a GUI? `./scripts/serverctl ui` opens the local web interface in your
+browser with a one-time tokenized URL.
+
+## Features
+
+- **Connection profiles** — alias, host, port, user, notes, ordered
+  ProxyJump chains (with cycle detection).
+- **Three credential kinds** — vault-backed passwords, private keys with
+  optional vault-backed passphrases, and ssh-agent/OpenSSH defaults.
+  Credentials are reusable across servers and protected against deletion
+  while referenced.
+- **OpenSSH import** — parses your `~/.ssh/config` (following `Include`),
+  resolves each literal alias with `ssh -G`, previews before applying.
+- **Managed config rendering** — atomic, user-only-permission writes to
+  `~/.ssh/ssh-server-manager.conf`; your original config always loads last
+  so unrelated defaults keep working.
+- **Connection testing** — `server test` reports latency and a classified
+  error code (`authentication-failed`, `host-key-untrusted`, `timeout`,
+  `dns-failed`, …) and records history.
+- **Remote execution** — `serverctl exec alias -- cmd args`, with `--shell`
+  for pipelines, `--stdin`/`--stdin-binary` for streaming files, `--reuse N`
+  for ControlMaster connection sharing (macOS/Linux), and `--json` for
+  machine-readable results.
+- **Local web UI** — manage servers and credentials, test connections,
+  import config, and reveal a stored secret after passkey or master-password
+  re-authentication.
+- **Diagnostics** — `serverctl doctor` checks ssh availability and version,
+  vault backend safety, database and config paths, and Python dependencies.
+
+## Platform support
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| CLI + web UI | ✅ | ✅ | ✅ |
+| Credential vault | Keychain | Secret Service (gnome-keyring / KWallet / KeePassXC) | Credential Locker |
+| Secret reveal re-auth | Touch ID passkey or master password | passkey or master password | Windows Hello passkey or master password |
+| Connection reuse (`--reuse`) | ✅ | ✅ | — (OpenSSH ControlMaster needs Unix sockets; a warning is printed) |
+
+Details and headless-server notes: [docs/platforms.md](docs/platforms.md).
+CI runs the full test suite on all three platforms.
+
+## For AI agents
+
+This project ships as an Agent Skill ([SKILL.md](SKILL.md)) so Claude Code,
+Codex, and other agents can manage servers safely: agents get structured
+JSON output and connection error classification, while the AskPass
+architecture keeps secrets out of the model's context by design.
+
+Deploy the skill with one line:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xiayh0107/servers-connect/main/install.sh | sh
+```
+
+It links the skill into every detected agent (`~/.claude/skills`,
+`~/.codex/skills`, …), installs dependencies, and runs `doctor`. Windows
+uses `install.ps1`. See [docs/ai-agents.md](docs/ai-agents.md).
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [docs/installation.md](docs/installation.md) | Per-platform install, requirements, bootstrap |
+| [docs/quickstart.md](docs/quickstart.md) | First 10 minutes, common workflows |
+| [docs/cli.md](docs/cli.md) | Complete `serverctl` reference |
+| [docs/web-ui.md](docs/web-ui.md) | Web UI walkthrough and its security gates |
+| [docs/security.md](docs/security.md) | Threat model and security invariants |
+| [docs/platforms.md](docs/platforms.md) | Platform-specific behavior, headless Linux |
+| [docs/ai-agents.md](docs/ai-agents.md) | Using with Claude Code / Codex / MCP |
+| [docs/faq.md](docs/faq.md) | Troubleshooting and common questions |
+
+## License
+
+[MIT](../LICENSE)

ssh_server_manager-0.2.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "ssh-server-manager"
+version = "0.2.0"
+description = "Local-first SSH host and credential manager for humans and AI agents — OS-keychain vault, loopback web UI, agent-safe by design"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+keywords = ["ssh", "credentials", "keychain", "keyring", "agent-skill", "devops"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Security",
+]
+
+dependencies = [
+  "argon2-cffi>=23.1",
+  "fastapi>=0.115",
+  "keyring>=25.0",
+  "platformdirs>=4.0",
+  "uvicorn>=0.34",
+  "webauthn>=2.2",
+]
+
+[project.urls]
+Homepage = "https://xiayh0107.github.io/servers-connect/"
+Repository = "https://github.com/xiayh0107/servers-connect"
+Documentation = "https://github.com/xiayh0107/servers-connect/tree/main/ssh-server-manager/docs"
+Changelog = "https://github.com/xiayh0107/servers-connect/blob/main/ssh-server-manager/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+serverctl = "ssh_server_manager.cli:main"
+ssh-server-manager-askpass = "ssh_server_manager.askpass:main"
+
+[tool.setuptools]
+package-dir = {"" = "scripts"}
+packages = ["ssh_server_manager"]
+
+[tool.setuptools.package-data]
+ssh_server_manager = ["assets/ui/*"]
+
+[project.optional-dependencies]
+test = ["httpx>=0.28", "pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

ssh_server_manager-0.2.0/scripts/ssh_server_manager/__init__.py

@@ -0,0 +1,4 @@
+"""SSH Server Manager implementation."""
+
+__version__ = "0.2.0"
+

ssh_server_manager-0.2.0/scripts/ssh_server_manager/askpass.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def load_descriptors() -> list[dict[str, Any]]:
+    try:
+        value = json.loads(os.environ.get("SSM_ASKPASS_MAP", "[]"))
+    except json.JSONDecodeError:
+        return []
+    return value if isinstance(value, list) else []
+
+
+def choose_descriptor(prompt: str, descriptors: list[dict[str, Any]]) -> dict[str, Any] | None:
+    lowered = prompt.casefold()
+    if "yes/no" in lowered or ("fingerprint" in lowered and "continue connecting" in lowered):
+        return None
+    passphrases = [item for item in descriptors if item.get("slot") == "passphrase"]
+    if "passphrase" in lowered:
+        for item in passphrases:
+            key_path = str(item.get("key_path", ""))
+            if key_path.casefold() in lowered or Path(key_path).name.casefold() in lowered:
+                return item
+        return passphrases[0] if len(passphrases) == 1 else None
+    passwords = [item for item in descriptors if item.get("slot") == "password"]
+    if "password" in lowered:
+        scored: list[tuple[int, dict[str, Any]]] = []
+        for item in passwords:
+            score = sum(
+                bool(value and str(value).casefold() in lowered)
+                for value in (item.get("username"), item.get("hostname"), item.get("alias"))
+            )
+            scored.append((score, item))
+        scored.sort(key=lambda pair: pair[0], reverse=True)
+        if scored and (scored[0][0] > 0 or len(scored) == 1):
+            return scored[0][1]
+    return None
+
+
+def main() -> int:
+    prompt = sys.argv[1] if len(sys.argv) > 1 else ""
+    item = choose_descriptor(prompt, load_descriptors())
+    if not item:
+        return 1
+    try:
+        from .vault import get_vault
+
+        secret = get_vault().get_secret(item["credential_id"], item["slot"])
+    except Exception:
+        return 1
+    if not secret:
+        return 1
+    sys.stdout.write(secret)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+