ssh-over-sse-cli 0.1.0__py3-none-any.whl

ssh_over_sse_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: ssh-over-sse-cli
+Version: 0.1.0
+Summary: OpenSSH ProxyCommand client for ssh-sse/v1
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=45
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+# ssh-sse-cli
+
+Connect to SSH servers through an HTTPS gateway with your usual OpenSSH commands.
+
+## Install
+
+Requires Linux or macOS, Python 3.12 or newer, and OpenSSH.
+
+With uv:
+
+```sh
+uv tool install --python 3.12 ssh-over-sse-cli
+```
+
+Or with pip:
+
+```sh
+pip install 'ssh-over-sse[cli]'
+```
+
+Use `ssh-over-sse[all]` with pip to install the gateway command too.
+Supported keys are Ed25519, RSA (2048–8192 bits), and ECDSA (P-256, P-384, P-521).
+Load encrypted keys into `ssh-agent` before use.
+
+## Configure SSH
+
+Ask your administrator for the gateway URL and an allowed destination. Add an
+entry to your SSH configuration, replacing the example values:
+
+```sshconfig
+Host my-server
+    HostName 192.0.2.20
+    Port 22
+    User alice
+    IdentityFile ~/.ssh/id_ed25519
+    IdentitiesOnly yes
+    StrictHostKeyChecking yes
+    ProxyCommand ssh-sse-cli --url https://gateway.example.com --ssh-host %n
+```
+
+Connect or transfer files normally:
+
+```sh
+ssh my-server
+scp report.txt my-server:report.txt
+sftp my-server
+```
+
+The client reads the destination, port, SSH user, and first available identity
+from the selected host. `--target`, `--user`, and `-i` override those values.
+If you use `ssh -F`, pass the same file using `--ssh-config` in the ProxyCommand.
+To pass outer command-line user or port overrides, add `--user %r --target %h:%p`.
+
+Your public key must be authorized by the gateway account and destination server.
+Your private key stays on your computer. Keep SSH host-key verification enabled.
+
+## Check your key
+
+Open the gateway URL in a browser to view the landing page. Then run:
+
+```sh
+ssh-sse-cli --url https://gateway.example.com check
+```
+
+Without a host alias, the identity defaults to `~/.ssh/id_ed25519`. To select a
+key or use an existing SSH host's identity:
+
+```sh
+ssh-sse-cli --url https://gateway.example.com -i ~/.ssh/id_ecdsa check
+ssh-sse-cli --url https://gateway.example.com --ssh-host my-server check
+```
+
+The check requires no destination or SSH user. It verifies gateway access without
+connecting to a destination. Success prints
+`Gateway SSH key authentication succeeded.` and exits with status 0. Errors exit
+with status 1. HTTP 401 means the key was rejected; HTTP 500 indicates a gateway
+or server error.
+
+For a direct backend check, use its HTTP address:
+
+```sh
+ssh-sse-cli --url http://192.0.2.10:7010 -i ~/.ssh/id_ecdsa check
+```
+
+SSH connections use the public HTTPS URL. A successful key check does not confirm
+destination permissions or the destination's SSH login.
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `--url` | Gateway root URL |
+| `--ssh-host` | Read connection and identity settings from an SSH host alias |
+| `--ssh-config` | Read an alternate SSH configuration file |
+| `--target` | Override the destination as `HOST:PORT`; bracket IPv6 addresses |
+| `--user` | Override the destination SSH username |
+| `-i`, `--identity` | Select an identity file |
+| `--config` | Read client settings from a file |
+| `--ca-file` | Trust a private HTTPS certificate authority |
+| `--log-level` | Set diagnostics to `DEBUG`, `INFO`, `WARNING`, or `ERROR` |
+
+Client settings default to `~/.config/ssh-over-sse/client.yaml` when that file
+exists. Store your gateway URL there to omit `--url`:
+
+```yaml
+url: https://gateway.example.com
+```
+
+Command-line options take precedence. Connection diagnostics appear on stderr;
+`check` prints its success message on stdout.
+
+## Troubleshooting
+
+If authentication fails, check the URL, selected key, and gateway authorization.
+For encrypted keys, check that the identity is loaded into `ssh-agent`. Ask your
+administrator to confirm destination permissions if the key check succeeds but
+SSH cannot connect. After an interruption, start a new connection.
+
+```sh
+ssh-sse-cli --help
+```

ssh_over_sse_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ssh_sse_tool/__init__.py,sha256=yEo61nlPcB0HIPTn9MtlKWVxnZkOmbJnEvH0aI-L8OQ,40
+ssh_sse_tool/auth.py,sha256=u_j3DMvebsfIWNSoWqkXtLeBDvfQCUXgWBimxrfY-bQ,2609
+ssh_sse_tool/cli.py,sha256=C6AB86o2y3XDMKQ6lt17UNjIFh1BBWJfzTQ58kVFHyA,2558
+ssh_sse_tool/config.py,sha256=zeBamyb4UO2GdFRMMi6BxaApGIyBXxIMdC63e1NdP_U,8915
+ssh_sse_tool/protocol.py,sha256=GlY3t-rF4zK0Dy7RxeFqpLDgikjDsh3QlY5aaLZaMA8,1290
+ssh_sse_tool/sse.py,sha256=iP69t9XzPgj_suqIq68VdT-n2wDhq78gC-iwryB0Eg8,3320
+ssh_sse_tool/stdio.py,sha256=1ZtTzLib7ngXuQRoTkn2L8uyYS9KbAZB6YdBQRz-eP4,1515
+ssh_sse_tool/transport.py,sha256=u4ZBudzn8zdWDlKKlspcUvMmCuc8LF7oI-u1qQjA7m0,11189
+ssh_over_sse_cli-0.1.0.dist-info/METADATA,sha256=b47afg0-kYRBfveLbERxHf3R_MBErSjMeqGjlrGHrEk,4040
+ssh_over_sse_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ssh_over_sse_cli-0.1.0.dist-info/entry_points.txt,sha256=wO_cvxhdFSS0MHg0sjy8koJDvVwSLUjkVhx7V1mRsQk,54
+ssh_over_sse_cli-0.1.0.dist-info/RECORD,,

ssh_over_sse_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ssh_over_sse_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ssh-sse-cli = ssh_sse_tool.cli:main

ssh_sse_tool/__init__.py

@@ -0,0 +1 @@
+"""SSH-over-SSE ProxyCommand client."""

ssh_sse_tool/auth.py

@@ -0,0 +1,65 @@
+"""OpenSSH SSHSIG signer, including public-key path + ssh-agent support."""
+
+import asyncio
+import base64
+import hashlib
+from pathlib import Path
+
+from cryptography.exceptions import UnsupportedAlgorithm
+from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePublicKey
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, load_ssh_public_key
+
+
+async def command(*args, data=None):
+    process = await asyncio.create_subprocess_exec(
+        *args,
+        stdin=asyncio.subprocess.PIPE if data is not None else asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL,
+    )
+    try:
+        stdout, _ = await asyncio.wait_for(process.communicate(data), 10)
+        if process.returncode:
+            raise ValueError("SSH key operation failed; load your identity into ssh-agent")
+        return stdout
+    finally:
+        if process.returncode is None:
+            process.kill()
+            await process.wait()
+
+
+async def identity_key(identity):
+    path = Path(identity)
+    pub = path if path.suffix == ".pub" else Path(str(path) + ".pub")
+    if pub.is_file():
+        if pub.stat().st_size > 8192:
+            raise ValueError("public key too large")
+        line = pub.read_bytes().strip()
+    else:
+        line = (await command("ssh-keygen", "-y", "-f", str(path))).strip()
+    try:
+        key = load_ssh_public_key(line)
+    except UnsupportedAlgorithm:
+        raise ValueError("unsupported SSH public key") from None
+    if not isinstance(key, (Ed25519PublicKey, RSAPublicKey, EllipticCurvePublicKey)):
+        raise ValueError("unsupported SSH public key")
+    if isinstance(key, RSAPublicKey) and not 2048 <= key.key_size <= 8192:
+        raise ValueError("RSA keys must be 2048 to 8192 bits")
+    if isinstance(key, EllipticCurvePublicKey) and key.curve.name not in (
+        "secp256r1",
+        "secp384r1",
+        "secp521r1",
+    ):
+        raise ValueError("unsupported ECDSA curve")
+    normalized = key.public_bytes(Encoding.OpenSSH, PublicFormat.OpenSSH).decode()
+    blob = base64.b64decode(normalized.split()[1], validate=True)
+    fp = "SHA256:" + base64.b64encode(hashlib.sha256(blob).digest()).decode().rstrip("=")
+    return normalized, fp
+
+
+async def sign(identity, namespace, message):
+    return base64.b64encode(
+        await command("ssh-keygen", "-Y", "sign", "-f", identity, "-n", namespace, data=message)
+    ).decode()

ssh_sse_tool/cli.py

@@ -0,0 +1,86 @@
+"""Local OpenSSH ProxyCommand entrypoint. stdout is raw SSH bytes only."""
+
+import argparse
+import asyncio
+import logging
+import signal
+import sys
+
+import httpx
+import yaml
+
+from .config import settings
+from .stdio import Stdio
+from .transport import GatewayError, Transport
+
+
+async def run(config):
+    stdio = Stdio()
+    task = asyncio.current_task()
+    assert task is not None
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, task.cancel)
+    try:
+        await Transport(config).run(stdio)
+    finally:
+        stdio.close()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.remove_signal_handler(sig)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="ssh-sse-cli", description="OpenSSH ProxyCommand over HTTPS POST + SSE"
+    )
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=["check"],
+        help="verify gateway access with your SSH key without connecting to a target",
+    )
+    for name in (
+        "url",
+        "target",
+        "user",
+        "config",
+        "log-level",
+        "ca-file",
+        "ssh-host",
+        "ssh-config",
+    ):
+        parser.add_argument("--" + name)
+    parser.add_argument("-i", "--identity", help="SSH identity file")
+    parser.add_argument(
+        "--test-only-allow-http-localhost", action="store_true", help=argparse.SUPPRESS
+    )
+    args = parser.parse_args()
+    try:
+        config = settings(args)
+        # HTTP-library debug logs can contain authorization headers: never enable them.
+        logging.basicConfig(level=getattr(logging, config.log_level), stream=sys.stderr)
+        logging.getLogger("httpx").setLevel(logging.CRITICAL)
+        logging.getLogger("httpcore").setLevel(logging.CRITICAL)
+        if args.command == "check":
+            asyncio.run(Transport(config).check())
+            print("Gateway SSH key authentication succeeded.")
+        else:
+            asyncio.run(run(config))
+    except GatewayError as error:
+        parser.exit(1, f"ssh-sse-cli: {error}\n")
+    except (
+        ValueError,
+        OSError,
+        TimeoutError,
+        TypeError,
+        KeyError,
+        RecursionError,
+        yaml.YAMLError,
+        httpx.HTTPError,
+    ):
+        parser.exit(
+            1,
+            "ssh-sse-cli: authentication or transport failed; check configuration, key agent and gateway audit logs\n",
+        )
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        parser.exit(130, "ssh-sse-cli: interrupted\n")

ssh_sse_tool/config.py

@@ -0,0 +1,242 @@
+"""Client arguments/config validation, with no production TLS bypass."""
+
+import getpass
+import ipaddress
+import os
+import re
+import socket
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+
+
+class UniqueLoader(yaml.SafeLoader):
+    pass
+
+
+def unique_mapping(loader, node):
+    result = {}
+    for k, v in node.value:
+        key = loader.construct_object(k)
+        if not isinstance(key, str) or key in result:
+            raise ValueError("duplicate config key")
+        result[key] = loader.construct_object(v)
+    return result
+
+
+UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, unique_mapping)
+
+
+def target(value):
+    if not isinstance(value, str) or any(c.isspace() for c in value):
+        raise ValueError("invalid target")
+    pattern = r"\[([^\]]+)\]:([0-9]+)" if value.startswith("[") else r"([^:\[\]]+):([0-9]+)"
+    match = re.fullmatch(pattern, value)
+    if not match or not 1 <= int(match[2]) <= 65535:
+        raise ValueError("target must be HOST:PORT (bracket IPv6)")
+    host = match[1]
+    try:
+        host = str(ipaddress.ip_address(host))
+    except ValueError:
+        if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9.-]{0,252}", host):
+            raise ValueError("invalid target host") from None
+    return host, int(match[2])
+
+
+def base_url(value, test_only_http=False, *, allow_http_check=False):
+    if not isinstance(value, str) or any(c.isspace() for c in value):
+        raise ValueError("invalid gateway URL")
+    parsed = urlsplit(value)
+    if not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("invalid gateway URL")
+    if parsed.scheme != "https":
+        if (not test_only_http and not allow_http_check) or parsed.scheme != "http":
+            raise ValueError("HTTPS is required")
+        try:
+            loopback = ipaddress.ip_address(parsed.hostname).is_loopback
+        except ValueError:
+            loopback = parsed.hostname == "localhost"
+        if not loopback and not allow_http_check:
+            raise ValueError("test HTTP requires loopback")
+    if not re.fullmatch(r"(?:/[a-zA-Z0-9_-]+)*/?", parsed.path):
+        raise ValueError("invalid base URL path")
+    _ = parsed.port  # validate port syntax/range
+    return value.rstrip("/")
+
+
+@dataclass(frozen=True)
+class Settings:
+    url: str
+    host: str
+    port: int
+    user: str
+    principal: str | None
+    identity: str
+    namespace: str = "ssh-sse-gateway@your-organization.example"
+    ca_file: str | None = None
+    request_timeout: float = 30
+    stream_timeout: float = 75
+    log_level: str = "WARNING"
+
+
+def ssh_defaults(alias, config_file=None, user=None):
+    """Read effective local OpenSSH configuration without opening a connection."""
+    if not isinstance(alias, str) or not re.fullmatch(r"[A-Za-z0-9_.:@\[\]-]{1,253}", alias):
+        raise ValueError("invalid SSH host alias")
+    command = ["ssh", "-G"]
+    if config_file is not None:
+        if not isinstance(config_file, str):
+            raise ValueError("invalid SSH config path")
+        command.extend(["-F", str(Path(config_file).expanduser())])
+    if user is not None:
+        if not isinstance(user, str) or not re.fullmatch(r"[a-zA-Z0-9_@.+-]{1,128}", user):
+            raise ValueError("invalid SSH user")
+        command.extend(["-l", user])
+    command.extend(["--", alias])
+    try:
+        result = subprocess.run(
+            command,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        raise ValueError("cannot read effective SSH configuration") from None
+    if result.returncode or len(result.stdout) > 1048576:
+        raise ValueError("cannot read effective SSH configuration")
+    values: dict[str, str] = {}
+    identities = []
+    for line in result.stdout.splitlines():
+        name, separator, value = line.partition(" ")
+        if not separator:
+            continue
+        if name == "identityfile":
+            identities.append(value)
+        elif name in ("hostname", "port", "user"):
+            values.setdefault(name, value)
+    if set(values) != {"hostname", "port", "user"}:
+        raise ValueError("incomplete effective SSH configuration")
+    hostname = values["hostname"]
+    tokens = {
+        "%": "%",
+        "d": str(Path.home()),
+        "h": hostname,
+        "n": alias,
+        "r": values["user"],
+        "p": values["port"],
+        "u": getpass.getuser(),
+        "i": str(os.getuid()),
+        "l": socket.gethostname(),
+    }
+    for identity in identities:
+        if identity.lower() == "none":
+            continue
+
+        def expand(match):
+            if match[1] not in tokens:
+                raise ValueError("unsupported IdentityFile token; specify --identity")
+            return tokens[match[1]]
+
+        path = Path(os.path.expandvars(re.sub(r"%(.)", expand, identity))).expanduser()
+        if path.is_file():
+            values["identity"] = str(path)
+            break
+        public = Path(str(path) + ".pub")
+        if public.is_file():
+            values["identity"] = str(public)
+            break
+    host = f"[{hostname}]" if ":" in hostname else hostname
+    values["target"] = host + ":" + values["port"]
+    return values
+
+
+def settings(args):
+    raw = {}
+    default_config = Path.home() / ".config/ssh-over-sse/client.yaml"
+    config_path = args.config or (str(default_config) if default_config.is_file() else None)
+    if config_path:
+        path = Path(config_path).expanduser()
+        if path.stat().st_size > 65536:
+            raise ValueError("config too large")
+        raw = yaml.load(path.read_text(), Loader=UniqueLoader)
+        allowed = {
+            "url",
+            "target",
+            "user",
+            "principal",
+            "identity",
+            "namespace",
+            "ca_file",
+            "request_timeout",
+            "stream_timeout",
+            "log_level",
+            "ssh_host",
+            "ssh_config",
+        }
+        if not isinstance(raw, dict) or set(raw) - allowed:
+            raise ValueError("invalid client config")
+    for key in (
+        "url",
+        "target",
+        "user",
+        "identity",
+        "log_level",
+        "ca_file",
+        "ssh_host",
+        "ssh_config",
+    ):
+        value = getattr(args, key, None)
+        if value is not None:
+            raw[key] = value
+    alias = raw.pop("ssh_host", None)
+    ssh_config = raw.pop("ssh_config", None)
+    if alias is not None:
+        defaults = ssh_defaults(alias, ssh_config, raw.get("user"))
+        for key in ("target", "user", "identity"):
+            if key in defaults:
+                raw.setdefault(key, defaults[key])
+        if "identity" not in raw:
+            raise ValueError("no usable IdentityFile for this host; specify --identity")
+    elif ssh_config is not None:
+        raise ValueError("--ssh-config requires --ssh-host")
+    if getattr(args, "command", None) == "check":
+        # Settings retains its transport fields; check proofs carry no destination.
+        raw.setdefault("target", "localhost:22")
+        raw.setdefault("user", getpass.getuser())
+    raw.setdefault("identity", "~/.ssh/id_ed25519")
+    for key in ("url", "target", "user", "identity"):
+        if not isinstance(raw.get(key), str) or not raw[key]:
+            raise ValueError(f"{key} is required")
+    host, port = target(raw.pop("target"))
+    raw["url"] = base_url(
+        raw["url"],
+        args.test_only_allow_http_localhost,
+        allow_http_check=getattr(args, "command", None) == "check",
+    )
+    raw.setdefault("principal", None)
+    for key in ("user", "principal"):
+        if key == "principal" and raw[key] is None:
+            continue
+        if not isinstance(raw[key], str) or not re.fullmatch(r"[a-zA-Z0-9_@.+-]{1,128}", raw[key]):
+            raise ValueError("invalid user/principal")
+    for key in ("request_timeout", "stream_timeout"):
+        if key in raw and (type(raw[key]) not in (int, float) or not 0 < raw[key] <= 604800):
+            raise ValueError("invalid timeout")
+    if "namespace" in raw and (
+        not isinstance(raw["namespace"], str) or not re.fullmatch(r"[^\s]{1,255}", raw["namespace"])
+    ):
+        raise ValueError("invalid namespace")
+    if raw.get("log_level", "WARNING") not in ("DEBUG", "INFO", "WARNING", "ERROR"):
+        raise ValueError("invalid log level")
+    if "ca_file" in raw and not isinstance(raw["ca_file"], str):
+        raise ValueError("invalid CA file")
+    raw["identity"] = str(Path(raw["identity"]).expanduser().resolve())
+    if raw.get("ca_file"):
+        raw["ca_file"] = str(Path(raw["ca_file"]).expanduser())
+    return Settings(host=host, port=port, **raw)

ssh_sse_tool/protocol.py

@@ -0,0 +1,48 @@
+"""Canonical authentication transcript contract for ssh-sse/v1."""
+
+import json
+
+PROTOCOL = "ssh-sse/v1"
+TRANSCRIPT_FIELDS = (
+    "protocol",
+    "purpose",
+    "audience",
+    "namespace",
+    "challenge_id",
+    "nonce",
+    "principal",
+    "target_host",
+    "target_port",
+    "ssh_user",
+    "expires_at",
+    "public_key_fingerprint",
+)
+
+
+def transcript(challenge, request, *, check=False):
+    data = {"purpose": "ssh-sse-gateway/check/v1" if check else "ssh-sse-gateway/v1"}
+    for key in TRANSCRIPT_FIELDS:
+        if key in challenge:
+            data[key] = challenge[key]
+        elif key in request:
+            data[key] = request[key]
+    if set(data) != set(TRANSCRIPT_FIELDS) or data["protocol"] != PROTOCOL:
+        raise ValueError("invalid transcript")
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode(
+        "ascii"
+    )
+
+
+def strict_json(data):
+    def unique(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError("duplicate JSON field")
+            result[key] = value
+        return result
+
+    def constant(value):
+        raise ValueError("invalid JSON constant")
+
+    return json.loads(data, object_pairs_hook=unique, parse_constant=constant)

ssh_sse_tool/sse.py

@@ -0,0 +1,87 @@
+"""Incremental bounded SSE decoder with strict binary sequence validation."""
+
+import base64
+import binascii
+
+from .protocol import strict_json
+
+
+class SSE:
+    def __init__(self, max_chunk=16384):
+        self.buffer = bytearray()
+        self.fields = {}
+        self.event_size = 0
+        self.seq = 0
+        self.eof = False
+        self.max_chunk = max_chunk
+        self.max_event = max_chunk * 2 + 1024
+
+    def feed(self, chunk):
+        if self.eof and chunk:
+            raise ValueError("bytes after EOF event")
+        self.buffer.extend(chunk)
+        result = []
+        while b"\n" in self.buffer:
+            raw, _, rest = self.buffer.partition(b"\n")
+            self.buffer = bytearray(rest)
+            if len(raw) > self.max_event:
+                raise ValueError("oversized SSE line")
+            line = raw.rstrip(b"\r").decode("utf-8", errors="strict")
+            self.event_size += len(raw) + 1
+            if self.event_size > self.max_event:
+                raise ValueError("oversized SSE event")
+            if not line:
+                if self.fields:
+                    result.append(self.event())
+                self.fields = {}
+                self.event_size = 0
+            elif line.startswith(":"):
+                continue
+            else:
+                name, sep, value = line.partition(":")
+                if not sep or name not in ("event", "id", "data"):
+                    raise ValueError("invalid SSE field")
+                if value.startswith(" "):
+                    value = value[1:]
+                if name in self.fields:
+                    if name != "data":
+                        raise ValueError("duplicate SSE field")
+                    self.fields[name] += "\n" + value
+                else:
+                    self.fields[name] = value
+        if len(self.buffer) > self.max_event:
+            raise ValueError("oversized SSE line")
+        return result
+
+    def event(self):
+        if self.eof:
+            raise ValueError("event after EOF")
+        kind = self.fields.get("event")
+        data = strict_json(self.fields.get("data", ""))
+        if kind == "data":
+            if (
+                set(self.fields) != {"event", "id", "data"}
+                or not isinstance(data, dict)
+                or set(data) != {"seq", "payload_b64"}
+                or type(data["seq"]) is not int
+                or data["seq"] != self.seq
+                or self.fields["id"] != str(self.seq)
+                or not isinstance(data["payload_b64"], str)
+            ):
+                raise ValueError("invalid SSE sequence")
+            try:
+                decoded = base64.b64decode(data["payload_b64"], validate=True)
+            except binascii.Error:
+                raise ValueError("invalid SSE Base64") from None
+            if not 0 < len(decoded) <= self.max_chunk:
+                raise ValueError("invalid SSE payload size")
+            self.seq += 1
+            return decoded
+        if kind == "eof" and set(self.fields) == {"event", "data"} and data == {}:
+            self.eof = True
+            return None
+        raise ValueError("gateway transport error or unexpected SSE event")
+
+    def finish(self):
+        if self.buffer or self.fields or not self.eof:
+            raise ValueError("SSE interrupted before explicit EOF")

ssh_sse_tool/stdio.py

@@ -0,0 +1,54 @@
+"""Cancelable bounded nonblocking pipe I/O for OpenSSH ProxyCommand."""
+
+import asyncio
+import os
+
+
+async def ready(fd, write=False):
+    loop = asyncio.get_running_loop()
+    future = loop.create_future()
+
+    def wake():
+        if not future.done():
+            future.set_result(None)
+
+    add = loop.add_writer if write else loop.add_reader
+    remove = loop.remove_writer if write else loop.remove_reader
+    add(fd, wake)
+    try:
+        await future
+    finally:
+        remove(fd)
+
+
+class Stdio:
+    def __init__(self, input_fd=0, output_fd=1):
+        self.input_fd, self.output_fd = input_fd, output_fd
+        self.previous = {fd: os.get_blocking(fd) for fd in (input_fd, output_fd)}
+        for fd in self.previous:
+            os.set_blocking(fd, False)
+
+    async def read(self, size):
+        while True:
+            try:
+                return os.read(self.input_fd, size)
+            except BlockingIOError:
+                await ready(self.input_fd)
+
+    async def write(self, data):
+        view = memoryview(data)
+        while view:
+            try:
+                count = os.write(self.output_fd, view)
+                if not count:
+                    raise BrokenPipeError()
+                view = view[count:]
+            except BlockingIOError:
+                await ready(self.output_fd, write=True)
+
+    def close(self):
+        for fd, blocking in self.previous.items():
+            try:
+                os.set_blocking(fd, blocking)
+            except OSError:
+                pass

ssh_sse_tool/transport.py

@@ -0,0 +1,274 @@
+"""One input POST at a time; no retries, resume, or redirects."""
+
+import asyncio
+import re
+import ssl
+import time
+from urllib.parse import urlsplit
+
+import httpx
+
+from .auth import identity_key, sign
+from .config import base_url
+from .protocol import PROTOCOL, strict_json, transcript
+from .sse import SSE
+
+
+class GatewayError(ValueError):
+    """Sanitized gateway status, without response bodies or credentials."""
+
+
+def json_response(response):
+    if response.status_code >= 300:
+        # Only expose stable codes, never server response bodies or tokens.
+        code = "GATEWAY_ERROR"
+        try:
+            candidate = strict_json(response.content).get("code")
+            if isinstance(candidate, str) and re.fullmatch(r"[A-Z][A-Z0-9_]{0,62}", candidate):
+                code = candidate
+        except (ValueError, AttributeError):
+            pass
+        raise GatewayError(f"{code} (HTTP {response.status_code})")
+    if len(response.content) > 16384:
+        raise ValueError("oversized gateway control response")
+    return strict_json(response.content)
+
+
+def require_identity_encoding(response):
+    if response.headers.get("content-encoding", "identity").strip().lower() != "identity":
+        raise ValueError("compressed gateway responses are not supported")
+
+
+async def control_response(client, method, url, **kwargs):
+    # Streaming prevents a malicious gateway from forcing an unbounded control read.
+    timeout = kwargs.get("timeout", client.timeout)
+    deadline = timeout.read if isinstance(timeout, httpx.Timeout) else timeout
+    async with asyncio.timeout(30 if deadline is None else deadline):
+        async with client.stream(method, url, **kwargs) as response:
+            require_identity_encoding(response)
+            content = bytearray()
+            async for chunk in response.aiter_bytes():
+                if len(content) + len(chunk) > 16384:
+                    raise ValueError("oversized gateway control response")
+                content.extend(chunk)
+            if response.status_code >= 300:
+                json_response(httpx.Response(response.status_code, content=bytes(content)))
+            if response.headers.get("content-type", "").split(";")[0] != "application/json":
+                raise ValueError("invalid control response type")
+            return json_response(httpx.Response(response.status_code, content=bytes(content)))
+
+
+class Transport:
+    def __init__(self, settings):
+        self.settings = settings
+        self.path = settings.url + "/v1"
+        self.session_path = None
+        self.headers = {}
+        self.remote_eof = False
+        self.input_task: asyncio.Task | None = None
+
+    async def authenticate(self, client, *, check=False):
+        s = self.settings
+        public, fp = await identity_key(s.identity)
+        challenge = await control_response(
+            client,
+            "POST",
+            self.path + "/challenges",
+            json={"principal": s.principal or "", "public_key": public},
+        )
+        expected = {
+            "protocol",
+            "audience",
+            "namespace",
+            "challenge_id",
+            "nonce",
+            "expires_at",
+            "principal",
+            "public_key_fingerprint",
+        }
+        if (
+            not isinstance(challenge, dict)
+            or set(challenge) != expected
+            or challenge["protocol"] != PROTOCOL
+            or (
+                challenge["audience"] != s.url
+                and not (
+                    check
+                    and s.url.startswith("http://")
+                    and isinstance(challenge["audience"], str)
+                    and base_url(challenge["audience"]) == challenge["audience"]
+                )
+            )
+            or challenge["namespace"] != s.namespace
+            or not isinstance(challenge["principal"], str)
+            or not re.fullmatch(r"[a-zA-Z0-9_@.+-]{1,128}", challenge["principal"])
+            or (s.principal is not None and challenge["principal"] != s.principal)
+            or challenge["public_key_fingerprint"] != fp
+            or type(challenge["expires_at"]) is not int
+            or not time.time() < challenge["expires_at"] <= time.time() + 604800
+            or any(
+                not isinstance(challenge[k], str) or not 32 <= len(challenge[k]) <= 128
+                for k in ("nonce", "challenge_id")
+            )
+        ):
+            raise ValueError("invalid gateway challenge binding")
+        request = dict(
+            protocol=PROTOCOL,
+            challenge_id=challenge["challenge_id"],
+            principal=challenge["principal"],
+            target_host="" if check else s.host,
+            target_port=0 if check else s.port,
+            ssh_user="" if check else s.user,
+            public_key_fingerprint=fp,
+            signature_format="sshsig",
+        )
+        request["signature_b64"] = await sign(
+            s.identity, s.namespace, transcript(challenge, request, check=check)
+        )
+        if check:
+            result = await control_response(client, "POST", self.path + "/check", json=request)
+            if result != {"authenticated": True} or type(result.get("authenticated")) is not bool:
+                raise ValueError("invalid gateway key-check response")
+            return None
+        session_url = s.url if urlsplit(s.url).path else s.url + "/"
+        session = await control_response(client, "POST", session_url, json=request)
+        if not isinstance(session, dict) or set(session) != {
+            "session_id",
+            "session_token",
+            "expires_at",
+            "max_chunk_bytes",
+            "max_in_flight_bytes",
+        }:
+            raise ValueError("invalid gateway session")
+        for key in ("session_id", "session_token"):
+            if not isinstance(session[key], str) or not re.fullmatch(
+                r"[A-Za-z0-9_-]{32,128}", session[key]
+            ):
+                raise ValueError("invalid session capability")
+        chunk = session["max_chunk_bytes"]
+        if type(chunk) is not int or not 1 <= chunk <= 16384:
+            raise ValueError("invalid chunk size")
+        self.session_path = self.path + "/sessions/" + session["session_id"]
+        self.headers = {"Authorization": "Bearer " + session["session_token"]}
+        return chunk
+
+    async def post_chunk(self, client, data, seq):
+        assert self.session_path is not None
+        response = await control_response(
+            client,
+            "POST",
+            self.session_path + "/input",
+            content=data,
+            headers={
+                **self.headers,
+                "Content-Type": "application/octet-stream",
+                "X-SSH-SSE-Seq": str(seq),
+            },
+        )
+        if (
+            response != {"acked_seq": seq, "bytes": len(data)}
+            or type(response.get("acked_seq")) is not int
+            or type(response.get("bytes")) is not int
+        ):
+            raise ValueError("ambiguous input acknowledgement")
+
+    async def post_eof(self, client):
+        assert self.session_path is not None
+        result = await control_response(
+            client, "POST", self.session_path + "/input-eof", headers=self.headers
+        )
+        if result != {"eof": True} or type(result.get("eof")) is not bool:
+            raise ValueError("ambiguous input EOF acknowledgement")
+
+    async def send(self, client, stdio, chunk):
+        assert self.session_path is not None
+        seq = 0
+        while not self.remote_eof:
+            data = await stdio.read(chunk)
+            if self.remote_eof:
+                return
+            if not data:
+                self.input_task = asyncio.create_task(self.post_eof(client))
+                await self.input_task
+                return
+            self.input_task = asyncio.create_task(self.post_chunk(client, data, seq))
+            await self.input_task
+            seq += 1
+
+    async def receive(self, client, stdio, chunk):
+        assert self.session_path is not None
+        parser = SSE(chunk)
+        async with client.stream(
+            "GET",
+            self.session_path + "/events",
+            headers=self.headers,
+            timeout=httpx.Timeout(
+                self.settings.stream_timeout, connect=self.settings.request_timeout
+            ),
+        ) as response:
+            require_identity_encoding(response)
+            if (
+                response.status_code != 200
+                or response.headers.get("content-type", "").split(";")[0] != "text/event-stream"
+            ):
+                raise ValueError("gateway SSE subscription failed")
+            async for part in response.aiter_bytes(chunk_size=None):
+                for data in parser.feed(part):
+                    if data is not None:
+                        await asyncio.wait_for(stdio.write(data), self.settings.stream_timeout)
+                if parser.eof:
+                    parser.finish()
+                    return
+        parser.finish()
+
+    async def check(self):
+        async with self.client() as client:
+            await self.authenticate(client, check=True)
+
+    def client(self):
+        context = ssl.create_default_context(cafile=self.settings.ca_file)
+        return httpx.AsyncClient(
+            verify=context,
+            trust_env=False,
+            follow_redirects=False,
+            timeout=self.settings.request_timeout,
+            limits=httpx.Limits(max_connections=4),
+            headers={"Accept-Encoding": "identity"},
+        )
+
+    async def run(self, stdio):
+        tasks = []
+        async with self.client() as client:
+            try:
+                chunk = await self.authenticate(client)
+                assert chunk is not None
+                sender = asyncio.create_task(self.send(client, stdio, chunk))
+                receiver = asyncio.create_task(self.receive(client, stdio, chunk))
+                tasks = [sender, receiver]
+                done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+                if receiver in done:
+                    await receiver
+                    self.remote_eof = True
+                    # Remote EOF does not prove an outstanding POST was acknowledged.
+                    # Finish that request before cancelling any blocked stdin read.
+                    if self.input_task is not None:
+                        await asyncio.wait_for(
+                            asyncio.shield(self.input_task), self.settings.request_timeout
+                        )
+                    if sender.done():
+                        await sender
+                else:
+                    await sender
+                    await receiver
+            finally:
+                for task in tasks:
+                    task.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)
+                if self.session_path:
+                    try:
+                        async with client.stream(
+                            "DELETE", self.session_path, headers=self.headers, timeout=2
+                        ):
+                            pass
+                    except (httpx.HTTPError, asyncio.CancelledError):
+                        pass