api

Documentation

Overview

Package api implements the ussycode HTTPS API endpoints.

The API provides:

• POST /exec -- execute SSH commands via HTTPS
• GET /health -- health check
• GET /version -- version info

Authentication uses Bearer tokens in the Authorization header. Token formats:

• usy0.<base64url_permissions>.<base64url_ssh_signature> (stateless)
• usy1.<opaque_token_id> (short token, DB-backed)

Package api implements the ussycode HTTPS API endpoints.

Index

• Variables
• type CommandExecutor
• type Config
• type ErrorResponse
• type ExecRequest
• type ExecResponse
• type Handler
  • func NewHandler(database *db.DB, executor CommandExecutor, resolver KeyResolver, ...) *Handler
  • func (h *Handler) Routes(mux *http.ServeMux)
• type KeyResolver
• type RateLimiter
  • func NewRateLimiter(ratePerMinute float64, burst int) *RateLimiter
  • func (rl *RateLimiter) Allow(key string) bool
  • func (rl *RateLimiter) RetryAfter(key string) time.Duration
• type TokenPermissions

Variables

var Version = "dev"

Version is set at build time via ldflags.

Types

type CommandExecutor

type CommandExecutor interface {
	// Execute runs a command as the given user and returns the output.
	Execute(ctx context.Context, user *db.User, command string, args []string) (output string, exitCode int, err error)
}

CommandExecutor executes SSH-style commands programmatically. This interface decouples the API from the SSH shell implementation.

type Config

type Config struct {
	RatePerMinute float64 // requests per minute per fingerprint (default: 60)
	Burst         int     // max burst (default: 10)
}

Config holds API handler configuration.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
	Code  int    `json:"code"`
}

ErrorResponse is the JSON error response.

type ExecRequest

type ExecRequest struct {
	Command string `json:"command"`
}

ExecRequest is the JSON request body for POST /exec.

type ExecResponse

type ExecResponse struct {
	Output   string `json:"output"`
	ExitCode int    `json:"exit_code"`
}

ExecResponse is the JSON response for a successful exec.

type Handler

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

Handler implements the ussycode HTTPS API.

func NewHandler

func NewHandler(database *db.DB, executor CommandExecutor, resolver KeyResolver, logger *slog.Logger, cfg *Config) *Handler

NewHandler creates a new API handler.

func (*Handler) Routes

func (h *Handler) Routes(mux *http.ServeMux)

Routes registers API routes on the given mux.

type KeyResolver

type KeyResolver func(ctx context.Context, userID int64) ([]ssh.PublicKey, error)

KeyResolver looks up SSH public keys for a given user ID.

type RateLimiter

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

RateLimiter provides per-key token bucket rate limiting. It uses an in-memory sync.Map and is safe for concurrent use.

func NewRateLimiter

func NewRateLimiter(ratePerMinute float64, burst int) *RateLimiter

NewRateLimiter creates a rate limiter. rate is requests per minute, burst is the max burst size.

func (*RateLimiter) Allow

func (rl *RateLimiter) Allow(key string) bool

Allow checks if a request is allowed for the given key (e.g., SSH fingerprint). Returns true if the request is within rate limits.

func (*RateLimiter) RetryAfter

func (rl *RateLimiter) RetryAfter(key string) time.Duration

RetryAfter returns the duration until the next request will be allowed for the given key.

type TokenPermissions

type TokenPermissions struct {
	Exp  int64    `json:"exp"`            // expiry unix timestamp
	Nbf  int64    `json:"nbf"`            // not-before unix timestamp
	Cmds []string `json:"cmds,omitempty"` // allowed commands (empty = all)
	Ctx  string   `json:"ctx,omitempty"`  // optional context
}

TokenPermissions is the permissions JSON embedded in usy0 tokens.