ssh

package
v1.0.0-rc.16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 42 Imported by: 0

Documentation

Index

Constants

View Source
const (

	// UnlimitedWorkspaceLifetime as WorkspaceMaxTimeout removes the workspace
	// lifetime cap entirely; the idle deadline still applies.
	UnlimitedWorkspaceLifetime = time.Duration(-1)
)

Variables

View Source
var ErrWorkspaceAccessDenied = errors.New("workspace access denied")
View Source
var ErrWorkspaceUnavailable = errors.New("workspace unavailable")

ErrWorkspaceUnavailable means the controller could not answer: the VM is missing or moving, or the controller failed. It is never a credential failure.

Functions

func ResolveBranchName

func ResolveBranchName(login string, branches []string) (string, error)

ResolveBranchName selects from an already-authorized repository branch list. It replaces grant-login parsing for the install; no branch name is a path.

func SetRevocationSource

func SetRevocationSource(source RevocationSource)

SetRevocationSource subscribes the SSH server to source. Call once at startup; a nil source disables revocation-driven termination.

func StartKeepalive

func StartKeepalive(ctx context.Context, sender KeepaliveSender) func()

StartKeepalive maintains an authenticated forwarded SSH hop.

Types

type AmbiguousBranchError

type AmbiguousBranchError struct{ Candidates []string }

AmbiguousBranchError contains only validated, authorized branch names.

func (*AmbiguousBranchError) Error

func (e *AmbiguousBranchError) Error() string

type AuthLimitResult

type AuthLimitResult int
const (
	AuthLimitAllowed AuthLimitResult = iota
	AuthLimitThrottled
	AuthLimitBanned
)

type AuthLimiter

type AuthLimiter struct {
	// contains filtered or unexported fields
}

func NewAuthLimiter

func NewAuthLimiter(cfg AuthLimiterConfig) *AuthLimiter

func NewDefaultAuthLimiter

func NewDefaultAuthLimiter() *AuthLimiter

func (*AuthLimiter) Check

func (l *AuthLimiter) Check(ip, credential string) AuthLimitResult

Check admits one authentication attempt for credential (a key fingerprint or workspace login) from ip. An empty credential tracks the IP alone.

func (*AuthLimiter) RecordFailure

func (l *AuthLimiter) RecordFailure(ip, credential string)

RecordFailure counts a genuine credential failure. Callers must never record server or workspace faults here.

func (*AuthLimiter) RecordSuccess

func (l *AuthLimiter) RecordSuccess(ip, credential string)

type AuthLimiterConfig

type AuthLimiterConfig struct {
	AttemptsPerMinute   int
	IPAttemptsPerMinute int
	MaxAuthFailures     int
	InitialBan          time.Duration
	MaxBan              time.Duration
	StateTTL            time.Duration
	MaxTrackedIPs       int
	Now                 func() time.Time
}

AuthLimiterConfig bounds SSH authentication. Bans and the tight attempt rate apply per (IP, credential), so one client behind a shared NAT address (a GKE node, an office) never locks out another. IPAttemptsPerMinute is the looser per-IP pre-auth throttle; it never bans.

type BranchResolver

type BranchResolver interface {
	ResolveBranch(context.Context, int64, string) (WorkspaceAccess, error)
}

BranchResolver checks active roster membership, branch authorization and the member's provisioned identity without waking or executing anything. The install must supply this and a daemon-backed WorkspaceBridge together; a Plue grant bridge is not a branch execution provider.

type DaemonBridge

type DaemonBridge struct {
	Ready func(context.Context, WorkspaceAccess) error
	Admit func(context.Context, WorkspaceAccess, microsandbox.AdmissionRequest, io.Writer) (DaemonClient, func(), error)
	Track func(context.Context, WorkspaceAccess, uint32) (func(), error)
}

DaemonBridge requires every authority before authentication succeeds. Ready is read-only; Admit waits as a person, reconciles the wake and returns the boot-bound transport. Track holds safe-idle and reports the SSH actor/session and broker cgroup until its release. ID zero reserves tracking before wake; a nonzero ID publishes the broker session. Missing providers never wake a machine. The install composes these only after member provisioning is available.

func (*DaemonBridge) ConnectTCP

ConnectTCP opens only the daemon's guest-loopback primitive; net.Pipe is an in-process read buffer, never a host network destination.

func (*DaemonBridge) Serve

func (b *DaemonBridge) Serve(sess gliderssh.Session, a WorkspaceAccess) (int, error)

func (*DaemonBridge) Validate

func (b *DaemonBridge) Validate(ctx context.Context, a WorkspaceAccess) error

type DaemonClient

type DaemonClient interface {
	OpenSession(context.Context, machined.SessionUser, machined.SessionKind, []string, *machined.SessionSize) (uint32, error)
	CloseSession(context.Context, uint32) error
	TCPConnect(context.Context, uint16) (uint32, error)
	Stream(context.Context, uint32) (DaemonStream, error)
}

func NewDaemonClient

func NewDaemonClient(s *machined.Sessions) DaemonClient

type DaemonStream

type DaemonStream interface {
	Send(context.Context, []byte) error
	Receive(context.Context) ([]byte, error)
}

type InstallBranchResolver

type InstallBranchResolver struct{ Database *pgxpool.Pool }

InstallBranchResolver resolves only the installed repository's roster and canonical branch machines. Resolution never wakes a machine or mints a grant. The gateway repeats it for every channel, including direct-tcpip.

func (*InstallBranchResolver) ResolveBranch

func (r *InstallBranchResolver) ResolveBranch(ctx context.Context, member int64, login string) (WorkspaceAccess, error)

type KeepaliveSender

type KeepaliveSender interface {
	SendRequest(name string, wantReply bool, payload []byte) (bool, []byte, error)
}

keepaliveSender is the *gossh.ServerConn surface the keepalive uses.

type Metrics

type Metrics struct {
	// AuthAttempts counts SSH authentication attempts by result.
	AuthAttempts *prometheus.CounterVec

	// ActiveConns tracks the number of currently active SSH connections.
	ActiveConns prometheus.Gauge

	// GitOperations counts completed git operations by command and result.
	GitOperations *prometheus.CounterVec

	// GitOpDuration records the duration of git operations as a histogram.
	GitOpDuration *prometheus.HistogramVec
}

Metrics holds all Prometheus metric definitions for the SSH server. Metric names follow the spec in docs/specs/infra.md: smithers_ssh_{name}_{unit}

func NewMetrics

func NewMetrics(reg prometheus.Registerer) *Metrics

NewMetrics creates a new Metrics instance and registers all metrics with the provided Prometheus registerer.

type RepoHostGitProxy

type RepoHostGitProxy interface {
	ProxyReceivePack(ctx context.Context, owner, repo string, stdin io.Reader, stdout io.Writer, meta ...repohost.ReceivePackMetadata) error
	ProxyUploadPack(ctx context.Context, owner, repo string, stdin io.Reader, stdout io.Writer) error
	ProxyUploadPackBody(ctx context.Context, owner, repo string, body io.Reader, stdout io.Writer) error
	InfoRefsUploadPack(ctx context.Context, owner, repo string) ([]byte, error)
	InfoRefsReceivePack(ctx context.Context, owner, repo string) ([]byte, error)
}

type RevocationSource

type RevocationSource interface {
	Subscribe(fn func(revocation.Event)) func()
}

RevocationSource fans revocation events out to this process; *revocation.Bus satisfies it.

type SSHPrincipalQuerier

type SSHPrincipalQuerier interface {
	GetUserBySSHFingerprint(ctx context.Context, fingerprint string) (db.GetUserBySSHFingerprintRow, error)
	GetAnyDeployKeyByFingerprint(ctx context.Context, fingerprint string) (db.DeployKey, error)
	GetRepoByOwnerAndLowerName(ctx context.Context, arg db.GetRepoByOwnerAndLowerNameParams) (db.Repository, error)
	GetDeployKeyByFingerprint(ctx context.Context, arg db.GetDeployKeyByFingerprintParams) (db.DeployKey, error)
	TouchDeployKeyLastUsed(ctx context.Context, id int64) error
	ListAllProtectedBookmarksByRepo(ctx context.Context, repositoryID int64) ([]db.ProtectedBookmark, error)

} // RepoHostGitProxy proxies git RPC streams to repo-host.

SSHPrincipalQuerier defines the lookup used to resolve SSH principals and to enforce protected-bookmark policy on receive-pack.

type Server

type Server struct {
	Queries                  SSHPrincipalQuerier
	Authorizer               services.SSHAuthorizer
	RepoHostClient           RepoHostGitProxy
	LFSAuthBridge            *lfsauth.Bridge
	AuditService             *services.AuditService
	AuthLimiter              *AuthLimiter
	Metrics                  *Metrics
	HostKeyDir               string
	Addr                     string
	MaxConnections           int
	MaxConnectionsPerIP      int
	MaxReceivePackSize       int64
	MaxUploadPackRequestSize int64
	ReceivePackTimeout       time.Duration
	UploadPackTimeout        time.Duration
	// IdleTimeout bounds how long a connection may sit without any SSH
	// read/write activity (including the pre-auth handshake) before it is
	// closed. Zero means "derive from the pack timeouts"; it is never
	// unlimited, because connection slots are counted before authentication
	// and an idle client would otherwise hold one forever.
	IdleTimeout time.Duration
	// MaxTimeout is the absolute lifetime cap for a connection, bounding
	// slow-trickle clients that defeat IdleTimeout by sending a byte at a
	// time. Zero means the package default; it is never unlimited.
	MaxTimeout time.Duration
	// WorkspaceMaxTimeout is the absolute lifetime cap for an authenticated
	// workspace session connection, which replaces MaxTimeout once workspace
	// auth succeeds: a workspace command may run for hours, and the idle
	// deadline (kept alive by server keepalives) still reaps dead clients.
	// Zero means the package default; UnlimitedWorkspaceLifetime disables it.
	WorkspaceMaxTimeout time.Duration
	// MaxSessionsPerConn caps concurrent session channels multiplexed over a
	// single SSH connection, so one authenticated connection cannot fan out
	// unbounded git operations while only counting once against
	// MaxConnections. Zero means the package default.
	MaxSessionsPerConn int
	// WorkspaceBridge terminates public workspace SSH at this gateway and
	// establishes a second, authenticated SSH connection through the private
	// workspace control plane. Nil preserves the repository-only server.
	WorkspaceBridge WorkspaceBridge
	// BranchLogins selects the install parser; false preserves Plue grants.
	BranchLogins   bool
	BranchResolver BranchResolver
	// InstallMainMirror is the engine's install fact
	// (repohost.Client.InstallMainMirror): only the GitHub sync writes main
	// and the default bookmark, so no SSH push may.
	InstallMainMirror bool
	// contains filtered or unexported fields
}

Server is the Smithers SSH server for git operations.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the SSH server.

func (*Server) Prepare

func (s *Server) Prepare() error

Prepare loads the stable host key before the composition announces readiness.

func (*Server) Serve

func (s *Server) Serve(listener net.Listener) error

Serve adds a listener to the same gateway, sharing its host key, connection limits and revocation registry. Closing a listener does not end sessions.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the SSH server without interrupting active sessions. If the server has not been started, Shutdown is a no-op and returns nil. The provided context controls the maximum time to wait for in-flight connections to drain.

type WorkspaceAccess

type WorkspaceAccess struct {
	SandboxID string
	User      string
	Token     string
	// Branch logins bind the roster identity and stable branch machine id.
	MemberID int64
	UID      uint32
}

WorkspaceAccess is the non-persisted credential material for one public SSH connection. Token must never be logged or included in an error.

type WorkspaceBridge

type WorkspaceBridge interface {
	Validate(context.Context, WorkspaceAccess) error
	Serve(gliderssh.Session, WorkspaceAccess) (int, error)
}

WorkspaceBridge validates composition-owned access and serves an authenticated channel through its execution transport: daemon sessions on the install, or the existing private SSH grant hop in the hosted composition.

type WorkspaceTCPBridge

type WorkspaceTCPBridge interface {
	ConnectTCP(context.Context, WorkspaceAccess, uint16) (WorkspaceTCPConnection, error)
}

WorkspaceTCPBridge connects only to guest loopback through the authenticated machine transport. It must never dial the host network. Legacy workspace bridges without this capability continue to refuse local forwarding.

type WorkspaceTCPConnection

type WorkspaceTCPConnection interface {
	net.Conn
	CloseWrite() error
}

WorkspaceTCPConnection preserves EOF independently in each direction.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址