Documentation
¶
Index ¶
- Constants
- Variables
- func ResolveBranchName(login string, branches []string) (string, error)
- func SetRevocationSource(source RevocationSource)
- func StartKeepalive(ctx context.Context, sender KeepaliveSender) func()
- type AmbiguousBranchError
- type AuthLimitResult
- type AuthLimiter
- type AuthLimiterConfig
- type BranchResolver
- type DaemonBridge
- type DaemonClient
- type DaemonStream
- type InstallBranchResolver
- type KeepaliveSender
- type Metrics
- type RepoHostGitProxy
- type RevocationSource
- type SSHPrincipalQuerier
- type Server
- type WorkspaceAccess
- type WorkspaceBridge
- type WorkspaceTCPBridge
- type WorkspaceTCPConnection
Constants ¶
const ( // UnlimitedWorkspaceLifetime as WorkspaceMaxTimeout removes the workspace // lifetime cap entirely; the idle deadline still applies. UnlimitedWorkspaceLifetime = time.Duration(-1) )
Variables ¶
var ErrWorkspaceAccessDenied = errors.New("workspace access denied")
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 ¶
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 ¶
func (b *DaemonBridge) ConnectTCP(ctx context.Context, a WorkspaceAccess, port uint16) (WorkspaceTCPConnection, error)
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 InstallBranchResolver ¶
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 ¶
ListenAndServe starts the SSH server.
func (*Server) Prepare ¶
Prepare loads the stable host key before the composition announces readiness.
func (*Server) Serve ¶
Serve adds a listener to the same gateway, sharing its host key, connection limits and revocation registry. Closing a listener does not end sessions.
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 ¶
WorkspaceTCPConnection preserves EOF independently in each direction.