ssh-over-sse-gateway 0.1.0__tar.gz

ssh_over_sse_gateway-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+*.egg-info/
+.runtime/
+.coverage

ssh_over_sse_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: ssh-over-sse-gateway
+Version: 0.1.0
+Summary: Policy-restricted SSH TCP relay over HTTPS POST and SSE
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=45
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: starlette<2,>=1.3.1
+Requires-Dist: uvicorn<1,>=0.35
+Description-Content-Type: text/markdown
+
+# ssh-sse-gateway
+
+Provide authorized SSH access through an HTTPS endpoint. Run the gateway on a
+host that can reach your approved SSH destinations.
+
+## Install
+
+Requires Python 3.12 or newer and OpenSSH's `ssh-keygen`.
+
+With uv:
+
+```sh
+uv tool install --python 3.12 ssh-over-sse-gateway
+```
+
+Or with pip:
+
+```sh
+pip install 'ssh-over-sse[gateway]'
+```
+
+Use `ssh-over-sse[all]` with pip to install the client command too.
+
+## Configure
+
+Save your configuration as `~/.config/ssh-over-sse/gateway.yaml`. Use your public
+HTTPS root URL and allow each SSH destination and login username:
+
+```yaml
+server:
+  audience: https://gateway.example.com
+  listen: 0.0.0.0:7010
+  ingress_network_restricted: true
+targets:
+  - host: 192.0.2.20
+    ports: [22]
+    ssh_users: [alice]
+```
+
+Replace the example values and restrict the file to its owner. Limit backend
+access to your trusted network before setting `ingress_network_restricted: true`;
+this setting acknowledges your network restrictions and does not create them.
+
+The default listener is `127.0.0.1:7010`. With OCI providing HTTPS, the gateway
+runs plain HTTP on port **7010** and needs no backend certificate. The example
+above accepts ingress on all interfaces.
+
+## Authorize users
+
+The gateway reads public keys from its account's `~/.ssh/authorized_keys` by
+default. Set `server.authorized_keys_file` if the file is elsewhere.
+
+Supported entries are unrestricted Ed25519, RSA (2048–8192 bits), and ECDSA
+(P-256, P-384, P-521) public keys. Entries with SSH restrictions such as `from=` or
+`command=` are skipped. Use only keys intended to have gateway access.
+
+All eligible keys authenticate to the gateway account. The requested destination
+and SSH username must also be allowed in your configuration. The destination
+server separately authorizes the user's SSH login. Private user keys stay on
+users' computers.
+
+Removing a key denies new access and ends its active connections. Restart the
+gateway after changing destination permissions; restarting ends active sessions.
+
+## Start
+
+Validate the configuration, then start:
+
+```sh
+ssh-sse-gateway --check-config
+ssh-sse-gateway
+```
+
+To use another configuration file:
+
+```sh
+ssh-sse-gateway --config /path/to/gateway.yaml --check-config
+ssh-sse-gateway --config /path/to/gateway.yaml
+```
+
+Configure HTTPS ingress to forward requests to the gateway. It must pass
+authorization headers and support streaming without buffering or compression.
+The root URL shows a landing page in a browser. Users pass that same root URL to
+`ssh-sse-cli`.
+
+For direct HTTPS without an ingress, set `server.tls_mode: direct` and provide
+`--tls-cert /path/to/cert.pem` and `--tls-key /path/to/key.pem` when starting.
+Restrict the server's private certificate key to its owner.
+
+## Check access
+
+From a user's computer:
+
+```sh
+ssh-sse-cli --url https://gateway.example.com -i ~/.ssh/id_ecdsa check
+```
+
+Success confirms gateway key access. Users still need destination permission and
+an authorized SSH login. A landing page alone does not confirm SSH access.
+
+## Troubleshooting
+
+If startup fails, run `--check-config` and check required values, file ownership,
+and permissions. If users cannot connect, check the HTTPS route, public-key
+access, destination permissions, and network reachability.
+
+```sh
+ssh-sse-gateway --help
+```

ssh_over_sse_gateway-0.1.0/README.md

@@ -0,0 +1,109 @@
+# ssh-sse-gateway
+
+Provide authorized SSH access through an HTTPS endpoint. Run the gateway on a
+host that can reach your approved SSH destinations.
+
+## Install
+
+Requires Python 3.12 or newer and OpenSSH's `ssh-keygen`.
+
+With uv:
+
+```sh
+uv tool install --python 3.12 ssh-over-sse-gateway
+```
+
+Or with pip:
+
+```sh
+pip install 'ssh-over-sse[gateway]'
+```
+
+Use `ssh-over-sse[all]` with pip to install the client command too.
+
+## Configure
+
+Save your configuration as `~/.config/ssh-over-sse/gateway.yaml`. Use your public
+HTTPS root URL and allow each SSH destination and login username:
+
+```yaml
+server:
+  audience: https://gateway.example.com
+  listen: 0.0.0.0:7010
+  ingress_network_restricted: true
+targets:
+  - host: 192.0.2.20
+    ports: [22]
+    ssh_users: [alice]
+```
+
+Replace the example values and restrict the file to its owner. Limit backend
+access to your trusted network before setting `ingress_network_restricted: true`;
+this setting acknowledges your network restrictions and does not create them.
+
+The default listener is `127.0.0.1:7010`. With OCI providing HTTPS, the gateway
+runs plain HTTP on port **7010** and needs no backend certificate. The example
+above accepts ingress on all interfaces.
+
+## Authorize users
+
+The gateway reads public keys from its account's `~/.ssh/authorized_keys` by
+default. Set `server.authorized_keys_file` if the file is elsewhere.
+
+Supported entries are unrestricted Ed25519, RSA (2048–8192 bits), and ECDSA
+(P-256, P-384, P-521) public keys. Entries with SSH restrictions such as `from=` or
+`command=` are skipped. Use only keys intended to have gateway access.
+
+All eligible keys authenticate to the gateway account. The requested destination
+and SSH username must also be allowed in your configuration. The destination
+server separately authorizes the user's SSH login. Private user keys stay on
+users' computers.
+
+Removing a key denies new access and ends its active connections. Restart the
+gateway after changing destination permissions; restarting ends active sessions.
+
+## Start
+
+Validate the configuration, then start:
+
+```sh
+ssh-sse-gateway --check-config
+ssh-sse-gateway
+```
+
+To use another configuration file:
+
+```sh
+ssh-sse-gateway --config /path/to/gateway.yaml --check-config
+ssh-sse-gateway --config /path/to/gateway.yaml
+```
+
+Configure HTTPS ingress to forward requests to the gateway. It must pass
+authorization headers and support streaming without buffering or compression.
+The root URL shows a landing page in a browser. Users pass that same root URL to
+`ssh-sse-cli`.
+
+For direct HTTPS without an ingress, set `server.tls_mode: direct` and provide
+`--tls-cert /path/to/cert.pem` and `--tls-key /path/to/key.pem` when starting.
+Restrict the server's private certificate key to its owner.
+
+## Check access
+
+From a user's computer:
+
+```sh
+ssh-sse-cli --url https://gateway.example.com -i ~/.ssh/id_ecdsa check
+```
+
+Success confirms gateway key access. Users still need destination permission and
+an authorized SSH login. A landing page alone does not confirm SSH access.
+
+## Troubleshooting
+
+If startup fails, run `--check-config` and check required values, file ownership,
+and permissions. If users cannot connect, check the HTTPS route, public-key
+access, destination permissions, and network reachability.
+
+```sh
+ssh-sse-gateway --help
+```

ssh_over_sse_gateway-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "ssh-over-sse-gateway"
+version = "0.1.0"
+readme = "README.md"
+description = "Policy-restricted SSH TCP relay over HTTPS POST and SSE"
+requires-python = ">=3.12"
+dependencies = ["starlette>=1.3.1,<2", "uvicorn>=0.35,<1", "pyyaml>=6,<7", "cryptography>=45"]
+[project.scripts]
+ssh-sse-gateway = "ssh_sse_gateway.cli:main"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=1", "httpx>=0.28", "ruff>=0.12", "mypy>=1.16", "types-PyYAML"]
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+[tool.ruff]
+line-length = 100
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+[tool.mypy]
+check_untyped_defs = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ssh_sse_gateway"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/pyproject.toml", "/README.md", "/uv.lock", "/src"]

ssh_over_sse_gateway-0.1.0/src/ssh_sse_gateway/__init__.py

@@ -0,0 +1 @@
+"""SSH-over-SSE gateway."""

ssh_over_sse_gateway-0.1.0/src/ssh_sse_gateway/app.py

@@ -0,0 +1,368 @@
+"""ASGI routes for ssh-sse/v1. No forwarding headers are trusted."""
+
+import asyncio
+import base64
+import ipaddress
+import json
+import time
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse, StreamingResponse
+from starlette.routing import Route
+
+from .audit import audit
+from .auth import AuthError, Challenges
+from .config import valid_name
+from .metrics import Metrics
+from .policy import authorize
+from .sessions import Sessions
+
+
+async def landing(request):
+    return HTMLResponse(
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        "<title>ssh-over-sse</title></head><body><h1>ssh-over-sse</h1></body></html>",
+        headers={
+            "Content-Security-Policy": "default-src 'none'",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+async def body(request, limit):
+    result = bytearray()
+    async with asyncio.timeout(request.app.state.config.server.request_timeout):
+        async for part in request.stream():
+            if len(result) + len(part) > limit:
+                raise AuthError("LIMIT_EXCEEDED", 413)
+            result.extend(part)
+    return bytes(result)
+
+
+def no_duplicates(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+async def control(request):
+    if request.headers.get("content-type", "").split(";")[0] != "application/json":
+        raise AuthError("BAD_REQUEST", 400)
+    try:
+        result = json.loads(await body(request, 16384), object_pairs_hook=no_duplicates)
+        if not isinstance(result, dict):
+            raise ValueError()
+        return result
+    except (ValueError, TypeError, RecursionError):
+        raise AuthError("BAD_REQUEST", 400) from None
+    except TimeoutError:
+        raise AuthError("REQUEST_TIMEOUT", 408) from None
+
+
+async def challenge(request):
+    data = await control(request)
+    if set(data) != {"principal", "public_key"} or (
+        data.get("principal") != "" and not valid_name(data.get("principal"))
+    ):
+        raise AuthError("BAD_REQUEST", 400)
+    try:
+        result = request.app.state.challenges.create(data["principal"], data["public_key"])
+        return JSONResponse(result, headers={"Cache-Control": "no-store"})
+    except AuthError:
+        request.app.state.metrics.increment("auth_failure_total")
+        audit("gateway_auth_failure", reason="UNAUTHORIZED")
+        raise
+
+
+async def check_key(request):
+    data = await control(request)
+    if (
+        data.get("target_host") != ""
+        or type(data.get("target_port")) is not int
+        or data["target_port"] != 0
+        or data.get("ssh_user") != ""
+        or not isinstance(data.get("challenge_id"), str)
+    ):
+        raise AuthError("BAD_REQUEST", 400)
+    state = request.app.state
+    try:
+        await state.challenges.verify(data, check=True)
+    except AuthError:
+        state.metrics.increment("auth_failure_total")
+        audit("gateway_auth_failure", reason="UNAUTHORIZED")
+        raise
+    state.metrics.increment("auth_success_total")
+    audit(
+        "gateway_key_check",
+        principal=data["principal"],
+        key_fingerprint=data["public_key_fingerprint"],
+    )
+    return JSONResponse({"authenticated": True}, headers={"Cache-Control": "no-store"})
+
+
+async def create_session(request):
+    data = await control(request)
+    for key in ("principal", "ssh_user"):
+        if not valid_name(data.get(key)):
+            raise AuthError("BAD_REQUEST", 400)
+    for key in ("challenge_id", "signature_b64", "public_key_fingerprint", "target_host"):
+        if not isinstance(data.get(key), str) or len(data[key]) > 12000:
+            raise AuthError("BAD_REQUEST", 400)
+    if type(data.get("target_port")) is not int:
+        raise AuthError("BAD_REQUEST", 400)
+    state = request.app.state
+    try:
+        await state.challenges.verify(data)
+    except AuthError:
+        request.app.state.metrics.increment("auth_failure_total")
+        audit("gateway_auth_failure", reason="UNAUTHORIZED")
+        raise
+    try:
+        host = authorize(
+            state.config,
+            data["principal"],
+            data["target_host"],
+            data["target_port"],
+            data["ssh_user"],
+        )
+    except ValueError:
+        state.metrics.increment("target_denied_total")
+        audit("gateway_target_denied", principal=data["principal"], reason="FORBIDDEN_TARGET")
+        raise AuthError("FORBIDDEN_TARGET", 403) from None
+    state.metrics.increment("auth_success_total")
+    audit(
+        "gateway_auth_success",
+        principal=data["principal"],
+        key_fingerprint=data["public_key_fingerprint"],
+    )
+    session, token = await state.sessions.open(
+        data["principal"], host, data["target_port"], data["public_key_fingerprint"]
+    )
+    s = state.config.server
+    return JSONResponse(
+        dict(
+            session_id=session.id,
+            session_token=token,
+            expires_at=int(time.time() + s.session_max_lifetime),
+            max_chunk_bytes=s.max_chunk_bytes,
+            max_in_flight_bytes=s.max_buffer_bytes_per_direction,
+        ),
+        status_code=201,
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+def authenticated(request):
+    if request.url.query:
+        raise AuthError("BAD_REQUEST", 400)
+    return request.app.state.sessions.get(
+        request.path_params["id"], request.headers.get("authorization", "")
+    )
+
+
+async def input_bytes(request):
+    session = authenticated(request)
+    b, sessions = session.bridge, request.app.state.sessions
+    if b.input_busy or b.input_eof or request.headers.get("x-ssh-sse-seq") != str(b.in_seq):
+        await sessions.close(session, "BAD_SEQUENCE")
+        raise AuthError("BAD_SEQUENCE", 409)
+    b.input_busy = True
+    success = False
+    try:
+        if request.headers.get("content-type") != "application/octet-stream":
+            raise AuthError("BAD_REQUEST", 400)
+        data = await body(request, b.settings.max_chunk_bytes)
+        if not data or b.closed:
+            raise AuthError("BAD_REQUEST", 400)
+        await b.write(data)
+        seq = b.in_seq
+        b.in_seq += 1
+        success = True
+        return JSONResponse({"acked_seq": seq, "bytes": len(data)})
+    except (OSError, TimeoutError):
+        raise AuthError("TRANSPORT_INTERRUPTED", 502) from None
+    finally:
+        b.input_busy = False
+        if not success:
+            await sessions.close(session, "INPUT_INTERRUPTED")
+
+
+async def input_eof(request):
+    session = authenticated(request)
+    b = session.bridge
+    if b.input_busy:
+        await request.app.state.sessions.close(session, "BAD_SEQUENCE")
+        raise AuthError("BAD_SEQUENCE", 409)
+    b.input_busy = True
+    success = False
+    try:
+        if await body(request, 0):
+            raise AuthError("BAD_REQUEST", 400)
+        await b.half_close()
+        success = True
+        return JSONResponse({"eof": True})
+    except (OSError, TimeoutError):
+        await request.app.state.sessions.close(session, "INPUT_INTERRUPTED")
+        raise AuthError("TRANSPORT_INTERRUPTED", 502) from None
+    finally:
+        b.input_busy = False
+        if not success:
+            await request.app.state.sessions.close(session, "INPUT_INTERRUPTED")
+
+
+async def delete(request):
+    # Valid existing capability required; repeated deletion returns generic 404.
+    session = authenticated(request)
+    await request.app.state.sessions.close(session, "CLIENT_CLOSED")
+    return JSONResponse({"closed": True})
+
+
+class BoundedStreamingResponse(StreamingResponse):
+    def __init__(
+        self, content: AsyncGenerator[bytes, None], *, stall_timeout, on_close=None, **kwargs
+    ):
+        super().__init__(content, **kwargs)
+        self.stall_timeout = stall_timeout
+        self.iterator = content
+        self.on_close = on_close
+
+    async def __call__(self, scope, receive, send):
+        try:
+            await super().__call__(scope, receive, send)
+        finally:
+            # A header failure can happen before the generator's finally is entered.
+            if self.on_close is not None:
+                await asyncio.shield(asyncio.create_task(self.on_close()))
+
+    async def stream_response(self, send):
+        async def bounded_send(message):
+            await asyncio.wait_for(send(message), self.stall_timeout)
+
+        try:
+            await super().stream_response(bounded_send)
+        finally:
+            await self.iterator.aclose()
+
+
+async def events(request):
+    session = authenticated(request)
+    b = session.bridge
+    if b.attached or request.headers.get("last-event-id") is not None:
+        await request.app.state.sessions.close(session, "SSE_REATTACH")
+        raise AuthError("TRANSPORT_INTERRUPTED", 409)
+    b.attached = True
+
+    async def generate():
+        seq = 0
+        try:
+            while True:
+                try:
+                    data = await asyncio.wait_for(b.output.get(), b.settings.heartbeat)
+                except TimeoutError:
+                    yield b": heartbeat\n\n"
+                    continue
+                if data is None:
+                    if b.failure:
+                        yield b'event: error\ndata: {"code":"TRANSPORT_INTERRUPTED"}\n\n'
+                    else:
+                        yield b"event: eof\ndata: {}\n\n"
+                    return
+                payload = json.dumps(
+                    {"seq": seq, "payload_b64": base64.b64encode(data).decode()},
+                    separators=(",", ":"),
+                )
+                yield f"id: {seq}\nevent: data\ndata: {payload}\n\n".encode()
+                b.bytes_out += len(data)
+                b.activity = time.monotonic()
+                seq += 1
+        finally:
+            # Shield cleanup from StreamingResponse's disconnect cancellation scope.
+            cleanup = asyncio.create_task(request.app.state.sessions.close(session, "SSE_CLOSED"))
+            await asyncio.shield(cleanup)
+
+    return BoundedStreamingResponse(
+        generate(),
+        stall_timeout=b.settings.stall_timeout,
+        on_close=lambda: request.app.state.sessions.close(session, "SSE_CLOSED"),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache, no-transform", "X-Accel-Buffering": "no"},
+    )
+
+
+async def metrics(request):
+    if not request.client or not ipaddress.ip_address(request.client.host).is_loopback:
+        return JSONResponse({"code": "NOT_FOUND"}, status_code=404)
+    return PlainTextResponse(request.app.state.metrics.render(request.app.state.sessions))
+
+
+async def error(request, exc):
+    if exc.status == 429:
+        request.app.state.metrics.increment("rate_limited_total")
+        audit("rate_limited", reason=exc.code)
+    return JSONResponse(
+        {"code": exc.code}, status_code=exc.status, headers={"Cache-Control": "no-store"}
+    )
+
+
+class Limits:
+    def __init__(self, app, metrics):
+        self.app = app
+        self.metrics = metrics
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            headers = scope.get("headers", [])
+            if sum(len(k) + len(v) for k, v in headers) > 16384 or len(headers) > 64:
+                return await JSONResponse({"code": "LIMIT_EXCEEDED"}, status_code=431)(
+                    scope, receive, send
+                )
+        start = time.monotonic()
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            if scope["type"] == "http":
+                self.metrics.requests += 1
+                self.metrics.latency_sum += time.monotonic() - start
+
+
+def create_app(config):
+    @asynccontextmanager
+    async def lifespan(app):
+        reaper = asyncio.create_task(app.state.sessions.reap())
+        try:
+            yield
+        finally:
+            reaper.cancel()
+            await asyncio.gather(reaper, return_exceptions=True)
+            await app.state.sessions.shutdown()
+
+    base = config.server.base_path + "/v1"
+    app = Starlette(
+        routes=[
+            Route("/", landing, methods=["GET"]),
+            Route(config.server.base_path or "/", create_session, methods=["POST"]),
+            Route("/metrics", metrics),
+            Route(base + "/challenges", challenge, methods=["POST"]),
+            Route(base + "/check", check_key, methods=["POST"]),
+            Route(base + "/sessions", create_session, methods=["POST"]),
+            Route(base + "/sessions/{id}/input", input_bytes, methods=["POST"]),
+            Route(base + "/sessions/{id}/input-eof", input_eof, methods=["POST"]),
+            Route(base + "/sessions/{id}/events", events),
+            Route(base + "/sessions/{id}", delete, methods=["DELETE"]),
+        ],
+        lifespan=lifespan,
+        exception_handlers={AuthError: error},
+    )
+    app.router.redirect_slashes = False
+    app.state.metrics = Metrics()
+    app.add_middleware(Limits, metrics=app.state.metrics)
+    app.state.config = config
+    app.state.challenges = Challenges(config)
+    app.state.sessions = Sessions(config, app.state.metrics)
+    return app

ssh_over_sse_gateway-0.1.0/src/ssh_sse_gateway/audit.py

@@ -0,0 +1,31 @@
+"""Allowlisted structured audit fields; never serialize requests or exceptions."""
+
+import json
+import logging
+from datetime import datetime, timezone
+
+logger = logging.getLogger("ssh_sse.audit")
+FIELDS = {
+    "session_id",
+    "principal",
+    "key_fingerprint",
+    "target",
+    "reason",
+    "duration",
+    "bytes_in",
+    "bytes_out",
+    "active_sessions",
+}
+
+
+def audit(event, **fields):
+    logger.info(
+        json.dumps(
+            {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "event": event,
+                **{k: v for k, v in fields.items() if k in FIELDS},
+            },
+            separators=(",", ":"),
+        )
+    )