heyvm 1.0.0

package/bin/heyvm.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * heyvm CLI entry point
+ * Launches the heyvm TUI with the Go backend
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// When installed globally via npm, __dirname is in node_modules/heyvm/bin
+// When run locally, __dirname is in the project's bin directory
+const rootDir = join(__dirname, '..');
+const coreBinaryPath = join(rootDir, 'bin', 'heyvm-core');
+const uiEntryPath = join(rootDir, 'ui', 'scripts', 'start-with-core.js');
+
+// Check if installation is complete
+if (!existsSync(coreBinaryPath)) {
+	console.error('❌ Error: heyvm-core binary not found.');
+	console.error('\nThe Go backend was not built during installation.');
+	console.error('Please ensure Go >= 1.21 is installed and run:');
+	console.error('  npm install -g heyvm');
+	console.error('\nDownload Go from: https://go.dev/dl/');
+	process.exit(1);
+}
+
+if (!existsSync(uiEntryPath)) {
+	console.error('❌ Error: UI entry point not found.');
+	console.error('Installation appears incomplete. Please reinstall:');
+	console.error('  npm install -g heyvm');
+	process.exit(1);
+}
+
+// Launch heyvm via the UI's start script
+const heyvmProcess = spawn('node', [uiEntryPath], {
+	stdio: 'inherit',
+	cwd: process.cwd(), // Use user's current directory
+});
+
+heyvmProcess.on('error', (err) => {
+	console.error('❌ Failed to start heyvm:', err.message);
+	process.exit(1);
+});
+
+heyvmProcess.on('exit', (code) => {
+	process.exit(code || 0);
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+	heyvmProcess.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+	heyvmProcess.kill('SIGTERM');
+});

package/core/README.md

@@ -0,0 +1,51 @@
+# heyvm Core
+
+Go backend for heyvm - handles SSH connections, SFTP file transfers, and VM management.
+
+## Development
+
+```bash
+# Build
+go build -o ../bin/heyvm-core ./cmd/heyvm-core
+
+# Run
+../bin/heyvm-core
+
+# Install dependencies
+go mod tidy
+
+# Run tests
+go test ./...
+```
+
+## Architecture
+
+- **Language**: Go
+- **SSH Library**: golang.org/x/crypto/ssh
+- **SFTP Library**: github.com/pkg/sftp
+- **Config Storage**: YAML files in ~/.heyvm/
+- **Credential Storage**: OS keychain (99designs/keyring)
+- **Communication**: JSON-RPC over stdin/stdout
+
+## Directory Structure
+
+```
+core/
+├── cmd/
+│   └── heyvm-core/    # Main entry point
+├── internal/
+│   ├── auth/          # Authentication providers (SSH key, password)
+│   ├── config/        # Configuration management
+│   ├── ipc/           # JSON-RPC protocol handler
+│   ├── sftp/          # SFTP file operations
+│   ├── ssh/           # SSH session management
+│   └── vm/            # VM models and registry
+└── go.mod             # Go module definition
+```
+
+## Configuration
+
+heyvm stores configuration in `~/.heyvm/`:
+- `config.yaml` - VM definitions
+- `state.json` - Runtime state
+- `logs/` - Application logs

package/core/cmd/heyvm-core/main.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/adishm/heyvm/internal/ipc"
+	"github.com/adishm/heyvm/internal/vm"
+)
+
+func main() {
+	// Initialize config directory (~/.heyvm/)
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	configDir := filepath.Join(homeDir, ".heyvm")
+	if err := os.MkdirAll(configDir, 0700); err != nil {
+		log.Fatal(err)
+	}
+
+	// Create logs directory
+	logsDir := filepath.Join(configDir, "logs")
+	if err := os.MkdirAll(logsDir, 0700); err != nil {
+		log.Fatal(err)
+	}
+
+	// Set up logging to file
+	logFile := filepath.Join(logsDir, "heyvm-core.log")
+	f, err := os.OpenFile(logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer f.Close()
+	log.SetOutput(f)
+
+	log.Println("=====================================")
+	log.Println("heyvm-core starting...")
+	log.Printf("Config directory: %s", configDir)
+	log.Printf("Log file: %s", logFile)
+
+	// Initialize VM registry
+	registry, err := vm.NewRegistry(configDir)
+	if err != nil {
+		log.Fatalf("Failed to create VM registry: %v", err)
+	}
+
+	// Load existing VMs from config
+	if err := registry.Load(); err != nil {
+		log.Printf("Warning: Could not load VM registry: %v", err)
+		log.Println("Starting with empty registry (this is normal for first run)")
+	} else {
+		vmCount := registry.Count()
+		log.Printf("Loaded %d VM(s) from config", vmCount)
+	}
+
+	// Create IPC handler
+	handler := ipc.NewHandler(registry)
+
+	log.Println("IPC handler initialized")
+	log.Println("heyvm-core ready to accept requests")
+	log.Println("=====================================")
+
+	// Start IPC request/response loop
+	// This blocks until stdin is closed or an error occurs
+	if err := handler.Start(); err != nil {
+		log.Fatalf("IPC handler error: %v", err)
+	}
+
+	log.Println("heyvm-core shutting down gracefully")
+}

package/core/go.mod

@@ -0,0 +1,25 @@
+module github.com/adishm/heyvm
+
+go 1.24.0
+
+toolchain go1.24.12
+
+require (
+	github.com/99designs/keyring v1.2.2
+	github.com/pkg/sftp v1.13.10
+	golang.org/x/crypto v0.47.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 // indirect
+	github.com/danieljoos/wincred v1.1.2 // indirect
+	github.com/dvsekhvalnov/jose2go v1.5.0 // indirect
+	github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 // indirect
+	github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
+	github.com/kr/fs v0.1.0 // indirect
+	github.com/mtibben/percent v0.2.1 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/term v0.39.0 // indirect
+)

package/core/go.sum

@@ -0,0 +1,47 @@
+github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 h1:/vQbFIOMbk2FiG/kXiLl8BRyzTWDw7gX/Hz7Dd5eDMs=
+github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4/go.mod h1:hN7oaIRCjzsZ2dE+yG5k+rsdt3qcwykqK6HVGcKwsw4=
+github.com/99designs/keyring v1.2.2 h1:pZd3neh/EmUzWONb35LxQfvuY7kiSXAq3HQd97+XBn0=
+github.com/99designs/keyring v1.2.2/go.mod h1:wes/FrByc8j7lFOAGLGSNEg8f/PaI3cgTBqhFkHUrPk=
+github.com/danieljoos/wincred v1.1.2 h1:QLdCxFs1/Yl4zduvBdcHB8goaYk9RARS2SgLLRuAyr0=
+github.com/danieljoos/wincred v1.1.2/go.mod h1:GijpziifJoIBfYh+S7BbkdUTU4LfM+QnGqR5Vl2tAx0=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dvsekhvalnov/jose2go v1.5.0 h1:3j8ya4Z4kMCwT5nXIKFSV84YS+HdqSSO0VsTQxaLAeM=
+github.com/dvsekhvalnov/jose2go v1.5.0/go.mod h1:QsHjhyTlD/lAVqn/NSbVZmSCGeDehTB/mPZadG+mhXU=
+github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 h1:ZpnhV/YsD2/4cESfV5+Hoeu/iUR3ruzNvZ+yQfO03a0=
+github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2/go.mod h1:bBOAhwG1umN6/6ZUMtDFBMQR8jRg9O75tm9K00oMsK4=
+github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c h1:6rhixN/i8ZofjG1Y75iExal34USq5p+wiN1tpie8IrU=
+github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c/go.mod h1:NMPJylDgVpX0MLRlPy15sqSwOFv/U1GZ2m21JhFfek0=
+github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/mtibben/percent v0.2.1 h1:5gssi8Nqo8QU/r2pynCm+hBQHpkB/uNK7BJCFogWdzs=
+github.com/mtibben/percent v0.2.1/go.mod h1:KG9uO+SZkUp+VkRHsCdYQV3XSZrrSpR3O9ibNBTZrns=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU=
+github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
+golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
+golang.org/x/sys v0.0.0-20210819135213-f52c844e1c1c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=
+golang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200902074654-038fdea0a05b h1:QRR6H1YWRnHb4Y/HeNFCTJLFVxaq6wH4YuVdsUOr75U=
+gopkg.in/check.v1 v1.0.0-20200902074654-038fdea0a05b/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package/core/internal/auth/errors.go

@@ -0,0 +1,29 @@
+package auth
+
+import "errors"
+
+var (
+	// ErrUnsupportedAuthType is returned when the auth type is not supported
+	ErrUnsupportedAuthType = errors.New("unsupported authentication type")
+
+	// ErrKeyFileNotFound is returned when SSH key file doesn't exist
+	ErrKeyFileNotFound = errors.New("SSH key file not found")
+
+	// ErrInvalidKeyFile is returned when SSH key file is invalid
+	ErrInvalidKeyFile = errors.New("invalid SSH key file")
+
+	// ErrKeyPermissions is returned when SSH key has incorrect permissions
+	ErrKeyPermissions = errors.New("SSH key file has incorrect permissions (should be 0600)")
+
+	// ErrConnectionFailed is returned when SSH connection fails
+	ErrConnectionFailed = errors.New("SSH connection failed")
+
+	// ErrAuthenticationFailed is returned when authentication fails
+	ErrAuthenticationFailed = errors.New("authentication failed")
+
+	// ErrPasswordNotFound is returned when password is not found in keychain
+	ErrPasswordNotFound = errors.New("password not found in keychain")
+
+	// ErrKeychainAccessDenied is returned when keychain access is denied
+	ErrKeychainAccessDenied = errors.New("keychain access denied")
+)

package/core/internal/auth/password.go

@@ -0,0 +1,187 @@
+package auth
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/99designs/keyring"
+	"github.com/adishm/heyvm/internal/vm"
+	"golang.org/x/crypto/ssh"
+)
+
+const (
+	keyringService = "heyvm"
+)
+
+// PasswordAuth implements Provider using password authentication
+// Passwords are stored securely in the OS keychain
+type PasswordAuth struct {
+	ring         keyring.Keyring
+	client       *ssh.Client
+	tempPassword string // Temporary password for testing (not stored)
+}
+
+// NewPasswordAuth creates a new password authentication provider
+func NewPasswordAuth() (*PasswordAuth, error) {
+	// Initialize OS keyring
+	ring, err := keyring.Open(keyring.Config{
+		ServiceName:              keyringService,
+		KeychainTrustApplication: true,
+		// Use file backend as fallback if OS keychain is unavailable
+		AllowedBackends: []keyring.BackendType{
+			keyring.KeychainBackend,      // macOS
+			keyring.SecretServiceBackend, // Linux
+			keyring.WinCredBackend,       // Windows
+			keyring.FileBackend,          // Fallback
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to open keyring: %w", err)
+	}
+
+	return &PasswordAuth{
+		ring: ring,
+	}, nil
+}
+
+// NewPasswordAuthWithTemp creates a provider with a temporary password (for testing)
+func NewPasswordAuthWithTemp(tempPassword string) (*PasswordAuth, error) {
+	// Initialize OS keyring (may not be used if temp password is provided)
+	ring, err := keyring.Open(keyring.Config{
+		ServiceName:              keyringService,
+		KeychainTrustApplication: true,
+		AllowedBackends: []keyring.BackendType{
+			keyring.KeychainBackend,
+			keyring.SecretServiceBackend,
+			keyring.WinCredBackend,
+			keyring.FileBackend,
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to open keyring: %w", err)
+	}
+
+	return &PasswordAuth{
+		ring:         ring,
+		tempPassword: tempPassword,
+	}, nil
+}
+
+// Connect establishes an SSH connection using password authentication
+func (a *PasswordAuth) Connect(v *vm.VM) (*ssh.Client, error) {
+	var password string
+	var err error
+
+	// Use temporary password if provided, otherwise get from keyring
+	if a.tempPassword != "" {
+		password = a.tempPassword
+	} else {
+		password, err = a.GetPassword(v.ID)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get password: %w", err)
+		}
+	}
+
+	// Configure SSH client
+	config := &ssh.ClientConfig{
+		User: v.Username,
+		Auth: []ssh.AuthMethod{
+			ssh.Password(password),
+		},
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(), // TODO: Implement proper host key verification
+		Timeout:         30 * time.Second,            // Increased timeout for large transfers
+	}
+
+	// Set keep-alive settings to prevent connection drops during large transfers
+	config.SetDefaults()
+
+	// Connect to SSH server
+	address := fmt.Sprintf("%s:%d", v.Host, v.Port)
+	client, err := ssh.Dial("tcp", address, config)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrConnectionFailed, err)
+	}
+
+	a.client = client
+	return client, nil
+}
+
+// Disconnect closes the SSH connection
+func (a *PasswordAuth) Disconnect() error {
+	if a.client != nil {
+		return a.client.Close()
+	}
+	return nil
+}
+
+// SupportsSFTP returns true (password auth supports SFTP)
+func (a *PasswordAuth) SupportsSFTP() bool {
+	return true
+}
+
+// Name returns the provider name
+func (a *PasswordAuth) Name() string {
+	return "Password Authentication"
+}
+
+// StorePassword stores a password in the OS keychain
+func (a *PasswordAuth) StorePassword(vmID, password string) error {
+	if vmID == "" {
+		return fmt.Errorf("VM ID cannot be empty")
+	}
+	if password == "" {
+		return fmt.Errorf("password cannot be empty")
+	}
+
+	item := keyring.Item{
+		Key:         vmID,
+		Data:        []byte(password),
+		Label:       fmt.Sprintf("heyvm password for VM %s", vmID),
+		Description: "SSH password for heyvm VM",
+	}
+
+	if err := a.ring.Set(item); err != nil {
+		return fmt.Errorf("failed to store password in keychain: %w", err)
+	}
+
+	return nil
+}
+
+// GetPassword retrieves a password from the OS keychain
+func (a *PasswordAuth) GetPassword(vmID string) (string, error) {
+	if vmID == "" {
+		return "", fmt.Errorf("VM ID cannot be empty")
+	}
+
+	item, err := a.ring.Get(vmID)
+	if err != nil {
+		if err == keyring.ErrKeyNotFound {
+			return "", ErrPasswordNotFound
+		}
+		return "", fmt.Errorf("failed to retrieve password from keychain: %w", err)
+	}
+
+	return string(item.Data), nil
+}
+
+// RemovePassword removes a password from the OS keychain
+func (a *PasswordAuth) RemovePassword(vmID string) error {
+	if vmID == "" {
+		return fmt.Errorf("VM ID cannot be empty")
+	}
+
+	if err := a.ring.Remove(vmID); err != nil {
+		if err == keyring.ErrKeyNotFound {
+			return ErrPasswordNotFound
+		}
+		return fmt.Errorf("failed to remove password from keychain: %w", err)
+	}
+
+	return nil
+}
+
+// HasPassword checks if a password exists in the keychain for the given VM ID
+func (a *PasswordAuth) HasPassword(vmID string) bool {
+	_, err := a.GetPassword(vmID)
+	return err == nil
+}

package/core/internal/auth/provider.go

@@ -0,0 +1,33 @@
+package auth
+
+import (
+	"github.com/adishm/heyvm/internal/vm"
+	"golang.org/x/crypto/ssh"
+)
+
+// Provider defines the interface for authentication providers
+type Provider interface {
+	// Connect establishes an SSH connection to the VM
+	Connect(v *vm.VM) (*ssh.Client, error)
+
+	// Disconnect closes the connection
+	Disconnect() error
+
+	// SupportsSFTP returns true if this provider supports SFTP
+	SupportsSFTP() bool
+
+	// Name returns the name of the provider
+	Name() string
+}
+
+// NewProvider creates an appropriate authentication provider based on VM config
+func NewProvider(v *vm.VM) (Provider, error) {
+	switch v.Auth.Type {
+	case vm.AuthTypeKey:
+		return NewSSHKeyAuth(v.Auth.KeyPath)
+	case vm.AuthTypePassword:
+		return NewPasswordAuth()
+	default:
+		return nil, ErrUnsupportedAuthType
+	}
+}

package/core/internal/auth/ssh_key.go

@@ -0,0 +1,142 @@
+package auth
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/adishm/heyvm/internal/vm"
+	"golang.org/x/crypto/ssh"
+)
+
+// SSHKeyAuth implements Provider using SSH key authentication
+type SSHKeyAuth struct {
+	keyPath string
+	client  *ssh.Client
+}
+
+// NewSSHKeyAuth creates a new SSH key authentication provider
+func NewSSHKeyAuth(keyPath string) (*SSHKeyAuth, error) {
+	if keyPath == "" {
+		return nil, fmt.Errorf("key path cannot be empty")
+	}
+
+	// Expand home directory
+	expandedPath, err := expandPath(keyPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to expand path: %w", err)
+	}
+
+	// Check if key file exists
+	info, err := os.Stat(expandedPath)
+	if os.IsNotExist(err) {
+		return nil, fmt.Errorf("%w: %s (expanded from: %s)", ErrKeyFileNotFound, expandedPath, keyPath)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("failed to access key file: %w", err)
+	}
+
+	// Check key file permissions (should be 0600 or 0400)
+	mode := info.Mode().Perm()
+	if mode&0077 != 0 {
+		// Key is readable/writable by group or others
+		return nil, fmt.Errorf("%w: has permissions %o (run: chmod 400 %s)", ErrKeyPermissions, mode, expandedPath)
+	}
+
+	return &SSHKeyAuth{
+		keyPath: expandedPath,
+	}, nil
+}
+
+// expandPath expands ~ to home directory and handles path resolution
+func expandPath(path string) (string, error) {
+	if path == "" {
+		return path, nil
+	}
+
+	// Handle ~ at the beginning
+	if path[0] == '~' {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("failed to get home directory: %w", err)
+		}
+
+		// Handle ~/path
+		if len(path) == 1 {
+			return home, nil
+		}
+		if path[1] == '/' || path[1] == filepath.Separator {
+			return filepath.Join(home, path[2:]), nil
+		}
+		// Handle ~path (shouldn't happen but be safe)
+		return filepath.Join(home, path[1:]), nil
+	}
+
+	// Return absolute path
+	return filepath.Abs(path)
+}
+
+// Connect establishes an SSH connection using key authentication
+func (a *SSHKeyAuth) Connect(v *vm.VM) (*ssh.Client, error) {
+	// Read private key
+	key, err := os.ReadFile(a.keyPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read private key from %s: %w", a.keyPath, err)
+	}
+
+	// Parse private key (supports PEM, OpenSSH, RSA, Ed25519, ECDSA)
+	signer, err := ssh.ParsePrivateKey(key)
+	if err != nil {
+		// Check if it's an encrypted key
+		if _, ok := err.(*ssh.PassphraseMissingError); ok {
+			return nil, fmt.Errorf("SSH key is encrypted (passphrase-protected keys not yet supported in Phase 1)")
+		}
+		return nil, fmt.Errorf("%w: %v (supported formats: PEM, OpenSSH, RSA, Ed25519, ECDSA)", ErrInvalidKeyFile, err)
+	}
+
+	// Configure SSH client
+	config := &ssh.ClientConfig{
+		User: v.Username,
+		Auth: []ssh.AuthMethod{
+			ssh.PublicKeys(signer),
+		},
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(), // TODO: Implement proper host key verification
+		Timeout:         30 * time.Second,            // Increased timeout for large transfers
+	}
+
+	// Set keep-alive settings to prevent connection drops during large transfers
+	// This will send keep-alive packets every 15 seconds
+	config.SetDefaults()
+	// Note: Keep-alive is configured at the session level after connection
+
+	// Connect to SSH server
+	address := fmt.Sprintf("%s:%d", v.Host, v.Port)
+	client, err := ssh.Dial("tcp", address, config)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v (check host/port/username)", ErrConnectionFailed, err)
+	}
+
+	a.client = client
+	return client, nil
+}
+
+// Disconnect closes the SSH connection
+func (a *SSHKeyAuth) Disconnect() error {
+	if a.client != nil {
+		err := a.client.Close()
+		a.client = nil // Clear the reference
+		return err
+	}
+	return nil
+}
+
+// SupportsSFTP returns true (SSH key auth supports SFTP)
+func (a *SSHKeyAuth) SupportsSFTP() bool {
+	return true
+}
+
+// Name returns the provider name
+func (a *SSHKeyAuth) Name() string {
+	return "SSH Key Authentication"
+}