sitecard 0.1.0__tar.gz

sitecard-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: sitecard
+Version: 0.1.0
+Summary: Issue temporary SSH access cards for development workspaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: asyncssh==2.24.0
+Requires-Dist: cryptography>=39
+Requires-Dist: websockets
+
+# Sitecard
+
+Issue temporary SSH access cards for development sites and workspaces.
+
+This directory holds only the static sanitized README staged into the
+generated `sitecard` distribution. The distributable package itself is
+generated by `scripts/build-sitecard-dist.sh` and never checked in.
+
+## What it is
+
+Sitecard opens temporary authenticated SSH access to a selected development
+workspace for remote debugging and compatibility testing. The site is the
+workspace host; the card is the short-lived access path.
+
+- Distribution name: `sitecard`
+- Version: `0.1.0`
+- Description: `Issue temporary SSH access cards for development workspaces`
+- Requires Python `>=3.10`
+- Console script: `sitecard = sitecard.commands:main`
+
+## What it is not
+
+The generated distribution contains no deployment helpers, local secrets,
+target addresses, assessment keys, tests, or unrelated files.
+
+## Build
+
+From the repository root:
+
+```sh
+sh scripts/build-sitecard-dist.sh
+```
+
+Artifacts land in `dist/sitecard/`. The build fails if any
+case-insensitive occurrence of the internal project name remains in
+staging files, archive entry names, or archive file contents.
+
+## Use
+
+```sh
+sitecard -h
+sitecard serve --help
+sitecard serve .
+```
+
+`serve` is a true alias of `start` with identical arguments.

sitecard-0.1.0/README.md

@@ -0,0 +1,46 @@
+# Sitecard
+
+Issue temporary SSH access cards for development sites and workspaces.
+
+This directory holds only the static sanitized README staged into the
+generated `sitecard` distribution. The distributable package itself is
+generated by `scripts/build-sitecard-dist.sh` and never checked in.
+
+## What it is
+
+Sitecard opens temporary authenticated SSH access to a selected development
+workspace for remote debugging and compatibility testing. The site is the
+workspace host; the card is the short-lived access path.
+
+- Distribution name: `sitecard`
+- Version: `0.1.0`
+- Description: `Issue temporary SSH access cards for development workspaces`
+- Requires Python `>=3.10`
+- Console script: `sitecard = sitecard.commands:main`
+
+## What it is not
+
+The generated distribution contains no deployment helpers, local secrets,
+target addresses, assessment keys, tests, or unrelated files.
+
+## Build
+
+From the repository root:
+
+```sh
+sh scripts/build-sitecard-dist.sh
+```
+
+Artifacts land in `dist/sitecard/`. The build fails if any
+case-insensitive occurrence of the internal project name remains in
+staging files, archive entry names, or archive file contents.
+
+## Use
+
+```sh
+sitecard -h
+sitecard serve --help
+sitecard serve .
+```
+
+`serve` is a true alias of `start` with identical arguments.

sitecard-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sitecard"
+version = "0.1.0"
+description = "Issue temporary SSH access cards for development workspaces"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "asyncssh==2.24.0",
+    "cryptography>=39",
+    "websockets",
+]
+
+[project.scripts]
+sitecard = "sitecard.commands:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sitecard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sitecard-0.1.0/src/sitecard/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sitecard-0.1.0/src/sitecard/account.py

@@ -0,0 +1,23 @@
+"""Current-account helpers for hosts without a passwd database entry."""
+
+from __future__ import annotations
+
+import getpass
+import os
+
+
+def current_username(default: str = "sitecard") -> str:
+    """Return the current username, or a stable fallback for synthetic UIDs."""
+    try:
+        return getpass.getuser() or default
+    except (KeyError, OSError):
+        return default
+
+
+def ensure_username_environment(username: str | None = None) -> str:
+    """Populate the account variables required by libraries such as AsyncSSH."""
+    resolved = username or current_username()
+    for name in ("USER", "LOGNAME"):
+        if not os.environ.get(name):
+            os.environ[name] = resolved
+    return resolved

sitecard-0.1.0/src/sitecard/bridge.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Stdio/TCP <-> WebSocket bridge for the Sitecard cloudflare transport.
+
+Two modes pump a raw byte stream across a WebSocket relay (a Cloudflare Worker):
+
+  origin  Connects out to the relay and, on the first inbound byte, dials the
+          local SSH server, splicing the two. Loops to serve many sessions.
+  client  Connects out to the relay and splices it to stdin/stdout, so it can be
+          used as an ssh ProxyCommand.
+
+The relay pairs one "origin" and one "client" socket per tunnel id. The role
+is the final path segment of ``/relay/<session>/<role>``.
+
+Launched by the CLI as ``python -m sitecard.bridge`` for both the origin
+(remote) and client (ProxyCommand) roles; it needs the websockets package.
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+
+import websockets
+
+CHUNK = 65536
+CONNECT_KWARGS = dict(max_size=None, ping_interval=20, ping_timeout=20, close_timeout=5)
+
+
+def log(message):
+    sys.stderr.write("sitecard-bridge: " + message + "\n")
+    sys.stderr.flush()
+
+
+def role_url(base, role):
+    return base.rstrip("/") + "/" + role
+
+
+def _write_all(fd, data):
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        view = view[written:]
+
+
+async def _await_first_completed(*coros):
+    tasks = [asyncio.ensure_future(coro) for coro in coros]
+    done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+    for task in pending:
+        task.cancel()
+    for task in pending:
+        try:
+            await task
+        except (asyncio.CancelledError, Exception):  # noqa: BLE001 - draining only
+            pass
+    for task in done:
+        exc = task.exception()
+        if exc is not None:
+            raise exc
+
+
+async def run_client(base):
+    url = role_url(base, "client")
+    async with websockets.connect(url, **CONNECT_KWARGS) as ws:
+        loop = asyncio.get_event_loop()
+        stdin_fd = sys.stdin.fileno()
+
+        async def stdin_to_ws():
+            while True:
+                data = await loop.run_in_executor(None, os.read, stdin_fd, CHUNK)
+                if not data:
+                    break
+                await ws.send(data)
+
+        async def ws_to_stdout():
+            async for message in ws:
+                if isinstance(message, str):
+                    message = message.encode()
+                _write_all(1, message)
+
+        await _await_first_completed(stdin_to_ws(), ws_to_stdout())
+
+
+async def run_origin_once(base, host, port):
+    url = role_url(base, "origin")
+    async with websockets.connect(url, **CONNECT_KWARGS) as ws:
+        # Wait for the client's first byte before dialing the local server, so
+        # the server's SSH banner is never emitted into a peerless relay.
+        try:
+            first = await ws.recv()
+        except websockets.ConnectionClosed:
+            return
+        if isinstance(first, str):
+            first = first.encode()
+        reader, writer = await asyncio.open_connection(host, port)
+        writer.write(first)
+        await writer.drain()
+
+        async def tcp_to_ws():
+            while True:
+                data = await reader.read(CHUNK)
+                if not data:
+                    break
+                await ws.send(data)
+
+        async def ws_to_tcp():
+            async for message in ws:
+                if isinstance(message, str):
+                    message = message.encode()
+                writer.write(message)
+                await writer.drain()
+
+        try:
+            await _await_first_completed(tcp_to_ws(), ws_to_tcp())
+        finally:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:  # noqa: BLE001 - best-effort teardown
+                pass
+
+
+async def run_origin(base, host, port):
+    delay = 1
+    while True:
+        try:
+            await run_origin_once(base, host, port)
+            delay = 1
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - keep the tunnel alive
+            log("origin session ended: " + repr(exc))
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 30)
+            continue
+        await asyncio.sleep(0.5)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Sitecard WebSocket bridge")
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    client = sub.add_parser("client", help="stdio <-> relay (ssh ProxyCommand)")
+    client.add_argument("url", help="base relay URL, e.g. wss://host/relay/ID")
+
+    origin = sub.add_parser("origin", help="local SSH server <-> relay")
+    origin.add_argument("url", help="base relay URL, e.g. wss://host/relay/ID")
+    origin.add_argument("--host", default="127.0.0.1")
+    origin.add_argument("--port", type=int, required=True)
+
+    args = parser.parse_args(argv)
+    try:
+        if args.mode == "client":
+            asyncio.run(run_client(args.url))
+        else:
+            asyncio.run(run_origin(args.url, args.host, args.port))
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sitecard-0.1.0/src/sitecard/client_config.py

@@ -0,0 +1,116 @@
+"""The ssh-config block for Sitecard.
+
+``ssh-config`` prints a ``Host`` block so plain ``ssh USER@HOST`` works on the
+connecting machine. With no HOST it prints the default ``Host *.srv.us`` block
+for the srv.us transport; with a HOST it prints a block for that host using the
+currently configured transport's ProxyCommand. ``--write`` appends it to
+~/.ssh/config (never prepends, which would drag any leading global keywords
+under the new Host block), is idempotent, chmods the file to 0600, and then runs
+``ssh -G`` to confirm the block actually took effect.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SRVUS_PROXY_COMMAND = (
+    "openssl s_client -quiet -no_ign_eof -verify_return_error "
+    "-verify_hostname %h -connect %h:443 -servername %h 2>/dev/null"
+)
+DEFAULT_HOST = "*.srv.us"
+
+
+def block(host: str, proxy_command: str) -> str:
+    """Build the ssh-config block for a host and ProxyCommand."""
+    return (
+        f"Host {host}\n"
+        f"  ProxyCommand {proxy_command}\n"
+        "  StrictHostKeyChecking no\n"
+        "  UserKnownHostsFile /dev/null\n"
+        "  LogLevel ERROR"
+    )
+
+
+def config_path() -> Path:
+    return Path(os.path.expanduser("~/.ssh/config"))
+
+
+def print_block(
+    host: str = DEFAULT_HOST, proxy_command: str = SRVUS_PROXY_COMMAND
+) -> None:
+    print(block(host, proxy_command))
+
+
+def write(
+    host: str = DEFAULT_HOST, proxy_command: str = SRVUS_PROXY_COMMAND
+) -> int:
+    config = config_path()
+    ssh_dir = config.parent
+    try:
+        ssh_dir.mkdir(parents=True, exist_ok=True)
+        ssh_dir.chmod(0o700)
+    except OSError:
+        _error(f"Unable to prepare {ssh_dir}")
+        return 1
+
+    try:
+        present = config.is_file() and any(
+            line.strip().startswith("Host " + host)
+            for line in config.read_text().splitlines()
+        )
+    except OSError:
+        present = False
+    if present:
+        print(f"Already present in {config}")
+    else:
+        # Appending never changes the meaning of existing lines, unlike
+        # prepending, which would pull any leading global keywords under this
+        # Host block.
+        try:
+            with open(config, "a") as handle:
+                if config.exists() and config.stat().st_size > 0:
+                    handle.write("\n")
+                handle.write(block(host, proxy_command) + "\n")
+            config.chmod(0o600)
+        except OSError as error:
+            _error(f"Unable to write {config}: {error}")
+            return 1
+        print(f"Added the {host} block to {config}")
+
+    # ssh takes the first value it finds for each keyword, so an earlier
+    # matching block wins. Ask ssh what it will actually do rather than assuming.
+    ssh = shutil.which("ssh")
+    if ssh:
+        probe = host.replace("*", "example")
+        try:
+            resolved = subprocess.run(
+                [ssh, "-G", probe],
+                capture_output=True,
+                text=True,
+                timeout=15,
+            ).stdout
+        except (OSError, subprocess.SubprocessError):
+            return 0
+        proxycommand = next(
+            (
+                line.split(" ", 1)[1].strip()
+                for line in resolved.splitlines()
+                if line.lower().startswith("proxycommand ")
+            ),
+            "",
+        )
+        marker = proxy_command.split()[0]
+        if marker not in proxycommand:
+            _error(
+                f"Warning: an earlier block in {config} overrides it; move the "
+                f'{host} block above any "Host *" block.'
+            )
+    return 0
+
+
+def _error(message: str) -> None:
+    print(message, file=sys.stderr)