sh-agent 0.1.0__py3-none-any.whl

sh_agent/__init__.py

@@ -0,0 +1,19 @@
+from .auth import Authenticator, AuthError, Identity
+from .config import Config
+from .protocol import PROTOCOL_VERSION, ClientMessage, ServerMessage
+from .pty_session import PtySession, RingBuffer
+from .registry import AuditLog, SessionRegistry
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "AuditLog",
+    "AuthError",
+    "Authenticator",
+    "ClientMessage",
+    "Config",
+    "Identity",
+    "PtySession",
+    "RingBuffer",
+    "ServerMessage",
+    "SessionRegistry",
+]

sh_agent/__main__.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+
+import uvicorn
+
+from . import onboarding
+from .app import create_app
+from .auth import AuthConfig
+from .config import Config, tailnet_address
+
+
+def _pairing_banner(
+    bind: str,
+    port: int,
+    token: str,
+    write_token: str | None,
+    generated: bool = False,
+) -> None:
+    """Print the address, a scannable code, and a copy-pasteable link.
+
+    Every line is flushed as it is produced. The agent runs forever afterwards, so
+    anything left in a buffer would never reach the user -- and the QR is the one
+    piece of output somebody cannot wait for.
+    """
+    tailnet = tailnet_address()
+    print(f"sh-agent listening on {bind}:{port}", flush=True)
+    if tailnet and bind == tailnet:
+        print(f"reachable from tailnet at {bind}:{port}", flush=True)
+
+    host, source = onboarding.resolve_pairing_host(bind, tailnet)
+    if not host:
+        print(
+            f"not printing a pairing code: listening on {bind}, which a phone cannot reach.\n"
+            "start with SH_HOST=0.0.0.0 (shared LAN) or run Tailscale for tailnet access.",
+            flush=True,
+        )
+        return
+
+    uri = onboarding.pairing_uri(host, port, token, write_token)
+    if generated:
+        print(
+            f"generated a new token, stored in {onboarding.DEFAULT_CONFIG_DIR / 'agent.env'}",
+            flush=True,
+        )
+    if source == "lan":
+        print(
+            f"pairing over the local network ({host}); run Tailscale to pair from anywhere",
+            flush=True,
+        )
+    print("\nPair your phone by scanning this, or open the link:\n", flush=True)
+    print(onboarding.render_qr(uri), flush=True)
+    print(f"\n{uri}\n", flush=True)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="sh-agent")
+    parser.add_argument("--host", default=None)
+    parser.add_argument("--port", type=int, default=None)
+    parser.add_argument("--allow-lan", action="store_true")
+    parser.add_argument("--shell", default=None)
+    parser.add_argument("--cwd", default=None)
+    parser.add_argument("--palette", default=None)
+    parser.add_argument("--audit", default=None)
+    parser.add_argument("--generate-token", action="store_true")
+    parser.add_argument("--print-bind", action="store_true")
+    parser.add_argument(
+        "--pairing",
+        action="store_true",
+        help="print the pairing code for the current token and exit",
+    )
+    args = parser.parse_args()
+
+    if args.generate_token:
+        print(secrets.token_urlsafe(32))
+        return 0
+
+    config = Config()
+    if args.host:
+        config.host = args.host
+    if args.port:
+        config.port = args.port
+    if args.allow_lan:
+        config.allow_lan = True
+    if args.shell:
+        config.shell = args.shell
+    if args.cwd:
+        config.cwd = args.cwd
+    if args.palette:
+        config.palette_path = args.palette
+    if args.audit:
+        config.audit_path = args.audit
+    config.auth = Config().auth
+
+    if args.print_bind:
+        print(config.public_bind)
+        return 0
+
+    # Resolve credentials before building the auth config, so a token generated on
+    # this run is the one the agent actually serves. Environment wins, then a
+    # previously stored token, then a freshly generated one that gets persisted --
+    # a generated token that is not stored leaves the phone's saved copy invalid
+    # the moment this terminal closes, with no way to recover it.
+    credentials = onboarding.load_or_create(
+        env_token=os.environ.get("SH_TOKEN"),
+        env_write_token=os.environ.get("SH_WRITE_TOKEN"),
+    )
+    config.auth = AuthConfig(
+        token=credentials.token,
+        write_token=credentials.write_token,
+        tailscale_require=config.auth.tailscale_require,
+        tailscale_allow=config.auth.tailscale_allow,
+        tailscale_socket=config.auth.tailscale_socket,
+    )
+
+    bind = config.public_bind
+
+    # --pairing reprints the code without starting a server, so a second phone can
+    # be added, or a lost one replaced, without touching the host.
+    if args.pairing:
+        _pairing_banner(bind, config.port, credentials.token, credentials.write_token, credentials.generated)
+        return 0
+
+    if config.allow_lan:
+        print("WARNING: LAN binding enabled; the daemon is reachable outside the tailnet", flush=True)
+
+    _pairing_banner(bind, config.port, credentials.token, credentials.write_token, credentials.generated)
+
+    if config.auth.write_token:
+        print("palette write access: ENABLED", flush=True)
+    else:
+        print("palette write access: disabled (set SH_WRITE_TOKEN to enable)", flush=True)
+
+    uvicorn.run(create_app(config), host=bind, port=config.port, log_level="info", access_log=False)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sh_agent/app.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from .auth import Authenticator, AuthError
+from .config import Config
+from .palette import PaletteStore
+from .registry import AuditLog, SessionRegistry
+from .routes import commands, health, session
+from .tmux import SlugNamer
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    config: Config = app.state.config
+    audit: AuditLog = app.state.audit
+    loop = asyncio.get_running_loop()
+
+    registry = SessionRegistry(
+        loop=loop,
+        shell=config.shell,
+        cwd=config.cwd,
+        idle_ttl=config.idle_ttl,
+        max_sessions=config.max_sessions,
+        detach_grace=config.detach_grace,
+        reap_interval=config.reap_interval,
+        ring_capacity=config.ring_capacity,
+        namer=SlugNamer(config.tmux_secret),
+        tmux_max_sessions=config.tmux_max_sessions,
+        tmux_idle_ttl=config.tmux_idle_ttl,
+        tmux_enabled=config.tmux_enabled,
+    )
+    app.state.registry = registry
+    registry.start_reaper()
+
+    audit.record(
+        "agent.start",
+        bind=f"{config.public_bind}:{config.port}",
+        allow_lan=config.allow_lan,
+        write_enabled=bool(config.auth.write_token),
+        tailscale_required=config.auth.tailscale_require,
+    )
+    if audit.error:
+        print(
+            f"WARNING: audit log disabled -- {audit.error}\n"
+            f"         set SH_AUDIT to a writable path to record auth and session events",
+            file=sys.stderr,
+        )
+    try:
+        yield
+    finally:
+        audit.record("agent.stop")
+        await registry.shutdown()
+
+
+def create_app(config: Config | None = None) -> FastAPI:
+    resolved = config or Config()
+    app = FastAPI(
+        title="sh agent",
+        version="0.1.0",
+        lifespan=lifespan,
+        docs_url=None,
+        redoc_url=None,
+    )
+    app.state.config = resolved
+    app.state.audit = AuditLog(resolved.audit_path)
+    app.state.palette = PaletteStore(resolved.palette_path)
+    app.state.authenticator = Authenticator(resolved.auth)
+
+    @app.exception_handler(AuthError)
+    async def auth_error_handler(request: Request, exc: AuthError) -> JSONResponse:
+        resolved_audit: AuditLog = request.app.state.audit
+        resolved_audit.record(
+            "auth.rejected",
+            peer_ip=request.client.host if request.client else None,
+            reason=str(exc),
+            status=exc.status_code,
+        )
+        headers = {"WWW-Authenticate": "Bearer"} if exc.status_code == 401 else None
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"detail": str(exc)},
+            headers=headers,
+        )
+
+    app.include_router(health.router)
+    app.include_router(session.router)
+    app.include_router(commands.router)
+    return app
+
+
+app = create_app()

sh_agent/auth.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import hmac
+import http.client
+import json
+import os
+import socket
+from dataclasses import dataclass, field
+
+from .env import bool_env as _bool_env
+from .env import list_env as _list_env
+
+TAILSCALE_SOCKET = "/var/run/tailscale/tailscaled.sock"
+LOCALAPI_PREFIX = "/localapi/v0"
+
+
+@dataclass
+class Identity:
+    peer_ip: str | None = None
+    login: str | None = None
+    node: str | None = None
+    verified_by: str = "token"
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "peer_ip": self.peer_ip,
+            "login": self.login,
+            "node": self.node,
+            "verified_by": self.verified_by,
+        }
+
+
+class AuthError(Exception):
+    def __init__(self, message: str, status_code: int = 401) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass
+class AuthConfig:
+    token: str | None = None
+    write_token: str | None = None
+    tailscale_require: bool = field(default_factory=lambda: _bool_env("SH_TAILSCALE_REQUIRE"))
+    tailscale_allow: list[str] = field(default_factory=lambda: _list_env("SH_TAILSCALE_ALLOW"))
+    tailscale_socket: str = field(
+        default_factory=lambda: os.environ.get("SH_TAILSCALE_SOCKET", TAILSCALE_SOCKET)
+    )
+
+    @classmethod
+    def from_env(cls) -> AuthConfig:
+        return cls(
+            token=os.environ.get("SH_TOKEN") or None,
+            write_token=os.environ.get("SH_WRITE_TOKEN") or None,
+        )
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    def __init__(self, socket_path: str, timeout: float = 2.0) -> None:
+        super().__init__("localhost", timeout=timeout)
+        self._socket_path = socket_path
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        sock.connect(self._socket_path)
+        self.sock = sock
+
+
+class TailscaleWhois:
+    def __init__(self, socket_path: str = TAILSCALE_SOCKET) -> None:
+        self._socket_path = socket_path
+
+    def available(self) -> bool:
+        return os.path.exists(self._socket_path)
+
+    def lookup(self, addr: str) -> dict[str, object]:
+        conn = _UnixHTTPConnection(self._socket_path)
+        try:
+            conn.request("GET", f"{LOCALAPI_PREFIX}/whois?addr={addr}")
+            response = conn.getresponse()
+            body = response.read()
+        finally:
+            conn.close()
+        if response.status != 200:
+            raise AuthError(f"whois failed with status {response.status}")
+        return json.loads(body)
+
+
+class Authenticator:
+    def __init__(self, config: AuthConfig, whois: TailscaleWhois | None = None) -> None:
+        self.config = config
+        self.whois = whois or TailscaleWhois(config.tailscale_socket)
+
+    def _constant_time_equals(self, provided: str | None, expected: str | None) -> bool:
+        if not expected or provided is None:
+            return False
+        return hmac.compare_digest(provided, expected)
+
+    def extract_bearer(self, authorization: str | None) -> str | None:
+        if not authorization:
+            return None
+        scheme, _, value = authorization.partition(" ")
+        if scheme.lower() != "bearer" or not value.strip():
+            return None
+        return value.strip()
+
+    def identify(self, peer_ip: str | None) -> Identity:
+        identity = Identity(peer_ip=peer_ip)
+        if peer_ip and self.whois.available():
+            try:
+                data = self.whois.lookup(f"{peer_ip}:0")
+            except Exception:
+                data = None
+            if isinstance(data, dict):
+                logins = (data.get("UserProfile") or {}).get("LoginName") or []
+                if logins:
+                    identity.login = str(logins[0])
+                    identity.node = data.get("NodeName")
+                    identity.verified_by = "tailscale"
+        return identity
+
+    def _enforce_tailnet(self, identity: Identity) -> Identity:
+        if self.config.tailscale_require and identity.verified_by != "tailscale":
+            raise AuthError("tailscale identity required but unavailable")
+        if self.config.tailscale_allow:
+            if identity.verified_by != "tailscale":
+                raise AuthError("peer is not on the tailnet")
+            if identity.login not in self.config.tailscale_allow:
+                raise AuthError(f"identity not allowed: {identity.login}")
+        return identity
+
+    def enforce(self, authorization: str | None, peer_ip: str | None) -> Identity:
+        if not self.config.token:
+            raise AuthError("server has no SH_TOKEN configured")
+        if not self._constant_time_equals(self.extract_bearer(authorization), self.config.token):
+            raise AuthError("invalid token")
+        return self._enforce_tailnet(self.identify(peer_ip))
+
+    def enforce_write(self, authorization: str | None, peer_ip: str | None) -> Identity:
+        provided = self.extract_bearer(authorization)
+        if not self.config.write_token:
+            raise AuthError("write access disabled: set SH_WRITE_TOKEN to enable", status_code=403)
+        if self._constant_time_equals(provided, self.config.write_token):
+            return self._enforce_tailnet(self.identify(peer_ip))
+        if self.config.token and self._constant_time_equals(provided, self.config.token):
+            raise AuthError("write token required", status_code=403)
+        raise AuthError("invalid token")

sh_agent/config.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+import socket
+from dataclasses import dataclass, field
+
+from .auth import AuthConfig
+from .env import bool_env as _bool_env
+from .env import float_env as _float_env
+from .env import int_env as _int_env
+
+DEFAULT_PORT = 8765
+DEFAULT_PALETTE_PATH = os.path.expanduser("~/.config/sh/palette.json")
+DEFAULT_AUDIT_PATH = os.path.expanduser("~/.local/state/sh/audit.log")
+
+
+def tailnet_address() -> str | None:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
+            probe.settimeout(0.2)
+            probe.connect(("100.100.100.100", 1))
+            address = probe.getsockname()[0]
+        return address if address.startswith("100.") else None
+    except OSError:
+        return None
+
+
+@dataclass
+class Config:
+    host: str = field(default_factory=lambda: os.environ.get("SH_HOST", "127.0.0.1"))
+    port: int = field(default_factory=lambda: _int_env("SH_PORT", DEFAULT_PORT))
+    allow_lan: bool = field(
+        default_factory=lambda: os.environ.get("SH_ALLOW_LAN", "").lower() in {"1", "true", "yes"}
+    )
+    shell: str | None = field(default_factory=lambda: os.environ.get("SH_SHELL"))
+    cwd: str | None = field(default_factory=lambda: os.environ.get("SH_CWD") or None)
+    palette_path: str = field(default_factory=lambda: os.environ.get("SH_PALETTE", DEFAULT_PALETTE_PATH))
+    audit_path: str | None = field(default_factory=lambda: os.environ.get("SH_AUDIT", DEFAULT_AUDIT_PATH))
+    idle_ttl: float = field(default_factory=lambda: _float_env("SH_IDLE_TTL", 30 * 60.0))
+    detach_grace: float = field(default_factory=lambda: _float_env("SH_DETACH_GRACE", 120.0))
+    reap_interval: float = field(default_factory=lambda: _float_env("SH_REAP_INTERVAL", 15.0))
+    max_sessions: int = field(default_factory=lambda: _int_env("SH_MAX_SESSIONS", 8))
+    ring_capacity: int = field(default_factory=lambda: _int_env("SH_RING_CAPACITY", 256 * 1024))
+    auth: AuthConfig = field(default_factory=AuthConfig.from_env)
+    tmux_enabled: bool = field(default_factory=lambda: _bool_env("SH_TMUX_ENABLED", True))
+    tmux_max_sessions: int = field(default_factory=lambda: _int_env("SH_TMUX_MAX_SESSIONS", 12))
+    tmux_idle_ttl: float = field(default_factory=lambda: _float_env("SH_TMUX_IDLE_TTL", 3600.0))
+
+    @property
+    def tmux_secret(self) -> str:
+        configured = os.environ.get("SH_TMUX_SECRET")
+        if configured:
+            return configured
+        return self.auth.token or "sh-default"
+
+    @property
+    def public_bind(self) -> str:
+        if self.allow_lan:
+            return self.host
+        return tailnet_address() or self.host

sh_agent/env.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+
+
+def int_env(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def float_env(name: str, default: float) -> float:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def bool_env(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def list_env(name: str) -> list[str]:
+    raw = os.environ.get(name, "")
+    return [item.strip() for item in raw.split(",") if item.strip()]

sh_agent/onboarding.py

@@ -0,0 +1,185 @@
+"""Persisted credentials and phone pairing.
+
+The token used to be generated, printed and thrown away, which meant closing the
+terminal that started the agent invalidated whatever the phone had already saved
+with no way to recover it. It is now written to a file the agent reads on the
+next start, and the phone pairs by scanning a QR code rather than by someone
+reading an IP off one line and typing it into a phone keyboard.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import quote
+
+DEFAULT_CONFIG_DIR = Path(os.environ.get("SH_CONFIG_DIR") or Path.home() / ".config" / "sh")
+SCHEME = "sh"
+
+
+@dataclass
+class Credentials:
+    token: str
+    write_token: str | None = None
+    generated: bool = False
+
+
+def generate_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    """Read KEY=VALUE lines, ignoring anything unparseable.
+
+    This file is written by us, but a user editing it by hand should not get a
+    stack trace because of a stray comment or a blank line.
+    """
+    values: dict[str, str] = {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return values
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not key:
+            continue
+        value = value.strip().strip("'\"")
+        if value:
+            values[key] = value
+    return values
+
+
+def _write_env_file(path: Path, values: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Written literally, not percent-encoded: systemd parses EnvironmentFile as
+    # KEY=value, so encoding here would corrupt the token it hands the agent.
+    # token_urlsafe only ever emits [A-Za-z0-9_-], which needs no quoting.
+    lines = []
+    for key, value in values.items():
+        if "\n" in value or "\r" in value or " " in value:
+            raise ValueError(f"refusing to persist {key}: value is not safe for an env file")
+        lines.append(f"{key}={value}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    # The token is a shell credential; 0600 so it is not world-readable, and a
+    # directory that does not leak its contents.
+    path.chmod(0o600)
+    try:
+        path.parent.chmod(0o700)
+    except OSError:
+        pass
+
+
+def load_or_create(
+    config_dir: Path | None = None,
+    env_token: str | None = None,
+    env_write_token: str | None = None,
+) -> Credentials:
+    """Resolve credentials from the environment, falling back to a stored file.
+
+    Precedence is environment, then a previously stored token, then a freshly
+    generated one. Only the generated token is ever written back: an environment
+    variable is a per-run override, and persisting it would let a value that
+    happened to be set for one invocation -- a test harness, a shell export --
+    silently become permanent configuration.
+    """
+    directory = config_dir or DEFAULT_CONFIG_DIR
+    path = directory / "agent.env"
+
+    stored = _parse_env_file(path) if path.exists() else {}
+
+    token = env_token or stored.get("SH_TOKEN") or ""
+    write_token = env_write_token or stored.get("SH_WRITE_TOKEN") or None
+    generated = False
+
+    if not token:
+        token = generate_token()
+        generated = True
+        stored["SH_TOKEN"] = token
+        try:
+            _write_env_file(path, stored)
+        except OSError:
+            # A read-only home should not stop the agent from running; the token
+            # is printed in that case so the user can still pair.
+            pass
+
+    return Credentials(token=token, write_token=write_token, generated=generated)
+
+
+def local_address() -> str | None:
+    """The address this machine reaches the outside world from.
+
+    Used to turn a wildcard bind into something a phone can actually dial. The
+    UDP connect sends no packets; it just asks the routing table which local
+    address would be used, which avoids enumerating interfaces.
+    """
+    import socket
+
+    for probe in ("100.100.100.100", "8.8.8.8"):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+                sock.settimeout(0.2)
+                sock.connect((probe, 1))
+                return str(sock.getsockname()[0])
+        except OSError:
+            continue
+    return None
+
+
+def resolve_pairing_host(bind: str, tailnet: str | None = None) -> tuple[str | None, str]:
+    """Pick an address to put in the pairing code, and say why.
+
+    A wildcard bind is what the agent listens on, not what a phone dials, so it
+    never appears in a pairing code. The tailnet address is preferred over the
+    LAN one because it is the only one that also works off the home network.
+    """
+    if tailnet and bind != "127.0.0.1":
+        return tailnet, "tailnet"
+    if bind not in ("0.0.0.0", "::", ""):
+        if bind in ("127.0.0.1", "::1", "localhost"):
+            return None, "loopback"
+        return bind, "configured"
+    address = local_address()
+    if address:
+        return address, "lan"
+    return None, "unknown"
+
+
+def pairing_uri(host: str, port: int, token: str, write_token: str | None = None) -> str:
+    """A link the phone can open or scan.
+
+    Percent-encoded rather than JSON so the QR payload stays a plain URI that a
+    camera app, a browser and the app's own deep-link handler all understand.
+    """
+    parts = [f"host={quote(host, safe='')}", f"port={port}", f"token={quote(token, safe='')}"]
+    if write_token:
+        parts.append(f"wt={quote(write_token, safe='')}")
+    return f"{SCHEME}://connect?{'&'.join(parts)}"
+
+
+def render_qr(uri: str, border: int = 2) -> str:
+    """A scannable QR in the terminal.
+
+    segno renders to text with no image dependency, which matters for a package
+    whose whole job is to run on whatever machine someone has. It writes to the
+    stream it is given and returns None, so it is handed a buffer rather than
+    being allowed to print behind the caller's back.
+
+    compact=True draws each module as a half-block glyph instead of a coloured
+    space. The default output depends on the terminal honouring ANSI colour and
+    turns into unreadable escape codes the moment it is piped to a file, run
+    under tmux, or read by a camera that cannot resolve the colour.
+    """
+    try:
+        import segno
+    except ImportError:  # pragma: no cover - segno is a declared dependency
+        return ""
+    buffer = io.StringIO()
+    segno.make(uri, error="m").terminal(out=buffer, border=border, compact=True)
+    return buffer.getvalue()