feat: add connections, a saved SSH connection manager

api/go.mod

@@ -3,6 +3,7 @@ module github.com/shellhub-io/shellhub/api
 go 1.25.8
 
 require (
+	code.dny.dev/ssrf v0.2.0
 	github.com/cnf/structhash v0.0.0-20201127153200-e1b16c1ebc08
 	github.com/getkin/kin-openapi v0.140.0
 	github.com/getsentry/sentry-go v0.47.0
@@ -117,6 +118,7 @@ require (
 	go.opentelemetry.io/otel v1.41.0 // indirect
 	go.opentelemetry.io/otel/metric v1.41.0 // indirect
 	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	golang.org/x/exp v0.0.0-20221126150942-6ab00d035af9 // indirect
 	golang.org/x/net v0.56.0 // indirect
 	golang.org/x/sync v0.21.0 // indirect
 	golang.org/x/sys v0.46.0 // indirect

api/go.sum

@@ -1,3 +1,5 @@
+code.dny.dev/ssrf v0.2.0 h1:wCBP990rQQ1CYfRpW+YK1+8xhwUjv189AQ3WMo1jQaI=
+code.dny.dev/ssrf v0.2.0/go.mod h1:B+91l25OnyaLIeCx0WRJN5qfJ/4/ZTZxRXgm0lj/2w8=
 dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
 dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
@@ -335,6 +337,8 @@ golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8U
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
 golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/exp v0.0.0-20221126150942-6ab00d035af9 h1:yZNXmy+j/JpX19vZkVktWqAo7Gny4PBWYYK3zskGpx4=
+golang.org/x/exp v0.0.0-20221126150942-6ab00d035af9/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc=
 golang.org/x/lint v0.0.0-20190930215403-16217165b5de/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=

api/pkg/responses/known_host.go

@@ -0,0 +1,15 @@
+package responses
+
+import "github.com/shellhub-io/shellhub/pkg/models"
+
+// KnownHostScanResult is the presented host key plus its verification status,
+// returned by a host-key scan. It lives here (not in the service package) so the
+// generated Service mock can reference it without importing the service package,
+// which would form an import cycle with the service's own tests.
+type KnownHostScanResult struct {
+	KeyType     string                 `json:"key_type"`
+	Fingerprint string                 `json:"fingerprint"`
+	PublicKey   string                 `json:"public_key"`
+	Status      models.KnownHostStatus `json:"status"`
+	Stored      *models.KnownHost      `json:"stored"`
+}

api/routes/connection.go

@@ -0,0 +1,149 @@
+package routes
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/shellhub-io/shellhub/api/pkg/gateway"
+	svc "github.com/shellhub-io/shellhub/api/services"
+	"github.com/shellhub-io/shellhub/pkg/api/requests"
+)
+
+const (
+	CreateConnectionURL = "/connections"
+	ListConnectionsURL  = "/connections"
+	GetConnectionURL    = "/connections/:id"
+	ConnectionStatusURL = "/connections/:id/status"
+	UpdateConnectionURL = "/connections/:id"
+	DeleteConnectionURL = "/connections/:id"
+)
+
+const ParamConnectionID = "id"
+
+func (h *Handler) CreateConnection(c gateway.Context) error {
+	var req requests.ConnectionCreate
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	// For external connections, probe at save time. A 422 lets the UI distinguish
+	// a blocked target (not a permitted address) from an unreachable host (the
+	// NAT/firewall hint + install-the-agent funnel). Force skips the probe.
+	if req.Kind == "external" && !req.Force {
+		reachable, err := h.service.ProbeReachability(c.Ctx(), &requests.ConnectionProbe{Host: req.Host, Port: req.Port})
+		switch {
+		case errors.Is(err, svc.ErrEgressBlocked):
+			return c.JSON(http.StatusUnprocessableEntity, map[string]string{"error": "blocked"})
+		case err != nil:
+			return err
+		case !reachable:
+			return c.JSON(http.StatusUnprocessableEntity, map[string]string{"error": "unreachable"})
+		}
+	}
+
+	connection, err := h.service.CreateConnection(c.Ctx(), &req)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusCreated, connection)
+}
+
+func (h *Handler) ListConnections(c gateway.Context) error {
+	req := new(requests.ConnectionList)
+	if err := c.Bind(req); err != nil {
+		return err
+	}
+
+	req.Paginator.Normalize()
+	req.Sorter.Normalize()
+
+	if err := c.Validate(req); err != nil {
+		return err
+	}
+
+	connections, count, err := h.service.ListConnections(c.Ctx(), req)
+	if err != nil {
+		return err
+	}
+
+	c.Response().Header().Set("X-Total-Count", strconv.Itoa(count))
+
+	return c.JSON(http.StatusOK, connections)
+}
+
+func (h *Handler) GetConnection(c gateway.Context) error {
+	var req requests.ConnectionGet
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	connection, err := h.service.GetConnection(c.Ctx(), &req)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, connection)
+}
+
+func (h *Handler) ConnectionStatus(c gateway.Context) error {
+	var req requests.ConnectionGet
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	online, err := h.service.ConnectionStatus(c.Ctx(), &req)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, map[string]bool{"online": online})
+}
+
+func (h *Handler) UpdateConnection(c gateway.Context) error {
+	var req requests.ConnectionUpdate
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	connection, err := h.service.UpdateConnection(c.Ctx(), &req)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, connection)
+}
+
+func (h *Handler) DeleteConnection(c gateway.Context) error {
+	var req requests.ConnectionDelete
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	if err := h.service.DeleteConnection(c.Ctx(), &req); err != nil {
+		return err
+	}
+
+	return c.NoContent(http.StatusOK)
+}

api/routes/known_host.go

@@ -0,0 +1,101 @@
+package routes
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/shellhub-io/shellhub/api/pkg/gateway"
+	svc "github.com/shellhub-io/shellhub/api/services"
+	"github.com/shellhub-io/shellhub/pkg/api/requests"
+)
+
+const (
+	ScanKnownHostURL   = "/connections/host-key/scan"
+	AcceptKnownHostURL = "/connections/host-key/accept"
+	GetKnownHostURL    = "/connections/host-key"
+	DeleteKnownHostURL = "/connections/host-key"
+)
+
+func (h *Handler) ScanKnownHost(c gateway.Context) error {
+	var req requests.KnownHostScan
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	result, err := h.service.ScanKnownHost(c.Ctx(), &req)
+	if err != nil {
+		// Surface a target we can't reach/read as a 422 (not a 500), and let the
+		// UI tell a blocked address apart from an unreachable host.
+		switch {
+		case errors.Is(err, svc.ErrEgressBlocked):
+			return c.JSON(http.StatusUnprocessableEntity, map[string]string{"error": "blocked"})
+		case errors.Is(err, svc.ErrKnownHostUnreachable):
+			return c.JSON(http.StatusUnprocessableEntity, map[string]string{"error": "unreachable"})
+		}
+
+		return err
+	}
+
+	return c.JSON(http.StatusOK, result)
+}
+
+func (h *Handler) AcceptKnownHost(c gateway.Context) error {
+	var req requests.KnownHostAccept
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	knownHost, err := h.service.AcceptKnownHost(c.Ctx(), &req)
+	if err != nil {
+		if errors.Is(err, svc.ErrKnownHostInvalidKey) {
+			return c.JSON(http.StatusUnprocessableEntity, map[string]string{"error": "invalid_key"})
+		}
+
+		return err
+	}
+
+	return c.JSON(http.StatusOK, knownHost)
+}
+
+func (h *Handler) GetKnownHost(c gateway.Context) error {
+	var req requests.KnownHostGet
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	knownHost, err := h.service.GetKnownHost(c.Ctx(), &req)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, knownHost)
+}
+
+func (h *Handler) DeleteKnownHost(c gateway.Context) error {
+	var req requests.KnownHostDelete
+	if err := c.Bind(&req); err != nil {
+		return err
+	}
+
+	if err := c.Validate(&req); err != nil {
+		return err
+	}
+
+	if err := h.service.DeleteKnownHost(c.Ctx(), &req); err != nil {
+		return err
+	}
+
+	return c.NoContent(http.StatusOK)
+}

api/routes/routes.go

@@ -151,6 +151,18 @@ func NewRouter(service services.Service, opts ...Option) *echo.Echo {
 	publicAPI.PUT(SetDeviceCustomFieldURL, gateway.Handler(handler.SetDeviceCustomField), routesmiddleware.RequiresPermission(authorizer.DeviceCustomFieldUpdate))
 	publicAPI.DELETE(DeleteDeviceCustomFieldURL, gateway.Handler(handler.DeleteDeviceCustomField), routesmiddleware.RequiresPermission(authorizer.DeviceCustomFieldUpdate))
 
+	publicAPI.GET(ListConnectionsURL, routesmiddleware.Authorize(gateway.Handler(handler.ListConnections)))
+	publicAPI.GET(GetConnectionURL, routesmiddleware.Authorize(gateway.Handler(handler.GetConnection)))
+	publicAPI.GET(ConnectionStatusURL, routesmiddleware.Authorize(gateway.Handler(handler.ConnectionStatus)))
+	publicAPI.POST(CreateConnectionURL, gateway.Handler(handler.CreateConnection), routesmiddleware.RequiresPermission(authorizer.ConnectionCreate))
+	publicAPI.PUT(UpdateConnectionURL, gateway.Handler(handler.UpdateConnection), routesmiddleware.RequiresPermission(authorizer.ConnectionUpdate))
+	publicAPI.DELETE(DeleteConnectionURL, gateway.Handler(handler.DeleteConnection), routesmiddleware.RequiresPermission(authorizer.ConnectionDelete))
+
+	publicAPI.POST(ScanKnownHostURL, routesmiddleware.Authorize(gateway.Handler(handler.ScanKnownHost)))
+	publicAPI.POST(AcceptKnownHostURL, routesmiddleware.Authorize(gateway.Handler(handler.AcceptKnownHost)))
+	publicAPI.GET(GetKnownHostURL, routesmiddleware.Authorize(gateway.Handler(handler.GetKnownHost)))
+	publicAPI.DELETE(DeleteKnownHostURL, routesmiddleware.Authorize(gateway.Handler(handler.DeleteKnownHost)))
+
 	publicAPI.GET(URLGetTags, gateway.Handler(handler.GetTags))
 	publicAPI.POST(URLCreateTag, gateway.Handler(handler.CreateTag), routesmiddleware.RequiresPermission(authorizer.TagCreate))
 	publicAPI.PATCH(URLUpdateTag, gateway.Handler(handler.UpdateTag), routesmiddleware.RequiresPermission(authorizer.TagUpdate))