ssh

Documentation

Overview

Package ssh implements the ussycode SSH gateway server. Users SSH into this server and interact with a custom shell, not a system shell. The gateway identifies users by their SSH public key fingerprint and routes them to registration or the main shell accordingly.

Index

• func CalculateELO(ratingA, ratingB int, result float64) (int, int)
• func RegisterCommand(name string, fn CommandFunc)
• func UpdateELOAfterMatch(ctx context.Context, s *Shell, matchID string) error
• type APIExecutor
  • func NewAPIExecutor(gw *Gateway) *APIExecutor
  • func (e *APIExecutor) Execute(ctx context.Context, user *db.User, command string, args []string) (string, int, error)
• type ArenaScenario
• type CommandFunc
• type Gateway
  • func New(database *db.DB, vmManager *vm.Manager, metaSrv *gateway.Server, ...) (*Gateway, error)
  • func (g *Gateway) ListenAndServe() error
  • func (g *Gateway) LookupRoutussyUser(fingerprint string) (*routussyUserResponse, error)
  • func (g *Gateway) Shutdown(ctx context.Context) error
• type Lesson
• type Shell
  • func (s *Shell) Run() error

Functions

func CalculateELO

func CalculateELO(ratingA, ratingB int, result float64) (int, int)

CalculateELO computes new ELO ratings for two players after a match. result: 1.0 = player A wins, 0.0 = player B wins, 0.5 = draw. Returns (newRatingA, newRatingB).

func RegisterCommand

func RegisterCommand(name string, fn CommandFunc)

RegisterCommand adds a command to the commands map at runtime. Used by packages that would cause init cycles if registered statically.

func UpdateELOAfterMatch

func UpdateELOAfterMatch(ctx context.Context, s *Shell, matchID string) error

UpdateELOAfterMatch updates ELO ratings for all participants after a match. This supports 2-player matches by comparing the top scorer (winner) vs others.

Types

type APIExecutor

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

APIExecutor executes the SSH command surface programmatically for the HTTPS API. It reuses the same command handlers as the interactive SSH shell so the SSH and HTTP surfaces stay aligned.

func NewAPIExecutor

func NewAPIExecutor(gw *Gateway) *APIExecutor

NewAPIExecutor creates a programmatic executor backed by the SSH command map.

func (*APIExecutor) Execute

func (e *APIExecutor) Execute(ctx context.Context, user *db.User, command string, args []string) (string, int, error)

Execute runs a single command for the given user.

type ArenaScenario

type ArenaScenario struct {
	Name            string `json:"name"`
	Description     string `json:"description"`
	DurationMinutes int    `json:"duration_minutes"`
	MaxAgents       int    `json:"max_agents"`
	Ports           []int  `json:"ports,omitempty"`
}

ArenaScenario represents a scenario definition loaded from templates/arena/.

type CommandFunc

type CommandFunc func(s *Shell, args []string) error

CommandFunc is a handler for a shell command.

type Gateway

type Gateway struct {
	DB         *db.DB
	VM         *vm.Manager
	Metadata   *gateway.Server
	Proxy      *proxy.Manager
	LLMGateway gateway.LLMGateway

	// RoutussyURL is the base URL of the Routussy proxy for SSH key validation
	// and API key lookup. If empty, all SSH keys are accepted (legacy behavior).
	RoutussyURL string

	// RoutussyInternalKey is the shared secret for authenticating to Routussy
	// internal API endpoints. Sent as Bearer token.
	RoutussyInternalKey string
	// contains filtered or unexported fields
}

Gateway is the SSH gateway server.

func New

func New(database *db.DB, vmManager *vm.Manager, metaSrv *gateway.Server, proxyMgr *proxy.Manager, hostKeyPath, addr, domain string) (*Gateway, error)

New creates a new SSH gateway. If the host key file doesn't exist, it generates a new ed25519 key.

func (*Gateway) ListenAndServe

func (g *Gateway) ListenAndServe() error

ListenAndServe starts the SSH server.

func (*Gateway) LookupRoutussyUser

func (g *Gateway) LookupRoutussyUser(fingerprint string) (*routussyUserResponse, error)

LookupRoutussyUser queries routussy for a user by SSH fingerprint and returns their metadata. Used to inject API keys into VM environments.

func (*Gateway) Shutdown

func (g *Gateway) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the SSH server.

type Lesson

type Lesson struct {
	Number      int
	Title       string
	Explanation string
	Command     string // the expected command the user should type
	Hint        string // shown if the user gets stuck
	Simulate    bool   // if true, lesson is informational-only (no command validation)
}

Lesson represents a single tutorial lesson with explanation and validation.

type Shell

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

Shell is the custom interactive shell presented to authenticated users.

func (*Shell) Run

func (s *Shell) Run() error

Run starts the interactive shell REPL.