ssh-server-manager 0.2.0__py3-none-any.whl

ssh_server_manager/vault.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Protocol
+
+
+SERVICE_NAME = "ssh-server-manager"
+
+
+class VaultError(RuntimeError):
+    pass
+
+
+class VaultProtocol(Protocol):
+    def set_secret(self, credential_id: str, slot: str, value: str) -> None: ...
+
+    def get_secret(self, credential_id: str, slot: str) -> str | None: ...
+
+    def delete_secret(self, credential_id: str, slot: str) -> None: ...
+
+    def diagnose(self) -> dict[str, object]: ...
+
+
+def account_name(credential_id: str, slot: str) -> str:
+    if slot not in {"password", "passphrase"}:
+        raise VaultError(f"unsupported secret slot: {slot}")
+    return f"credential:{credential_id}:{slot}"
+
+
+class KeyringVault:
+    def __init__(self) -> None:
+        try:
+            import keyring
+            from keyring import errors
+        except ImportError as exc:
+            raise VaultError("Python keyring is not installed; run scripts/bootstrap") from exc
+        self.keyring = keyring
+        self.errors = errors
+        self.backend = keyring.get_keyring()
+        self._require_safe_backend()
+
+    def _require_safe_backend(self) -> None:
+        unsafe = ("null", "fail", "plaintext", "keyrings.alt", "filekeyring")
+
+        def check(backend: object) -> None:
+            backend_type = f"{backend.__class__.__module__}.{backend.__class__.__name__}".lower()
+            priority = getattr(backend, "priority", 0)
+            if any(marker in backend_type for marker in unsafe) or priority <= 0:
+                hint = ""
+                if sys.platform.startswith("linux"):
+                    hint = (
+                        "; on Linux install and unlock a Secret Service provider"
+                        " (gnome-keyring, KWallet, or KeePassXC with Secret Service enabled)"
+                        " — see docs/platforms.md for headless servers"
+                    )
+                raise VaultError(f"no safe OS credential backend is available ({backend_type}){hint}")
+            for child in getattr(backend, "backends", ()):
+                check(child)
+
+        check(self.backend)
+
+    def set_secret(self, credential_id: str, slot: str, value: str) -> None:
+        if not value:
+            raise VaultError("secret must not be empty")
+        try:
+            self.keyring.set_password(SERVICE_NAME, account_name(credential_id, slot), value)
+        except self.errors.KeyringError as exc:
+            raise VaultError(f"credential vault rejected the secret: {exc}") from exc
+
+    def get_secret(self, credential_id: str, slot: str) -> str | None:
+        try:
+            return self.keyring.get_password(SERVICE_NAME, account_name(credential_id, slot))
+        except self.errors.KeyringError as exc:
+            raise VaultError(f"credential vault could not read the secret: {exc}") from exc
+
+    def delete_secret(self, credential_id: str, slot: str) -> None:
+        try:
+            self.keyring.delete_password(SERVICE_NAME, account_name(credential_id, slot))
+        except self.errors.PasswordDeleteError:
+            return
+        except self.errors.KeyringError as exc:
+            raise VaultError(f"credential vault could not delete the secret: {exc}") from exc
+
+    def diagnose(self) -> dict[str, object]:
+        backend_type = f"{self.backend.__class__.__module__}.{self.backend.__class__.__name__}"
+        return {"available": True, "backend": backend_type, "priority": getattr(self.backend, "priority", None)}
+
+
+@dataclass
+class MemoryVault:
+    """In-memory vault used only by tests."""
+
+    values: dict[tuple[str, str], str]
+
+    def __init__(self) -> None:
+        self.values = {}
+
+    def set_secret(self, credential_id: str, slot: str, value: str) -> None:
+        self.values[(credential_id, slot)] = value
+
+    def get_secret(self, credential_id: str, slot: str) -> str | None:
+        return self.values.get((credential_id, slot))
+
+    def delete_secret(self, credential_id: str, slot: str) -> None:
+        self.values.pop((credential_id, slot), None)
+
+    def diagnose(self) -> dict[str, object]:
+        return {"available": True, "backend": "memory-test-only", "priority": 1}
+
+
+def get_vault() -> VaultProtocol:
+    return KeyringVault()

ssh_server_manager/webapp.py

@@ -0,0 +1,377 @@
+import asyncio
+import json
+import os
+import secrets
+import socket
+import stat
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .auth import AuthenticationError, RevealAuth
+from .db import ConflictError, Database, DatabaseError, NotFoundError
+from .importer import apply_import, preview_import
+from .paths import asset_dir, managed_ssh_config_path
+from .service import CredentialService
+from .ssh_config import SSHConfigError, render_config
+from .ssh_runner import SSHRunner
+from .validation import ValidationError
+from .vault import VaultError, get_vault
+
+
+SESSION_COOKIE = "ssm_session"
+
+
+class UIError(ValidationError):
+    """A user-actionable local UI launch error."""
+
+
+def _select_loopback_port(requested: int) -> int:
+    """Resolve a requested port before building the browser origin.
+
+    Port 0 asks the OS for an unused loopback port. Explicit ports are checked
+    early so a bind failure produces a useful CLI error instead of a traceback
+    after the one-time URL has already been emitted.
+    """
+    if not 0 <= requested <= 65535:
+        raise UIError("UI port must be between 0 and 65535")
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            probe.bind(("127.0.0.1", requested))
+        except OSError as exc:
+            raise UIError(
+                f"UI port {requested} is already in use; retry with --port 0 or choose another port"
+            ) from exc
+        return int(probe.getsockname()[1])
+
+
+def _write_private_url(path: Path, url: str) -> Path:
+    """Write a one-time launch URL without exposing it in command output."""
+    # Keep the final path component intact so an existing symlink cannot be
+    # resolved away before O_NOFOLLOW/lstat checks.
+    target = Path(os.path.abspath(os.fspath(path.expanduser())))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists() or target.is_symlink():
+        info = target.lstat()
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+            raise UIError(f"launch URL path is not a regular file: {target}")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(target, flags, 0o600)
+    try:
+        if hasattr(os, "fchmod"):
+            os.fchmod(descriptor, stat.S_IRUSR | stat.S_IWUSR)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            descriptor = -1
+            handle.write(url)
+            handle.write("\n")
+    finally:
+        if descriptor != -1:
+            os.close(descriptor)
+    if os.name == "nt":
+        os.chmod(target, stat.S_IRUSR | stat.S_IWUSR)
+    return target
+
+
+@dataclass
+class BrowserSession:
+    csrf: str
+    created_at: float = field(default_factory=time.time)
+    reveal_grants: dict[str, float] = field(default_factory=dict)
+    failed_master_attempts: list[float] = field(default_factory=list)
+
+
+class WebState:
+    def __init__(
+        self,
+        database: Database,
+        *,
+        launch_token: str,
+        origin: str,
+        launch_url_file: Path | None = None,
+    ) -> None:
+        self.database = database
+        self.launch_token = launch_token
+        self.launch_token_used = False
+        self.launch_url_file = launch_url_file
+        self.origin = origin
+        self.sessions: dict[str, BrowserSession] = {}
+        self.auth = RevealAuth(database, rp_id="localhost", origin=origin)
+
+    def create_session(self) -> tuple[str, BrowserSession]:
+        identifier = secrets.token_urlsafe(32)
+        session = BrowserSession(csrf=secrets.token_urlsafe(32))
+        self.sessions[identifier] = session
+        return identifier, session
+
+    def clean(self) -> None:
+        cutoff = time.time() - 12 * 60 * 60
+        self.sessions = {key: value for key, value in self.sessions.items() if value.created_at > cutoff}
+
+    def consume_launch_url_file(self) -> None:
+        if self.launch_url_file is None:
+            return
+        try:
+            self.launch_url_file.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def create_app(database: Database, *, launch_token: str, port: int, launch_url_file: Path | None = None):
+    try:
+        from fastapi import Body, Depends, FastAPI, HTTPException, Request, Response
+        from fastapi.responses import FileResponse, JSONResponse
+    except ImportError as exc:
+        raise RuntimeError("UI dependencies are missing; run scripts/bootstrap") from exc
+
+    origin = f"http://localhost:{port}"
+    state = WebState(database, launch_token=launch_token, origin=origin, launch_url_file=launch_url_file)
+    app = FastAPI(title="SSH Server Manager", docs_url=None, redoc_url=None, openapi_url=None)
+
+    @app.middleware("http")
+    async def security_middleware(request: Request, call_next):
+        host = request.headers.get("host", "").split(":", 1)[0].strip("[]").casefold()
+        if host not in {"localhost", "127.0.0.1", "::1"}:
+            return JSONResponse({"error": "invalid host"}, status_code=400)
+        request_origin = request.headers.get("origin")
+        if request_origin and request_origin != state.origin:
+            return JSONResponse({"error": "invalid origin"}, status_code=403)
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "no-referrer"
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; "
+            "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"
+        )
+        if request.url.path.startswith("/api/"):
+            response.headers["Cache-Control"] = "no-store"
+        return response
+
+    @app.exception_handler(AuthenticationError)
+    @app.exception_handler(ValidationError)
+    @app.exception_handler(DatabaseError)
+    @app.exception_handler(VaultError)
+    @app.exception_handler(SSHConfigError)
+    async def expected_error(_request: Request, exc: Exception):
+        status = 404 if isinstance(exc, NotFoundError) else 409 if isinstance(exc, ConflictError) else 400
+        return JSONResponse({"ok": False, "error": exc.__class__.__name__, "message": str(exc)}, status_code=status)
+
+    def browser_session(request: Request) -> tuple[str, BrowserSession]:
+        identifier = request.cookies.get(SESSION_COOKIE)
+        session = state.sessions.get(identifier or "")
+        if not identifier or not session:
+            raise HTTPException(status_code=401, detail="browser session is not initialized")
+        return identifier, session
+
+    async def csrf_session(request: Request) -> tuple[str, BrowserSession]:
+        identifier, session = browser_session(request)
+        supplied = request.headers.get("x-csrf-token")
+        if not supplied or not secrets.compare_digest(supplied, session.csrf):
+            raise HTTPException(status_code=403, detail="invalid CSRF token")
+        return identifier, session
+
+    @app.get("/")
+    async def index(request: Request, token: str | None = None):
+        state.clean()
+        identifier = request.cookies.get(SESSION_COOKIE)
+        session = state.sessions.get(identifier or "")
+        new_identifier = None
+        if not session:
+            if state.launch_token_used or not token or not secrets.compare_digest(token, state.launch_token):
+                raise HTTPException(status_code=401, detail="use the one-time URL opened by serverctl ui")
+            state.launch_token_used = True
+            state.consume_launch_url_file()
+            new_identifier, session = state.create_session()
+        response = FileResponse(asset_dir() / "index.html", headers={"Cache-Control": "no-store"})
+        if new_identifier:
+            response.set_cookie(
+                SESSION_COOKIE,
+                new_identifier,
+                httponly=True,
+                samesite="strict",
+                secure=False,
+                max_age=12 * 60 * 60,
+                path="/",
+            )
+        return response
+
+    @app.get("/assets/{filename}")
+    async def assets(filename: str, _session=Depends(browser_session)):
+        if filename not in {"app.js", "styles.css"}:
+            raise HTTPException(status_code=404)
+        return FileResponse(asset_dir() / filename)
+
+    @app.get("/api/bootstrap")
+    async def bootstrap(session_data=Depends(browser_session)):
+        _identifier, session = session_data
+        return {
+            "csrf": session.csrf,
+            "servers": database.list_servers(),
+            "credentials": database.list_credentials(),
+            "auth": state.auth.status(),
+            "managed_config": str(managed_ssh_config_path()),
+        }
+
+    @app.post("/api/servers")
+    async def add_server(payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)):
+        result = database.create_server(**payload)
+        render_config(database)
+        return result
+
+    @app.put("/api/servers/{identifier}")
+    async def update_server(identifier: str, payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)):
+        result = database.update_server(identifier, **payload)
+        render_config(database)
+        return result
+
+    @app.delete("/api/servers/{identifier}")
+    async def remove_server(identifier: str, _session=Depends(csrf_session)):
+        result = database.delete_server(identifier)
+        render_config(database)
+        return result
+
+    @app.post("/api/servers/{identifier}/test")
+    async def test_server(identifier: str, _session=Depends(csrf_session)):
+        return await asyncio.to_thread(SSHRunner(database).test, identifier)
+
+    @app.post("/api/import/preview")
+    async def import_preview(payload: dict[str, Any] = Body(default={}), _session=Depends(csrf_session)):
+        return await asyncio.to_thread(preview_import, database, config=payload.get("config"))
+
+    @app.post("/api/import/apply")
+    async def import_apply(payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)):
+        preview = await asyncio.to_thread(preview_import, database, config=payload.get("config"))
+        result = apply_import(database, preview, overwrite=bool(payload.get("overwrite")))
+        render_config(database)
+        return result
+
+    @app.post("/api/credentials")
+    async def add_credential(payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)):
+        service = CredentialService(database, get_vault())
+        kind = payload.get("kind")
+        if kind == "password":
+            result = service.create_password(payload.get("label", ""), payload.get("secret", ""))
+        elif kind == "key":
+            result = service.create_key(
+                payload.get("label", ""), payload.get("key_path", ""), payload.get("passphrase") or None
+            )
+        elif kind == "agent":
+            result = service.create_agent(payload.get("label", ""))
+        else:
+            raise ValidationError("unsupported credential kind")
+        render_config(database)
+        return result
+
+    @app.put("/api/credentials/{identifier}")
+    async def update_credential(
+        identifier: str, payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)
+    ):
+        service = CredentialService(database, get_vault())
+        result = service.update(
+            identifier,
+            label=payload.get("label"),
+            key_path=payload.get("key_path"),
+            secret=payload.get("secret"),
+            passphrase=payload.get("passphrase"),
+            clear_passphrase=bool(payload.get("clear_passphrase")),
+        )
+        render_config(database)
+        return result
+
+    @app.delete("/api/credentials/{identifier}")
+    async def remove_credential(identifier: str, _session=Depends(csrf_session)):
+        result = CredentialService(database, get_vault()).delete(identifier)
+        render_config(database)
+        return result
+
+    @app.post("/api/auth/passkey/register/options")
+    async def passkey_register_options(session_data=Depends(csrf_session)):
+        identifier, _session = session_data
+        return state.auth.begin_registration(identifier)
+
+    @app.post("/api/auth/passkey/register/verify")
+    async def passkey_register_verify(
+        payload: dict[str, Any] = Body(...), session_data=Depends(csrf_session)
+    ):
+        identifier, _session = session_data
+        return state.auth.finish_registration(identifier, payload)
+
+    @app.post("/api/auth/master/enroll")
+    async def master_enroll(payload: dict[str, Any] = Body(...), _session=Depends(csrf_session)):
+        return state.auth.enroll_master_password(payload.get("password", ""))
+
+    @app.post("/api/auth/reveal/options")
+    async def reveal_options(payload: dict[str, Any] = Body(...), session_data=Depends(csrf_session)):
+        identifier, _session = session_data
+        database.get_credential(payload.get("credential_id", ""))
+        return state.auth.begin_authentication(identifier)
+
+    @app.post("/api/auth/reveal/verify")
+    async def reveal_verify(payload: dict[str, Any] = Body(...), session_data=Depends(csrf_session)):
+        identifier, session = session_data
+        credential_id = payload.get("credential_id", "")
+        state.auth.finish_authentication(identifier, payload.get("response", {}))
+        session.reveal_grants[credential_id] = time.time() + 30
+        return {"ok": True}
+
+    @app.post("/api/auth/master/verify")
+    async def master_verify(payload: dict[str, Any] = Body(...), session_data=Depends(csrf_session)):
+        _identifier, session = session_data
+        now = time.time()
+        session.failed_master_attempts = [item for item in session.failed_master_attempts if item > now - 60]
+        if len(session.failed_master_attempts) >= 5:
+            raise AuthenticationError("too many failed attempts; wait one minute")
+        if not state.auth.verify_master_password(payload.get("password", "")):
+            session.failed_master_attempts.append(now)
+            raise AuthenticationError("master password is incorrect")
+        credential_id = payload.get("credential_id", "")
+        database.get_credential(credential_id)
+        session.reveal_grants[credential_id] = now + 30
+        return {"ok": True}
+
+    @app.post("/api/credentials/{identifier}/reveal")
+    async def reveal_credential(identifier: str, session_data=Depends(csrf_session)):
+        _session_id, session = session_data
+        expires = session.reveal_grants.pop(identifier, 0)
+        if expires < time.time():
+            raise AuthenticationError("reauthentication is required")
+        result = CredentialService(database, get_vault()).reveal(identifier)
+        return JSONResponse(result, headers={"Cache-Control": "no-store"})
+
+    return app
+
+
+def run_ui(
+    *, database: Database, port: int = 0, open_browser: bool = True, url_file: Path | None = None
+) -> None:
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise RuntimeError("UI dependencies are missing; run scripts/bootstrap") from exc
+    if not open_browser and url_file is None:
+        raise UIError("--no-open requires --url-file so the one-time URL stays out of terminal output")
+    actual_port = _select_loopback_port(port)
+    launch_token = secrets.token_urlsafe(32)
+    url = f"http://localhost:{actual_port}/?token={launch_token}"
+    if url_file is not None:
+        written = _write_private_url(url_file, url)
+        print(f"SSH Server Manager launch URL written to {written}", flush=True)
+    elif open_browser:
+        print(f"SSH Server Manager opening in your browser on port {actual_port}", flush=True)
+    if open_browser:
+        threading.Timer(0.8, lambda: webbrowser.open(url)).start()
+    app = create_app(database, launch_token=launch_token, port=actual_port, launch_url_file=url_file)
+    try:
+        uvicorn.run(app, host="127.0.0.1", port=actual_port, log_level="warning", access_log=False)
+    finally:
+        if url_file is not None:
+            try:
+                url_file.unlink(missing_ok=True)
+            except OSError:
+                pass

ssh_server_manager-0.2.0.dist-info/METADATA

@@ -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)